python · iritkatriel · Apr 15, 2022 · Jan 11, 2022 · Jan 11, 2022 · Jan 11, 2022
@@ -460,12 +460,45 @@ Querying the error indicator
          }
 
 
-.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+.. c:function:: PyObject* PyErr_GetActiveException(void)
+
+   Retrieve the active exception instance, as would be returned by :func:`sys.exception`.
+   This refers to an exception that was *already caught*, not to an exception that was
+   freshly raised. Returns a new reference to the exception or to ``Py_None``.
+   Does not modify the exception state.
+
+   .. note::
+
+      This function is not normally used by code that wants to handle exceptions.
+      Rather, it can be used when code needs to save and restore the exception
+      state temporarily.  Use :c:func:`PyErr_SetActiveException` to restore or
+      clear the exception state.
+
+   .. versionadded:: 3.11
 
-   Retrieve the exception info, as known from ``sys.exc_info()``.  This refers
+.. c:function:: void PyErr_SetActiveException(PyObject *exc)
+
+   Set the active exception, as known from ``sys.exception()``.  This refers
    to an exception that was *already caught*, not to an exception that was
-   freshly raised.  Returns new references for the three objects, any of which
-   may be ``NULL``.  Does not modify the exception info state.
+   freshly raised.
+   To clear the exception state, pass ``NULL``.
+
+   .. note::
+
+      This function is not normally used by code that wants to handle exceptions.
+      Rather, it can be used when code needs to save and restore the exception
+      state temporarily.  Use :c:func:`PyErr_GetActiveException` to get the exception
+      state.
+
+   .. versionadded:: 3.11
+
+.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+   Retrieve the old-style representation of the exception info, as known from
+   :func:`sys.exc_info`.  This refers to an exception that was *already caught*,
+   not to an exception that was freshly raised.  Returns new references for the
+   three objects, any of which may be ``NULL``.  Does not modify the exception
+   info state.
 
    .. note::
 

diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
@@ -781,6 +781,13 @@ New Features
   :c:func:`PyFloat_Unpack8`.
   (Contributed by Victor Stinner in :issue:`46906`.)
 
+* Added two new functions to get and set the active exception instance:
+  :c:func:`PyErr_GetActiveException` and :c:func:`PyErr_SetActiveException`.
+  These are alternatives to :c:func:`PyErr_SetExcInfo()` and
+  :c:func:`PyErr_GetExcInfo()` which work with the legacy 3-tuple
+  representation of exceptions.
+  (Contributed by Irit Katriel in :issue:`46343`.)
+
 
 Porting to Python 3.11
 ----------------------

diff --git a/Include/cpython/pyerrors.h b/Include/cpython/pyerrors.h
@@ -91,6 +91,8 @@ typedef PyOSErrorObject PyWindowsErrorObject;
 
 PyAPI_FUNC(void) _PyErr_SetKeyError(PyObject *);
 PyAPI_FUNC(_PyErr_StackItem*) _PyErr_GetTopmostException(PyThreadState *tstate);
+PyAPI_FUNC(PyObject*) _PyErr_GetActiveException(PyThreadState *);
+PyAPI_FUNC(void) _PyErr_SetActiveException(PyThreadState *, PyObject *);
 PyAPI_FUNC(void) _PyErr_GetExcInfo(PyThreadState *, PyObject **, PyObject **, PyObject **);
 
 /* Context manipulation (PEP 3134) */

diff --git a/Include/pyerrors.h b/Include/pyerrors.h
@@ -18,6 +18,10 @@ PyAPI_FUNC(PyObject *) PyErr_Occurred(void);
 PyAPI_FUNC(void) PyErr_Clear(void);
 PyAPI_FUNC(void) PyErr_Fetch(PyObject **, PyObject **, PyObject **);
 PyAPI_FUNC(void) PyErr_Restore(PyObject *, PyObject *, PyObject *);
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000
+PyAPI_FUNC(PyObject*) PyErr_GetActiveException(void);
+PyAPI_FUNC(void) PyErr_SetActiveException(PyObject *);
+#endif
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
 PyAPI_FUNC(void) PyErr_GetExcInfo(PyObject **, PyObject **, PyObject **);
 PyAPI_FUNC(void) PyErr_SetExcInfo(PyObject *, PyObject *, PyObject *);

diff --git a/Lib/test/test_capi.py b/Lib/test/test_capi.py
@@ -88,6 +88,28 @@ def test_no_FatalError_infinite_loop(self):
     def test_memoryview_from_NULL_pointer(self):
         self.assertRaises(ValueError, _testcapi.make_memoryview_from_NULL_pointer)
 
+    def test_exception(self):
+        raised_exception = ValueError("5")
+        new_exc = TypeError("TEST")
+        try:
+            raise raised_exception
+        except ValueError as e:
+            orig_sys_exception = sys.exception()
+            orig_exception = _testcapi.set_exception(new_exc)
+            new_sys_exception = sys.exception()
+            new_exception = _testcapi.set_exception(orig_exception)
+            reset_sys_exception = sys.exception()
+
+            self.assertEqual(orig_exception, e)
+
+            self.assertEqual(orig_exception, raised_exception)
+            self.assertEqual(orig_sys_exception, orig_exception)
+            self.assertEqual(reset_sys_exception, orig_exception)
+            self.assertEqual(new_exception, new_exc)
+            self.assertEqual(new_sys_exception, new_exception)
+        else:
+            self.fail("Exception not raised")
+
     def test_exc_info(self):
         raised_exception = ValueError("5")
         new_exc = TypeError("TEST")

diff --git a/Lib/test/test_stable_abi_ctypes.py b/Lib/test/test_stable_abi_ctypes.py
diff --git a/Misc/NEWS.d/next/C API/2022-01-11-12-52-37.bpo-46343.JQJWhZ.rst b/Misc/NEWS.d/next/C API/2022-01-11-12-52-37.bpo-46343.JQJWhZ.rst
@@ -0,0 +1,5 @@
+Added :c:func:`PyErr_GetActiveException` and
+:c:func:`PyErr_SetActiveException` as simpler alternatives to
+:c:func:`PyErr_GetExcInfo` and :c:func:`PyErr_SetExcInfo`.
+
+They are included in the stable ABI.
diff --git a/Misc/stable_abi.txt b/Misc/stable_abi.txt
@@ -2224,3 +2224,8 @@ function PyMemoryView_FromBuffer
 
 data Py_Version
     added 3.11
+function PyErr_GetActiveException
+    added 3.11
+function PyErr_SetActiveException
+    added 3.11
+
diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c
@@ -2562,6 +2562,21 @@ set_errno(PyObject *self, PyObject *args)
     Py_RETURN_NONE;
 }
 
+static PyObject *
+test_set_exception(PyObject *self, PyObject *args)
+{
+    PyObject *new_exc;
+    if (!PyArg_ParseTuple(args, "O:test_set_exception",
+                          &new_exc)) {
+        return NULL;
+    }
+
+    PyObject *exc = PyErr_GetActiveException();
+
+    PyErr_SetActiveException(Py_NewRef(new_exc));
+    return exc;
+}
+
 static PyObject *
 test_set_exc_info(PyObject *self, PyObject *args)
 {
@@ -6013,6 +6028,7 @@ static PyMethodDef TestMethods[] = {
 #endif
     {"traceback_print",         traceback_print,                 METH_VARARGS},
     {"exception_print",         exception_print,                 METH_VARARGS},
+    {"set_exception",           test_set_exception,              METH_VARARGS},
     {"set_exc_info",            test_set_exc_info,               METH_VARARGS},
     {"argparsing",              argparsing,                      METH_VARARGS},
     {"code_newempty",           code_newempty,                   METH_VARARGS},

diff --git a/Python/errors.c b/Python/errors.c
@@ -499,6 +499,35 @@ _PyErr_GetExcInfo(PyThreadState *tstate,
     Py_XINCREF(*p_traceback);
 }
 
+PyObject*
+_PyErr_GetActiveException(PyThreadState *tstate)
+{
+    _PyErr_StackItem *exc_info = _PyErr_GetTopmostException(tstate);
+    PyObject *exc = exc_info->exc_value;
+    return Py_XNewRef(exc);
+}
+
+PyObject*
+PyErr_GetActiveException(void)
+{
+    PyThreadState *tstate = _PyThreadState_GET();
+    return _PyErr_GetActiveException(tstate);
+}
+
+void
+_PyErr_SetActiveException(PyThreadState *tstate, PyObject *exc)
+{
+    PyObject *oldexc = tstate->exc_info->exc_value;
+    tstate->exc_info->exc_value = Py_XNewRef(exc);
+    Py_XDECREF(oldexc);
+}
+
+void
+PyErr_SetActiveException(PyObject *exc)
+{
+    PyThreadState *tstate = _PyThreadState_GET();
+    _PyErr_SetActiveException(tstate, exc);
+}
 
 void
 PyErr_GetExcInfo(PyObject **p_type, PyObject **p_value, PyObject **p_traceback)
@@ -510,17 +539,10 @@ PyErr_GetExcInfo(PyObject **p_type, PyObject **p_value, PyObject **p_traceback)
 void
 PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
 {
-    PyThreadState *tstate = _PyThreadState_GET();
-
-    PyObject *oldvalue = tstate->exc_info->exc_value;
-
-    tstate->exc_info->exc_value = value;
-
+    PyErr_SetActiveException(value);
     /* These args are no longer used, but we still need to steal a ref */
     Py_XDECREF(type);
     Py_XDECREF(traceback);
-
-    Py_XDECREF(oldvalue);
 }