https://github.com/python/cpython/commit/2c3e3ef6a267de2f3f30a66cc3f13210c2f32351 commit: 2c3e3ef6a267de2f3f30a66cc3f13210c2f32351 branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: colesbury <[email protected]> date: 2025-12-08T17:28:21Z summary:
[3.13] gh-123241: Document restrictions for `tp_traverse` implementations (gh-142272) (#142422) (cherry picked from commit 37988c57ea244b0ed2f969e9c6039710dfe8f31d) Co-authored-by: Sam Gross <[email protected]> files: M Doc/c-api/gcsupport.rst M Doc/c-api/typeobj.rst diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 3e23605778f05a..afec8cbea93bcc 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 0b816e4a7036ad..d03cfe9c62de0a 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. _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
