Skip to content

gh-150663: Document that PyErr_SetRaisedException accepts null #153046

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

Open
hrimov wants to merge 2 commits into
base: main
Choose a base branch
from
+4 −4
Open

gh-150663: Document that PyErr_SetRaisedException accepts null #153046

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4346e25
Document that PyErr_SetRaisedException accepts null
hrimov Jul 4, 2026
ba55411
Use note instead of warning and tweak null wording
hrimov Jul 4, 2026
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
8 changes: 4 additions & 4 deletions Doc/c-api/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -499,12 +499,12 @@ Querying the error indicator
.. c:function:: void PyErr_SetRaisedException(PyObject *exc)

Set *exc* as the exception currently being raised,
clearing the existing exception if one is set.
clearing the existing exception if one is set. If *exc* is ``NULL``,
just clear the existing exception.

@vstinner vstinner Jul 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest adding a new paragraph:

*exc must be a valid exception or ``NULL``.

@vstinner vstinner Jul 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
just clear the existing exception.
just clear the existing exception.
This call ":term:`steals <steal>`" a reference to *exc*.


.. warning::
.. note::

@vstinner vstinner Jul 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that it deserves to be documented as a note. Other PyErr functions also steal a reference, and they don't use a note or warning, but just write it in the documentation body.


This call ":term:`steals <steal>`" a reference to *exc*,
which must be a valid exception.

@ZeroIntensity ZeroIntensity Jul 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this line is helpful. We should just say "must be a valid exception or NULL".

This call ":term:`steals <steal>`" a reference to *exc*.

.. versionadded:: 3.12

Expand Down
Loading