From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 29 May 2021 03:21:26 +0000 (-0700)
Subject: bpo-44263: Better explain the GC contract for PyType_FromSpecWithBases (GH-26442... 
X-Git-Tag: v3.10.0b2~7
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=11049bece15b6fa08fa6d74aea8eb6bc2ebadfe5;p=thirdparty%2FPython%2Fcpython.git

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 55ed9d4f7fad..338365b6657e 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -33,6 +33,17 @@ Constructors for container types must conform to two rules:
 #. 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)
 
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index bdb636dff326..9d24f39803f2 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -169,6 +169,13 @@ The following functions and structs are used to create
    The associated module is not inherited by subclasses; it must be specified
    for each class individually.
 
+   If some of the bases in *bases* implements the GC protocol and the type being
+   created does not include the :const:`Py_TPFLAGS_HAVE_GC` in the flags included in
+   *spec*, then the GC protocol will be automatically implemented from its parents. On
+   the contrary, if the type being created does include :const:`Py_TPFLAGS_HAVE_GC` in
+   its flags then it *must* implement the GC protocol itself by at least including a slot
+   for :c:member:`~PyTypeObject.tp_traverse` in *spec*.
+
    This function calls :c:func:`PyType_Ready` on the new type.
 
    .. versionadded:: 3.9