| 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. |