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.