Description
All exception objects (instances of BaseException
) have the following12 unique attributes:
__cause__
__context__
__suppress_context__
__traceback__
__notes__
(only set ifexc.add_note()
was called)args
The Problem
The documentation doesn't have a good place to go to find out what attributes to expect on exception objects. There are some explicit enumerations on the Built-in Exceptions page for specific exception types (e.g. ImportError
), which is fine (see below), as well as one-off mentions of individual attributes spread around the docs, but no one place to go if you are asking "what attributes do exceptions have"?
The closest we have is the attribute list for traceback.TracebackException
.
Here's what I've found in the docs currently:
- https://docs.python.org/3.12/library/traceback.html
__traceback__
- mentioned at the top__traceback__
- used in examples__traceback__
- implies thatTracebackException.stack
(ergoStackSummary
/FrameSummary
) is a substitute__cause__
- mentions it's involved with exception chaining__cause__
- describes a correspondingTracebackExeption
attr__context__
- mentions it's involved with exception chaining__context__
- describes a correspondingTracebackExeption
attr__suppress_context__
- describes a correspondingTracebackExeption
attr__notes__
- describes a correspondingTracebackException
attr- talks about the relationship between
__cause__
,__context__
, and__suppress_context__
- indicates how
__cause__
and__context__
relate to exception formatting (e.g.sys.excepthook()
)
- https://docs.python.org/3.12/library/exceptions.html
__cause__
- explains how this gets set__context__
- explains how this gets set__suppress_context__
- explains what this is for- explains the relationship between
__cause__
,__context__
, and__suppress_context__
__traceback__
- explains how to use a legacy way of setting the traceback from Python codeargs
- explains how this gets set- explains (twice) how
__traceback__
,__cause__
,__context__
, and__notes__
are propagated toExceptionGroup
subgroups
- https://docs.python.org/3.12/reference/simple_stmts.html
- https://docs.python.org/3.12/reference/datamodel.html
__traceback__
- explains how it is set when exception unwinding hits an exception handler
- https://docs.python.org/3.12/reference/expressions.html
__traceback__
- explains how to replace the traceback on an exception thrown into a generator
- https://docs.python.org/3.12/library/types.html
__traceback__
- mentions that traceback objects can be found there
- https://docs.python.org/3.12/library/dis.html
__cause__
-RAISE_VARARGS
sets it forraise exc1 from exc2
- https://docs.python.org/3.12/c-api/exceptions.html
Like I said, if you want the full picture then currently you have to piece things together.
Furthermore, the following details are not clearly specified (unless I missed something):
- does
raise exc
only support exceptions? - must
__cause__
be an exception? - must
__context__
be an exception? - must
__traceback__
be aTracebackType
object? - what breaks if
__notes__
was set to a string? to something other than a list? - ...
Expectations
Without having given it much deep thought, I'd expect the following:
- an entry in the language reference detailing the interface all exceptions (i.e.
BaseException
) are expected to satisfy - a note in https://docs.python.org/3.12/library/exceptions.html pointing to that entry
- the various other places that currently provide details about these attributes should point to the language reference entry instead
Additionally, the following might be worth doing:
- a table in https://docs.python.org/3.12/library/exceptions.html indicating which builtin exception types have which attributes
- a link in https://docs.python.org/3.12/library/types.html to the language reference entry
Prior art for detailing attributes of core types includes work we did a while back for the import system, both related to modules and importers.
Also see:
- Missing Signature Info for Builtin Exceptions in help() and Docs #111405
- https://peps.python.org/pep-3134/
Activity
[-]The Attributes of Exception Objects are Clearly Documented and Easily Discoverable[/-][+]The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable[/+]Lincoln-developer commentedon Nov 16, 2023
Hey, kindly I would love to work on this issue if you don't mind. Thanks.