mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201)

Browse source
This commit is contained in:
Irit Katriel 2023-09-12 15:54:04 +01:00 • committed by GitHub
parent e121fca33b
commit 0e76cc359b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

42
Doc/library/traceback.rst
View file

@ -139,11 +139,11 @@ The module defines the following functions:
Format the exception part of a traceback using an exception value such as Format the exception part of a traceback using an exception value such as
given by ``sys.last_value``. The return value is a list of strings, each given by ``sys.last_value``. The return value is a list of strings, each
ending in a newline. Normally, the list contains a single string; however, ending in a newline. The list contains the exception's message, which is
for :exc:`SyntaxError` exceptions, it contains several lines that (when normally a single string; however, for :exc:`SyntaxError` exceptions, it
printed) display detailed information about where the syntax error occurred. contains several lines that (when printed) display detailed information
The message indicating which exception occurred is the always last string in about where the syntax error occurred. Following the message, the list
the list. contains the exception's :attr:`notes <BaseException.__notes__>`.
Since Python 3.10, instead of passing *value*, an exception object Since Python 3.10, instead of passing *value*, an exception object
can be passed as the first argument. If *value* is provided, the first can be passed as the first argument. If *value* is provided, the first
@ -153,6 +153,9 @@ The module defines the following functions:
The *etype* parameter has been renamed to *exc* and is now The *etype* parameter has been renamed to *exc* and is now
positional-only. positional-only.
.. versionchanged:: 3.11
The returned list now includes any notes attached to the exception.
.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True) .. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
@ -235,6 +238,12 @@ capture data for later printing in a lightweight fashion.
group's exceptions array. The formatted output is truncated when either group's exceptions array. The formatted output is truncated when either
limit is exceeded. limit is exceeded.
.. versionchanged:: 3.10
Added the *compact* parameter.
.. versionchanged:: 3.11
Added the *max_group_width* and *max_group_depth* parameters.
.. attribute:: __cause__ .. attribute:: __cause__
A :class:`TracebackException` of the original ``__cause__``. A :class:`TracebackException` of the original ``__cause__``.
@ -330,35 +339,28 @@ capture data for later printing in a lightweight fashion.
some containing internal newlines. :func:`~traceback.print_exception` some containing internal newlines. :func:`~traceback.print_exception`
is a wrapper around this method which just prints the lines to a file. is a wrapper around this method which just prints the lines to a file.
The message indicating which exception occurred is always the last
string in the output.
.. method:: format_exception_only(*, show_group=False) .. method:: format_exception_only(*, show_group=False)
Format the exception part of the traceback. Format the exception part of the traceback.
The return value is a generator of strings, each ending in a newline. The return value is a generator of strings, each ending in a newline.
When *show_group* is ``False``, the generator normally emits a single When *show_group* is ``False``, the generator emits the exception's
string; however, for :exc:`SyntaxError` exceptions, it emits several message followed by its notes (if it has any). The exception message
lines that (when printed) display detailed information about where is normally a single string; however, for :exc:`SyntaxError` exceptions,
the syntax error occurred. The message indicating which exception it consists of several lines that (when printed) display detailed
occurred is always the last string in the output. information about where the syntax error occurred.
When *show_group* is ``True``, and the exception is an instance of When *show_group* is ``True``, and the exception is an instance of
:exc:`BaseExceptionGroup`, the nested exceptions are included as :exc:`BaseExceptionGroup`, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth. well, recursively, with indentation relative to their nesting depth.
.. versionchanged:: 3.11
The exception's notes are now included in the output.
.. versionchanged:: 3.13 .. versionchanged:: 3.13
Added the *show_group* parameter. Added the *show_group* parameter.
.. versionchanged:: 3.10
Added the *compact* parameter.
.. versionchanged:: 3.11
Added the *max_group_width* and *max_group_depth* parameters.
:class:`StackSummary` Objects :class:`StackSummary` Objects
----------------------------- -----------------------------