Description
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/python-dev@python.org/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.