@@ -400,8 +400,61 @@ Querying the error indicator
400400 recursively in subtuples) are searched for a match.
401401
402402
403+ .. c:function:: PyObject *PyErr_GetRaisedException(void)
404+
405+ Returns the exception currently being raised, clearing the exception at
406+ the same time. Do not confuse this with the exception currently being
407+ handled which can be accessed with :c:func:`PyErr_GetHandledException`.
408+
409+ .. note::
410+
411+ This function is normally only used by code that needs to catch exceptions or
412+ by code that needs to save and restore the error indicator temporarily, e.g.::
413+
414+ {
415+ PyObject *exc = PyErr_GetRaisedException();
416+
417+ /* ... code that might produce other errors ... */
418+
419+ PyErr_SetRaisedException (exc);
420+ }
421+
422+ versionadded :: 3.12
423+
424+
425+ .. c :function :: void PyErr_SetRaisedException (PyObject *exc)
426+
427+ Sets the exception currently being raised ``exc ``.
428+ If the exception is already set, it is cleared first.
429+
430+ ``exc `` must be a valid exception.
431+ (Violating this rules will cause subtle problems later.)
432+ This call consumes a reference to the ``exc`` object: you must own a
433+ reference to that object before the call and after the call you no longer own
434+ that reference.
435+ (If you don't understand this, don't use this function. I warned you.)
436+
437+ .. note::
438+
439+ This function is normally only used by code that needs to save and restore the
440+ error indicator temporarily. Use :c:func:`PyErr_GetRaisedException` to save
441+ the current exception, e.g.::
442+
443+ {
444+ PyObject *exc = PyErr_GetRaisedException();
445+
446+ /* ... code that might produce other errors ... */
447+
448+ PyErr_SetRaisedException (exc);
449+ }
450+
451+ versionadded :: 3.12
452+
453+
403454.. c :function :: void PyErr_Fetch (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
404455
456+ As of 3.12, this function is deprecated. Use :c:func: `PyErr_GetRaisedException ` instead.
457+
405458 Retrieve the error indicator into three variables whose addresses are passed.
406459 If the error indicator is not set, set all three variables to ``NULL ``. If it is
407460 set, it will be cleared and you own a reference to each object retrieved. The
@@ -421,10 +474,14 @@ Querying the error indicator
421474 PyErr_Restore(type, value, traceback);
422475 }
423476
477+ .. deprecated :: 3.12
478+
424479
425480.. c :function :: void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
426481
427- Set the error indicator from the three objects. If the error indicator is
482+ As of 3.12, this function is deprecated. Use :c:func: `PyErr_SetRaisedException ` instead.
483+
484+ Set the error indicator from the three objects. If the error indicator is
428485 already set, it is cleared first. If the objects are ``NULL ``, the error
429486 indicator is cleared. Do not pass a ``NULL `` type and non-``NULL `` value or
430487 traceback. The exception type should be a class. Do not pass an invalid
@@ -440,9 +497,15 @@ Querying the error indicator
440497 error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current
441498 error indicator.
442499
500+ .. deprecated:: 3.12
501+
443502
444503.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
445504
505+ As of 3.12, this function is deprecated.
506+ Use :c:func: `PyErr_GetRaisedException ` instead of :c:func: `PyErr_Fetch ` to avoid
507+ any possible de-normalization.
508+
446509 Under certain circumstances, the values returned by :c:func: `PyErr_Fetch ` below
447510 can be "unnormalized", meaning that ``*exc `` is a class object but ``*val `` is
448511 not an instance of the same class. This function can be used to instantiate
@@ -459,6 +522,8 @@ Querying the error indicator
459522 PyException_SetTraceback(val, tb);
460523 }
461524
525+ .. deprecated :: 3.12
526+
462527
463528.. c :function :: PyObject* PyErr_GetHandledException (void)
464529
@@ -704,6 +769,18 @@ Exception Objects
704769 :attr: `__suppress_context__ ` is implicitly set to ``True `` by this function.
705770
706771
772+ .. c :function :: PyObject* PyException_GetArgs (PyObject *ex)
773+
774+ Return args of the given exception as a new reference,
775+ as accessible from Python through :attr: `args `.
776+
777+
778+ .. c :function :: void PyException_SetArgs (PyObject *ex, PyObject *args)
779+
780+ Set the args of the given exception,
781+ as accessible from Python through :attr: `args `.
782+
783+
707784.. _unicodeexceptions :
708785
709786Unicode Exception Objects
0 commit comments