Skip to content

Commit 0e76cc3

Browse files
authored
gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201)
1 parent e121fca commit 0e76cc3

File tree

1 file changed

+22
-20
lines changed

1 file changed

+22
-20
lines changed

Doc/library/traceback.rst

Lines changed: 22 additions & 20 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,35 +339,28 @@ 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(*, show_group=False)
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-
When *show_group* is ``False``, the generator normally emits a single
343-
string; however, for :exc:`SyntaxError` exceptions, it emits several
344-
lines that (when printed) display detailed information about where
345-
the syntax error occurred. The message indicating which exception
346-
occurred is always the last string in the output.
348+
When *show_group* is ``False``, the generator emits the exception's
349+
message followed by its notes (if it has any). The exception message
350+
is normally a single string; however, for :exc:`SyntaxError` exceptions,
351+
it consists of several lines that (when printed) display detailed
352+
information about where the syntax error occurred.
347353

348354
When *show_group* is ``True``, and the exception is an instance of
349355
:exc:`BaseExceptionGroup`, the nested exceptions are included as
350356
well, recursively, with indentation relative to their nesting depth.
351357

358+
.. versionchanged:: 3.11
359+
The exception's notes are now included in the output.
360+
352361
.. versionchanged:: 3.13
353362
Added the *show_group* parameter.
354363

355-
.. versionchanged:: 3.10
356-
Added the *compact* parameter.
357-
358-
.. versionchanged:: 3.11
359-
Added the *max_group_width* and *max_group_depth* parameters.
360-
361-
362364

363365
:class:`StackSummary` Objects
364366
-----------------------------

0 commit comments

Comments
 (0)