mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-04 03:44:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

gh-101578: Amend PyErr_{Set,Get}RaisedException docs (#101962)

Browse source 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Erlend E. Aasland 2023-02-19 21:22:29 +01:00 • committed by GitHub
parent 3b264df470
commit 60bbed7f17
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 20 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

39
Doc/c-api/exceptions.rst
View file

@ -402,14 +402,13 @@ Querying the error indicator
.. c:function:: PyObject *PyErr_GetRaisedException(void) .. c:function:: PyObject *PyErr_GetRaisedException(void)
Returns the exception currently being raised, clearing the exception at Return the exception currently being raised, clearing the error indicator at
the same time. Do not confuse this with the exception currently being the same time.
handled which can be accessed with :c:func:`PyErr_GetHandledException`.
.. note:: This function is used by code that needs to catch exceptions,
or code that needs to save and restore the error indicator temporarily.
This function is normally only used by code that needs to catch exceptions or For example::
by code that needs to save and restore the error indicator temporarily, e.g.::
{ {
PyObject *exc = PyErr_GetRaisedException(); PyObject *exc = PyErr_GetRaisedException();
@ -419,34 +418,20 @@ Querying the error indicator
PyErr_SetRaisedException(exc); PyErr_SetRaisedException(exc);
} }
.. seealso:: :c:func:`PyErr_GetHandledException`,
to save the exception currently being handled.
.. versionadded:: 3.12 .. versionadded:: 3.12
.. c:function:: void PyErr_SetRaisedException(PyObject *exc) .. c:function:: void PyErr_SetRaisedException(PyObject *exc)
Sets the exception currently being raised ``exc``. Set *exc* as the exception currently being raised,
If the exception is already set, it is cleared first. clearing the existing exception if one is set.
``exc`` must be a valid exception. .. warning::
(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 call steals a reference to *exc*, which must be a valid exception.
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 .. versionadded:: 3.12

3
Doc/data/refcounts.dat
View file

@ -606,6 +606,9 @@ PyErr_GetExcInfo:PyObject**:ptype:+1:
PyErr_GetExcInfo:PyObject**:pvalue:+1: PyErr_GetExcInfo:PyObject**:pvalue:+1:
PyErr_GetExcInfo:PyObject**:ptraceback:+1: PyErr_GetExcInfo:PyObject**:ptraceback:+1:
PyErr_GetRaisedException:PyObject*::+1:
PyErr_SetRaisedException::::
PyErr_GivenExceptionMatches:int::: PyErr_GivenExceptionMatches:int:::
PyErr_GivenExceptionMatches:PyObject*:given:0: PyErr_GivenExceptionMatches:PyObject*:given:0:
PyErr_GivenExceptionMatches:PyObject*:exc:0: PyErr_GivenExceptionMatches:PyObject*:exc:0: