Example usage

>>>try:...raiseTypeError('bad type')...exceptExceptionase:...e.add_note('Add some information')...raise...Traceback (most recent call last):  File"<stdin>", line2, in<module>TypeError:bad typeAdd some information>>>

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

fromhypothesisimportgiven,strategiesasst,target@given(st.integers())deftest(x):assertx<0assertx>0+ExceptionGroupTraceback(mostrecentcalllast):|File"test.py",line4,intest|deftest(x):||File"hypothesis/core.py",line1202,inwrapped_test|raisethe_error_hypothesis_found|^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|ExceptionGroup:Hypothesisfound2distinctfailures.+-+----------------1----------------|Traceback(mostrecentcalllast):|File"test.py",line6,intest|assertx>0|^^^^^^^^^^^^|AssertionError:assert-1>0||Falsifyingexample:test(|x=-1,|)+----------------2----------------|Traceback(mostrecentcalllast):|File"test.py",line5,intest|assertx<0|^^^^^^^^^^^^|AssertionError:assert0<0||Falsifyingexample:test(|x=0,|)+------------------------------------

Non-goals

Tracking multiple notes as a list, rather than by concatenating strings whennotes are added, is intended to maintain the distinction between theindividual notes. This might be required in specialized use cases, suchas translation of the notes by packages likefriendly-traceback.

However,__notes__ isnot intended to carry structured data. If yournote is for use by a program rather than display to a human,we recommendinstead (or additionally) choosing a convention for an attribute, e.g.err._parse_errors=... on the error orExceptionGroup.

As a rule of thumb, we suggest that you should preferexception chaining when theerror 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 orare collecting multiple exception objects to handle together.[1]

Useprint() (orlogging, etc.)

Reporting explanatory or contextual information about an error by printing orlogging has historically been an acceptable workaround. However, we dislikethe 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 towhich error. The newExceptionGroup type intensifies these existingchallenges.

Keeping the__notes__ attached to the exception object, in the same way asthe__traceback__ attribute, eliminates these problems.

raiseWrapper(explanation)fromerr

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

First, it changes the type of the exception, which is often a breaking changefor downstream code. We consideralways raising aWrapper exceptionunacceptably inelegant; but because custom exception types might have anynumber of required arguments we can’t always create an instance of thesametype with our explanation. In cases where the exact exception type is knownthis can work, such as the standard libraryhttp.clientcode,but not for libraries which call user code.

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

classExplanation(Exception):def__str__(self):return"\n"+str(self.args[0])try:raiseAssertionError("Failed!")exceptExceptionase:raiseExplanation("You can reproduce this error by ...")frome

$ python example.pyTraceback (most recent call last):File "example.py", line 6, in <module>    raise AssertionError(why)AssertionError: Failed!                                                    # These lines areThe above exception was the direct cause of ...     # confusing for new                                                    # users, and theyTraceback (most recent call last):                  # only exist dueFile "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 exceptionchaining rather than__notes__.

An assignable__note__ attribute

The first draft and implementation of this PEP defined a single attribute__note__, which defaulted toNone 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 bylibraries such asfriendly-traceback, without resorting to dubious parsingheuristics, 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 Pythonintraceback.py. To geterr.__notes__ printed from a downstreamimplementation wouldalso require writing custom traceback-printing code;while this could be shared between projects and reuse some pieces oftraceback.py[3] we prefer to implement this once, upstream.

Custom exception types could implement their__str__ method to include ourproposed__notes__ semantics, but this would be rarely and inconsistentlyapplicable.

Don’t attach notes toExceptions, just store them inExceptionGroups

The initial motivation for this PEP was to associate a note with each errorin anExceptionGroup. At the cost of a remarkably awkward API and thecross-referencing problem discussedabove, thisuse-case could be supported by storing notes on theExceptionGroupinstance 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 functioncontextlib.add_exc_note()

Itwas suggestedthat we add a utility such as the one below to the standard library. We do notsee this idea as core to the proposal of this PEP, and thus leave it for lateror downstream implementation - perhaps based on this example code:

@contextlib.contextmanagerdefadd_exc_note(note:str):try:yieldexceptExceptionaserr:err.add_note(note)raisewithadd_exc_note(f"While attempting to frobnicate{item=}"):frobnicate_or_raise(item)

Augment theraise statement

One discussion proposedraiseException()with"notecontents", but thisdoes not address the original motivation of compatibility withExceptionGroup.

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