Transforming python exceptions while preserving the traceback

Sometimes a simple exception isn't enough information to explain what went wrong:

>>> def do_foo():
>>>     pass
>>>
>>>
>>> def do_bar():
>>>     pass
>>>
>>>
>>> dispatch_table = {
>>>     'foo': do_foo,
>>>     'bar': do_bar,
>>> }
>>>
>>> key = 'baz'
>>> result = dispatch_table[key]
Traceback (most recent call last):
  File "foo.py", line 15, in <module>
    result = dispatch_table[key]
KeyError: 'baz'

Presuming that 'baz' was the user's input, we want the user to understand that they have passed in an unsupported/nonexistent command. A KeyError doesn't explain that: it only says a key wasn't found in a dictionary. (And if the user isn't experienced in python, it doesn't even say that!)

A simple solution is to add a message to the raised exception via a try/except block. But this has problems as well:

>>> try:
>>>     result = dispatch_table[key]
>>> except KeyError:
>>>     raise KeyError("Command not found: {}".format(key))
Traceback (most recent call last):
  File "foo.py", line 17, in <module>
    result = dispatch_table[key]
KeyError: 'baz'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "foo.py", line 19, in <module>
    raise KeyError("Command not found: {}".format(key))
KeyError: 'Command not found: baz'

Why two stack traces? Due to how python handles exception chaining, the original exception remains unhandled, so both are raised together. This might actually increase the confusion for the user.

It turns out that in python 3, the raise statement has an optional from clause. From the docs:

Exception chaining can be explicitly suppressed by specifying None in the from clause

...like so:

>>> try:
>>>     result = dispatch_table[key]
>>> except KeyError:
>>>     raise KeyError("Command not found: {}".format(key)) from None
Traceback (most recent call last):
  File "foo.py", line 19, in <module>
    raise KeyError("Command not found: {}".format(key)) from None
KeyError: 'Command not found: baz'

Supressing the stack trace may not be ideal when the user submits this error message in a bug report. Where exactly did it occur? What if we want the original stack trace to be printed with our own preferred exception?

The last piece of the puzzle is the .with_traceback(tb) method:

>>> try:
>>>     result = dispatch_table[key]
>>> except KeyError as ke:
>>>     raise KeyError("Command not found: {}".format(key)).with_traceback(
>>>         ke.__traceback__) from None
Traceback (most recent call last):
  File "foo.py", line 20, in <module>
    ke.__traceback__) from None
  File "foo.py", line 17, in <module>
    result = dispatch_table[key]
KeyError: 'Command not found: baz'

Perfect. The user gets a human-readable error message, and a terse but meaningful stacktrace to submit in a bug report. This works by supressing the chained exception using from None, while attaching its stack trace to the exception we want to raise.

This can work with locally defined exceptions as well:

>>> class InputError(Exception):
>>>    pass
>>>
>>> try:
>>>     result = dispatch_table[key]
>>> except KeyError as ke:
>>>     raise InputError("Command not found: {}".format(key)).with_traceback(
>>>         ke.__traceback__) from None
Traceback (most recent call last):
  File "foo.py", line 24, in <module>
    ke.__traceback__) from None
  File "foo.py", line 21, in <module>
    result = dispatch_table[key]
__main__.InputError: Command not found: baz

rpdelaney/PYTHON_EXCEPTION_TRACEBACKS.md

See also