1.. highlight:: c 2 3.. _typeobjects: 4 5Type Objects 6------------ 7 8.. index:: 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 limited 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:: void PyType_Modified(PyTypeObject *type) 54 55 Invalidate the internal lookup cache for the type and all of its 56 subtypes. This function must be called after any manual 57 modification of the attributes or base classes of the type. 58 59 60.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature) 61 62 Return non-zero if the type object *o* sets the feature *feature*. 63 Type features are denoted by single bit flags. 64 65 66.. c:function:: int PyType_IS_GC(PyTypeObject *o) 67 68 Return true if the type object includes support for the cycle detector; this 69 tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. 70 71 72.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) 73 74 Return true if *a* is a subtype of *b*. 75 76 This function only checks for actual subtypes, which means that 77 :meth:`~class.__subclasscheck__` is not called on *b*. Call 78 :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass` 79 would do. 80 81 82.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) 83 84 Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use 85 Python's default memory allocation mechanism to allocate a new instance and 86 initialize all its contents to ``NULL``. 87 88.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) 89 90 Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a 91 new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot. 92 93.. c:function:: int PyType_Ready(PyTypeObject *type) 94 95 Finalize a type object. This should be called on all type objects to finish 96 their initialization. This function is responsible for adding inherited slots 97 from a type's base class. Return ``0`` on success, or return ``-1`` and sets an 98 exception on error. 99 100 .. note:: 101 If some of the base classes implements the GC protocol and the provided 102 type does not include the :const:`Py_TPFLAGS_HAVE_GC` in its flags, then 103 the GC protocol will be automatically implemented from its parents. On 104 the contrary, if the type being created does include 105 :const:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the 106 GC protocol itself by at least implementing the 107 :c:member:`~PyTypeObject.tp_traverse` handle. 108 109.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot) 110 111 Return the function pointer stored in the given slot. If the 112 result is ``NULL``, this indicates that either the slot is ``NULL``, 113 or that the function was called with invalid parameters. 114 Callers will typically cast the result pointer into the appropriate 115 function type. 116 117 See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument. 118 119 .. versionadded:: 3.4 120 121 .. versionchanged:: 3.10 122 :c:func:`PyType_GetSlot` can now accept all types. 123 Previously, it was limited to :ref:`heap types <heap-types>`. 124 125.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type) 126 127 Return the module object associated with the given type when the type was 128 created using :c:func:`PyType_FromModuleAndSpec`. 129 130 If no module is associated with the given type, sets :py:class:`TypeError` 131 and returns ``NULL``. 132 133 This function is usually used to get the module in which a method is defined. 134 Note that in such a method, ``PyType_GetModule(Py_TYPE(self))`` 135 may not return the intended result. 136 ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses 137 are not necessarily defined in the same module as their superclass. 138 See :c:type:`PyCMethod` to get the class that defines the method. 139 140 .. versionadded:: 3.9 141 142.. c:function:: void* PyType_GetModuleState(PyTypeObject *type) 143 144 Return the state of the module object associated with the given type. 145 This is a shortcut for calling :c:func:`PyModule_GetState()` on the result 146 of :c:func:`PyType_GetModule`. 147 148 If no module is associated with the given type, sets :py:class:`TypeError` 149 and returns ``NULL``. 150 151 If the *type* has an associated module but its state is ``NULL``, 152 returns ``NULL`` without setting an exception. 153 154 .. versionadded:: 3.9 155 156 157Creating Heap-Allocated Types 158............................. 159 160The following functions and structs are used to create 161:ref:`heap types <heap-types>`. 162 163.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases) 164 165 Creates and returns a :ref:`heap type <heap-types>` from the *spec* 166 (:const:`Py_TPFLAGS_HEAPTYPE`). 167 168 The *bases* argument can be used to specify base classes; it can either 169 be only one class or a tuple of classes. 170 If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead. 171 If that also is ``NULL``, the *Py_tp_base* slot is used instead. 172 If that also is ``NULL``, the new type derives from :class:`object`. 173 174 The *module* argument can be used to record the module in which the new 175 class is defined. It must be a module object or ``NULL``. 176 If not ``NULL``, the module is associated with the new type and can later be 177 retrieved with :c:func:`PyType_GetModule`. 178 The associated module is not inherited by subclasses; it must be specified 179 for each class individually. 180 181 This function calls :c:func:`PyType_Ready` on the new type. 182 183 .. versionadded:: 3.9 184 185 .. versionchanged:: 3.10 186 187 The function now accepts a single class as the *bases* argument and 188 ``NULL`` as the ``tp_doc`` slot. 189 190.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases) 191 192 Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``. 193 194 .. versionadded:: 3.3 195 196.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec) 197 198 Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``. 199 200.. c:type:: PyType_Spec 201 202 Structure defining a type's behavior. 203 204 .. c:member:: const char* PyType_Spec.name 205 206 Name of the type, used to set :c:member:`PyTypeObject.tp_name`. 207 208 .. c:member:: int PyType_Spec.basicsize 209 .. c:member:: int PyType_Spec.itemsize 210 211 Size of the instance in bytes, used to set 212 :c:member:`PyTypeObject.tp_basicsize` and 213 :c:member:`PyTypeObject.tp_itemsize`. 214 215 .. c:member:: int PyType_Spec.flags 216 217 Type flags, used to set :c:member:`PyTypeObject.tp_flags`. 218 219 If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, 220 :c:func:`PyType_FromSpecWithBases` sets it automatically. 221 222 .. c:member:: PyType_Slot *PyType_Spec.slots 223 224 Array of :c:type:`PyType_Slot` structures. 225 Terminated by the special slot value ``{0, NULL}``. 226 227.. c:type:: PyType_Slot 228 229 Structure defining optional functionality of a type, containing a slot ID 230 and a value pointer. 231 232 .. c:member:: int PyType_Slot.slot 233 234 A slot ID. 235 236 Slot IDs are named like the field names of the structures 237 :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`, 238 :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and 239 :c:type:`PyAsyncMethods` with an added ``Py_`` prefix. 240 For example, use: 241 242 * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc` 243 * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add` 244 * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length` 245 246 The following fields cannot be set at all using :c:type:`PyType_Spec` and 247 :c:type:`PyType_Slot`: 248 249 * :c:member:`~PyTypeObject.tp_dict` 250 * :c:member:`~PyTypeObject.tp_mro` 251 * :c:member:`~PyTypeObject.tp_cache` 252 * :c:member:`~PyTypeObject.tp_subclasses` 253 * :c:member:`~PyTypeObject.tp_weaklist` 254 * :c:member:`~PyTypeObject.tp_vectorcall` 255 * :c:member:`~PyTypeObject.tp_weaklistoffset` 256 (see :ref:`PyMemberDef <pymemberdef-offsets>`) 257 * :c:member:`~PyTypeObject.tp_dictoffset` 258 (see :ref:`PyMemberDef <pymemberdef-offsets>`) 259 * :c:member:`~PyTypeObject.tp_vectorcall_offset` 260 (see :ref:`PyMemberDef <pymemberdef-offsets>`) 261 262 The following fields cannot be set using :c:type:`PyType_Spec` and 263 :c:type:`PyType_Slot` under the limited API: 264 265 * :c:member:`~PyBufferProcs.bf_getbuffer` 266 * :c:member:`~PyBufferProcs.bf_releasebuffer` 267 268 Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be 269 problematic on some platforms. 270 To avoid issues, use the *bases* argument of 271 :py:func:`PyType_FromSpecWithBases` instead. 272 273 .. versionchanged:: 3.9 274 275 Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API. 276 277 .. c:member:: void *PyType_Slot.pfunc 278 279 The desired value of the slot. In most cases, this is a pointer 280 to a function. 281 282 Slots other than ``Py_tp_doc`` may not be ``NULL``. 283