diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 57a0728d4e9af4..9d721997b7e885 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -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. @@ -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) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index f33c20fbf31c0a..e1c807a4cf4e40 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -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 ` 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 ` 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 + 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: