From: Sam Gross <colesbury@gmail.com>
Date: Mon, 8 Dec 2025 17:22:13 +0000 (-0500)
Subject: gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272)
X-Git-Tag: v3.15.0a3~156
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=37988c57ea244b0ed2f969e9c6039710dfe8f31d;p=thirdparty%2FPython%2Fcpython.git

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

diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index f6fa52b36c5a..fed795b1e8c9 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -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*:
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 49fe02d919df..efac86078f9a 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -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.