summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorIrit Katriel <1055913+iritkatriel@users.noreply.github.com>2023-09-13 10:35:26 (GMT)
committerGitHub <noreply@github.com>2023-09-13 10:35:26 (GMT)
commit08bd2aa79381eca34bcec9e6307d08ec1104ed0c (patch)
tree35d21832655421db85f19ae9ce68290cc022e322
parent21f4e6d6cb53b2edbc22dbd5ab92702dcce5b795 (diff)
downloadcpython-08bd2aa79381eca34bcec9e6307d08ec1104ed0c.zip
cpython-08bd2aa79381eca34bcec9e6307d08ec1104ed0c.tar.gz
cpython-08bd2aa79381eca34bcec9e6307d08ec1104ed0c.tar.bz2
[3.12] gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201) (#109334)
gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201) (cherry picked from commit 0e76cc359ba5d5e29d7c75355d7c1bc7e817eecf)
-rw-r--r--Doc/library/traceback.rst40
1 files changed, 21 insertions, 19 deletions
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 36171a3..55ac361 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -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,28 +339,21 @@ 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 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.
- The message indicating which exception occurred is always the last
- string in the output.
+ .. versionchanged:: 3.11
+ The exception's notes are now included in the output.
- .. versionchanged:: 3.10
- Added the *compact* parameter.
-
- .. versionchanged:: 3.11
- Added the *max_group_width* and *max_group_depth* parameters.
:class:`StackSummary` Objects