[3.13] gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272...

(cherry picked from commit 37988c57ea244b0ed2f969e9c6039710dfe8f31d)

Co-authored-by: Sam Gross <colesbury@gmail.com>

diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index 3e23605778f05a73d56efc3c22757e3be0510209..afec8cbea93bccd5504e653077f1b76b2068c481 100644 (file)
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -175,6 +175,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*:

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 0b816e4a7036ad0d7fdfb970b578c7e39bc3c0cb..d03cfe9c62de0a937dbf59c7d385857acf670c48 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1483,6 +1483,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.