gh-137791: Improve documentation for the reference counting changes in 3.14 #137819
Conversation
|
I don't know if this is what the OP actually meant. Negative reference counts might not be caused by the I hope the OP responds soon what they actually mean, and point to an actual issue/code. |
Agreed. I'm trying to clarify that the borrowed reference changes only affect code in very niche cases. |
Doc/whatsnew/3.14.rst
Outdated
| references <strong reference>` is avoided in the Python interpreter. This | ||
| generally does not affect existing code, but C API extensions that checked | ||
| :c:func:`Py_REFCNT` of ``1`` to determine if an object is not referenced by | ||
| any other code should instead use :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
0 is still guaranteed, as far as I know. I'll do my best to make things clearer otherwise.
There was a problem hiding this comment.
I've updated both notes. Let me know if that looks any better.
📚 Documentation preview 📚: https://cpython-previews--137819.org.readthedocs.build/