Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

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

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
35a8494
Improve the Py_REFCNT() documentation for 3.14.
ZeroIntensity Aug 15, 2025
ee1f95b
Improve 3.14 whatsnew about reference counting changes.
ZeroIntensity Aug 15, 2025
b807f77
Use a clearer note for Py_REFCNT().
ZeroIntensity Aug 15, 2025
ad6c98c
Try to clarify that this is a breaking change in Python 3.14.
ZeroIntensity Aug 15, 2025
bb49de8
Merge branch 'main' into 314-refcount-changes
AA-Turner Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion Doc/c-api/refcounting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ of Python objects.
references to the object are actually held. For example, some
objects are :term:`immortal` and have a very high refcount that does not
reflect the actual number of references. Consequently, do not rely
on the returned value to be accurate, other than a value of 0 or 1.
on the returned value to be accurate.

Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count.

Expand All @@ -38,6 +38,10 @@ of Python objects.
.. versionchanged:: 3.11
The parameter type is no longer :c:expr:`const PyObject*`.

.. versionchanged:: 3.14
A return value of 1 is no longer sufficient to determine that *o* is
solely referenced by the caller.


.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Expand Down
12 changes: 9 additions & 3 deletions Doc/whatsnew/3.14.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3046,10 +3046,16 @@ Porting to Python 3.14
* The interpreter internally avoids some reference count modifications when
loading objects onto the operands stack by :term:`borrowing <borrowed reference>`
references when possible. This can lead to smaller reference count values
compared to previous Python versions. C API extensions that checked
:c:func:`Py_REFCNT` of ``1`` to determine if an function argument is not
compared to previous Python versions, because the creation of :term:`strong
references <strong reference>` is avoided in the Python interpreter.

This means that in Python 3.14, the :term:`reference count` of an object can
be ``1`` even when an object has more than one reference in the interpreter
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

stack. 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` as a safer replacement.
:c:func:`PyUnstable_Object_IsUniqueReferencedTemporary` as a safer
replacement.


* Private functions promoted to public C APIs:
Expand Down
Loading