added sys.exception()

python · iritkatriel · Jan 13, 2022 · Jan 5, 2022 · Jan 10, 2022 · Jan 10, 2022
commit 3a125051cf0c739912ae38de74db40b48511ded9
diff --git 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 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``

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
@@ -167,7 +167,7 @@ then re-raise the exception (allowing a caller to handle the exception as well):
        raise
 
 Alternatively the last except clause may omit the exception name(s), however the exception
-value must then be retrieved from ``sys.exc_info()[1]``.
+value must then be retrieved with ``sys.exception()``.
 
 The :keyword:`try` ... :keyword:`except` statement has an optional *else
 clause*, which, when present, must follow all *except clauses*.  It is useful

diff --git a/Lib/test/test_sys.py b/Lib/test/test_sys.py
@@ -71,6 +71,26 @@ def baddisplayhook(obj):
             code = compile("42", "<string>", "single")
             self.assertRaises(ValueError, eval, code)
 
+class ExcInfoTest(unittest.TestCase):
+    def test_exc_info_no_exception(self):
+        self.assertEqual(sys.exc_info(), (None, None, None))
+        self.assertEqual(sys.exception(), None)
+
+    def test_exc_info_with_exception(self):
+        def f():
+            raise ValueError(42)
+
+        try:
+            f()
+        except Exception as e_:
+            e = e_
+            exc_info = sys.exc_info()
+            exc = sys.exception()
+
+        self.assertIs(exc, e)
+        self.assertIs(exc_info[0], type(e))
+        self.assertIs(exc_info[1], e)
+        self.assertIs(exc_info[2], e.__traceback__)
 
 class ExceptHookTest(unittest.TestCase):
 

diff --git a/Python/clinic/sysmodule.c.h b/Python/clinic/sysmodule.c.h
@@ -771,6 +771,28 @@ sys_excepthook_impl(PyObject *module, PyObject *exctype, PyObject *value,
 }
 
 
+/*[clinic input]
+sys.exception
+
+Return the current exception.
+
+Return the most recent exception caught by an except clause
+in the current stack frame or in an older stack frame, or None
+if no such exception exists.
+[clinic start generated code]*/
+
+static PyObject *
+sys_exception_impl(PyObject *module)
+/*[clinic end generated code: output=2381ee2f25953e40 input=c88fbb94b6287431]*/
+{
+    _PyErr_StackItem *err_info = _PyErr_GetTopmostException(_PyThreadState_GET());
+    if (err_info->exc_value != NULL) {
+        return Py_NewRef(err_info->exc_value);
+    }
+    Py_RETURN_NONE;
+}
+
+
 /*[clinic input]
 sys.exc_info
 
@@ -1963,6 +1985,7 @@ static PyMethodDef sys_methods[] = {
     SYS__CURRENT_FRAMES_METHODDEF
     SYS__CURRENT_EXCEPTIONS_METHODDEF
     SYS_DISPLAYHOOK_METHODDEF
+    SYS_EXCEPTION_METHODDEF
     SYS_EXC_INFO_METHODDEF
     SYS_EXCEPTHOOK_METHODDEF
     SYS_EXIT_METHODDEF
@@ -2457,6 +2480,7 @@ Functions:\n\
 \n\
 displayhook() -- print an object to the screen, and save it in builtins._\n\
 excepthook() -- print an exception and its traceback to sys.stderr\n\
+exception() -- return the current exception (thread safe)\n\
 exc_info() -- return thread-safe information about the current exception\n\
 exit() -- exit the interpreter by raising SystemExit\n\
 getdlopenflags() -- returns flags to be used for dlopen() calls\n\