Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-31 04:23:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-123241: Document restrictions for tp_traverse implementations (gh-142272)

Browse source
This commit is contained in:
Sam Gross 2025-12-08 12:22:13 -05:00 • committed by GitHub
parent f2fba4c99a
commit 37988c57ea
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 9 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/c-api/gcsupport.rst
View file

@ -232,6 +232,10 @@ The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
object argument. If *visit* returns a non-zero value that value should be
returned immediately.
The traversal function must not have any side effects. Implementations
may not modify the reference counts of any Python objects nor create or
destroy any Python objects.
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
must name its arguments exactly *visit* and *arg*:

5
Doc/c-api/typeobj.rst
View file

@ -1569,6 +1569,11 @@ and :c:data:`PyType_Type` effectively act as defaults.)
but the instance has no strong reference to the elements inside it, as they
are allowed to be removed even if the instance is still alive).
.. warning::
The traversal function must not have any side effects. It must not
modify the reference counts of any Python objects nor create or destroy
any Python objects.
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
:c:func:`!local_traverse` to have these specific names; don't name them just
anything.