Skip to content

Commit 08bd2aa

Browse files
authored
[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 0e76cc3)
1 parent 21f4e6d commit 08bd2aa

File tree

1 file changed

+21
-19
lines changed

1 file changed

+21
-19
lines changed

Doc/library/traceback.rst

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -139,11 +139,11 @@ The module defines the following functions:
139139

140140
Format the exception part of a traceback using an exception value such as
141141
given by ``sys.last_value``. The return value is a list of strings, each
142-
ending in a newline. Normally, the list contains a single string; however,
143-
for :exc:`SyntaxError` exceptions, it contains several lines that (when
144-
printed) display detailed information about where the syntax error occurred.
145-
The message indicating which exception occurred is the always last string in
146-
the list.
142+
ending in a newline. The list contains the exception's message, which is
143+
normally a single string; however, for :exc:`SyntaxError` exceptions, it
144+
contains several lines that (when printed) display detailed information
145+
about where the syntax error occurred. Following the message, the list
146+
contains the exception's :attr:`notes <BaseException.__notes__>`.
147147

148148
Since Python 3.10, instead of passing *value*, an exception object
149149
can be passed as the first argument. If *value* is provided, the first
@@ -153,6 +153,9 @@ The module defines the following functions:
153153
The *etype* parameter has been renamed to *exc* and is now
154154
positional-only.
155155

156+
.. versionchanged:: 3.11
157+
The returned list now includes any notes attached to the exception.
158+
156159

157160
.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
158161

@@ -235,6 +238,12 @@ capture data for later printing in a lightweight fashion.
235238
group's exceptions array. The formatted output is truncated when either
236239
limit is exceeded.
237240

241+
.. versionchanged:: 3.10
242+
Added the *compact* parameter.
243+
244+
.. versionchanged:: 3.11
245+
Added the *max_group_width* and *max_group_depth* parameters.
246+
238247
.. attribute:: __cause__
239248

240249
A :class:`TracebackException` of the original ``__cause__``.
@@ -330,28 +339,21 @@ capture data for later printing in a lightweight fashion.
330339
some containing internal newlines. :func:`~traceback.print_exception`
331340
is a wrapper around this method which just prints the lines to a file.
332341

333-
The message indicating which exception occurred is always the last
334-
string in the output.
335-
336342
.. method:: format_exception_only()
337343

338344
Format the exception part of the traceback.
339345

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

342-
Normally, the generator emits a single string; however, for
343-
:exc:`SyntaxError` exceptions, it emits several lines that (when
344-
printed) display detailed information about where the syntax
345-
error occurred.
348+
The generator emits the exception's message followed by its notes
349+
(if it has any). The exception message is normally a single string;
350+
however, for :exc:`SyntaxError` exceptions, it consists of several
351+
lines that (when printed) display detailed information about where
352+
the syntax error occurred.
346353

347-
The message indicating which exception occurred is always the last
348-
string in the output.
354+
.. versionchanged:: 3.11
355+
The exception's notes are now included in the output.
349356

350-
.. versionchanged:: 3.10
351-
Added the *compact* parameter.
352-
353-
.. versionchanged:: 3.11
354-
Added the *max_group_width* and *max_group_depth* parameters.
355357

356358

357359
:class:`StackSummary` Objects

0 commit comments

Comments
 (0)