PyObject_SetAttr, when called with value == NULL, actually deletes the attribute, but the documentation doesn't say it. It mentions PyObject_DelAttr, but it is only a macro and can therefore not be looked up using e.g. ctypes.

See two alternative issues: issue25701 for documenting existing behavior, and issue25773 for deprecating it (and converting PyObject_DelAttr to a function).

As of Issue 25701, the null-to-delete feature is documented as being deprecated in favour of calling the related Del functions or macros. There was a python-dev thread at <https://marc.info/[email protected]>.

I’m not sure if that is good enough, or do we need to e.g. clarify that the deprecation is only at the API (C header) level, and not the ABI level?

This behaviour is documented as deprecated all the way back to 2.7. Should we repurpose the issue to removing it? Otherwise it can be closed.

https://docs.python.org/2.7/c-api/object.html#c.PyObject_SetAttr

I read the python-dev thread now and I see it was decided that it’s not worth removing it.

In recent versions of the doc it is mentioned that the function is in the stable ABI. Should we clarify exactly what is meant by ‘deprecated’?

This cannot be changed in 3.x, since the PyObject_DelAttr macro calls PyObject_SetAttr(..., NULL), and the macro is expanded in all extensions that use the stable ABI.
(Technically, it would be possible to add a PyObject_SetAttr *macro* that would warn/fail, while keeping the PyObject_SetAttr *function* untouched, but that would be a pain to test/maintain.) 

The wording could be clarified to something like: "This behaviour is deprecated in favour of using PyObject_DelAttr(), but there are currently no plans to remove it."

New changeset 3bf6315c4cabf72d64e65e6f85bf72c65137255a by Irit Katriel in branch 'main':
bpo-22039: [doc] clarify that there are no plans to disable deleting an attribute via PyObject_SetAttr (GH-30639)
https://github.com/python/cpython/commit/3bf6315c4cabf72d64e65e6f85bf72c65137255a

New changeset 7b694b816f30c463ffcab0952d3319320d23e154 by Miss Islington (bot) in branch '3.9':
[3.9] bpo-22039: [doc] clarify that there are no plans to disable deleting an attribute via PyObject_SetAttr (GH-30639) (GH-30685)
https://github.com/python/cpython/commit/7b694b816f30c463ffcab0952d3319320d23e154

New changeset 0861a50bd434d1f3e12fe7122e37356f1fce93dc by Miss Islington (bot) in branch '3.10':
bpo-22039: [doc] clarify that there are no plans to disable deleting an attribute via PyObject_SetAttr (GH-30639) (GH-30684)
https://github.com/python/cpython/commit/0861a50bd434d1f3e12fe7122e37356f1fce93dc