diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 5c0e261b90763c..9a04b56947a1bb 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -218,7 +218,7 @@ The module also defines the following classes: :class:`TracebackException` objects are created from actual exceptions to capture data for later printing in a lightweight fashion. -.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False) +.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10) Capture an exception for later rendering. *limit*, *lookup_lines* and *capture_locals* are as for the :class:`StackSummary` class. @@ -230,6 +230,12 @@ capture data for later printing in a lightweight fashion. Note that when locals are captured, they are also shown in the traceback. + *max_group_width* and *max_group_depth* control the formatting of exception + groups (see :exc:`BaseExceptionGroup`). The depth refers to the nesting + level of the group, and the width refers to the size of a single exception + group's exceptions array. The formatted output is truncated when either + limit is exceeded. + .. attribute:: __cause__ A :class:`TracebackException` of the original ``__cause__``. @@ -238,6 +244,14 @@ capture data for later printing in a lightweight fashion. A :class:`TracebackException` of the original ``__context__``. + .. attribute:: exceptions + + If ``self`` represents an :exc:`ExceptionGroup`, this field holds a list of + :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. @@ -323,6 +337,9 @@ capture data for later printing in a lightweight fashion. .. versionchanged:: 3.10 Added the *compact* parameter. + .. versionchanged:: 3.11 + Added the *max_group_width* and *max_group_depth* parameters. + :class:`StackSummary` Objects ----------------------------- diff --git a/Lib/traceback.py b/Lib/traceback.py index 419f6e81b5e1be..0ea77bfb94612e 100644 --- a/Lib/traceback.py +++ b/Lib/traceback.py @@ -658,6 +658,8 @@ class TracebackException: - :attr:`__cause__` A TracebackException of the original *__cause__*. - :attr:`__context__` A TracebackException of the original *__context__*. + - :attr:`exceptions` For exception groups - a list of TracebackException + instances for the nested *exceptions*. ``None`` for other exceptions. - :attr:`__suppress_context__` The *__suppress_context__* value from the original exception. - :attr:`stack` A `StackSummary` representing the traceback. diff --git a/Misc/NEWS.d/next/Documentation/2023-05-28-21-01-00.gh-issue-89455.qAKRrA.rst b/Misc/NEWS.d/next/Documentation/2023-05-28-21-01-00.gh-issue-89455.qAKRrA.rst new file mode 100644 index 00000000000000..fdfa4357f001b5 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2023-05-28-21-01-00.gh-issue-89455.qAKRrA.rst @@ -0,0 +1,3 @@ +Add missing documentation for the ``max_group_depth`` and ``max_group_width`` +parameters and the ``exceptions`` attribute of the +:class:`traceback.TracebackException` class.