Document that `PyErr_SetRaisedException()` accepts NULL

[philthompson10]

Documentation

The warning states that exc must be a valid exception. However NULL is also a valid value.

Linked PRs

• gh-150663: Document that PyErr_SetRaisedException() accepts NULL #150705
• gh-150663: Document that PyErr_SetRaisedException accepts null #153046
• [3.15] gh-150663: Document that PyErr_SetRaisedException accepts null (GH-153046) #154021
• [3.14] gh-150663: Document that PyErr_SetRaisedException accepts null (GH-153046) #154022
• [3.13] gh-150663: Document that PyErr_SetRaisedException accepts null (GH-153046) #154023

[picnixz]

I don't consider this as a "valid value". Sure we don't forbid it but it's an implementation detail.

[philthompson10]

On 31/05/2026 18:51, Bénédikt Tran wrote: picnixz left a comment (python/cpython#150663) I don't consider this as a "valid value". Sure we don't forbid it but it's an implementation detail.

The example code for PyErr_GetRaisedException() assumes NULL is a legitimate value. The API would be a pain to use if it wasn’t and a test was required for reliable behaviour.

[picnixz]

I still think it's an implementation detail. What is the problem of not documenting NULL as being allowed? for clearing an exception, use PyErr_Clear() or if you want the exception, use PyErr_GetRaisedException().

I don't think it makes sense to use NULL with PyErr_SetRaisedException().

[philthompson10]

On 31/05/2026 19:58, Bénédikt Tran wrote: picnixz left a comment (python/cpython#150663) I still think it's an implementation detail. What is the problem of not documenting NULL as being allowed? for clearing an exception, use `PyErr_Clear()` or if you want the exception, use `PyErr_GetRaisedException()`. I don't think it makes sense to use NULL with `PyErr_SetRaisedException()`.

The getter and setter are normally used as a pair. The getter will return NULL if there is no current exception so the setter should accept NULL. The setter is being used to restore the previous state, whether there was an exception or not.

[picnixz]

I'm sorry but clearing the exception should not be achieved using PyErr_SetRaisedException. I would prefer that users do not use that to clear the exception and rather use PyErr_Clear().

But if @vstinner wants to document this implementation detail, I won't block.

[philthompson10]

On 31/05/2026 21:51, Bénédikt Tran wrote: picnixz left a comment (python/cpython#150663) I'm sorry but clearing the exception should not be achieved using `PyErr_SetRaisedException`. I would prefer that users do not use that to clear the exception and rather use `PyErr_Clear()`. But if @vstinner wants to document this implementation detail, I won't block.

PyErr_SetRaisedException() is a replacement for PyErr_Restore() which is documented to clear the current exception if a NULL exception is passed.

[encukou]

I'm not @vstinner, but I'm strongly +1 on documenting NULL. The getter and setter are not only used as a pair, they're also used in situations where you don't care about whether an exception is set -- for example:

cpython/Modules/xxlimited.c

Lines 272 to 286 in f4bda4d

	// This function must preserve currently raised exception, if any.
	PyObject *exc = PyErr_GetRaisedException();
	PyObject_GC_UnTrack(self);
	Xxo_finalize(self);
	PyTypeObject *tp = Py_TYPE(self);
	freefunc free = PyType_GetSlot(tp, Py_tp_free);
	free(self);
	Py_DECREF(tp);
	if (PyErr_Occurred()) {
	PyErr_WriteUnraisable(NULL);
	}
	PyErr_SetRaisedException(exc);

Requiring an extra if here would be too much purity over practicality.

[picnixz]

Ok I'm convinced with this pattern.