Add Py_SETREF() and Py_XSETREF() macros to the limited C API 3.12

[vstinner]

The Py_SETREF() and Py_XSETREF() macros were added to Python 3.6 (and 3.5.2) in 2016 with commit 57a01d3.

In 2017, Serhiy @serhiy-storchaka proposed to add these two macros to the limited C API: https://mail.python.org/archives/list/[email protected]/thread/HGBT2Y4VAZOOU5XI2RPSURDGFBMRJKPO/ But these macros were not added.

Py_CLEAR() is already part of the limited C API (since Python 3.2) and is very similar to Py_SETREF(). Py_CLEAR() rely on the C preprocessor to get a reference to a variable, so the variable can be set to NULL without having to pass a pointer to the variable. The usage is Py_CLEAR(var), rather than Py_CLEAR(&var). The Py_SETREF() macro does the same, but the value is passed by the caller, it's not always NULL.

Multiple projects use these macros. Code search in PyPI top 5000 projects using (Py_SETREF|Py_XSETREF) regex. 16 projects (177 matching lines in total):

• bitarray-2.6.0
• coverage-6.4.4
• datatable-1.0.0
• gnureadline-8.1.2
• immutables-0.18
• inflate64-0.3.0
• iteration_utilities-0.11.0
• mypy-0.971
• numpy-1.23.2
• pandas-1.4.4
• pickle5-0.0.12
• python-rapidjson-1.8
• python-snappy-0.6.1
• scipy-1.9.1
• typed_ast-1.5.4
• zstd-1.5.2.5

numpy and the pythoncapi-compat project (code) define these macros on Python older than 3.5.2.

I propose to add Py_SETREF() and Py_XSETREF() macros to the limited C API of Python 3.12.

By the way, I recently documented these two macros in Python 3.12 (commit c03e05c): https://docs.python.org/dev/c-api/refcounting.html#c.Py_SETREF

See also issue #98724 and its PR #99100 which discuss Py_CLEAR(), Py_SETREF() and Py_XSETREF() in length.

---

I would prefer exposing functions (taking a reference to a variable, &var) which can be used when C macros cannot be used, for example in Rust or other programming languages. But adding functions is a different which can be addressed separately.

Linked PRs

• gh-99574: Add Py_SETREF() to the limited C API #99575

[vstinner]

Obviously, since Py_SETREF() and Py_XSETREF() are macros, they are not part of the stable ABI. I only propose to add them to the limited C API.

[serhiy-storchaka]

Since the previous attempt to add them failed, should not it be discussed in more public place?