Example usage

>>> try:
...     raise TypeError('bad type')
... except Exception as e:
...     e.add_note('Add some information')
...     raise
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
TypeError: bad type
Add some information
>>>

When collecting exceptions into an exception group, we may want to add context information for the individual errors. In the following example with Hypothesis’ proposed support for ExceptionGroup, each exception includes a note of the minimal failing example:

from hypothesis import given, strategies as st, target

@given(st.integers())
def test(x):
    assert x < 0
    assert x > 0


+ Exception Group Traceback (most recent call last):
|   File "test.py", line 4, in test
|     def test(x):
|
|   File "hypothesis/core.py", line 1202, in wrapped_test
|     raise the_error_hypothesis_found
|     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| ExceptionGroup: Hypothesis found 2 distinct failures.
+-+---------------- 1 ----------------
    | Traceback (most recent call last):
    |   File "test.py", line 6, in test
    |     assert x > 0
    |     ^^^^^^^^^^^^
    | AssertionError: assert -1 > 0
    |
    | Falsifying example: test(
    |     x=-1,
    | )
    +---------------- 2 ----------------
    | Traceback (most recent call last):
    |   File "test.py", line 5, in test
    |     assert x < 0
    |     ^^^^^^^^^^^^
    | AssertionError: assert 0 < 0
    |
    | Falsifying example: test(
    |     x=0,
    | )
    +------------------------------------

Non-goals

Tracking multiple notes as a list, rather than by concatenating strings when notes are added, is intended to maintain the distinction between the individual notes. This might be required in specialized use cases, such as translation of the notes by packages like friendly-traceback.

However, __notes__ is not intended to carry structured data. If your note is for use by a program rather than display to a human, we recommend instead (or additionally) choosing a convention for an attribute, e.g. err._parse_errors = ... on the error or ExceptionGroup.

As a rule of thumb, we suggest that you should prefer exception chaining when the error is going to be re-raised or handled as an individual error, and prefer .add_note() when you want to avoid changing the exception type or are collecting multiple exception objects to handle together. [1]

Use print() (or logging, etc.)

Reporting explanatory or contextual information about an error by printing or logging has historically been an acceptable workaround. However, we dislike the way this separates the content from the exception object it refers to - which can lead to “orphan” reports if the error was caught and handled later, or merely significant difficulties working out which explanation corresponds to which error. The new ExceptionGroup type intensifies these existing challenges.

Keeping the __notes__ attached to the exception object, in the same way as the __traceback__ attribute, eliminates these problems.

raise Wrapper(explanation) from err

An alternative pattern is to use exception chaining: by raising a ‘wrapper’ exception containing the context or explanation from the current exception, we avoid the separation challenges from print(). However, this has two key problems.

First, it changes the type of the exception, which is often a breaking change for downstream code. We consider always raising a Wrapper exception unacceptably inelegant; but because custom exception types might have any number of required arguments we can’t always create an instance of the same type with our explanation. In cases where the exact exception type is known this can work, such as the standard library http.client code, but not for libraries which call user code.

Second, exception chaining reports several lines of additional detail, which are distracting for experienced users and can be very confusing for beginners. For example, six of the eleven lines reported for this simple example relate to exception chaining, and are unnecessary with BaseException.add_note():

class Explanation(Exception):
    def __str__(self):
        return "\n" + str(self.args[0])

try:
    raise AssertionError("Failed!")
except Exception as e:
    raise Explanation("You can reproduce this error by ...") from e

$ python example.py
Traceback (most recent call last):
File "example.py", line 6, in <module>
    raise AssertionError(why)
AssertionError: Failed!
                                                    # These lines are
The above exception was the direct cause of ...     # confusing for new
                                                    # users, and they
Traceback (most recent call last):                  # only exist due
File "example.py", line 8, in <module>              # to implementation
    raise Explanation(msg) from e                   # constraints :-(
Explanation:                                        # Hence this PEP!
You can reproduce this error by ...

In cases where these two problems do not apply, we encourage use of exception chaining rather than __notes__.

An assignable __note__ attribute

The first draft and implementation of this PEP defined a single attribute __note__, which defaulted to None but could have a string assigned. This is substantially simpler if, and only if, there is at most one note.

To promote interoperability and support translation of error messages by libraries such as friendly-traceback, without resorting to dubious parsing heuristics, we therefore settled on the .add_note()-and-__notes__ API.

Subclass Exception and add note support downstream

Traceback printing is built into the C code, and reimplemented in pure Python in traceback.py. To get err.__notes__ printed from a downstream implementation would also require writing custom traceback-printing code; while this could be shared between projects and reuse some pieces of traceback.py [3] we prefer to implement this once, upstream.

Custom exception types could implement their __str__ method to include our proposed __notes__ semantics, but this would be rarely and inconsistently applicable.

Don’t attach notes to Exceptions, just store them in ExceptionGroups

The initial motivation for this PEP was to associate a note with each error in an ExceptionGroup. At the cost of a remarkably awkward API and the cross-referencing problem discussed above, this use-case could be supported by storing notes on the ExceptionGroup instance instead of on each exception it contains.

We believe that the cleaner interface, and other use-cases described above, are sufficient to justify the more general feature proposed by this PEP.

Add a helper function contextlib.add_exc_note()

It was suggested that we add a utility such as the one below to the standard library. We do not see this idea as core to the proposal of this PEP, and thus leave it for later or downstream implementation - perhaps based on this example code:

@contextlib.contextmanager
def add_exc_note(note: str):
    try:
        yield
    except Exception as err:
        err.add_note(note)
        raise

with add_exc_note(f"While attempting to frobnicate {item=}"):
    frobnicate_or_raise(item)

Augment the raise statement

One discussion proposed raise Exception() with "note contents", but this does not address the original motivation of compatibility with ExceptionGroup.

Furthermore, we do not believe that the problem we are solving requires or justifies new language syntax.