From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 29 May 2021 17:49:16 +0000 (-0700)
Subject: bpo-44263: Mention PyType_Ready in the gc protocol warning (GH-26445) (#26446)
X-Git-Tag: v3.10.0b2~5
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d8ce746e7c5193757c8d316105870b0dc5d6fa53;p=thirdparty%2FPython%2Fcpython.git

bpo-44263: Mention PyType_Ready in the gc protocol warning (GH-26445) (#26446)

(cherry picked from commit 43cf7c864a2941b3f8f823e5928721dd286b7778)

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 338365b6657e..4bd2fb3837a1 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -38,8 +38,9 @@ Constructors for container types must conform to two rules:
       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
+      When calling :c:func:`PyType_Ready` or some of the APIs that indirectly
+      call it like :c:func:`PyType_FromSpecWithBases` or
+      :c:func:`PyType_FromSpec` the interpreter 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
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 9d24f39803f2..7a677593d073 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -97,6 +97,15 @@ Type Objects
    from a type's base class.  Return ``0`` on success, or return ``-1`` and sets an
    exception on error.
 
+   .. note::
+       If some of the base classes implements the GC protocol and the provided
+       type does not include the :const:`Py_TPFLAGS_HAVE_GC` in its flags, 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 implementing the
+       :c:member:`~PyTypeObject.tp_traverse` handle.
+
 .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
 
    Return the function pointer stored in the given slot. If the
@@ -169,13 +178,6 @@ 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