[3.12] gh-109184: update traceback module doc w.r.t notes (message is no longer alway...

gh-109184: update traceback module doc w.r.t notes (message is no longer always at the end) (#109201)

(cherry picked from commit 0e76cc359ba5d5e29d7c75355d7c1bc7e817eecf)

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 36171a3b5a610d0d8e0d2256f83af11c2f9c78d4..55ac361b1903a2a063d9645a50f534c640ef4bb6 100644 (file)
--- 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