Skip to content

Commit 219696a

Browse files
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@users.noreply.github.com>
1 parent 594de16 commit 219696a

File tree

1 file changed

+25
-6
lines changed

1 file changed

+25
-6
lines changed

Doc/c-api/typeobj.rst

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -149,10 +149,16 @@ Quick Reference
149149
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
150150

151151
.. [#slots]
152-
A slot name in parentheses indicates it is (effectively) deprecated.
153-
Names in angle brackets should be treated as read-only.
154-
Names in square brackets are for internal use only.
155-
"<R>" (as a prefix) means the field is required (must be non-``NULL``).
152+
153+
**()**: A slot name in parentheses indicates it is (effectively) deprecated.
154+
155+
**<>**: Names in angle brackets should be initially set to ``NULL`` and
156+
treated as read-only.
157+
158+
**[]**: Names in square brackets are for internal use only.
159+
160+
**<R>** (as a prefix) means the field is required (must be non-``NULL``).
161+
156162
.. [#cols] Columns:
157163
158164
**"O"**: set on :c:type:`PyBaseObject_Type`
@@ -1923,8 +1929,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
19231929
19241930
Tuple of base types.
19251931

1926-
This is set for types created by a class statement. It should be ``NULL`` for
1927-
statically defined types.
1932+
This field should be set to ``NULL`` and treated as read-only.
1933+
Python will fill it in when the type is :c:func:`initialized <PyType_Ready>`.
1934+
1935+
For dynamically created classes, the ``Py_tp_bases``
1936+
:c:type:`slot <PyType_Slot>` can be used instead of the *bases* argument
1937+
of :c:func:`PyType_FromSpecWithBases`.
1938+
The argument form is preferred.
1939+
1940+
.. warning::
1941+
1942+
Multiple inheritance does not work well for statically defined types.
1943+
If you set ``tp_bases`` to a tuple, Python will not raise an error,
1944+
but some slots will only be inherited from the first base.
19281945

19291946
**Inheritance:**
19301947

@@ -1936,6 +1953,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
19361953
Tuple containing the expanded set of base types, starting with the type itself
19371954
and ending with :class:`object`, in Method Resolution Order.
19381955

1956+
This field should be set to ``NULL`` and treated as read-only.
1957+
Python will fill it in when the type is :c:func:`initialized <PyType_Ready>`.
19391958

19401959
**Inheritance:**
19411960

0 commit comments

Comments
 (0)