[Python-checkins] gh-99249: Clarify "read-only" slots tp_bases & tp_mro (GH-99342)

Mon Nov 28 03:22:27 EST 2022

https://github.com/python/cpython/commit/219696abb240607d3f807853c4c180825e60716e
commit: 219696abb240607d3f807853c4c180825e60716e
branch: main
author: Petr Viktorin <encukou at gmail.com>
committer: encukou <encukou at gmail.com>
date: 2022年11月28日T09:22:08+01:00
summary:
gh-99249: Clarify "read-only" slots tp_bases & tp_mro (GH-99342)
These slots are marked "should be treated as read-only" in the
table at the start of the document. That doesn't say anything about
setting them in the static struct.
`tp_bases` docs did say that it should be ``NULL`` (TIL!). If you
ignore that, seemingly nothing bad happens. However, some slots
may not be inherited, depending on which sub-slot structs are present.
(FWIW, NumPy sets tp_bases and is affected by the quirk -- though to
be fair, its DUAL_INHERIT code probably predates tp_bases docs, and
also the result happens to be benign.)
This patch makes things explicit.
It also makes the summary table legend easier to scan.
Co-authored-by: Kumar Aditya <59607654+kumaraditya303 at users.noreply.github.com>
files:
M Doc/c-api/typeobj.rst

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 4c462f460567..8f8869ec668a 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -149,10 +149,16 @@ Quick Reference
 +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
 
 .. [#slots]
- A slot name in parentheses indicates it is (effectively) deprecated.
- Names in angle brackets should be treated as read-only.
- Names in square brackets are for internal use only.
- "<R>" (as a prefix) means the field is required (must be non-``NULL``).
+
+ **()**: A slot name in parentheses indicates it is (effectively) deprecated.
+
+ **<>**: Names in angle brackets should be initially set to ``NULL`` and
+ treated as read-only.
+
+ **[]**: Names in square brackets are for internal use only.
+
+ **<R>** (as a prefix) means the field is required (must be non-``NULL``).
+
 .. [#cols] Columns:
 
 **"O"**: set on :c:type:`PyBaseObject_Type`
@@ -1923,8 +1929,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 
 Tuple of base types.
 
- This is set for types created by a class statement. It should be ``NULL`` for
- statically defined types.
+ This field should be set to ``NULL`` and treated as read-only.
+ Python will fill it in when the type is :c:func:`initialized <PyType_Ready>`.
+
+ For dynamically created classes, the ``Py_tp_bases``
+ :c:type:`slot <PyType_Slot>` can be used instead of the *bases* argument
+ of :c:func:`PyType_FromSpecWithBases`.
+ The argument form is preferred.
+
+ .. warning::
+
+ Multiple inheritance does not work well for statically defined types.
+ If you set ``tp_bases`` to a tuple, Python will not raise an error,
+ but some slots will only be inherited from the first base.
 
 **Inheritance:**
 
@@ -1936,6 +1953,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 Tuple containing the expanded set of base types, starting with the type itself
 and ending with :class:`object`, in Method Resolution Order.
 
+ This field should be set to ``NULL`` and treated as read-only.
+ Python will fill it in when the type is :c:func:`initialized <PyType_Ready>`.
 
 **Inheritance:**
 
