[3.14] 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 f6fa52b36c5ab31a1ab3909fd1bceb6d6b68ba41..fed795b1e8c963715b3ac9c487fb6371b0039be6 100644 (file)
--- 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 b2e8626cb6e8119a9edd9d99b108cb2337f1c792..42bfbeccff142967a5a35c48ae9581069001ec85 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1554,6 +1554,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.