gh-158842: Add Py_SETREF() and Py_XSETREF() to the limited C API

[vstinner]

Test these macros with the limited C API in _testlimitedcapi and test_cext.

Move also other tests (refcount, Py_CLEAR, etc.) to _testlimitedcapi.

• Issue: [C API] Add Py_SETREF() and Py_XSETREF() macros to the limited C API 3.16 #158842

[vstinner]

cc @ngoldbaum @serhiy-storchaka @encukou

[vstinner]

Note: _testlimitedcapi.test_py_setref() checks that Py_SETREF/Py_XSETREF() arguments are only evaluated once.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34952784 | 📁 Comparing 7ce90fe against main (9112dae)

  🔍 Preview build  

4 files changed

± c-api/refcounting.html
± c-api/stable.html
± whatsnew/3.16.html
± whatsnew/changelog.html

[encukou]

Could you add them to stable_abi.toml, too?

[picnixz]

If this only moving code, then this LGTM.

[picnixz]

Could you add them to stable_abi.toml, too?

Oh right... I totally forgot about that. It's for the docs rendering right?

[vstinner]

Could you add them to stable_abi.toml, too?

Sure, done. I forgot that we also put macros in stable_abi.toml. I also added Py_CLEAR(). It seems like Py_CLEAR() was added to Python 2.4 (so it's available since limited C API 3.2).

[ngoldbaum]

It's for the docs rendering right?

I learned recently that abi3audit uses the toml table as input for a codegen script that generates the abi3audit implementation. I'd also like to use it in PyO3 for static checks. So downstream appreciates it being accurate and updated.

[vstinner]

@encukou: Oh, Doc/c-api/refcounting.rst has .. c:function:: void Py_CLEAR(PyObject *o) whereas Misc/stable_abi.toml has [macro.Py_CLEAR].

It makes Sphinx grumpy because it's once documented as a function, and then documented as a macro... Should I change the documentation to document Py_CLEAR() as a macro?

Sphinx error:

sphinx.errors.SphinxParallelError: sphinx.errors.ExtensionError: Handler <function add_annotations at 0x7172f4a81fd0> for event 'doctree-read' threw an exception (exception: Object type mismatch in limited API annotation for Py_CLEAR: 'macro' != 'function')

[encukou]

Maybe leave the existing ones to a different PR. As docs fixes, they're backportable.

…

On October 5, 2026 7:30:50 PM GMT+02:00, Victor Stinner ***@***.***> wrote: vstinner left a comment (python/cpython#158843) @encukou: Oh, Doc/c-api/refcounting.rst has `.. c:function:: void Py_CLEAR(PyObject *o)` whereas Misc/stable_abi.toml has `[macro.Py_CLEAR]`. It makes Sphinx grumpy because it's once documented as a function, and then documented as a macro... Should I change the documentation to document Py_CLEAR() as a macro? Sphinx error: `sphinx.errors.SphinxParallelError: sphinx.errors.ExtensionError: Handler <function add_annotations at 0x7172f4a81fd0> for event 'doctree-read' threw an exception (exception: Object type mismatch in limited API annotation for Py_CLEAR: 'macro' != 'function')` -- Reply to this email directly or view it on GitHub: #158843 (comment) You are receiving this because you were mentioned. Message ID: ***@***.***>

[vstinner]

Maybe leave the existing ones to a different PR. As docs fixes, they're backportable.

I created issue #158886 and PR #158887 to add all old macros of the limited C API to Misc/stable_abi.toml, not only Py_CLEAR() :-)

[vstinner]

Check labels / Unresolved review (pull_request): Cancelled after 15m

I'm not sure why this job took 15 minutes. It seems like something went wrong. I clicked on re-run failed jobs.

[vstinner]

Merged. Thanks for reviews!

[encukou]

Thank you!