mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-16 06:40:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.11] gh-98154: Clarify Usage of "Reference Count" In the Docs (gh-107753)

Browse source 
PEP 683 (immortal objects) revealed some ways in which the Python documentation has been unnecessarily coupled to the implementation details of reference counts.  In the end users should focus on reference ownership, including taking references and releasing them, rather than on how many reference counts an object has.

This change updates the documentation to reflect that perspective.
This commit is contained in:
Eric Snow 2023-08-07 16:17:12 -06:00 • committed by GitHub
parent 22b39d13ec
commit 951320e4d0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 123 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

12
Doc/c-api/unicode.rst
View file

@ -576,7 +576,7 @@ APIs:
Copy an instance of a Unicode subtype to a new true Unicode object if
necessary. If *obj* is already a true Unicode object (not a subtype),
return the reference with incremented refcount.
return a new :term:`strong reference` to the object.
Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
@ -1537,11 +1537,11 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
Intern the argument *\*string* in place. The argument must be the address of a
pointer variable pointing to a Python Unicode string object. If there is an
existing interned string that is the same as *\*string*, it sets *\*string* to
it (decrementing the reference count of the old string object and incrementing
the reference count of the interned string object), otherwise it leaves
*\*string* alone and interns it (incrementing its reference count).
(Clarification: even though there is a lot of talk about reference counts, think
of this function as reference-count-neutral; you own the object after the call
it (releasing the reference to the old string object and creating a new
:term:`strong reference` to the interned string object), otherwise it leaves
*\*string* alone and interns it (creating a new :term:`strong reference`).
(Clarification: even though there is a lot of talk about references, think
of this function as reference-neutral; you own the object after the call
if and only if you owned it before the call.)