bpo-46328: Add sys.exception() (GH-30514)

1 files changed, 30 insertions, 15 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 7d1b21f..5e47201 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -378,26 +378,41 @@ always available.
    .. versionadded:: 3.8
       __unraisablehook__
 
+
+.. function:: exception()
+
+   This function returns the exception instance that is currently being
+   handled.  This exception is specific both to the current thread and
+   to the current stack frame.  If the current stack frame is not handling
+   an exception, the exception is taken from the calling stack frame, or its
+   caller, and so on until a stack frame is found that is handling an
+   exception.  Here, "handling an exception" is defined as "executing an
+   except clause." For any stack frame, only the exception being currently
+   handled is accessible.
+
+   .. index:: object: traceback
+
+   If no exception is being handled anywhere on the stack, ``None`` is
+   returned.
+
+   .. versionadded:: 3.11
+
+
 .. function:: exc_info()
 
-   This function returns a tuple of three values that give information about the
-   exception that is currently being handled.  The information returned is specific
-   both to the current thread and to the current stack frame.  If the current stack
-   frame is not handling an exception, the information is taken from the calling
-   stack frame, or its caller, and so on until a stack frame is found that is
-   handling an exception.  Here, "handling an exception" is defined as "executing
-   an except clause."  For any stack frame, only information about the exception
-   being currently handled is accessible.
+   This function returns the old-style representation of the handled
+   exception. If an exception ``e`` is currently handled (so
+   :func:`exception` would return ``e``), :func:`exc_info` returns the
+   tuple ``(type(e), e, e.__traceback__)``.
+   That is, a tuple containing the type of the exception (a subclass of
+   :exc:`BaseException`), the exception itself, and a :ref:`traceback
+   object <traceback-objects>` which typically encapsulates the call
+   stack at the point where the exception last occurred.
 
    .. index:: object: traceback
 
-   If no exception is being handled anywhere on the stack, a tuple containing
-   three ``None`` values is returned.  Otherwise, the values returned are
-   ``(type, value, traceback)``.  Their meaning is: *type* gets the type of the
-   exception being handled (a subclass of :exc:`BaseException`); *value* gets
-   the exception instance (an instance of the exception type); *traceback* gets
-   a :ref:`traceback object <traceback-objects>` which typically encapsulates
-   the call stack at the point where the exception last occurred.
+   If no exception is being handled anywhere on the stack, this function
+   return a tuple containing three ``None`` values.
 
    .. versionchanged:: 3.11
       The ``type`` and ``traceback`` fields are now derived from the ``value``