Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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

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
Show Stats 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
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,
for :exc:`SyntaxError` exceptions, it contains several lines that (when
printed) display detailed information about where the syntax error occurred.
The message indicating which exception occurred is the always last string in
the list.
ending in a newline. The list contains the exception's message, which is
normally a single string; however, for :exc:`SyntaxError` exceptions, it
contains several lines that (when printed) display detailed information
about where the syntax error occurred. Following the message, the list
contains the exception's :attr:`notes <BaseException.__notes__>`.
Since Python 3.10, instead of passing *value*, an exception object
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
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)
@ -235,6 +238,12 @@ capture data for later printing in a lightweight fashion.
group's exceptions array. The formatted output is truncated when either
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__
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`
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)
Format the exception part of the traceback.
The return value is a generator of strings, each ending in a newline.
When *show_group* is ``False``, the generator normally emits a single
string; however, for :exc:`SyntaxError` exceptions, it emits several
lines that (when printed) display detailed information about where
the syntax error occurred. The message indicating which exception
occurred is always the last string in the output.
When *show_group* is ``False``, the generator emits the exception's
message followed by its notes (if it has any). The exception message
is normally a single string; however, for :exc:`SyntaxError` exceptions,
it consists of several lines that (when printed) display detailed
information about where the syntax error occurred.
When *show_group* is ``True``, and the exception is an instance of
:exc:`BaseExceptionGroup`, the nested exceptions are included as
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
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
-----------------------------