gh-150663: Document that PyErr_SetRaisedException() accepts NULL

[philthompson10]

Documented that PyErr_SetRaisedException() accepts NULL as the value of the exception being set.

• Issue: Document that PyErr_SetRaisedException() accepts NULL #150663

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32969998 | 📁 Comparing 4d07172 against main (46b5e3e)

  🔍 Preview build  

31 files changed · ± 31 modified

± Modified

• c-api/exceptions.html
• c-api/typehints.html
• howto/a-conceptual-overview-of-asyncio.html
• library/_thread.html
• library/array.html
• library/asyncio-future.html
• library/asyncio-task.html
• library/collections.html
• library/constants.html
• library/contextvars.html
• and 21 more...

[serhiy-storchaka]

The fact that it can be NULL should not be in a warning.

[ZeroIntensity]

Keep the warning, but only use it for the note about reference stealing. The sentence about exc being NULL should go in the body.

[serhiy-storchaka]

I think that it is better to use note instead of warning, like in PyList_SetItem and many other functions that steal references.

I suggest to add "If exc is NULL, just clear the existing exception." to the body and replace warning with note.

[philthompson10]

On 03/06/2026 13:17, Peter Bierma wrote: @ZeroIntensity commented on this pull request. > + A stolen reference to *exc* is set as the exception currently > being raised, + clearing the existing exception if one is set. *exc* may be ``NULL`` in Keep the warning, but only use it for the note about reference stealing. The sentence about `exc` being `NULL` should go in the body.

No other call in this section uses warnings for this information. Specifically `PyErr_Restore()` includes it in the body.

[ZeroIntensity]

1. It was there before and not causing any problems, so I don't see why we need to change it here. Doing so just makes merging this more prone to friction.
2. More generally, I don't think it's a good idea to base documentation decisions about PyErr_SetRaisedException on PyErr_Restore. By design, PyErr_SetRaisedException is much easier to use without a call to PyErr_GetRaisedException; in contrast, PyErr_Restore is almost exclusively called with a pair to PyErr_Fetch (because it's hard to get the exception triple from an arbitrary exception object), which makes it clearer that stealing is the intended choice.