mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-19 00:00:48 +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

13
Doc/c-api/object.rst
View file

@ -15,8 +15,8 @@ Object Protocol
.. c:macro:: Py_RETURN_NOTIMPLEMENTED
Properly handle returning :c:data:`Py_NotImplemented` from within a C
function (that is, increment the reference count of NotImplemented and
return it).
function (that is, create a new :term:`strong reference`
to NotImplemented and return it).
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
@ -320,11 +320,12 @@ Object Protocol
When *o* is non-``NULL``, returns a type object corresponding to the object type
of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
is equivalent to the Python expression ``type(o)``.
This function creates a new :term:`strong reference` to the return value.
There's really no reason to use this
function instead of the :c:func:`Py_TYPE()` function, which returns a
pointer of type :c:expr:`PyTypeObject*`, except when the incremented reference
count is needed.
pointer of type :c:expr:`PyTypeObject*`, except when a new
:term:`strong reference` is needed.
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)