Visitar URL original
gh-101578: Amend PyErr_{Set,Get}RaisedException docs by erlend-aasland · Pull Request #101962 · python/cpython · GitHub
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erlend-aasland merged 6 commits into from
Feb 19, 2023
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fd0dde1
gh-101578: Amend PyErr_{Set,Get}RaisedException docs
erlend-aasland Feb 16, 2023
415a70d
Address CAM's first round of review
erlend-aasland Feb 17, 2023
45ecfe5
Address CAM's second round of review
erlend-aasland Feb 17, 2023
02334f4
Move seealso to get API
erlend-aasland Feb 17, 2023
3cf91f8
Fixup seealo, hopefully for real this time
erlend-aasland Feb 17, 2023
fd94dd8
Update Doc/c-api/exceptions.rst
erlend-aasland Feb 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
gh-101578: Amend PyErr_{Set,Get}RaisedException docs
  • Loading branch information
@erlend-aasland
erlend-aasland committed Feb 16, 2023
commit fd0dde1e0c599e1e4bde0ee2a02ca806745449e0
49 changes: 19 additions & 30 deletions Doc/c-api/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -402,51 +402,40 @@ 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.::
Example::
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

{
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);
}

Use :c:func:`PyErr_GetHandledException` to fetch the exception
currently being handled.
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

.. seealso:: :c:func:`PyErr_SetRaisedException`
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

.. 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.

``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.)
Set *exc* as the exception currently being raised.
If another exception is already raised, it is cleared first.
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

.. note::
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

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();
This call steals a reference to *exc*, which must be a valid exception.

/* ... code that might produce other errors ... */

PyErr_SetRaisedException(exc);
}
.. seealso:: :c:func:`PyErr_GetRaisedException`
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated

.. versionadded:: 3.12

Expand Down
3 changes: 3 additions & 0 deletions Doc/data/refcounts.dat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down