[Python-checkins] gh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (GH-102012)

[miss-islington]

https://github.com/python/cpython/commit/78eee7618534d09121c7bb4e47b43ef5867a2a16
commit: 78eee7618534d09121c7bb4e47b43ef5867a2a16
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2023-02-21T03:06:20-08:00
summary:

gh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (GH-102012)

(cherry picked from commit 4d3bc89a3f54c4f09756a9b644b3912bf54191a7)

Co-authored-by: Irit Katriel <1055913+iritkatriel at users.noreply.github.com>

files:
M Doc/library/exceptions.rst
M Doc/library/traceback.rst
M Doc/library/types.rst
M Doc/library/wsgiref.rst
M Doc/reference/compound_stmts.rst
M Doc/reference/datamodel.rst

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 1217b817b4e8..4a57e9c87993 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -123,7 +123,7 @@ The following exceptions are used mostly as base classes for other exceptions.
          try:
              ...
          except SomeException:
-             tb = sys.exc_info()[2]
+             tb = sys.exception().__traceback__
              raise OtherException(...).with_traceback(tb)
 
    .. method:: add_note(note)
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index a7a015f17193..053e97325e31 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -16,9 +16,8 @@ interpreter.
 
 .. index:: object: traceback
 
-The module uses traceback objects --- this is the object type that is stored in
-the :data:`sys.last_traceback` variable and returned as the third item from
-:func:`sys.exc_info`.
+The module uses traceback objects --- these are objects of type :class:`types.TracebackType`,
+which are assigned to the ``__traceback__`` field of :class:`BaseException` instances.
 
 .. seealso::
 
@@ -81,7 +80,7 @@ The module defines the following functions:
 
 .. function:: print_exc(limit=None, file=None, chain=True)
 
-   This is a shorthand for ``print_exception(*sys.exc_info(), limit, file,
+   This is a shorthand for ``print_exception(sys.exception(), limit, file,
    chain)``.
 
 
@@ -440,11 +439,11 @@ exception and traceback:
    try:
        lumberjack()
    except IndexError:
-       exc_type, exc_value, exc_traceback = sys.exc_info()
+       exc = sys.exception()
        print("*** print_tb:")
-       traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
+       traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
        print("*** print_exception:")
-       traceback.print_exception(exc_value, limit=2, file=sys.stdout)
+       traceback.print_exception(exc, limit=2, file=sys.stdout)
        print("*** print_exc:")
        traceback.print_exc(limit=2, file=sys.stdout)
        print("*** format_exc, first and last line:")
@@ -452,12 +451,12 @@ exception and traceback:
        print(formatted_lines[0])
        print(formatted_lines[-1])
        print("*** format_exception:")
-       print(repr(traceback.format_exception(exc_value)))
+       print(repr(traceback.format_exception(exc)))
        print("*** extract_tb:")
-       print(repr(traceback.extract_tb(exc_traceback)))
+       print(repr(traceback.extract_tb(exc.__traceback__)))
        print("*** format_tb:")
-       print(repr(traceback.format_tb(exc_traceback)))
-       print("*** tb_lineno:", exc_traceback.tb_lineno)
+       print(repr(traceback.format_tb(exc.__traceback__)))
+       print("*** tb_lineno:", exc.__traceback__.tb_lineno)
 
 The output for the example would look similar to this:
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index e0e77dfbfe7e..aafba29b4cf6 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -320,7 +320,7 @@ Standard names are defined for the following types:
 
 .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)
 
-   The type of traceback objects such as found in ``sys.exc_info()[2]``.
+   The type of traceback objects such as found in ``sys.exception().__traceback__``.
 
    See :ref:`the language reference <traceback-objects>` for details of the
    available attributes and operations, and guidance on creating tracebacks
diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst
index 75dea4663351..39a4c1ba1423 100644
--- a/Doc/library/wsgiref.rst
+++ b/Doc/library/wsgiref.rst
@@ -674,7 +674,7 @@ input, output, and error streams.
       This method is a WSGI application to generate an error page for the user.  It is
       only invoked if an error occurs before headers are sent to the client.
 
-      This method can access the current error information using ``sys.exc_info()``,
+      This method can access the current error using ``sys.exception()``,
       and should pass that information to *start_response* when calling it (as
       described in the "Error Handling" section of :pep:`3333`).
 
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index d5cb2899c231..52bb0b22b042 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -301,31 +301,28 @@ keeping all locals in that frame alive until the next garbage collection occurs.
    object: traceback
 
 Before an :keyword:`!except` clause's suite is executed,
-details about the exception are
-stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
-:func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
-exception instance and a traceback object (see section :ref:`types`) identifying
-the point in the program where the exception occurred.  The details about the
-exception accessed via :func:`sys.exc_info` are restored to their previous values
-when leaving an exception handler::
-
-   >>> print(sys.exc_info())
-   (None, None, None)
+the exception is stored in the :mod:`sys` module, where it can be accessed
+from within the body of the :keyword:`!except` clause by calling
+:func:`sys.exception`. When leaving an exception handler, the exception
+stored in the :mod:`sys` module is reset to its previous value::
+
+   >>> print(sys.exception())
+   None
    >>> try:
    ...     raise TypeError
    ... except:
-   ...     print(sys.exc_info())
+   ...     print(repr(sys.exception()))
    ...     try:
    ...          raise ValueError
    ...     except:
-   ...         print(sys.exc_info())
-   ...     print(sys.exc_info())
+   ...         print(repr(sys.exception()))
+   ...     print(repr(sys.exception()))
    ...
-   (<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
-   (<class 'ValueError'>, ValueError(), <traceback object at 0x10efad040>)
-   (<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
-   >>> print(sys.exc_info())
-   (None, None, None)
+   TypeError()
+   ValueError()
+   TypeError()
+   >>> print(sys.exception())
+   None
 
 
 .. index::
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index dce48a466301..e94b535901c5 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1122,6 +1122,7 @@ Internal types
          single: exc_info (in module sys)
          single: last_traceback (in module sys)
          single: sys.exc_info
+         single: sys.exception
          single: sys.last_traceback
 
       Traceback objects represent a stack trace of an exception.  A traceback object