GH-101578: Normalize the current exception (GH-101607)

* Make sure that the current exception is always normalized.

* Remove redundant type and traceback fields for the current exception.

* Add new API functions: PyErr_GetRaisedException, PyErr_SetRaisedException

* Add new API functions: PyException_GetArgs, PyException_SetArgs

1 files changed, 78 insertions, 1 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 087e0a6..de9b15e 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -400,8 +400,61 @@ Querying the error indicator
    recursively in subtuples) are searched for a match.
 
 
+.. c:function:: PyObject *PyErr_GetRaisedException(void)
+
+   Returns the exception currently being raised, clearing the exception at
+   the same time. Do not confuse this with the exception currently being
+   handled which can be accessed with  :c:func:`PyErr_GetHandledException`.
+
+   .. note::
+
+      This function is normally only used by code that needs to catch exceptions or
+      by code that needs to save and restore the error indicator temporarily, e.g.::
+
+         {
+            PyObject *exc = PyErr_GetRaisedException();
+
+            /* ... code that might produce other errors ... */
+
+            PyErr_SetRaisedException(exc);
+         }
+
+   .. versionadded:: 3.12
+
+
+.. c:function:: void PyErr_SetRaisedException(PyObject *exc)
+
+   Sets the exception currently being raised ``exc``.
+   If the exception is already set, it is cleared first.
+
+   ``exc`` must be a valid exception.
+   (Violating this rules will cause subtle problems later.)
+   This call consumes a reference to the ``exc`` object: you must own a
+   reference to that object before the call and after the call you no longer own
+   that reference.
+   (If you don't understand this, don't use this function. I warned you.)
+
+   .. note::
+
+      This function is normally only used by code that needs to save and restore the
+      error indicator temporarily.  Use :c:func:`PyErr_GetRaisedException` to save
+      the current exception, e.g.::
+
+         {
+            PyObject *exc = PyErr_GetRaisedException();
+
+            /* ... code that might produce other errors ... */
+
+            PyErr_SetRaisedException(exc);
+         }
+
+   .. versionadded:: 3.12
+
+
 .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
 
+    As of 3.12, this function is deprecated. Use :c:func:`PyErr_GetRaisedException` instead.
+
    Retrieve the error indicator into three variables whose addresses are passed.
    If the error indicator is not set, set all three variables to ``NULL``.  If it is
    set, it will be cleared and you own a reference to each object retrieved.  The
@@ -421,10 +474,14 @@ Querying the error indicator
             PyErr_Restore(type, value, traceback);
          }
 
+   .. deprecated:: 3.12
+
 
 .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
 
-   Set  the error indicator from the three objects.  If the error indicator is
+    As of 3.12, this function is deprecated. Use :c:func:`PyErr_SetRaisedException` instead.
+
+   Set the error indicator from the three objects.  If the error indicator is
    already set, it is cleared first.  If the objects are ``NULL``, the error
    indicator is cleared.  Do not pass a ``NULL`` type and non-``NULL`` value or
    traceback.  The exception type should be a class.  Do not pass an invalid
@@ -440,9 +497,15 @@ Querying the error indicator
       error indicator temporarily.  Use :c:func:`PyErr_Fetch` to save the current
       error indicator.
 
+   .. deprecated:: 3.12
+
 
 .. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
 
+   As of 3.12, this function is deprecated.
+   Use :c:func:`PyErr_GetRaisedException` instead of :c:func:`PyErr_Fetch` to avoid
+   any possible de-normalization.
+
    Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
    can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
    not an instance of the  same class.  This function can be used to instantiate
@@ -459,6 +522,8 @@ Querying the error indicator
            PyException_SetTraceback(val, tb);
          }
 
+   .. deprecated:: 3.12
+
 
 .. c:function:: PyObject* PyErr_GetHandledException(void)
 
@@ -704,6 +769,18 @@ Exception Objects
    :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
 
 
+.. c:function:: PyObject* PyException_GetArgs(PyObject *ex)
+
+   Return args of the given exception as a new reference,
+   as accessible from Python through :attr:`args`.
+
+
+.. c:function:: void PyException_SetArgs(PyObject *ex, PyObject *args)
+
+   Set the args of the given exception,
+   as accessible from Python through :attr:`args`.
+
+
 .. _unicodeexceptions:
 
 Unicode Exception Objects