Debian Codegraph @

docs/source/design/exception_handling.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_exception_handling:
5
6 ******************
7 Exception handling
8 ******************
9
10 .. topic:: Specification scope and status
11
12 This specification describes the current implementation target.
13
14
15 Catching exceptions
16 ===================
17
18 Whenever we catch an exception in an ``except`` clause, the following rules
19 apply:
20
21 - unless we (re-)raise, the first line instantiates a
22 :class:`~datalad.support.exceptions.CapturedException`::
23
24 except Exception as e:
25 ce = CapturedException(e)
26
27 First, this ensures a low-level (8) log entry including the traceback of that
28 exception. The depth of the included traceback can be limited by setting the
29 ``datalad.exc.str.tb_limit`` config accordingly.
30
31 Second, it deletes the frame stack references of the exception and keeps
32 textual information only, in order to avoid circular references, where an
33 object (whose method raised the exception) isn't going to be picked by the
34 garbage collection. This can be particularly troublesome if that object holds
35 a reference to a subprocess for example. However, it's not easy to see in what
36 situation this would really be needed and we never need anything other than
37 the textual information about what happened. Making the reference cleaning a
38 general rule is easiest to write, maintain and review.
39
40 - if we raise, neither a log entry nor such a
41 :class:`~datalad.support.exceptions.CapturedException` instance is to be
42 created.
43 Eventually, there will be a spot where that (re-)raised exception is caught.
44 This then is the right place to log it. That log entry will have the
45 traceback, there's no need to leave a trace by means of log messages!
46
47 - if we raise, but do not simply reraise that exact same exception, in order to
48 change the exception class and/or its message, ``raise from`` must be used!::
49
50 except SomeError as e:
51 raise NewError("new message") from e
52
53 This ensures that the original exception is properly registered as the cause
54 for the exception via its ``__cause__`` attribute. Hence, the original
55 exception's traceback will be part of the later on logged traceback of the new
56 exception.
57
58
59 Messaging about an exception
60 ============================
61
62 In addition to the auto-generated low-level log entry there might be a need to
63 create a higher-level log, a user message or a (result) dictionary that includes
64 information from that exception. While such messaging may use anything the
65 (captured) exception provides, please consider that "technical" details about an
66 exception are already auto-logged and generally not incredibly meaningful for
67 users.
68
69 For message creation :class:`~datalad.support.exceptions.CapturedException`
70 comes with a couple of ``format_*`` helper methods, its ``__str__`` provides a
71 short representation of the form ``ExceptionClass(message)`` and its
72 ``__repr__`` the log form with a traceback that is used for the auto-generated
73 log.
74
75 For result dictionaries :class:`~datalad.support.exceptions.CapturedException`
76 can be assigned to the field ``exception``. Currently, ``get_status_dict`` will
77 consider this field and create an additional field with a traceback string.
78 Hence, whether putting a captured exception into that field actually has an
79 effect depends on whether ``get_status_dict`` is subsequently used with that
80 dictionary. In the future such functionality may move into result renderers
81 instead, leaving the decision of what to do with the passed
82 :class:`~datalad.support.exceptions.CapturedException` to them. Therefore, even
83 if of no immediate effect, enhancing the result dicts accordingly makes sense
84 already, since it may be useful when using datalad via its python interface
85 already and provide instant benefits whenever the result rendering gets such an
86 upgrade.