gh-127443: Add semantics for stolen references in Doc/data/refcounts.dat

[picnixz]

For now, it only changes the entry that are know to be stealing references. I'd like to have some help here: if you know which functions steals references, just drop the name and I'll update the PR (it's hard for me to find them automatically...).

This PR should be merged after #127451 and probably before #127443 so that I can use the new symbol and don't need to update the comment.

• Issue: Improve and maintain Doc/data/refcounts.dat #127443

---

📚 Documentation preview 📚: https://cpython-previews--127468.org.readthedocs.build/

[picnixz]

Some functions that steal references but are not yet included/fixed (waiting for other PRs):

• PyModule_Add (added in gh-127443: Update refcounts data with stable ABI functions. #127444)
• PyErr_SetRaisedException (fixed in gh-127443: fix some entries in Doc/data/refcounts.dat #127451)

[ZeroIntensity]

I will say, there are some functions that do truly steal a reference by DECREFing the input. For example, PyModule_AddObject--do we want to treat that with $, or with -1?

[picnixz]

If they DECREF the input maybe a -1 + comment is better? or maybe $$ that it stole even more things!

[ZeroIntensity]

I'll let you decide :)

[encukou]

I will say, there are some functions that do truly steal a reference by DECREFing the input. For example, PyModule_AddObject--do we want to treat that with $, or with -1?

On success, PyModule_AddObject steals a reference in the usual way: it does PyModule_AddObjectRef (+1) and Py_DECREF (-1).

However, on error it does not steal a reference -- it does failed PyModule_AddObjectRef (+0) and skips the decref. Still ±0 as far as refcounts.dat is concerned, but the caller ends up owning the reference in this case.
I assume most of the +1 for arguments are incorrect in error cases.
Adding stolen is an improvement; IMO we should also add borrowed where we know an argument is not stolen/weird, so it's possible to know what's been checked.

[encukou]

Would it make sense to prefix existing comments with #, and leave field 5 to annotations like stolen?
Existing tools (if there are any) would treat the whole thing as a comment.

[picnixz]

After a discussion with Petr, I think it would better not to introduce new semantics for now. The idea is to make the last field hold some special attributes. Those attributes would indicate stolen. This is also better to do it like this because existing tools (if any) may fail to parse $ tokens (technically... our own Sphinx extension failed on them).

So I'll close this one but will definitely re-use the data from here.

---

Note: I could limit myself to modifying the 5th field, but until I've written the tool and the correct syntax I expect, I prefer minimizing the commits.