Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Doc/c-api/exceptions.rst
View File

@ -402,51 +402,36 @@ Querying the error indicator
.. 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`.
Return the exception currently being raised, clearing the error indicator at
the same time.
.. 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
by code that needs to save and restore the error indicator temporarily, e.g.::
For example::
{
PyObject *exc = PyErr_GetRaisedException();
{
PyObject *exc = PyErr_GetRaisedException();
/* ... code that might produce other errors ... */
/* ... code that might produce other errors ... */
PyErr_SetRaisedException(exc);
}
PyErr_SetRaisedException(exc);
}
.. seealso:: :c:func:`PyErr_GetHandledException`,
to save the exception currently being handled.
.. 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.
Set *exc* as the exception currently being raised,
clearing the existing exception if one is set.
``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.)
.. warning::
.. 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);
}
This call steals a reference to *exc*, which must be a valid exception.
.. 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**:ptraceback:+1:
PyErr_GetRaisedException:PyObject*::+1:
PyErr_SetRaisedException::::
PyErr_GivenExceptionMatches:int:::
PyErr_GivenExceptionMatches:PyObject*:given:0:
PyErr_GivenExceptionMatches:PyObject*:exc:0: