| 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 |