From c44e52c4dd8f461a88841f1a1f072585f6e7ee58 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 13 Dec 2023 14:55:14 +0000 Subject: [PATCH 1/5] Improve docs on exception attributes --- Doc/c-api/exceptions.rst | 16 +++--- Doc/library/exceptions.rst | 91 +++++++++++++++++++++------------- Doc/library/traceback.rst | 28 +++++++---- Doc/reference/datamodel.rst | 3 +- Doc/reference/simple_stmts.rst | 22 +++++--- Doc/whatsnew/3.0.rst | 11 ++-- 6 files changed, 105 insertions(+), 66 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index a3a63b38c432f2..b1224956941d17 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -541,7 +541,8 @@ Querying the error indicator .. note:: - This function *does not* implicitly set the ``__traceback__`` + This function *does not* implicitly set the + :attr:`~BaseException.__traceback__` attribute on the exception value. If setting the traceback appropriately is desired, the following additional snippet is needed:: @@ -753,7 +754,8 @@ Exception Objects .. c:function:: PyObject* PyException_GetTraceback(PyObject *ex) Return the traceback associated with the exception as a new reference, as - accessible from Python through :attr:`__traceback__`. If there is no + accessible from Python through :attr:`~BaseException.__traceback__`. + If there is no traceback associated, this returns ``NULL``. @@ -767,8 +769,8 @@ Exception Objects Return the context (another exception instance during whose handling *ex* was raised) associated with the exception as a new reference, as accessible from - Python through :attr:`__context__`. If there is no context associated, this - returns ``NULL``. + Python through :attr:`~BaseException.__context__`. If there is no context + associated, this returns ``NULL``. .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) @@ -782,7 +784,8 @@ Exception Objects Return the cause (either an exception instance, or ``None``, set by ``raise ... from ...``) associated with the exception as a new - reference, as accessible from Python through :attr:`__cause__`. + reference, as accessible from Python through + :attr:`~BaseException.__cause__`. .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause) @@ -791,7 +794,8 @@ Exception Objects it. There is no type check to make sure that *cause* is either an exception instance or ``None``. This steals a reference to *cause*. - :attr:`__suppress_context__` is implicitly set to ``True`` by this function. + :attr:~BaseException.`__suppress_context__` is implicitly set to ``True`` by + this function. .. c:function:: PyObject* PyException_GetArgs(PyObject *ex) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index b67215b8b3a362..1bb79838967c80 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -38,36 +38,45 @@ information on defining exceptions is available in the Python Tutorial under Exception context ----------------- -When raising a new exception while another exception -is already being handled, the new exception's -:attr:`__context__` attribute is automatically set to the handled -exception. An exception may be handled when an :keyword:`except` or -:keyword:`finally` clause, or a :keyword:`with` statement, is used. - -This implicit exception context can be -supplemented with an explicit cause by using :keyword:`!from` with -:keyword:`raise`:: - - raise new_exc from original_exc - -The expression following :keyword:`from` must be an exception or ``None``. It -will be set as :attr:`__cause__` on the raised exception. Setting -:attr:`__cause__` also implicitly sets the :attr:`__suppress_context__` -attribute to ``True``, so that using ``raise new_exc from None`` -effectively replaces the old exception with the new one for display -purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), while -leaving the old exception available in :attr:`__context__` for introspection -when debugging. - -The default traceback display code shows these chained exceptions in -addition to the traceback for the exception itself. An explicitly chained -exception in :attr:`__cause__` is always shown when present. An implicitly -chained exception in :attr:`__context__` is shown only if :attr:`__cause__` -is :const:`None` and :attr:`__suppress_context__` is false. - -In either case, the exception itself is always shown after any chained -exceptions so that the final line of the traceback always shows the last -exception that was raised. +.. index:: pair: exception; chaining + __cause__ (exception attribute) + __context__ (exception attribute) + __suppress_context__ (exception attribute) + +.. attribute:: BaseException.__context__ + BaseException.__cause__ + BaseException.__suppress_context__ + + When raising a new exception while another exception + is already being handled, the new exception's + :attr:`__context__` attribute is automatically set to the handled + exception. An exception may be handled when an :keyword:`except` or + :keyword:`finally` clause, or a :keyword:`with` statement, is used. + + This implicit exception context can be + supplemented with an explicit cause by using :keyword:`!from` with + :keyword:`raise`:: + + raise new_exc from original_exc + + The expression following :keyword:`from` must be an exception or ``None``. It + will be set as :attr:`!__cause__` on the raised exception. Setting + :attr:!`__cause__` also implicitly sets the :attr:`!__suppress_context__` + attribute to ``True``, so that using ``raise new_exc from None`` + effectively replaces the old exception with the new one for display + purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), while + leaving the old exception available in :attr:`!__context__` for introspection + when debugging. + + The default traceback display code shows these chained exceptions in + addition to the traceback for the exception itself. An explicitly chained + exception in :attr:`!__cause__` is always shown when present. An implicitly + chained exception in :attr:`!__context__` is shown only if :attr:`!__cause__` + is :const:`None` and :attr:`!__suppress_context__` is false. + + In either case, the exception itself is always shown after any chained + exceptions so that the final line of the traceback always shows the last + exception that was raised. Inheriting from built-in exceptions @@ -126,6 +135,12 @@ The following exceptions are used mostly as base classes for other exceptions. tb = sys.exception().__traceback__ raise OtherException(...).with_traceback(tb) + .. attribute:: __traceback__ + + A writable field that holds the + :ref:`traceback object ` associated with this + exception. See also :ref:`raise`. + .. method:: add_note(note) Add the string ``note`` to the exception's notes which appear in the standard @@ -929,8 +944,10 @@ their subgroups based on the types of the contained exceptions. true for the exceptions that should be in the subgroup. The nesting structure of the current exception is preserved in the result, - as are the values of its :attr:`message`, :attr:`__traceback__`, - :attr:`__cause__`, :attr:`__context__` and :attr:`__notes__` fields. + as are the values of its :attr:`message`, + :attr:`~BaseException.__traceback__`, :attr:`~BaseException.__cause__`, + :attr:`~BaseException.__context__` and + :attr:`~BaseException.__notes__` fields. Empty nested groups are omitted from the result. The condition is checked for all exceptions in the nested exception group, @@ -956,10 +973,14 @@ their subgroups based on the types of the contained exceptions. and :meth:`split` return instances of the subclass rather than :exc:`ExceptionGroup`. - :meth:`subgroup` and :meth:`split` copy the :attr:`__traceback__`, - :attr:`__cause__`, :attr:`__context__` and :attr:`__notes__` fields from + :meth:`subgroup` and :meth:`split` copy the + :attr:`~BaseException.__traceback__`, + :attr:`~BaseException.__cause__`, :attr:`~BaseException.__context__` and + :attr:`~BaseException.__notes__` fields from the original exception group to the one returned by :meth:`derive`, so - these fields do not need to be updated by :meth:`derive`. :: + these fields do not need to be updated by :meth:`derive`. + + .. doctest:: >>> class MyGroup(ExceptionGroup): ... def derive(self, excs): diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 14cade690fc773..a8f6d16d91cf66 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -67,7 +67,8 @@ The module defines the following functions: The optional *limit* argument has the same meaning as for :func:`print_tb`. If *chain* is true (the default), then chained exceptions (the - :attr:`__cause__` or :attr:`__context__` attributes of the exception) will be + :attr:`~BaseException.__cause__` or :attr:`~BaseException.__context__` + attributes of the exception) will be printed as well, like the interpreter itself does when printing an unhandled exception. @@ -234,10 +235,11 @@ capture data for later printing in a lightweight fashion. Capture an exception for later rendering. *limit*, *lookup_lines* and *capture_locals* are as for the :class:`StackSummary` class. - If *compact* is true, only data that is required by :class:`TracebackException`'s + If *compact* is true, only data that is required by + :class:`!TracebackException`'s ``format`` method is saved in the class attributes. In particular, the - ``__context__`` field is calculated only if ``__cause__`` is ``None`` and - ``__suppress_context__`` is false. + :attr:`__context__` field is calculated only if :attr:`__cause__` is + ``None`` and :attr:`__suppress_context__` is false. Note that when locals are captured, they are also shown in the traceback. @@ -255,27 +257,31 @@ capture data for later printing in a lightweight fashion. .. attribute:: __cause__ - A :class:`TracebackException` of the original ``__cause__``. + A :class:`!TracebackException` of the original + :attr:`~BaseException.__cause__`. .. attribute:: __context__ - A :class:`TracebackException` of the original ``__context__``. + A :class:`!TracebackException` of the original + :attr`~BaseException.__context__`. .. attribute:: exceptions If ``self`` represents an :exc:`ExceptionGroup`, this field holds a list of - :class:`TracebackException` instances representing the nested exceptions. + :class:`!TracebackException` instances representing the nested exceptions. Otherwise it is ``None``. .. versionadded:: 3.11 .. attribute:: __suppress_context__ - The ``__suppress_context__`` value from the original exception. + The :attr:`~BaseException.__suppress_context__` value from the original + exception. .. attribute:: __notes__ - The ``__notes__`` value from the original exception, or ``None`` + The :attr:`~BaseException.__notes__` value from the original exception, + or ``None`` if the exception does not have any notes. If it is not ``None`` is it formatted in the traceback after the exception string. @@ -349,8 +355,8 @@ capture data for later printing in a lightweight fashion. Format the exception. - If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not - be formatted. + If *chain* is not ``True``, :attr:`__cause__` and :attr:`__context__` + will not be formatted. The return value is a generator of strings, each ending in a newline and some containing internal newlines. :func:`~traceback.print_exception` diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 16ee3e300c2b8b..5e3757e1f5c6f6 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1390,7 +1390,8 @@ unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section :ref:`try`.) It is accessible as the third item of the -tuple returned by :func:`sys.exc_info`, and as the ``__traceback__`` attribute +tuple returned by :func:`sys.exc_info`, and as the +:attr:`~BaseException.__traceback__` attribute of the caught exception. When the program contains no suitable diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a9e65be1eda340..a8b62f4672c8fc 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -578,7 +578,7 @@ The :dfn:`type` of the exception is the exception instance's class, the .. index:: pair: object; traceback A traceback object is normally created automatically when an exception is raised -and attached to it as the :attr:`__traceback__` attribute, which is writable. +and attached to it as the :attr:`~BaseException.__traceback__` attribute. You can create an exception and set your own traceback in one step using the :meth:`~BaseException.with_traceback` exception method (which returns the same exception instance, with its traceback set to its argument), like so:: @@ -592,11 +592,13 @@ same exception instance, with its traceback set to its argument), like so:: The ``from`` clause is used for exception chaining: if given, the second *expression* must be another exception class or instance. If the second expression is an exception instance, it will be attached to the raised -exception as the :attr:`__cause__` attribute (which is writable). If the +exception as the :attr:`~BaseException.__cause__` attribute (which is writable). If the expression is an exception class, the class will be instantiated and the resulting exception instance will be attached to the raised exception as the -:attr:`__cause__` attribute. If the raised exception is not handled, both -exceptions will be printed:: +:attr:!`__cause__` attribute. If the raised exception is not handled, both +exceptions will be printed: + +.. doctest:: >>> try: ... print(1 / 0) @@ -617,7 +619,9 @@ A similar mechanism works implicitly if a new exception is raised when an exception is already being handled. An exception may be handled when an :keyword:`except` or :keyword:`finally` clause, or a :keyword:`with` statement, is used. The previous exception is then -attached as the new exception's :attr:`__context__` attribute:: +attached as the new exception's :attr:`~BaseException.__context__` attribute: + +.. doctest:: >>> try: ... print(1 / 0) @@ -635,7 +639,9 @@ attached as the new exception's :attr:`__context__` attribute:: RuntimeError: Something bad happened Exception chaining can be explicitly suppressed by specifying :const:`None` in -the ``from`` clause:: +the ``from`` clause: + +.. doctest:: >>> try: ... print(1 / 0) @@ -653,8 +659,8 @@ and information about handling exceptions is in section :ref:`try`. :const:`None` is now permitted as ``Y`` in ``raise X from Y``. .. versionadded:: 3.3 - The ``__suppress_context__`` attribute to suppress automatic display of the - exception context. + The :attr:`~BaseException.__suppress_context__` attribute to suppress + automatic display of the exception context. .. versionchanged:: 3.11 If the traceback of the active exception is modified in an :keyword:`except` diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index 5953b32c6aaa18..89e12062abaddd 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -711,7 +711,7 @@ new powerful features added: {Exception}({args})` instead of :samp:`raise {Exception}, {args}`. Additionally, you can no longer explicitly specify a traceback; instead, if you *have* to do this, you can assign directly to the - :attr:`__traceback__` attribute (see below). + :attr:`~BaseException.__traceback__` attribute (see below). * :pep:`3110`: Catching exceptions. You must now use :samp:`except {SomeException} as {variable}` instead @@ -725,7 +725,7 @@ new powerful features added: handler block. This usually happens due to a bug in the handler block; we call this a *secondary* exception. In this case, the original exception (that was being handled) is saved as the - :attr:`__context__` attribute of the secondary exception. + :attr:`~BaseException.__context__` attribute of the secondary exception. Explicit chaining is invoked with this syntax:: raise SecondaryException() from primary_exception @@ -733,14 +733,15 @@ new powerful features added: (where *primary_exception* is any expression that produces an exception object, probably an exception that was previously caught). In this case, the primary exception is stored on the - :attr:`__cause__` attribute of the secondary exception. The + :attr:`~BaseException.__cause__` attribute of the secondary exception. The traceback printed when an unhandled exception occurs walks the chain - of :attr:`__cause__` and :attr:`__context__` attributes and prints a + of :attr:`!__cause__` and :attr:`~BaseException.__context__` attributes and + prints a separate traceback for each component of the chain, with the primary exception at the top. (Java users may recognize this behavior.) * :pep:`3134`: Exception objects now store their traceback as the - :attr:`__traceback__` attribute. This means that an exception + :attr:`~BaseException.__traceback__` attribute. This means that an exception object now contains all the information pertaining to an exception, and there are fewer reasons to use :func:`sys.exc_info` (though the latter is not removed). From 9aeb6a4aede1df0cced95ef12aa27fc083f73cfa Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 13 Dec 2023 14:59:16 +0000 Subject: [PATCH 2/5] thanks sphinx-lint --- Doc/c-api/exceptions.rst | 2 +- Doc/library/exceptions.rst | 2 +- Doc/library/traceback.rst | 2 +- Doc/reference/simple_stmts.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index b1224956941d17..0e170a974a26ba 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -794,7 +794,7 @@ Exception Objects it. There is no type check to make sure that *cause* is either an exception instance or ``None``. This steals a reference to *cause*. - :attr:~BaseException.`__suppress_context__` is implicitly set to ``True`` by + :attr:`~BaseException.__suppress_context__` is implicitly set to ``True`` by this function. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 1bb79838967c80..4fc32293c54a28 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -61,7 +61,7 @@ Exception context The expression following :keyword:`from` must be an exception or ``None``. It will be set as :attr:`!__cause__` on the raised exception. Setting - :attr:!`__cause__` also implicitly sets the :attr:`!__suppress_context__` + :attr:`!__cause__` also implicitly sets the :attr:`!__suppress_context__` attribute to ``True``, so that using ``raise new_exc from None`` effectively replaces the old exception with the new one for display purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`), while diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index a8f6d16d91cf66..22a90438c4337f 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -263,7 +263,7 @@ capture data for later printing in a lightweight fashion. .. attribute:: __context__ A :class:`!TracebackException` of the original - :attr`~BaseException.__context__`. + :attr:`~BaseException.__context__`. .. attribute:: exceptions diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a8b62f4672c8fc..de9fbc87743421 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -595,7 +595,7 @@ expression is an exception instance, it will be attached to the raised exception as the :attr:`~BaseException.__cause__` attribute (which is writable). If the expression is an exception class, the class will be instantiated and the resulting exception instance will be attached to the raised exception as the -:attr:!`__cause__` attribute. If the raised exception is not handled, both +:attr:`!__cause__` attribute. If the raised exception is not handled, both exceptions will be printed: .. doctest:: From f0ab2370d7a14cc2d3938a68d21b590d5b4a360a Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 13 Dec 2023 15:56:08 +0000 Subject: [PATCH 3/5] fix doctests --- Doc/reference/simple_stmts.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a8b62f4672c8fc..755fb156d0ee8e 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -607,12 +607,15 @@ exceptions will be printed: ... Traceback (most recent call last): File "", line 2, in + print(1 / 0) + ~~^~~ ZeroDivisionError: division by zero - + The above exception was the direct cause of the following exception: - + Traceback (most recent call last): File "", line 4, in + raise RuntimeError("Something bad happened") from exc RuntimeError: Something bad happened A similar mechanism works implicitly if a new exception is raised when @@ -630,12 +633,15 @@ attached as the new exception's :attr:`~BaseException.__context__` attribute: ... Traceback (most recent call last): File "", line 2, in + print(1 / 0) + ~~^~~ ZeroDivisionError: division by zero - + During handling of the above exception, another exception occurred: - + Traceback (most recent call last): File "", line 4, in + raise RuntimeError("Something bad happened") RuntimeError: Something bad happened Exception chaining can be explicitly suppressed by specifying :const:`None` in From 991d35ef1091a0557ad3283371ecd2ac049c46f6 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 13 Dec 2023 16:06:28 +0000 Subject: [PATCH 4/5] argh, okay, give up on doctests --- Doc/reference/simple_stmts.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 59dabe8bbe077f..34c3a620b87223 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -598,7 +598,7 @@ resulting exception instance will be attached to the raised exception as the :attr:`!__cause__` attribute. If the raised exception is not handled, both exceptions will be printed: -.. doctest:: +.. code-block:: pycon >>> try: ... print(1 / 0) @@ -610,9 +610,9 @@ exceptions will be printed: print(1 / 0) ~~^~~ ZeroDivisionError: division by zero - + The above exception was the direct cause of the following exception: - + Traceback (most recent call last): File "", line 4, in raise RuntimeError("Something bad happened") from exc @@ -624,7 +624,7 @@ when an :keyword:`except` or :keyword:`finally` clause, or a :keyword:`with` statement, is used. The previous exception is then attached as the new exception's :attr:`~BaseException.__context__` attribute: -.. doctest:: +.. code-block:: pycon >>> try: ... print(1 / 0) @@ -636,9 +636,9 @@ attached as the new exception's :attr:`~BaseException.__context__` attribute: print(1 / 0) ~~^~~ ZeroDivisionError: division by zero - + During handling of the above exception, another exception occurred: - + Traceback (most recent call last): File "", line 4, in raise RuntimeError("Something bad happened") From 7bd05a57de51c0d45f82d885a05f8980ca8662cc Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 13 Dec 2023 17:07:39 +0000 Subject: [PATCH 5/5] Various improvements --- Doc/c-api/exceptions.rst | 16 ++++++++-------- Doc/library/exceptions.rst | 7 +++++-- Doc/library/traceback.rst | 4 ++-- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 0e170a974a26ba..284a9c71e420da 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -754,8 +754,8 @@ Exception Objects .. c:function:: PyObject* PyException_GetTraceback(PyObject *ex) Return the traceback associated with the exception as a new reference, as - accessible from Python through :attr:`~BaseException.__traceback__`. - If there is no + accessible from Python through the :attr:`~BaseException.__traceback__` + attribute. If there is no traceback associated, this returns ``NULL``. @@ -769,8 +769,8 @@ Exception Objects Return the context (another exception instance during whose handling *ex* was raised) associated with the exception as a new reference, as accessible from - Python through :attr:`~BaseException.__context__`. If there is no context - associated, this returns ``NULL``. + Python through the :attr:`~BaseException.__context__` attribute. + If there is no context associated, this returns ``NULL``. .. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) @@ -784,8 +784,8 @@ Exception Objects Return the cause (either an exception instance, or ``None``, set by ``raise ... from ...``) associated with the exception as a new - reference, as accessible from Python through - :attr:`~BaseException.__cause__`. + reference, as accessible from Python through the + :attr:`~BaseException.__cause__` attribute. .. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause) @@ -794,8 +794,8 @@ Exception Objects it. There is no type check to make sure that *cause* is either an exception instance or ``None``. This steals a reference to *cause*. - :attr:`~BaseException.__suppress_context__` is implicitly set to ``True`` by - this function. + The :attr:`~BaseException.__suppress_context__` attribute is implicitly set + to ``True`` by this function. .. c:function:: PyObject* PyException_GetArgs(PyObject *ex) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 4fc32293c54a28..04686b6db0036c 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -43,13 +43,16 @@ Exception context __context__ (exception attribute) __suppress_context__ (exception attribute) +Three attributes on exception objects provide information about the context in +which an the exception was raised: + .. attribute:: BaseException.__context__ BaseException.__cause__ BaseException.__suppress_context__ When raising a new exception while another exception is already being handled, the new exception's - :attr:`__context__` attribute is automatically set to the handled + :attr:`!__context__` attribute is automatically set to the handled exception. An exception may be handled when an :keyword:`except` or :keyword:`finally` clause, or a :keyword:`with` statement, is used. @@ -139,7 +142,7 @@ The following exceptions are used mostly as base classes for other exceptions. A writable field that holds the :ref:`traceback object ` associated with this - exception. See also :ref:`raise`. + exception. See also: :ref:`raise`. .. method:: add_note(note) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 22a90438c4337f..dfbd04de243a3c 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -236,8 +236,8 @@ capture data for later printing in a lightweight fashion. *capture_locals* are as for the :class:`StackSummary` class. If *compact* is true, only data that is required by - :class:`!TracebackException`'s - ``format`` method is saved in the class attributes. In particular, the + :class:`!TracebackException`'s :meth:`format` method + is saved in the class attributes. In particular, the :attr:`__context__` field is calculated only if :attr:`__cause__` is ``None`` and :attr:`__suppress_context__` is false.