[Python-checkins] bpo-44263: Better explain the GC contract for PyType_FromSpecWithBases (GH-26442)
miss-islington
webhook-mailer at python.org
Fri May 28 23:21:02 EDT 2021
https://github.com/python/cpython/commit/a30cbaee84262cdd4597f3204861ccdd86bbf533
commit: a30cbaee84262cdd4597f3204861ccdd86bbf533
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-05-28T20:20:54-07:00
summary:
bpo-44263: Better explain the GC contract for PyType_FromSpecWithBases (GH-26442)
(cherry picked from commit 8b55bc3f93a655bc803bff79725d5fe3f124e2f0)
Co-authored-by: Pablo Galindo <Pablogsal at gmail.com>
files:
M Doc/c-api/gcsupport.rst
M Doc/c-api/type.rst
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index eee114c19d5904..76f9ab53b4f31a 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 ee76f52289387f..d694b8caf17996 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -168,6 +168,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
More information about the Python-checkins
mailing list