@@ -400,17 +400,59 @@ 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+ .. deprecated :: 3.12
442+
443+ Use :c:func: `PyErr_GetRaisedException ` instead.
444+
405445 Retrieve the error indicator into three variables whose addresses are passed.
406446 If the error indicator is not set, set all three variables to ``NULL ``. If it is
407447 set, it will be cleared and you own a reference to each object retrieved. The
408448 value and traceback object may be ``NULL `` even when the type object is not.
409449
410450 .. note ::
411451
412- This function is normally only used by code that needs to catch exceptions or
413- by code that needs to save and restore the error indicator temporarily, e.g.::
452+ This function is normally only used by legacy code that needs to catch
453+ exceptions or save and restore the error indicator temporarily.
454+
455+ For example::
414456
415457 {
416458 PyObject *type, *value, *traceback;
@@ -424,8 +466,14 @@ Querying the error indicator
424466
425467.. c :function :: void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
426468
427- Set the error indicator from the three objects. If the error indicator is
428- already set, it is cleared first. If the objects are ``NULL ``, the error
469+ .. deprecated :: 3.12
470+
471+ Use :c:func: `PyErr_SetRaisedException ` instead.
472+
473+ Set the error indicator from the three objects,
474+ *type *, *value *, and *traceback *,
475+ clearing the existing exception if one is set.
476+ If the objects are ``NULL ``, the error
429477 indicator is cleared. Do not pass a ``NULL `` type and non-``NULL `` value or
430478 traceback. The exception type should be a class. Do not pass an invalid
431479 exception type or value. (Violating these rules will cause subtle problems
@@ -436,13 +484,18 @@ Querying the error indicator
436484
437485 .. note::
438486
439- This function is normally only used by code that needs to save and restore the
440- error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current
441- error indicator.
487+ This function is normally only used by legacy code that needs to
488+ save and restore the error indicator temporarily.
489+ Use :c:func:`PyErr_Fetch` to save the current error indicator.
442490
443491
444492.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
445493
494+ .. deprecated :: 3.12
495+
496+ Use :c:func: `PyErr_GetRaisedException ` instead,
497+ to avoid any possible de-normalization.
498+
446499 Under certain circumstances, the values returned by :c:func: `PyErr_Fetch ` below
447500 can be "unnormalized", meaning that ``*exc `` is a class object but ``*val `` is
448501 not an instance of the same class. This function can be used to instantiate
@@ -704,6 +757,16 @@ Exception Objects
704757 :attr: `__suppress_context__ ` is implicitly set to ``True `` by this function.
705758
706759
760+ .. c :function :: PyObject* PyException_GetArgs (PyObject *ex)
761+
762+ Return :attr: `~BaseException.args ` of exception *ex *.
763+
764+
765+ .. c :function :: void PyException_SetArgs (PyObject *ex, PyObject *args)
766+
767+ Set :attr: `~BaseException.args ` of exception *ex * to *args *.
768+
769+
707770.. _unicodeexceptions :
708771
709772Unicode Exception Objects
0 commit comments