From 43cf7c864a2941b3f8f823e5928721dd286b7778 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Sat, 29 May 2021 04:32:42 +0100 Subject: bpo-44263: Mention PyType_Ready in the gc protocol warning (GH-26445) --- Doc/c-api/gcsupport.rst | 5 +++-- Doc/c-api/type.rst | 16 +++++++++------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 338365b..4bd2fb3 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 9d24f39..7a67759 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 -- cgit v0.12