@@ -400,8 +400,46 @@ Querying the error indicator
400400 recursively in subtuples) are searched for a match.
401401
402402
403+ .. c:function:: PyObject *PyErr_GetRaisedException(void)
404+
405+ Return the exception currently being raised, clearing the error indicator at
406+ the same time.
407+
408+ This function is used by code that needs to catch exceptions,
409+ or code that needs to save and restore the error indicator temporarily.
410+
411+ For example::
412+
413+ {
414+ PyObject *exc = PyErr_GetRaisedException();
415+
416+ /* ... code that might produce other errors ... */
417+
418+ PyErr_SetRaisedException (exc);
419+ }
420+
421+ seealso :: :c:func:`PyErr_GetHandledException`,
422+ to save the exception currently being handled.
423+
424+ .. versionadded :: 3.12
425+
426+
427+ .. c :function :: void PyErr_SetRaisedException (PyObject *exc)
428+
429+ Set *exc * as the exception currently being raised,
430+ clearing the existing exception if one is set.
431+
432+ .. warning ::
433+
434+ This call steals a reference to *exc *, which must be a valid exception.
435+
436+ .. versionadded :: 3.12
437+
438+
403439.. c :function :: void PyErr_Fetch (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
404440
441+ As of 3.12, this function is deprecated. Use :c:func: `PyErr_GetRaisedException ` instead.
442+
405443 Retrieve the error indicator into three variables whose addresses are passed.
406444 If the error indicator is not set, set all three variables to ``NULL ``. If it is
407445 set, it will be cleared and you own a reference to each object retrieved. The
@@ -421,10 +459,14 @@ Querying the error indicator
421459 PyErr_Restore(type, value, traceback);
422460 }
423461
462+ .. deprecated :: 3.12
463+
424464
425465.. c :function :: void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
426466
427- Set the error indicator from the three objects. If the error indicator is
467+ As of 3.12, this function is deprecated. Use :c:func: `PyErr_SetRaisedException ` instead.
468+
469+ Set the error indicator from the three objects. If the error indicator is
428470 already set, it is cleared first. If the objects are ``NULL ``, the error
429471 indicator is cleared. Do not pass a ``NULL `` type and non-``NULL `` value or
430472 traceback. The exception type should be a class. Do not pass an invalid
@@ -440,9 +482,15 @@ Querying the error indicator
440482 error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current
441483 error indicator.
442484
485+ .. deprecated:: 3.12
486+
443487
444488.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
445489
490+ As of 3.12, this function is deprecated.
491+ Use :c:func: `PyErr_GetRaisedException ` instead of :c:func: `PyErr_Fetch ` to avoid
492+ any possible de-normalization.
493+
446494 Under certain circumstances, the values returned by :c:func: `PyErr_Fetch ` below
447495 can be "unnormalized", meaning that ``*exc `` is a class object but ``*val `` is
448496 not an instance of the same class. This function can be used to instantiate
@@ -459,6 +507,8 @@ Querying the error indicator
459507 PyException_SetTraceback(val, tb);
460508 }
461509
510+ .. deprecated :: 3.12
511+
462512
463513.. c :function :: PyObject* PyErr_GetHandledException (void)
464514
@@ -704,6 +754,18 @@ Exception Objects
704754 :attr: `__suppress_context__ ` is implicitly set to ``True `` by this function.
705755
706756
757+ .. c :function :: PyObject* PyException_GetArgs (PyObject *ex)
758+
759+ Return args of the given exception as a new reference,
760+ as accessible from Python through :attr: `args `.
761+
762+
763+ .. c :function :: void PyException_SetArgs (PyObject *ex, PyObject *args)
764+
765+ Set the args of the given exception,
766+ as accessible from Python through :attr: `args `.
767+
768+
707769.. _unicodeexceptions :
708770
709771Unicode Exception Objects
0 commit comments