renamed Get/SetActiveException --> Get/SetHandledException

python · iritkatriel · Apr 15, 2022 · Jan 11, 2022 · Jan 11, 2022 · Jan 11, 2022
commit e6a3a7e01b8a4c18bac0af652b826416981927bc
@@ -460,7 +460,7 @@ Querying the error indicator
          }
 
 
-.. c:function:: PyObject* PyErr_GetActiveException(void)
+.. c:function:: PyObject* PyErr_GetHandledException(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
@@ -471,12 +471,12 @@ Querying the error indicator
 
       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
+      state temporarily.  Use :c:func:`PyErr_SetHandledException` to restore or
       clear the exception state.
 
    .. versionadded:: 3.11
 
-.. c:function:: void PyErr_SetActiveException(PyObject *exc)
+.. c:function:: void PyErr_SetHandledException(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
@@ -487,7 +487,7 @@ Querying the error indicator
 
       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 temporarily.  Use :c:func:`PyErr_GetHandledException` to get the exception
       state.
 
    .. versionadded:: 3.11
@@ -499,7 +499,7 @@ Querying the error indicator
    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.  This function is kept for backwards compatibility. Prefer using
-   :c:func:`PyErr_GetActiveException`.
+   :c:func:`PyErr_GetHandledException`.
 
    .. note::
 
@@ -518,7 +518,7 @@ Querying the error indicator
    freshly raised.  This function steals the references of the arguments.
    To clear the exception state, pass ``NULL`` for all three arguments.
    This function is kept for backwards compatibility. Prefer using
-   :c:func:`PyErr_SetActiveException`.
+   :c:func:`PyErr_SetHandledException`.
 
    .. note::
 

diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
@@ -782,7 +782,7 @@ New Features
   (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`.
+  :c:func:`PyErr_GetHandledException` and :c:func:`PyErr_SetHandledException`.
   These are alternatives to :c:func:`PyErr_SetExcInfo()` and
   :c:func:`PyErr_GetExcInfo()` which work with the legacy 3-tuple
   representation of exceptions.

diff --git a/Include/cpython/pyerrors.h b/Include/cpython/pyerrors.h
@@ -91,8 +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(PyObject*) _PyErr_GetHandledException(PyThreadState *);
+PyAPI_FUNC(void) _PyErr_SetHandledException(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
@@ -19,8 +19,8 @@ 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 *);
+PyAPI_FUNC(PyObject*) PyErr_GetHandledException(void);
+PyAPI_FUNC(void) PyErr_SetHandledException(PyObject *);
 #endif
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
 PyAPI_FUNC(void) PyErr_GetExcInfo(PyObject **, PyObject **, PyObject **);

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
@@ -1,5 +1,5 @@
-Added :c:func:`PyErr_GetActiveException` and
-:c:func:`PyErr_SetActiveException` as simpler alternatives to
+Added :c:func:`PyErr_GetHandledException` and
+:c:func:`PyErr_SetHandledException` 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,8 +2224,8 @@ function PyMemoryView_FromBuffer
 
 data Py_Version
     added 3.11
-function PyErr_GetActiveException
+function PyErr_GetHandledException
     added 3.11
-function PyErr_SetActiveException
+function PyErr_SetHandledException
     added 3.11
 
diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c
@@ -2565,10 +2565,10 @@ set_errno(PyObject *self, PyObject *args)
 static PyObject *
 test_set_exception(PyObject *self, PyObject *new_exc)
 {
-    PyObject *exc = PyErr_GetActiveException();
+    PyObject *exc = PyErr_GetHandledException();
     assert(PyExceptionInstance_Check(exc) || exc == NULL);
 
-    PyErr_SetActiveException(new_exc);
+    PyErr_SetHandledException(new_exc);
     return exc;
 }
 

diff --git a/Python/errors.c b/Python/errors.c
@@ -500,7 +500,7 @@ _PyErr_GetExcInfo(PyThreadState *tstate,
 }
 
 PyObject*
-_PyErr_GetActiveException(PyThreadState *tstate)
+_PyErr_GetHandledException(PyThreadState *tstate)
 {
     _PyErr_StackItem *exc_info = _PyErr_GetTopmostException(tstate);
     PyObject *exc = exc_info->exc_value;
@@ -511,25 +511,25 @@ _PyErr_GetActiveException(PyThreadState *tstate)
 }
 
 PyObject*
-PyErr_GetActiveException(void)
+PyErr_GetHandledException(void)
 {
     PyThreadState *tstate = _PyThreadState_GET();
-    return _PyErr_GetActiveException(tstate);
+    return _PyErr_GetHandledException(tstate);
 }
 
 void
-_PyErr_SetActiveException(PyThreadState *tstate, PyObject *exc)
+_PyErr_SetHandledException(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)
+PyErr_SetHandledException(PyObject *exc)
 {
     PyThreadState *tstate = _PyThreadState_GET();
-    _PyErr_SetActiveException(tstate, exc);
+    _PyErr_SetHandledException(tstate, exc);
 }
 
 void
@@ -542,7 +542,7 @@ PyErr_GetExcInfo(PyObject **p_type, PyObject **p_value, PyObject **p_traceback)
 void
 PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
 {
-    PyErr_SetActiveException(value);
+    PyErr_SetHandledException(value);
     /* These args are no longer used, but we still need to steal a ref */
     Py_XDECREF(type);
     Py_XDECREF(traceback);