From 643b8d0eac4e0f4535f153336d79aff3a4d7cace Mon Sep 17 00:00:00 2001 From: Kai Willadsen Date: Fri, 4 May 2018 09:03:42 +1000 Subject: docs: Add introduction to handling GLib.Error --- docs/guide/api/error_handling.rst | 48 +++++++++++++++++++++++++++++++++++++++ docs/guide/api/index.rst | 1 + 2 files changed, 49 insertions(+) create mode 100644 docs/guide/api/error_handling.rst diff --git a/docs/guide/api/error_handling.rst b/docs/guide/api/error_handling.rst new file mode 100644 index 00000000..6ad67a94 --- /dev/null +++ b/docs/guide/api/error_handling.rst @@ -0,0 +1,48 @@ +============== +Error Handling +============== + +GLib has its own method of handling errors using :obj:`GLib.Error`. These are +raised as Python exceptions, but with a few small differences. + +It's common in Python for exception subclasses to be used (e.g., +:obj:`ValueError` versus :obj:`IOError`) to distinguish different types of +errors. Libraries often define their own :obj:`Exception` subclasses, and library +users will handle these cases explicitly. + +In GLib-using libraries, errors are all :obj:`GLib.Error` instances, with no +subclassing for different error types. Instead, every :obj:`GLib.Error` +instance has attributes that distinguish types of error: + +* :attr:`domain` is the error domain, usually a string that you can covert to + a `GLib` quark with :func:`GLib.quark_to_string` +* :attr:`code` identifies a specific error within the domain +* :attr:`message` is a human-readable description of the error + +Error domains are defined per-module, and you can get an error domain from +:func:`*_error_quark` functions on the relevant module. For example, IO errors +from `Gio` are in the domain returned by :func:`Gio.io_error_quark`, and the +possible values for :attr:`code` are enumerated in :obj:`Gio.IOErrorEnum`. + +Once you've caught a :obj:`GLib.Error`, you can call +:meth:`GLib.Error.matches` to see whether it matches the specific error you +want to handle. + + +Examples +-------- + +Catching a specific error: + +.. code:: pycon + + >>> from gi.repository import GLib, Gio + >>> f = Gio.File.new_for_path('missing-path') + >>> try: + ... f.read() + ... except GLib.Error as err: + ... if err.matches(Gio.io_error_quark(), Gio.IOErrorEnum.NOT_FOUND): + ... print('File not found') + ... else: + ... raise + File not found diff --git a/docs/guide/api/index.rst b/docs/guide/api/index.rst index efeade31..41f17ab5 100644 --- a/docs/guide/api/index.rst +++ b/docs/guide/api/index.rst @@ -10,3 +10,4 @@ API Reference basic_types flags_enums gobject + error_handling -- cgit v1.2.1 From be57e6c4bfe6fd1a54050b76721d967495e30e7e Mon Sep 17 00:00:00 2001 From: Kai Willadsen Date: Fri, 4 May 2018 10:00:41 +1000 Subject: docs: Fix references in new error handling docs --- docs/guide/api/error_handling.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/guide/api/error_handling.rst b/docs/guide/api/error_handling.rst index 6ad67a94..fc873ce8 100644 --- a/docs/guide/api/error_handling.rst +++ b/docs/guide/api/error_handling.rst @@ -7,22 +7,22 @@ raised as Python exceptions, but with a few small differences. It's common in Python for exception subclasses to be used (e.g., :obj:`ValueError` versus :obj:`IOError`) to distinguish different types of -errors. Libraries often define their own :obj:`Exception` subclasses, and library -users will handle these cases explicitly. +errors. Libraries often define their own :obj:`Exception` subclasses, and +library users will handle these cases explicitly. In GLib-using libraries, errors are all :obj:`GLib.Error` instances, with no subclassing for different error types. Instead, every :obj:`GLib.Error` instance has attributes that distinguish types of error: -* :attr:`domain` is the error domain, usually a string that you can covert to - a `GLib` quark with :func:`GLib.quark_to_string` -* :attr:`code` identifies a specific error within the domain -* :attr:`message` is a human-readable description of the error +* :attr:`GLib.Error.domain` is the error domain, usually a string that you can + convert to a ``GLib`` quark with :func:`GLib.quark_to_string` +* :attr:`GLib.Error.code` identifies a specific error within the domain +* :attr:`GLib.Error.message` is a human-readable description of the error Error domains are defined per-module, and you can get an error domain from -:func:`*_error_quark` functions on the relevant module. For example, IO errors -from `Gio` are in the domain returned by :func:`Gio.io_error_quark`, and the -possible values for :attr:`code` are enumerated in :obj:`Gio.IOErrorEnum`. +``*_error_quark`` functions on the relevant module. For example, IO errors +from ``Gio`` are in the domain returned by :func:`Gio.io_error_quark`, and +possible error code values are enumerated in :obj:`Gio.IOErrorEnum`. Once you've caught a :obj:`GLib.Error`, you can call :meth:`GLib.Error.matches` to see whether it matches the specific error you -- cgit v1.2.1 From dda8ee3cf4e3e45b6376ad66a161b0380bd4bb34 Mon Sep 17 00:00:00 2001 From: Kai Willadsen Date: Sat, 5 May 2018 05:28:47 +1000 Subject: docs: Fix quark_from_string/to_string confusion --- docs/guide/api/error_handling.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/api/error_handling.rst b/docs/guide/api/error_handling.rst index fc873ce8..e392cca2 100644 --- a/docs/guide/api/error_handling.rst +++ b/docs/guide/api/error_handling.rst @@ -15,7 +15,7 @@ subclassing for different error types. Instead, every :obj:`GLib.Error` instance has attributes that distinguish types of error: * :attr:`GLib.Error.domain` is the error domain, usually a string that you can - convert to a ``GLib`` quark with :func:`GLib.quark_to_string` + convert to a ``GLib`` quark with :func:`GLib.quark_from_string` * :attr:`GLib.Error.code` identifies a specific error within the domain * :attr:`GLib.Error.message` is a human-readable description of the error -- cgit v1.2.1