gh-137791: Improve documentation for the reference counting changes in 3.14

[ZeroIntensity]

• Issue: Please document the exact changes you made in how reference counting changed for 3.14 internally for C-API developers #137791

---

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

[Fidget-Spinner]

I don't know if this is what the OP actually meant. Negative reference counts might not be caused by the REFCNT(n) == 1 issue but rather some other symptom of the borrowed references that we use.

I hope the OP responds soon what they actually mean, and point to an actual issue/code.

[ZeroIntensity]

Negative reference counts might not be caused by the REFCNT(n) == 1 issue but rather some other symptom of the borrowed references that we use.

Agreed. I'm trying to clarify that the borrowed reference changes only affect code in very niche cases.

[AA-Turner]

It doesn't feel great to suggest people move from a (theoretically) stable Py_REFCNT(op) == 1 to an explicitly unstable PyUnstable_ function.

Can we explain why the function we suggest users port to is marked as unstable (e.g. that in reality, Py_REFCNT(op) == 1 was less stable than it appeared?).

Per Petr's comment on the issue, if this is strictly a breaking change, the note in refcounting.rst should probably be more explicit that in previous versions, the semantics around 1 and 0 were guaranteed, but that they no longer are.

[ZeroIntensity]

0 is still guaranteed, as far as I know. I'll do my best to make things clearer otherwise.

[ZeroIntensity]

I've updated both notes. Let me know if that looks any better.

[aisk]

Nitpick:

Suggested change

	be ``1`` even when an object has more than one reference in the interpreter
	be ``1`` even when the object has more than one reference in the interpreter

[ZeroIntensity]

I think the current wording is fine. It's not clear to me what "the object" would refer to, because there isn't an example.

[aisk]

I think "the object" is refer to "the :term:reference count of an object" just in this sentence, but I know this is a nitpick, so current wording is totally fine to me.

[efimov-mikhail]

Should we also make changes to this docs?

cpython/Doc/library/sys.rst

Lines 914 to 918 in d396a32

	.. function:: getrefcount(object)
	Return the reference count of the *object*. The count returned is generally one
	higher than you might expect, because it includes the (temporary) reference as
	an argument to :func:`getrefcount`.

[ZeroIntensity]

I don't think there was much of an appetite for documenting this, so I'm going to close this.