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.12] gh-98154: Clarify Usage of "Reference Count" In the Docs (gh-107552) (#107752)

Browse source 
* gh-98154: Clarify Usage of "Reference Count" In the Docs (gh-107552)

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.  It also updates the docs relative to immortal objects in a handful of places.
(cherry picked from commit 5dc825d504)

Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>

* Fix a typo.

---------

Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
This commit is contained in:
Miss Islington (bot) 2023-08-08 07:25:35 -07:00 • committed by GitHub
parent e5582bdbcf
commit aa2ecef22a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 162 additions and 90 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -571,7 +571,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`.
@ -1445,11 +1445,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.)