bpo-44263: Better explain the GC contract for PyType_FromSpecWithBases (GH-26442) (GH-26443)
(cherry picked from commit 8b55bc3f93a655bc803bff79725d5fe3f124e2f0)
Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index 55ed9d4..338365b 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -33,6 +33,17 @@
#. Once all the fields which may contain references to other containers are
initialized, it must call :c:func:`PyObject_GC_Track`.
+ .. warning::
+ If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least
+ a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one
+ from its subclass or subclasses.
+
+ Some APIs like :c:func:`PyType_FromSpecWithBases` or
+ :c:func:`PyType_FromSpec` will automatically populate the
+ :c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
+ and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
+ class that implements the garbage collector protocol and the child class
+ does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)