You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All exception objects (instances of BaseException) have the following12 unique attributes:
__cause__
__context__
__suppress_context__
__traceback__
__notes__ (only set if exc.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"?
ericsnowcurrently
changed the title
The Attributes of Exception Objects are Clearly Documented and Easily Discoverable
The Attributes of Exception Objects are not Clearly Documented and Easily Discoverable
Nov 9, 2023
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:
__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__cause__
,__context__
, and__suppress_context__
__cause__
and__context__
relate to exception formatting (e.g.sys.excepthook()
)__cause__
- explains how this gets set__context__
- explains how this gets set__suppress_context__
- explains what this is for__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__traceback__
,__cause__
,__context__
, and__notes__
are propagated toExceptionGroup
subgroups__cause__
- explains how this is set viaraise exc1 from exc2
and what caveats apply__context__
- explains how this is set__suppress_context__
- mentions its effect__traceback__
- explains how this is set__traceback__
- explains how it is set when exception unwinding hits an exception handler__traceback__
- explains how to replace the traceback on an exception thrown into a generator__traceback__
- mentions that traceback objects can be found there__cause__
-RAISE_VARARGS
sets it forraise exc1 from exc2
__cause__
- explains how to get and set this__context__
- explains how to get and set this__traceback__
- explains how to get and set thisargs
- explains how to get and set thisLike 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):
raise exc
only support exceptions?__cause__
be an exception?__context__
be an exception?__traceback__
be aTracebackType
object?__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:
BaseException
) are expected to satisfyAdditionally, the following might be worth doing:
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:
Footnotes
Arguably,
msg
ormessage
should also be an attribute ofBaseException
, but that's out of scope for this issue. ↩Some builtin exceptions types have additional specific attributes. See gh-111405. ↩
The text was updated successfully, but these errors were encountered: