From 2c3e3ef6a267de2f3f30a66cc3f13210c2f32351 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 8 Dec 2025 18:28:21 +0100 Subject: [PATCH] [3.13] gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272) (#142422) (cherry picked from commit 37988c57ea244b0ed2f969e9c6039710dfe8f31d) Co-authored-by: Sam Gross --- Doc/c-api/gcsupport.rst | 4 ++++ Doc/c-api/typeobj.rst | 5 +++++ 2 files changed, 9 insertions(+) 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. -- 2.47.3