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:: PyObject* 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 true if the object *o* is a type object, including instances of types 25 derived from the standard type object. Return false in all other cases. 26 27 28.. c:function:: int PyType_CheckExact(PyObject *o) 29 30 Return true if the object *o* is a type object, but not a subtype of the 31 standard type object. Return false in all other cases. 32 33 34.. c:function:: unsigned int PyType_ClearCache() 35 36 Clear the internal lookup cache. Return the current version tag. 37 38.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type) 39 40 Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily 41 meant for use with `Py_LIMITED_API`; the individual flag bits are 42 guaranteed to be stable across Python releases, but access to 43 :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. 44 45 .. versionadded:: 3.2 46 47 .. versionchanged:: 3.4 48 The return type is now ``unsigned long`` rather than ``long``. 49 50 51.. c:function:: void PyType_Modified(PyTypeObject *type) 52 53 Invalidate the internal lookup cache for the type and all of its 54 subtypes. This function must be called after any manual 55 modification of the attributes or base classes of the type. 56 57 58.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature) 59 60 Return true if the type object *o* sets the feature *feature*. Type features 61 are denoted by single bit flags. 62 63 64.. c:function:: int PyType_IS_GC(PyTypeObject *o) 65 66 Return true if the type object includes support for the cycle detector; this 67 tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. 68 69 70.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) 71 72 Return true if *a* is a subtype of *b*. 73 74 This function only checks for actual subtypes, which means that 75 :meth:`~class.__subclasscheck__` is not called on *b*. Call 76 :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass` 77 would do. 78 79 80.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) 81 82 Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use 83 Python's default memory allocation mechanism to allocate a new instance and 84 initialize all its contents to ``NULL``. 85 86.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) 87 88 Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a 89 new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot. 90 91.. c:function:: int PyType_Ready(PyTypeObject *type) 92 93 Finalize a type object. This should be called on all type objects to finish 94 their initialization. This function is responsible for adding inherited slots 95 from a type's base class. Return ``0`` on success, or return ``-1`` and sets an 96 exception on error. 97 98.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot) 99 100 Return the function pointer stored in the given slot. If the 101 result is ``NULL``, this indicates that either the slot is ``NULL``, 102 or that the function was called with invalid parameters. 103 Callers will typically cast the result pointer into the appropriate 104 function type. 105 106 See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument. 107 108 An exception is raised if *type* is not a heap type. 109 110 .. versionadded:: 3.4 111 112 113Creating Heap-Allocated Types 114............................. 115 116The following functions and structs are used to create 117:ref:`heap types <heap-types>`. 118 119.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases) 120 121 Creates and returns a heap type object from the *spec* 122 (:const:`Py_TPFLAGS_HEAPTYPE`). 123 124 If *bases* is a tuple, the created heap type contains all types contained 125 in it as base types. 126 127 If *bases* is ``NULL``, the *Py_tp_base* slot is used instead. 128 If that also is ``NULL``, the new type derives from :class:`object`. 129 130 This function calls :c:func:`PyType_Ready` on the new type. 131 132 .. versionadded:: 3.3 133 134.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec) 135 136 Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``. 137 138.. c:type:: PyType_Spec 139 140 Structure defining a type's behavior. 141 142 .. c:member:: const char* PyType_Spec.name 143 144 Name of the type, used to set :c:member:`PyTypeObject.tp_name`. 145 146 .. c:member:: int PyType_Spec.basicsize 147 .. c:member:: int PyType_Spec.itemsize 148 149 Size of the instance in bytes, used to set 150 :c:member:`PyTypeObject.tp_basicsize` and 151 :c:member:`PyTypeObject.tp_itemsize`. 152 153 .. c:member:: int PyType_Spec.flags 154 155 Type flags, used to set :c:member:`PyTypeObject.tp_flags`. 156 157 If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, 158 :c:func:`PyType_FromSpecWithBases` sets it automatically. 159 160 .. c:member:: PyType_Slot *PyType_Spec.slots 161 162 Array of :c:type:`PyType_Slot` structures. 163 Terminated by the special slot value ``{0, NULL}``. 164 165.. c:type:: PyType_Slot 166 167 Structure defining optional functionality of a type, containing a slot ID 168 and a value pointer. 169 170 .. c:member:: int PyType_Slot.slot 171 172 A slot ID. 173 174 Slot IDs are named like the field names of the structures 175 :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`, 176 :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and 177 :c:type:`PyAsyncMethods` with an added ``Py_`` prefix. 178 For example, use: 179 180 * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc` 181 * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add` 182 * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length` 183 184 The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`: 185 186 * :c:member:`~PyTypeObject.tp_dict` 187 * :c:member:`~PyTypeObject.tp_mro` 188 * :c:member:`~PyTypeObject.tp_cache` 189 * :c:member:`~PyTypeObject.tp_subclasses` 190 * :c:member:`~PyTypeObject.tp_weaklist` 191 * :c:member:`~PyTypeObject.tp_print` 192 * :c:member:`~PyTypeObject.tp_weaklistoffset` 193 * :c:member:`~PyTypeObject.tp_dictoffset` 194 * :c:member:`~PyBufferProcs.bf_getbuffer` 195 * :c:member:`~PyBufferProcs.bf_releasebuffer` 196 197 Setting :c:data:`Py_tp_bases` may be problematic on some platforms. 198 To avoid issues, use the *bases* argument of 199 :py:func:`PyType_FromSpecWithBases` instead. 200 201 .. c:member:: void *PyType_Slot.pfunc 202 203 The desired value of the slot. In most cases, this is a pointer 204 to a function. 205 206 May not be ``NULL``. 207