Debian Codegraph @

Doc/c-api/type.rst

raw
1 .. highlight:: c
2
3 .. _typeobjects:
4
5 Type Objects
6 ------------
7
8 .. index:: pair: object; type
9
10
11 .. c:type:: PyTypeObject
12
13 The C structure of the objects used to describe built-in types.
14
15
16 .. c:var:: PyTypeObject PyType_Type
17
18 This is the type object for type objects; it is the same object as
19 :class:`type` in the Python layer.
20
21
22 .. c:function:: int PyType_Check(PyObject *o)
23
24 Return non-zero if the object *o* is a type object, including instances of
25 types derived from the standard type object. Return 0 in all other cases.
26 This function always succeeds.
27
28
29 .. c:function:: int PyType_CheckExact(PyObject *o)
30
31 Return non-zero if the object *o* is a type object, but not a subtype of
32 the standard type object. Return 0 in all other cases. This function
33 always succeeds.
34
35
36 .. c:function:: unsigned int PyType_ClearCache()
37
38 Clear the internal lookup cache. Return the current version tag.
39
40 .. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type)
41
42 Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
43 meant for use with ``Py_LIMITED_API``; the individual flag bits are
44 guaranteed to be stable across Python releases, but access to
45 :c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API <limited-c-api>`.
46
47 .. versionadded:: 3.2
48
49 .. versionchanged:: 3.4
50 The return type is now ``unsigned long`` rather than ``long``.
51
52
53 .. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
54
55 Return the type object's internal namespace, which is otherwise only
56 exposed via a read-only proxy (:attr:`cls.__dict__ <type.__dict__>`).
57 This is a
58 replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
59 The returned dictionary must be treated as read-only.
60
61 This function is meant for specific embedding and language-binding cases,
62 where direct access to the dict is necessary and indirect access
63 (e.g. via the proxy or :c:func:`PyObject_GetAttr`) isn't adequate.
64
65 Extension modules should continue to use ``tp_dict``,
66 directly or indirectly, when setting up their own types.
67
68 .. versionadded:: 3.12
69
70
71 .. c:function:: void PyType_Modified(PyTypeObject *type)
72
73 Invalidate the internal lookup cache for the type and all of its
74 subtypes. This function must be called after any manual
75 modification of the attributes or base classes of the type.
76
77
78 .. c:function:: int PyType_AddWatcher(PyType_WatchCallback callback)
79
80 Register *callback* as a type watcher. Return a non-negative integer ID
81 which must be passed to future calls to :c:func:`PyType_Watch`. In case of
82 error (e.g. no more watcher IDs available), return ``-1`` and set an
83 exception.
84
85 In free-threaded builds, :c:func:`PyType_AddWatcher` is not thread-safe,
86 so it must be called at start up (before spawning the first thread).
87
88 .. versionadded:: 3.12
89
90
91 .. c:function:: int PyType_ClearWatcher(int watcher_id)
92
93 Clear watcher identified by *watcher_id* (previously returned from
94 :c:func:`PyType_AddWatcher`). Return ``0`` on success, ``-1`` on error (e.g.
95 if *watcher_id* was never registered.)
96
97 An extension should never call ``PyType_ClearWatcher`` with a *watcher_id*
98 that was not returned to it by a previous call to
99 :c:func:`PyType_AddWatcher`.
100
101 .. versionadded:: 3.12
102
103
104 .. c:function:: int PyType_Watch(int watcher_id, PyObject *type)
105
106 Mark *type* as watched. The callback granted *watcher_id* by
107 :c:func:`PyType_AddWatcher` will be called whenever
108 :c:func:`PyType_Modified` reports a change to *type*. (The callback may be
109 called only once for a series of consecutive modifications to *type*, if
110 :c:func:`!_PyType_Lookup` is not called on *type* between the modifications;
111 this is an implementation detail and subject to change.)
112
113 An extension should never call ``PyType_Watch`` with a *watcher_id* that was
114 not returned to it by a previous call to :c:func:`PyType_AddWatcher`.
115
116 .. versionadded:: 3.12
117
118
119 .. c:function:: int PyType_Unwatch(int watcher_id, PyObject *type)
120
121 Mark *type* as not watched. This undoes a previous call to
122 :c:func:`PyType_Watch`. *type* must not be ``NULL``.
123
124 An extension should never call this function with a *watcher_id* that was
125 not returned to it by a previous call to :c:func:`PyType_AddWatcher`.
126
127 On success, this function returns ``0``. On failure, this function returns
128 ``-1`` with an exception set.
129
130 .. versionadded:: 3.12
131
132
133 .. c:type:: int (*PyType_WatchCallback)(PyObject *type)
134
135 Type of a type-watcher callback function.
136
137 The callback must not modify *type* or cause :c:func:`PyType_Modified` to be
138 called on *type* or any type in its MRO; violating this rule could cause
139 infinite recursion.
140
141 .. versionadded:: 3.12
142
143
144 .. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
145
146 Return non-zero if the type object *o* sets the feature *feature*.
147 Type features are denoted by single bit flags.
148
149
150 .. c:function:: int PyType_FastSubclass(PyTypeObject *type, int flag)
151
152 Return non-zero if the type object *type* sets the subclass flag *flag*.
153 Subclass flags are denoted by
154 :c:macro:`Py_TPFLAGS_*_SUBCLASS <Py_TPFLAGS_LONG_SUBCLASS>`.
155 This function is used by many ``_Check`` functions for common types.
156
157 .. seealso::
158 :c:func:`PyObject_TypeCheck`, which is used as a slower alternative in
159 ``_Check`` functions for types that don't come with subclass flags.
160
161
162 .. c:function:: int PyType_IS_GC(PyTypeObject *o)
163
164 Return true if the type object includes support for the cycle detector; this
165 tests the type flag :c:macro:`Py_TPFLAGS_HAVE_GC`.
166
167
168 .. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
169
170 Return true if *a* is a subtype of *b*.
171
172 This function only checks for actual subtypes, which means that
173 :meth:`~type.__subclasscheck__` is not called on *b*. Call
174 :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
175 would do.
176
177
178 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
179
180 Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type
181 object. Uses Python's default memory allocation mechanism to allocate memory
182 for a new instance, zeros the memory, then initializes the memory as if by
183 calling :c:func:`PyObject_Init` or :c:func:`PyObject_InitVar`.
184
185 Do not call this directly to allocate memory for an object; call the type's
186 :c:member:`~PyTypeObject.tp_alloc` slot instead.
187
188 For types that support garbage collection (i.e., the
189 :c:macro:`Py_TPFLAGS_HAVE_GC` flag is set), this function behaves like
190 :c:macro:`PyObject_GC_New` or :c:macro:`PyObject_GC_NewVar` (except the
191 memory is guaranteed to be zeroed before initialization), and should be
192 paired with :c:func:`PyObject_GC_Del` in :c:member:`~PyTypeObject.tp_free`.
193 Otherwise, it behaves like :c:macro:`PyObject_New` or
194 :c:macro:`PyObject_NewVar` (except the memory is guaranteed to be zeroed
195 before initialization) and should be paired with :c:func:`PyObject_Free` in
196 :c:member:`~PyTypeObject.tp_free`.
197
198
199 .. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
200
201 Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type
202 object. Creates a new instance using the type's
203 :c:member:`~PyTypeObject.tp_alloc` slot and returns the resulting object.
204
205
206 .. c:function:: int PyType_Ready(PyTypeObject *type)
207
208 Finalize a type object. This should be called on all type objects to finish
209 their initialization. This function is responsible for adding inherited slots
210 from a type's base class. Return ``0`` on success, or return ``-1`` and sets an
211 exception on error.
212
213 .. note::
214 If some of the base classes implements the GC protocol and the provided
215 type does not include the :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags, then
216 the GC protocol will be automatically implemented from its parents. On
217 the contrary, if the type being created does include
218 :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the
219 GC protocol itself by at least implementing the
220 :c:member:`~PyTypeObject.tp_traverse` handle.
221
222
223 .. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
224
225 Return the type's name. Equivalent to getting the type's
226 :attr:`~type.__name__` attribute.
227
228 .. versionadded:: 3.11
229
230
231 .. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
232
233 Return the type's qualified name. Equivalent to getting the
234 type's :attr:`~type.__qualname__` attribute.
235
236 .. versionadded:: 3.11
237
238 .. c:function:: PyObject* PyType_GetFullyQualifiedName(PyTypeObject *type)
239
240 Return the type's fully qualified name. Equivalent to
241 ``f"{type.__module__}.{type.__qualname__}"``, or :attr:`type.__qualname__`
242 if :attr:`type.__module__` is not a string or is equal to ``"builtins"``.
243
244 .. versionadded:: 3.13
245
246
247 .. c:function:: PyObject* PyType_GetModuleName(PyTypeObject *type)
248
249 Return the type's module name. Equivalent to getting the
250 :attr:`type.__module__` attribute.
251
252 .. versionadded:: 3.13
253
254
255 .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
256
257 Return the function pointer stored in the given slot. If the
258 result is ``NULL``, this indicates that either the slot is ``NULL``,
259 or that the function was called with invalid parameters.
260 Callers will typically cast the result pointer into the appropriate
261 function type.
262
263 See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument.
264
265 .. versionadded:: 3.4
266
267 .. versionchanged:: 3.10
268 :c:func:`PyType_GetSlot` can now accept all types.
269 Previously, it was limited to :ref:`heap types <heap-types>`.
270
271
272 .. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
273
274 Return the module object associated with the given type when the type was
275 created using :c:func:`PyType_FromModuleAndSpec`.
276
277 The returned reference is :term:`borrowed <borrowed reference>` from *type*,
278 and will be valid as long as you hold a reference to *type*.
279 Do not release it with :c:func:`Py_DECREF` or similar.
280
281 If no module is associated with the given type, sets :py:class:`TypeError`
282 and returns ``NULL``.
283
284 This function is usually used to get the module in which a method is defined.
285 Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
286 may not return the intended result.
287 ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
288 are not necessarily defined in the same module as their superclass.
289 See :c:type:`PyCMethod` to get the class that defines the method.
290 See :c:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot
291 be used.
292
293 .. versionadded:: 3.9
294
295
296 .. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
297
298 Return the state of the module object associated with the given type.
299 This is a shortcut for calling :c:func:`PyModule_GetState()` on the result
300 of :c:func:`PyType_GetModule`.
301
302 If no module is associated with the given type, sets :py:class:`TypeError`
303 and returns ``NULL``.
304
305 If the *type* has an associated module but its state is ``NULL``,
306 returns ``NULL`` without setting an exception.
307
308 .. versionadded:: 3.9
309
310
311 .. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
312
313 Find the first superclass whose module was created from
314 the given :c:type:`PyModuleDef` *def*, and return that module.
315
316 If no module is found, raises a :py:class:`TypeError` and returns ``NULL``.
317
318 This function is intended to be used together with
319 :c:func:`PyModule_GetState()` to get module state from slot methods (such as
320 :c:member:`~PyTypeObject.tp_init` or :c:member:`~PyNumberMethods.nb_add`)
321 and other places where a method's defining class cannot be passed using the
322 :c:type:`PyCMethod` calling convention.
323
324 The returned reference is :term:`borrowed <borrowed reference>` from *type*,
325 and will be valid as long as you hold a reference to *type*.
326 Do not release it with :c:func:`Py_DECREF` or similar.
327
328 .. versionadded:: 3.11
329
330
331 .. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)
332
333 Find the first superclass in *type*'s :term:`method resolution order` whose
334 :c:macro:`Py_tp_token` token is equal to the given one.
335
336 * If found, set *\*result* to a new :term:`strong reference`
337 to it and return ``1``.
338 * If not found, set *\*result* to ``NULL`` and return ``0``.
339 * On error, set *\*result* to ``NULL`` and return ``-1`` with an
340 exception set.
341
342 The *result* argument may be ``NULL``, in which case *\*result* is not set.
343 Use this if you need only the return value.
344
345 The *token* argument may not be ``NULL``.
346
347 .. versionadded:: 3.14
348
349
350 .. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
351
352 Attempt to assign a version tag to the given type.
353
354 Returns 1 if the type already had a valid version tag or a new one was
355 assigned, or 0 if a new tag could not be assigned.
356
357 .. versionadded:: 3.12
358
359
360 .. c:function:: int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)
361
362 Return true if instances of *type* support creating weak references, false
363 otherwise. This function always succeeds. *type* must not be ``NULL``.
364
365 .. seealso::
366 * :ref:`weakrefobjects`
367 * :py:mod:`weakref`
368
369
370 Creating Heap-Allocated Types
371 .............................
372
373 The following functions and structs are used to create
374 :ref:`heap types <heap-types>`.
375
376 .. c:function:: PyObject* PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
377
378 Create and return a :ref:`heap type <heap-types>` from the *spec*
379 (see :c:macro:`Py_TPFLAGS_HEAPTYPE`).
380
381 The metaclass *metaclass* is used to construct the resulting type object.
382 When *metaclass* is ``NULL``, the metaclass is derived from *bases*
383 (or *Py_tp_base[s]* slots if *bases* is ``NULL``, see below).
384
385 Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not
386 supported, except if ``tp_new`` is ``NULL``.
387
388 The *bases* argument can be used to specify base classes; it can either
389 be only one class or a tuple of classes.
390 If *bases* is ``NULL``, the :c:data:`Py_tp_bases` slot is used instead.
391 If that also is ``NULL``, the :c:data:`Py_tp_base` slot is used instead.
392 If that also is ``NULL``, the new type derives from :class:`object`.
393
394 The *module* argument can be used to record the module in which the new
395 class is defined. It must be a module object or ``NULL``.
396 If not ``NULL``, the module is associated with the new type and can later be
397 retrieved with :c:func:`PyType_GetModule`.
398 The associated module is not inherited by subclasses; it must be specified
399 for each class individually.
400
401 This function calls :c:func:`PyType_Ready` on the new type.
402
403 Note that this function does *not* fully match the behavior of
404 calling :py:class:`type() <type>` or using the :keyword:`class` statement.
405 With user-provided base types or metaclasses, prefer
406 :ref:`calling <capi-call>` :py:class:`type` (or the metaclass)
407 over ``PyType_From*`` functions.
408 Specifically:
409
410 * :py:meth:`~object.__new__` is not called on the new class
411 (and it must be set to ``type.__new__``).
412 * :py:meth:`~object.__init__` is not called on the new class.
413 * :py:meth:`~object.__init_subclass__` is not called on any bases.
414 * :py:meth:`~object.__set_name__` is not called on new descriptors.
415
416 .. versionadded:: 3.12
417
418
419 .. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
420
421 Equivalent to ``PyType_FromMetaclass(NULL, module, spec, bases)``.
422
423 .. versionadded:: 3.9
424
425 .. versionchanged:: 3.10
426
427 The function now accepts a single class as the *bases* argument and
428 ``NULL`` as the ``tp_doc`` slot.
429
430 .. versionchanged:: 3.12
431
432 The function now finds and uses a metaclass corresponding to the provided
433 base classes. Previously, only :class:`type` instances were returned.
434
435 The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
436 which may result in incomplete initialization.
437 Creating classes whose metaclass overrides
438 :c:member:`~PyTypeObject.tp_new` is deprecated.
439
440 .. versionchanged:: 3.14
441
442 Creating classes whose metaclass overrides
443 :c:member:`~PyTypeObject.tp_new` is no longer allowed.
444
445
446 .. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
447
448 Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, bases)``.
449
450 .. versionadded:: 3.3
451
452 .. versionchanged:: 3.12
453
454 The function now finds and uses a metaclass corresponding to the provided
455 base classes. Previously, only :class:`type` instances were returned.
456
457 The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
458 which may result in incomplete initialization.
459 Creating classes whose metaclass overrides
460 :c:member:`~PyTypeObject.tp_new` is deprecated.
461
462 .. versionchanged:: 3.14
463
464 Creating classes whose metaclass overrides
465 :c:member:`~PyTypeObject.tp_new` is no longer allowed.
466
467
468 .. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
469
470 Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``.
471
472 .. versionchanged:: 3.12
473
474 The function now finds and uses a metaclass corresponding to the
475 base classes provided in *Py_tp_base[s]* slots.
476 Previously, only :class:`type` instances were returned.
477
478 The :c:member:`~PyTypeObject.tp_new` of the metaclass is *ignored*.
479 which may result in incomplete initialization.
480 Creating classes whose metaclass overrides
481 :c:member:`~PyTypeObject.tp_new` is deprecated.
482
483 .. versionchanged:: 3.14
484
485 Creating classes whose metaclass overrides
486 :c:member:`~PyTypeObject.tp_new` is no longer allowed.
487
488
489 .. c:function:: int PyType_Freeze(PyTypeObject *type)
490
491 Make a type immutable: set the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag.
492
493 All base classes of *type* must be immutable.
494
495 On success, return ``0``.
496 On error, set an exception and return ``-1``.
497
498 The type must not be used before it's made immutable. For example, type
499 instances must not be created before the type is made immutable.
500
501 .. versionadded:: 3.14
502
503 .. raw:: html
504
505 <!-- Keep old URL fragments working (see gh-97908) -->
506 <span id='c.PyType_Spec.PyType_Spec.name'></span>
507 <span id='c.PyType_Spec.PyType_Spec.basicsize'></span>
508 <span id='c.PyType_Spec.PyType_Spec.itemsize'></span>
509 <span id='c.PyType_Spec.PyType_Spec.flags'></span>
510 <span id='c.PyType_Spec.PyType_Spec.slots'></span>
511
512 .. c:type:: PyType_Spec
513
514 Structure defining a type's behavior.
515
516 .. c:member:: const char* name
517
518 Name of the type, used to set :c:member:`PyTypeObject.tp_name`.
519
520 .. c:member:: int basicsize
521
522 If positive, specifies the size of the instance in bytes.
523 It is used to set :c:member:`PyTypeObject.tp_basicsize`.
524
525 If zero, specifies that :c:member:`~PyTypeObject.tp_basicsize`
526 should be inherited.
527
528 If negative, the absolute value specifies how much space instances of the
529 class need *in addition* to the superclass.
530 Use :c:func:`PyObject_GetTypeData` to get a pointer to subclass-specific
531 memory reserved this way.
532 For negative :c:member:`!basicsize`, Python will insert padding when
533 needed to meet :c:member:`~PyTypeObject.tp_basicsize`'s alignment
534 requirements.
535
536 .. versionchanged:: 3.12
537
538 Previously, this field could not be negative.
539
540 .. c:member:: int itemsize
541
542 Size of one element of a variable-size type, in bytes.
543 Used to set :c:member:`PyTypeObject.tp_itemsize`.
544 See ``tp_itemsize`` documentation for caveats.
545
546 If zero, :c:member:`~PyTypeObject.tp_itemsize` is inherited.
547 Extending arbitrary variable-sized classes is dangerous,
548 since some types use a fixed offset for variable-sized memory,
549 which can then overlap fixed-sized memory used by a subclass.
550 To help prevent mistakes, inheriting ``itemsize`` is only possible
551 in the following situations:
552
553 - The base is not variable-sized (its
554 :c:member:`~PyTypeObject.tp_itemsize`).
555 - The requested :c:member:`PyType_Spec.basicsize` is positive,
556 suggesting that the memory layout of the base class is known.
557 - The requested :c:member:`PyType_Spec.basicsize` is zero,
558 suggesting that the subclass does not access the instance's memory
559 directly.
560 - With the :c:macro:`Py_TPFLAGS_ITEMS_AT_END` flag.
561
562 .. c:member:: unsigned int flags
563
564 Type flags, used to set :c:member:`PyTypeObject.tp_flags`.
565
566 If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set,
567 :c:func:`PyType_FromSpecWithBases` sets it automatically.
568
569 .. c:member:: PyType_Slot *slots
570
571 Array of :c:type:`PyType_Slot` structures.
572 Terminated by the special slot value ``{0, NULL}``.
573
574 Each slot ID should be specified at most once.
575
576 .. raw:: html
577
578 <!-- Keep old URL fragments working (see gh-97908) -->
579 <span id='c.PyType_Slot.PyType_Slot.slot'></span>
580 <span id='c.PyType_Slot.PyType_Slot.pfunc'></span>
581
582 .. c:type:: PyType_Slot
583
584 Structure defining optional functionality of a type, containing a slot ID
585 and a value pointer.
586
587 .. c:member:: int slot
588
589 A slot ID.
590
591 Slot IDs are named like the field names of the structures
592 :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`,
593 :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and
594 :c:type:`PyAsyncMethods` with an added ``Py_`` prefix.
595 For example, use:
596
597 * :c:data:`Py_tp_dealloc` to set :c:member:`PyTypeObject.tp_dealloc`
598 * :c:data:`Py_nb_add` to set :c:member:`PyNumberMethods.nb_add`
599 * :c:data:`Py_sq_length` to set :c:member:`PySequenceMethods.sq_length`
600
601 An additional slot is supported that does not correspond to a
602 :c:type:`!PyTypeObject` struct field:
603
604 * :c:data:`Py_tp_token`
605
606 The following “offset” fields cannot be set using :c:type:`PyType_Slot`:
607
608 * :c:member:`~PyTypeObject.tp_weaklistoffset`
609 (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)
610 * :c:member:`~PyTypeObject.tp_dictoffset`
611 (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead if possible)
612 * :c:member:`~PyTypeObject.tp_vectorcall_offset`
613 (use ``"__vectorcalloffset__"`` in
614 :ref:`PyMemberDef <pymemberdef-offsets>`)
615
616 If it is not possible to switch to a ``MANAGED`` flag (for example,
617 for vectorcall or to support Python older than 3.12), specify the
618 offset in :c:data:`Py_tp_members`.
619 See :ref:`PyMemberDef documentation <pymemberdef-offsets>`
620 for details.
621
622 The following internal fields cannot be set at all when creating a heap
623 type:
624
625 * :c:member:`~PyTypeObject.tp_dict`,
626 :c:member:`~PyTypeObject.tp_mro`,
627 :c:member:`~PyTypeObject.tp_cache`,
628 :c:member:`~PyTypeObject.tp_subclasses`, and
629 :c:member:`~PyTypeObject.tp_weaklist`.
630
631 Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
632 problematic on some platforms.
633 To avoid issues, use the *bases* argument of
634 :c:func:`PyType_FromSpecWithBases` instead.
635
636 .. versionchanged:: 3.9
637 Slots in :c:type:`PyBufferProcs` may be set in the unlimited API.
638
639 .. versionchanged:: 3.11
640 :c:member:`~PyBufferProcs.bf_getbuffer` and
641 :c:member:`~PyBufferProcs.bf_releasebuffer` are now available
642 under the :ref:`limited API <limited-c-api>`.
643
644 .. versionchanged:: 3.14
645 The field :c:member:`~PyTypeObject.tp_vectorcall` can now be set
646 using :c:data:`Py_tp_vectorcall`. See the field's documentation
647 for details.
648
649 .. c:member:: void *pfunc
650
651 The desired value of the slot. In most cases, this is a pointer
652 to a function.
653
654 *pfunc* values may not be ``NULL``, except for the following slots:
655
656 * :c:data:`Py_tp_doc`
657 * :c:data:`Py_tp_token` (for clarity, prefer :c:data:`Py_TP_USE_SPEC`
658 rather than ``NULL``)
659
660
661 .. c:macro:: Py_tp_token
662
663 A :c:member:`~PyType_Slot.slot` that records a static memory layout ID
664 for a class.
665
666 If the :c:type:`PyType_Spec` of the class is statically
667 allocated, the token can be set to the spec using the special value
668 :c:data:`Py_TP_USE_SPEC`:
669
670 .. code-block:: c
671
672 static PyType_Slot foo_slots[] = {
673 {Py_tp_token, Py_TP_USE_SPEC},
674
675 It can also be set to an arbitrary pointer, but you must ensure that:
676
677 * The pointer outlives the class, so it's not reused for something else
678 while the class exists.
679 * It "belongs" to the extension module where the class lives, so it will not
680 clash with other extensions.
681
682 Use :c:func:`PyType_GetBaseByToken` to check if a class's superclass has
683 a given token -- that is, check whether the memory layout is compatible.
684
685 To get the token for a given class (without considering superclasses),
686 use :c:func:`PyType_GetSlot` with ``Py_tp_token``.
687
688 .. versionadded:: 3.14
689
690 .. c:namespace:: NULL
691
692 .. c:macro:: Py_TP_USE_SPEC
693
694 Used as a value with :c:data:`Py_tp_token` to set the token to the
695 class's :c:type:`PyType_Spec`.
696 Expands to ``NULL``.
697
698 .. versionadded:: 3.14