@@ -38,36 +38,48 @@ information on defining exceptions is available in the Python Tutorial under
3838Exception context
3939-----------------
4040
41- When raising a new exception while another exception
42- is already being handled, the new exception's
43- :attr: `__context__ ` attribute is automatically set to the handled
44- exception. An exception may be handled when an :keyword: `except ` or
45- :keyword: `finally ` clause, or a :keyword: `with ` statement, is used.
46-
47- This implicit exception context can be
48- supplemented with an explicit cause by using :keyword: `!from ` with
49- :keyword: `raise `::
50-
51- raise new_exc from original_exc
52-
53- The expression following :keyword: `from<raise> ` must be an exception or ``None ``. It
54- will be set as :attr: `__cause__ ` on the raised exception. Setting
55- :attr: `__cause__ ` also implicitly sets the :attr: `__suppress_context__ `
56- attribute to ``True ``, so that using ``raise new_exc from None ``
57- effectively replaces the old exception with the new one for display
58- purposes (e.g. converting :exc: `KeyError ` to :exc: `AttributeError `), while
59- leaving the old exception available in :attr: `__context__ ` for introspection
60- when debugging.
61-
62- The default traceback display code shows these chained exceptions in
63- addition to the traceback for the exception itself. An explicitly chained
64- exception in :attr: `__cause__ ` is always shown when present. An implicitly
65- chained exception in :attr: `__context__ ` is shown only if :attr: `__cause__ `
66- is :const: `None ` and :attr: `__suppress_context__ ` is false.
67-
68- In either case, the exception itself is always shown after any chained
69- exceptions so that the final line of the traceback always shows the last
70- exception that was raised.
41+ .. index :: pair: exception; chaining
42+ __cause__ (exception attribute)
43+ __context__ (exception attribute)
44+ __suppress_context__ (exception attribute)
45+
46+ Three attributes on exception objects provide information about the context in
47+ which an the exception was raised:
48+
49+ .. attribute :: BaseException.__context__
50+ BaseException.__cause__
51+ BaseException.__suppress_context__
52+
53+ When raising a new exception while another exception
54+ is already being handled, the new exception's
55+ :attr: `!__context__ ` attribute is automatically set to the handled
56+ exception. An exception may be handled when an :keyword: `except ` or
57+ :keyword: `finally ` clause, or a :keyword: `with ` statement, is used.
58+
59+ This implicit exception context can be
60+ supplemented with an explicit cause by using :keyword: `!from ` with
61+ :keyword: `raise `::
62+
63+ raise new_exc from original_exc
64+
65+ The expression following :keyword: `from<raise> ` must be an exception or ``None ``. It
66+ will be set as :attr: `!__cause__ ` on the raised exception. Setting
67+ :attr: `!__cause__ ` also implicitly sets the :attr: `!__suppress_context__ `
68+ attribute to ``True ``, so that using ``raise new_exc from None ``
69+ effectively replaces the old exception with the new one for display
70+ purposes (e.g. converting :exc: `KeyError ` to :exc: `AttributeError `), while
71+ leaving the old exception available in :attr: `!__context__ ` for introspection
72+ when debugging.
73+
74+ The default traceback display code shows these chained exceptions in
75+ addition to the traceback for the exception itself. An explicitly chained
76+ exception in :attr: `!__cause__ ` is always shown when present. An implicitly
77+ chained exception in :attr: `!__context__ ` is shown only if :attr: `!__cause__ `
78+ is :const: `None ` and :attr: `!__suppress_context__ ` is false.
79+
80+ In either case, the exception itself is always shown after any chained
81+ exceptions so that the final line of the traceback always shows the last
82+ exception that was raised.
7183
7284
7385Inheriting from built-in exceptions
@@ -126,6 +138,12 @@ The following exceptions are used mostly as base classes for other exceptions.
126138 tb = sys.exception().__traceback__
127139 raise OtherException(...).with_traceback(tb)
128140
141+ .. attribute :: __traceback__
142+
143+ A writable field that holds the
144+ :ref: `traceback object <traceback-objects >` associated with this
145+ exception. See also: :ref: `raise `.
146+
129147 .. method :: add_note(note)
130148
131149 Add the string ``note `` to the exception's notes which appear in the standard
@@ -929,8 +947,10 @@ their subgroups based on the types of the contained exceptions.
929947 true for the exceptions that should be in the subgroup.
930948
931949 The nesting structure of the current exception is preserved in the result,
932- as are the values of its :attr: `message `, :attr: `__traceback__ `,
933- :attr: `__cause__ `, :attr: `__context__ ` and :attr: `__notes__ ` fields.
950+ as are the values of its :attr: `message `,
951+ :attr: `~BaseException.__traceback__ `, :attr: `~BaseException.__cause__ `,
952+ :attr: `~BaseException.__context__ ` and
953+ :attr: `~BaseException.__notes__ ` fields.
934954 Empty nested groups are omitted from the result.
935955
936956 The condition is checked for all exceptions in the nested exception group,
@@ -956,10 +976,14 @@ their subgroups based on the types of the contained exceptions.
956976 and :meth: `split ` return instances of the subclass rather
957977 than :exc: `ExceptionGroup `.
958978
959- :meth: `subgroup ` and :meth: `split ` copy the :attr: `__traceback__ `,
960- :attr: `__cause__ `, :attr: `__context__ ` and :attr: `__notes__ ` fields from
979+ :meth: `subgroup ` and :meth: `split ` copy the
980+ :attr: `~BaseException.__traceback__ `,
981+ :attr: `~BaseException.__cause__ `, :attr: `~BaseException.__context__ ` and
982+ :attr: `~BaseException.__notes__ ` fields from
961983 the original exception group to the one returned by :meth: `derive `, so
962- these fields do not need to be updated by :meth: `derive `. ::
984+ these fields do not need to be updated by :meth: `derive `.
985+
986+ .. doctest ::
963987
964988 >>> class MyGroup (ExceptionGroup ):
965989 ... def derive (self excs ):
0 commit comments