Skip to content

Commit

Permalink
pythongh-99249: Clarify "read-only" slots tp_bases & tp_mro (pythonGH…
Browse files Browse the repository at this point in the history
…-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>
  • Loading branch information
encukou and kumaraditya303 authored Nov 28, 2022
1 parent 594de16 commit 219696a
Showing 1 changed file with 25 additions and 6 deletions.
31 changes: 25 additions & 6 deletions Doc/c-api/typeobj.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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:**

Expand All @@ -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:**

Expand Down

0 comments on commit 219696a

Please sign in to comment.