Skip to content

Commit

Permalink
pythongh-109184: update traceback module doc w.r.t notes (message is …
Browse files Browse the repository at this point in the history
…no longer always at the end) (python#109201)

(cherry picked from commit 0e76cc3)
  • Loading branch information
iritkatriel committed Sep 12, 2023
1 parent b4c1cf9 commit 247999f
Showing 1 changed file with 21 additions and 20 deletions.
41 changes: 21 additions & 20 deletions Doc/library/traceback.rst
Original file line number Diff line number Diff line change
Expand Up @@ -140,11 +140,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
Expand All @@ -154,6 +154,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)

Expand Down Expand Up @@ -236,6 +239,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__``.
Expand Down Expand Up @@ -331,28 +340,20 @@ 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()

Format the exception part of the traceback.

The return value is a generator of strings, each ending in a newline.

Normally, the generator 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.
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.

.. versionchanged:: 3.10
Added the *compact* parameter.

.. versionchanged:: 3.11
Added the *max_group_width* and *max_group_depth* parameters.
.. versionchanged:: 3.11
The exception's notes are now included in the output.


:class:`StackSummary` Objects
Expand Down

0 comments on commit 247999f

Please sign in to comment.