From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 8 Dec 2025 17:28:21 +0000 (+0100)
Subject: [3.13] gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272... 
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2c3e3ef6a267de2f3f30a66cc3f13210c2f32351;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272) (#142422)

(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 3e23605778f0..afec8cbea93b 100644
--- 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 0b816e4a7036..d03cfe9c62de 100644
--- 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.