@@ -486,12 +486,16 @@ type objects) *must* have the :attr:`ob_size` field.
486
486
PyObject* PyObject._ob_prev
487
487
488
488
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
495
499
:envvar: `PYTHONDUMPREFS ` is set.
496
500
497
501
**Inheritance: **
@@ -502,10 +506,11 @@ type objects) *must* have the :attr:`ob_size` field.
502
506
.. c :member :: Py_ssize_t PyObject.ob_refcnt
503
507
504
508
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.
509
514
510
515
**Inheritance: **
511
516
@@ -540,8 +545,9 @@ PyVarObject Slots
540
545
541
546
.. c :member :: Py_ssize_t PyVarObject.ob_size
542
547
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.
545
551
546
552
**Inheritance: **
547
553
@@ -566,11 +572,13 @@ and :c:type:`PyType_Type` effectively act as defaults.)
566
572
:class: `T ` defined in module :mod: `M ` in subpackage :mod: `Q ` in package :mod: `P `
567
573
should have the :c:member: `~PyTypeObject.tp_name ` initializer ``"P.Q.M.T" ``.
568
574
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
570
577
the module name explicitly stored in the type dict as the value for key
571
578
``'__module__' ``.
572
579
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.
574
582
Everything before the last dot is made accessible as the :attr: `__module__ `
575
583
attribute, and everything after the last dot is made accessible as the
576
584
:attr: `~definition.__name__ ` attribute.
@@ -725,7 +733,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
725
733
always inherited. If it's not, then the subclass won't use
726
734
:ref: `vectorcall <vectorcall >`, except when
727
735
: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 >`
729
737
(including subclasses defined in Python).
730
738
731
739
@@ -1116,7 +1124,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1116
1124
1117
1125
**Inheritance: **
1118
1126
1119
- This flag is never inherited by heap types.
1127
+ This flag is never inherited by :ref: ` heap types < heap-types >` .
1120
1128
For extension types, it is inherited whenever
1121
1129
:c:member: `~PyTypeObject.tp_descr_get ` is inherited.
1122
1130
@@ -1163,9 +1171,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1163
1171
1164
1172
**Inheritance: **
1165
1173
1166
- This bit is inherited for * static * subtypes if
1174
+ This bit is inherited for :ref: ` static subtypes < static-types >` if
1167
1175
: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 ``.
1169
1177
1170
1178
.. versionadded :: 3.9
1171
1179
@@ -1181,7 +1189,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1181
1189
1182
1190
This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.
1183
1191
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 >`.
1185
1194
1186
1195
**Inheritance: **
1187
1196
@@ -1250,9 +1259,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1250
1259
:c:func: `local_traverse ` to have these specific names; don't name them just
1251
1260
anything.
1252
1261
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
1256
1264
:c:func: `Py_TYPE(self) <Py_TYPE> `, or delegate this responsibility by
1257
1265
calling ``tp_traverse `` of another heap-allocated type (such as a
1258
1266
heap-allocated superclass).
@@ -1667,8 +1675,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1667
1675
1668
1676
**Default: **
1669
1677
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.
1672
1680
1673
1681
1674
1682
.. c :member :: initproc PyTypeObject.tp_init
@@ -1703,7 +1711,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1703
1711
1704
1712
**Default: **
1705
1713
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.
1707
1715
1708
1716
1709
1717
.. c :member :: allocfunc PyTypeObject.tp_alloc
@@ -1754,14 +1762,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1754
1762
1755
1763
**Inheritance: **
1756
1764
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 ``.
1759
1768
1760
1769
**Default: **
1761
1770
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
1765
1774
instances, like a factory function.
1766
1775
1767
1776
@@ -1803,7 +1812,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
1803
1812
1804
1813
(The only example of this are types themselves. The metatype,
1805
1814
:c:data: `PyType_Type `, defines this function to distinguish between statically
1806
- and dynamically allocated types.)
1815
+ and :ref: ` dynamically allocated types < heap-types >` .)
1807
1816
1808
1817
**Inheritance: **
1809
1818
@@ -1949,10 +1958,10 @@ objects on the thread which called tp_dealloc will not violate any assumptions
1949
1958
of the library.
1950
1959
1951
1960
1952
- .. _ heap -types :
1961
+ .. _ static -types :
1953
1962
1954
- Heap Types
1955
- ----------
1963
+ Static Types
1964
+ ------------
1956
1965
1957
1966
Traditionally, types defined in C code are *static *, that is,
1958
1967
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>`
1972
1981
any extension modules using static types must be compiled for a specific
1973
1982
Python minor version.
1974
1983
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.
1978
1994
1979
1995
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 `.
1981
1998
1982
1999
1983
2000
.. _number-structs :
@@ -2489,7 +2506,7 @@ include common usage you may encounter. Some demonstrate tricky corner
2489
2506
cases. For more examples, practical info, and a tutorial, see
2490
2507
:ref: `defining-new-types ` and :ref: `new-types-topics `.
2491
2508
2492
- A basic static type::
2509
+ A basic :ref: ` static type < static-types >` ::
2493
2510
2494
2511
typedef struct {
2495
2512
PyObject_HEAD
@@ -2596,7 +2613,7 @@ to create instances (e.g. uses a separate factory func)::
2596
2613
.tp_repr = (reprfunc)myobj_repr,
2597
2614
};
2598
2615
2599
- The simplest static type ( with fixed-length instances) ::
2616
+ The simplest :ref: ` static type < static-types >` with fixed-length instances::
2600
2617
2601
2618
typedef struct {
2602
2619
PyObject_HEAD
@@ -2607,7 +2624,7 @@ The simplest static type (with fixed-length instances)::
2607
2624
.tp_name = "mymod.MyObject",
2608
2625
};
2609
2626
2610
- The simplest static type ( with variable-length instances) ::
2627
+ The simplest :ref: ` static type < static-types >` with variable-length instances::
2611
2628
2612
2629
typedef struct {
2613
2630
PyObject_VAR_HEAD
0 commit comments