gh-158886: Add macros of the limited C API to stable_abi.toml

[vstinner]

• Issue: [C API] Add all macros to Misc/stable_abi.toml #158886

[vstinner]

The Doctest job fails with:

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

I documented PyObject_New() as a function in stable_abi.toml ([function.PyObject_New]) to fix to fix Doctest, but it doesn't work as expected.

Problem: macros declared as functions by stable_abi.toml are checked by Lib/test/test_stable_abi_ctypes.py which fails since they are macros and not functions...

[vstinner]

I updated the PR to document all macros as macros, not as functions.

[vstinner]

Updated Doctest error:

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

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34957345 | 📁 Comparing 1db4cb9 against main (eab2d16)

  🔍 Preview build  

33 files changed · ± 33 modified

± Modified

• c-api/allocation.html
• c-api/bool.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• c-api/complex.html
• c-api/curses.html
• c-api/dict.html
• c-api/exceptions.html
• c-api/float.html
• and 23 more...

[vstinner]

I updated Doc/tools/extensions/c_annotations.py to accept that some documented functions are defined as macros by stable_abi.toml.

[encukou]

Could you limit this PR to the refcounting macros, and keep the issue open for the rest?
I don't think they should all be added at once.

---

One problem is that this annotates macros as “Part of the stable ABI”:

But, macros are not ABI.

We already have this issue with, for example, Py_BEGIN_ALLOW_THREADS, but there it's at least clear from the prose (or context) that it's a macro. Adding this to things documented as functions would be misleading.

---

For macros like Py_ULL or PyAPI_DATA, I think it would be better to treat them as exposed by mistake, rather than limited API. For ones like Py_IS_FINITE, we probably need more discussion (or not -- we can leave them in a gray area and focus on other stuff).

For macros like PyBytes_Check, IMO we should document the (approximate) expansion, so wrappers like PyO3 can reimplement them using just the stable ABI.