gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201)
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 3eb77fc..67ee73d 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -139,11 +139,11 @@
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 *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 @@
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 @@
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
-----------------------------
