Skip to content

Commit 5bd0619

Browse files
authored
bpo-43908: Document Static Types in the C API (GH-25710)
Update also PyTypeObject structure definition in the doc.
1 parent c6ad03f commit 5bd0619

File tree

7 files changed

+75
-50
lines changed

7 files changed

+75
-50
lines changed

Doc/c-api/type.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ Type Objects
111111
112112
.. versionchanged:: 3.10
113113
:c:func:`PyType_GetSlot` can now accept all types.
114-
Previously, it was limited to heap types.
114+
Previously, it was limited to :ref:`heap types <heap-types>`.
115115
116116
.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
117117
@@ -153,7 +153,7 @@ The following functions and structs are used to create
153153
154154
.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
155155
156-
Creates and returns a heap type object from the *spec*
156+
Creates and returns a :ref:`heap type <heap-types>` from the *spec*
157157
(:const:`Py_TPFLAGS_HEAPTYPE`).
158158
159159
The *bases* argument can be used to specify base classes; it can either

Doc/c-api/typeobj.rst

Lines changed: 58 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -486,12 +486,16 @@ type objects) *must* have the :attr:`ob_size` field.
486486
PyObject* PyObject._ob_prev
487487
488488
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
489-
Their initialization to ``NULL`` is taken care of by the ``PyObject_HEAD_INIT``
490-
macro. For statically allocated objects, these fields always remain ``NULL``.
491-
For dynamically allocated objects, these two fields are used to link the object
492-
into a doubly-linked list of *all* live objects on the heap. This could be used
493-
for various debugging purposes; currently the only use is to print the objects
494-
that are still alive at the end of a run when the environment variable
489+
490+
Their initialization to ``NULL`` is taken care of by the
491+
``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
492+
<static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
493+
allocated objects <heap-types>`, these two fields are used to link the
494+
object into a doubly-linked list of *all* live objects on the heap.
495+
496+
This could be used for various debugging purposes; currently the only uses
497+
are the :func:`sys.getobjects` function and to print the objects that are
498+
still alive at the end of a run when the environment variable
495499
:envvar:`PYTHONDUMPREFS` is set.
496500

497501
**Inheritance:**
@@ -502,10 +506,11 @@ type objects) *must* have the :attr:`ob_size` field.
502506
.. c:member:: Py_ssize_t PyObject.ob_refcnt
503507
504508
This is the type object's reference count, initialized to ``1`` by the
505-
``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
506-
the type's instances (objects whose :attr:`ob_type` points back to the type) do
507-
*not* count as references. But for dynamically allocated type objects, the
508-
instances *do* count as references.
509+
``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type
510+
objects <static-types>`, the type's instances (objects whose :attr:`ob_type`
511+
points back to the type) do *not* count as references. But for
512+
:ref:`dynamically allocated type objects <heap-types>`, the instances *do*
513+
count as references.
509514

510515
**Inheritance:**
511516

@@ -540,8 +545,9 @@ PyVarObject Slots
540545

541546
.. c:member:: Py_ssize_t PyVarObject.ob_size
542547
543-
For statically allocated type objects, this should be initialized to zero. For
544-
dynamically allocated type objects, this field has a special internal meaning.
548+
For :ref:`statically allocated type objects <static-types>`, this should be
549+
initialized to zero. For :ref:`dynamically allocated type objects
550+
<heap-types>`, this field has a special internal meaning.
545551

546552
**Inheritance:**
547553

@@ -566,11 +572,13 @@ and :c:type:`PyType_Type` effectively act as defaults.)
566572
:class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
567573
should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``.
568574

569-
For dynamically allocated type objects, this should just be the type name, and
575+
For :ref:`dynamically allocated type objects <heap-types>`,
576+
this should just be the type name, and
570577
the module name explicitly stored in the type dict as the value for key
571578
``'__module__'``.
572579

573-
For statically allocated type objects, the tp_name field should contain a dot.
580+
For :ref:`statically allocated type objects <static-types>`,
581+
the *tp_name* field should contain a dot.
574582
Everything before the last dot is made accessible as the :attr:`__module__`
575583
attribute, and everything after the last dot is made accessible as the
576584
:attr:`~definition.__name__` attribute.
@@ -725,7 +733,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
725733
always inherited. If it's not, then the subclass won't use
726734
:ref:`vectorcall <vectorcall>`, except when
727735
:c:func:`PyVectorcall_Call` is explicitly called.
728-
This is in particular the case for `heap types`_
736+
This is in particular the case for :ref:`heap types <heap-types>`
729737
(including subclasses defined in Python).
730738

731739

@@ -1116,7 +1124,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
11161124

11171125
**Inheritance:**
11181126

1119-
This flag is never inherited by heap types.
1127+
This flag is never inherited by :ref:`heap types <heap-types>`.
11201128
For extension types, it is inherited whenever
11211129
:c:member:`~PyTypeObject.tp_descr_get` is inherited.
11221130

@@ -1163,9 +1171,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
11631171

11641172
**Inheritance:**
11651173

1166-
This bit is inherited for *static* subtypes if
1174+
This bit is inherited for :ref:`static subtypes <static-types>` if
11671175
:c:member:`~PyTypeObject.tp_call` is also inherited.
1168-
`Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
1176+
:ref:`Heap types <heap-types>` do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
11691177

11701178
.. versionadded:: 3.9
11711179

@@ -1181,7 +1189,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
11811189

11821190
This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.
11831191

1184-
:c:func:`PyType_Ready` automatically applies this flag to static types.
1192+
:c:func:`PyType_Ready` automatically applies this flag to
1193+
:ref:`static types <static-types>`.
11851194

11861195
**Inheritance:**
11871196

@@ -1250,9 +1259,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
12501259
:c:func:`local_traverse` to have these specific names; don't name them just
12511260
anything.
12521261

1253-
Heap-allocated types (:const:`Py_TPFLAGS_HEAPTYPE`, such as those created
1254-
with :c:func:`PyType_FromSpec` and similar APIs) hold a reference to their
1255-
type. Their traversal function must therefore either visit
1262+
Instances of :ref:`heap-allocated types <heap-types>` hold a reference to
1263+
their type. Their traversal function must therefore either visit
12561264
:c:func:`Py_TYPE(self) <Py_TYPE>`, or delegate this responsibility by
12571265
calling ``tp_traverse`` of another heap-allocated type (such as a
12581266
heap-allocated superclass).
@@ -1667,8 +1675,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
16671675

16681676
**Default:**
16691677

1670-
This slot has no default. For static types, if the field is
1671-
``NULL`` then no :attr:`__dict__` gets created for instances.
1678+
This slot has no default. For :ref:`static types <static-types>`, if the
1679+
field is ``NULL`` then no :attr:`__dict__` gets created for instances.
16721680

16731681

16741682
.. c:member:: initproc PyTypeObject.tp_init
@@ -1703,7 +1711,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
17031711

17041712
**Default:**
17051713

1706-
For static types this field does not have a default.
1714+
For :ref:`static types <static-types>` this field does not have a default.
17071715

17081716

17091717
.. c:member:: allocfunc PyTypeObject.tp_alloc
@@ -1754,14 +1762,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
17541762

17551763
**Inheritance:**
17561764

1757-
This field is inherited by subtypes, except it is not inherited by static types
1758-
whose :c:member:`~PyTypeObject.tp_base` is ``NULL`` or ``&PyBaseObject_Type``.
1765+
This field is inherited by subtypes, except it is not inherited by
1766+
:ref:`static types <static-types>` whose :c:member:`~PyTypeObject.tp_base`
1767+
is ``NULL`` or ``&PyBaseObject_Type``.
17591768

17601769
**Default:**
17611770

1762-
For static types this field has no default. This means if the
1763-
slot is defined as ``NULL``, the type cannot be called to create new
1764-
instances; presumably there is some other way to create
1771+
For :ref:`static types <static-types>` this field has no default.
1772+
This means if the slot is defined as ``NULL``, the type cannot be called
1773+
to create new instances; presumably there is some other way to create
17651774
instances, like a factory function.
17661775

17671776

@@ -1803,7 +1812,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
18031812

18041813
(The only example of this are types themselves. The metatype,
18051814
:c:data:`PyType_Type`, defines this function to distinguish between statically
1806-
and dynamically allocated types.)
1815+
and :ref:`dynamically allocated types <heap-types>`.)
18071816

18081817
**Inheritance:**
18091818

@@ -1949,10 +1958,10 @@ objects on the thread which called tp_dealloc will not violate any assumptions
19491958
of the library.
19501959

19511960

1952-
.. _heap-types:
1961+
.. _static-types:
19531962

1954-
Heap Types
1955-
----------
1963+
Static Types
1964+
------------
19561965

19571966
Traditionally, types defined in C code are *static*, that is,
19581967
a static :c:type:`PyTypeObject` structure is defined directly in code
@@ -1972,12 +1981,20 @@ Also, since :c:type:`PyTypeObject` is not part of the :ref:`stable ABI <stable>`
19721981
any extension modules using static types must be compiled for a specific
19731982
Python minor version.
19741983

1975-
An alternative to static types is *heap-allocated types*, or *heap types*
1976-
for short, which correspond closely to classes created by Python's
1977-
``class`` statement.
1984+
1985+
.. _heap-types:
1986+
1987+
Heap Types
1988+
----------
1989+
1990+
An alternative to :ref:`static types <static-types>` is *heap-allocated types*,
1991+
or *heap types* for short, which correspond closely to classes created by
1992+
Python's ``class`` statement. Heap types have the :const:`Py_TPFLAGS_HEAPTYPE`
1993+
flag set.
19781994

19791995
This is done by filling a :c:type:`PyType_Spec` structure and calling
1980-
:c:func:`PyType_FromSpecWithBases`.
1996+
:c:func:`PyType_FromSpec`, :c:func:`PyType_FromSpecWithBases`,
1997+
or :c:func:`PyType_FromModuleAndSpec`.
19811998

19821999

19832000
.. _number-structs:
@@ -2489,7 +2506,7 @@ include common usage you may encounter. Some demonstrate tricky corner
24892506
cases. For more examples, practical info, and a tutorial, see
24902507
:ref:`defining-new-types` and :ref:`new-types-topics`.
24912508

2492-
A basic static type::
2509+
A basic :ref:`static type <static-types>`::
24932510

24942511
typedef struct {
24952512
PyObject_HEAD
@@ -2596,7 +2613,7 @@ to create instances (e.g. uses a separate factory func)::
25962613
.tp_repr = (reprfunc)myobj_repr,
25972614
};
25982615

2599-
The simplest static type (with fixed-length instances)::
2616+
The simplest :ref:`static type <static-types>` with fixed-length instances::
26002617

26012618
typedef struct {
26022619
PyObject_HEAD
@@ -2607,7 +2624,7 @@ The simplest static type (with fixed-length instances)::
26072624
.tp_name = "mymod.MyObject",
26082625
};
26092626

2610-
The simplest static type (with variable-length instances)::
2627+
The simplest :ref:`static type <static-types>` with variable-length instances::
26112628

26122629
typedef struct {
26132630
PyObject_VAR_HEAD

Doc/includes/typestruct.h

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,14 @@ typedef struct _typeobject {
3535

3636
const char *tp_doc; /* Documentation string */
3737

38+
/* Assigned meaning in release 2.0 */
3839
/* call function for all accessible objects */
3940
traverseproc tp_traverse;
4041

4142
/* delete references to contained objects */
4243
inquiry tp_clear;
4344

45+
/* Assigned meaning in release 2.1 */
4446
/* rich comparisons */
4547
richcmpfunc tp_richcompare;
4648

@@ -55,6 +57,7 @@ typedef struct _typeobject {
5557
struct PyMethodDef *tp_methods;
5658
struct PyMemberDef *tp_members;
5759
struct PyGetSetDef *tp_getset;
60+
// Strong reference on a heap type, borrowed reference on a static type
5861
struct _typeobject *tp_base;
5962
PyObject *tp_dict;
6063
descrgetfunc tp_descr_get;
@@ -76,5 +79,5 @@ typedef struct _typeobject {
7679
unsigned int tp_version_tag;
7780

7881
destructor tp_finalize;
79-
82+
vectorcallfunc tp_vectorcall;
8083
} PyTypeObject;

Doc/whatsnew/3.10.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1668,7 +1668,8 @@ New Features
16681668
slot.
16691669
(Contributed by Hai Shi in :issue:`41832`.)
16701670
1671-
* The :c:func:`PyType_GetSlot` function can accept static types.
1671+
* The :c:func:`PyType_GetSlot` function can accept
1672+
:ref:`static types <static-types>`.
16721673
(Contributed by Hai Shi and Petr Viktorin in :issue:`41073`.)
16731674
16741675
* Add a new :c:func:`PySet_CheckExact` function to the C-API to check if an

Doc/whatsnew/3.8.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,8 @@ PEP 590: Vectorcall: a fast calling protocol for CPython
352352
:ref:`vectorcall` is added to the Python/C API.
353353
It is meant to formalize existing optimizations which were already done
354354
for various classes.
355-
Any static type implementing a callable can use this protocol.
355+
Any :ref:`static type <static-types>` implementing a callable can use this
356+
protocol.
356357

357358
This is currently provisional.
358359
The aim is to make it fully public in Python 3.9.
@@ -2040,7 +2041,7 @@ Changes in the C API
20402041
This makes types created through :c:func:`PyType_FromSpec` behave like
20412042
other classes in managed code.
20422043

2043-
Statically allocated types are not affected.
2044+
:ref:`Statically allocated types <static-types>` are not affected.
20442045

20452046
For the vast majority of cases, there should be no side effect.
20462047
However, types that manually increase the reference count after allocating

Doc/whatsnew/3.9.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1124,7 +1124,7 @@ Changes in the Python API
11241124
Changes in the C API
11251125
--------------------
11261126

1127-
* Instances of heap-allocated types (such as those created with
1127+
* Instances of :ref:`heap-allocated types <heap-types>` (such as those created with
11281128
:c:func:`PyType_FromSpec` and similar APIs) hold a reference to their type
11291129
object since Python 3.8. As indicated in the "Changes in the C API" of Python
11301130
3.8, for the vast majority of cases, there should be no side effect but for
@@ -1147,7 +1147,8 @@ Changes in the C API
11471147
11481148
If your traverse function delegates to ``tp_traverse`` of its base class
11491149
(or another type), ensure that ``Py_TYPE(self)`` is visited only once.
1150-
Note that only heap types are expected to visit the type in ``tp_traverse``.
1150+
Note that only :ref:`heap type <heap-types>` are expected to visit the type
1151+
in ``tp_traverse``.
11511152

11521153
For example, if your ``tp_traverse`` function includes:
11531154

@@ -1160,7 +1161,7 @@ Changes in the C API
11601161
.. code-block:: c
11611162
11621163
#if PY_VERSION_HEX >= 0x03090000
1163-
// This was not needed before Python 3.9 (Python issue 35810 and 40217)
1164+
// This was not needed before Python 3.9 (bpo-35810 and bpo-40217)
11641165
if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
11651166
// a heap type's tp_traverse already visited Py_TYPE(self)
11661167
} else {

Include/cpython/object.h

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,8 @@ typedef struct {
186186
* backwards-compatibility */
187187
typedef Py_ssize_t printfunc;
188188

189+
// If this structure is modified, Doc/includes/typestruct.h should be updated
190+
// as well.
189191
struct _typeobject {
190192
PyObject_VAR_HEAD
191193
const char *tp_name; /* For printing, in format "<module>.<name>" */

0 commit comments

Comments
 (0)