1.. highlight:: c
2
3.. _typeobjects:
4
5Type 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 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:: PyObject* PyType_GetName(PyTypeObject *type)
110
111   Return the type's name. Equivalent to getting the type's ``__name__`` attribute.
112
113   .. versionadded:: 3.11
114
115.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
116
117   Return the type's qualified name. Equivalent to getting the
118   type's ``__qualname__`` attribute.
119
120   .. versionadded:: 3.11
121
122.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
123
124   Return the function pointer stored in the given slot. If the
125   result is ``NULL``, this indicates that either the slot is ``NULL``,
126   or that the function was called with invalid parameters.
127   Callers will typically cast the result pointer into the appropriate
128   function type.
129
130   See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument.
131
132   .. versionadded:: 3.4
133
134   .. versionchanged:: 3.10
135      :c:func:`PyType_GetSlot` can now accept all types.
136      Previously, it was limited to :ref:`heap types <heap-types>`.
137
138.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
139
140   Return the module object associated with the given type when the type was
141   created using :c:func:`PyType_FromModuleAndSpec`.
142
143   If no module is associated with the given type, sets :py:class:`TypeError`
144   and returns ``NULL``.
145
146   This function is usually used to get the module in which a method is defined.
147   Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
148   may not return the intended result.
149   ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
150   are not necessarily defined in the same module as their superclass.
151   See :c:type:`PyCMethod` to get the class that defines the method.
152   See :c:func:`PyType_GetModuleByDef` for cases when ``PyCMethod`` cannot
153   be used.
154
155   .. versionadded:: 3.9
156
157.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
158
159   Return the state of the module object associated with the given type.
160   This is a shortcut for calling :c:func:`PyModule_GetState()` on the result
161   of :c:func:`PyType_GetModule`.
162
163   If no module is associated with the given type, sets :py:class:`TypeError`
164   and returns ``NULL``.
165
166   If the *type* has an associated module but its state is ``NULL``,
167   returns ``NULL`` without setting an exception.
168
169   .. versionadded:: 3.9
170
171.. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
172
173   Find the first superclass whose module was created from
174   the given :c:type:`PyModuleDef` *def*, and return that module.
175
176   If no module is found, raises a :py:class:`TypeError` and returns ``NULL``.
177
178   This function is intended to be used together with
179   :c:func:`PyModule_GetState()` to get module state from slot methods (such as
180   :c:member:`~PyTypeObject.tp_init` or :c:member:`~PyNumberMethods.nb_add`)
181   and other places where a method's defining class cannot be passed using the
182   :c:type:`PyCMethod` calling convention.
183
184   .. versionadded:: 3.11
185
186
187Creating Heap-Allocated Types
188.............................
189
190The following functions and structs are used to create
191:ref:`heap types <heap-types>`.
192
193.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
194
195   Creates and returns a :ref:`heap type <heap-types>` from the *spec*
196   (:const:`Py_TPFLAGS_HEAPTYPE`).
197
198   The *bases* argument can be used to specify base classes; it can either
199   be only one class or a tuple of classes.
200   If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead.
201   If that also is ``NULL``, the *Py_tp_base* slot is used instead.
202   If that also is ``NULL``, the new type derives from :class:`object`.
203
204   The *module* argument can be used to record the module in which the new
205   class is defined. It must be a module object or ``NULL``.
206   If not ``NULL``, the module is associated with the new type and can later be
207   retrieved with :c:func:`PyType_GetModule`.
208   The associated module is not inherited by subclasses; it must be specified
209   for each class individually.
210
211   This function calls :c:func:`PyType_Ready` on the new type.
212
213   .. versionadded:: 3.9
214
215   .. versionchanged:: 3.10
216
217      The function now accepts a single class as the *bases* argument and
218      ``NULL`` as the ``tp_doc`` slot.
219
220.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
221
222   Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
223
224   .. versionadded:: 3.3
225
226.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
227
228   Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``.
229
230.. c:type:: PyType_Spec
231
232   Structure defining a type's behavior.
233
234   .. c:member:: const char* PyType_Spec.name
235
236      Name of the type, used to set :c:member:`PyTypeObject.tp_name`.
237
238   .. c:member:: int PyType_Spec.basicsize
239   .. c:member:: int PyType_Spec.itemsize
240
241      Size of the instance in bytes, used to set
242      :c:member:`PyTypeObject.tp_basicsize` and
243      :c:member:`PyTypeObject.tp_itemsize`.
244
245   .. c:member:: int PyType_Spec.flags
246
247      Type flags, used to set :c:member:`PyTypeObject.tp_flags`.
248
249      If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set,
250      :c:func:`PyType_FromSpecWithBases` sets it automatically.
251
252   .. c:member:: PyType_Slot *PyType_Spec.slots
253
254      Array of :c:type:`PyType_Slot` structures.
255      Terminated by the special slot value ``{0, NULL}``.
256
257.. c:type:: PyType_Slot
258
259   Structure defining optional functionality of a type, containing a slot ID
260   and a value pointer.
261
262   .. c:member:: int PyType_Slot.slot
263
264      A slot ID.
265
266      Slot IDs are named like the field names of the structures
267      :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`,
268      :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and
269      :c:type:`PyAsyncMethods` with an added ``Py_`` prefix.
270      For example, use:
271
272      * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc`
273      * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
274      * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
275
276      The following fields cannot be set at all using :c:type:`PyType_Spec` and
277      :c:type:`PyType_Slot`:
278
279      * :c:member:`~PyTypeObject.tp_dict`
280      * :c:member:`~PyTypeObject.tp_mro`
281      * :c:member:`~PyTypeObject.tp_cache`
282      * :c:member:`~PyTypeObject.tp_subclasses`
283      * :c:member:`~PyTypeObject.tp_weaklist`
284      * :c:member:`~PyTypeObject.tp_vectorcall`
285      * :c:member:`~PyTypeObject.tp_weaklistoffset`
286        (see :ref:`PyMemberDef <pymemberdef-offsets>`)
287      * :c:member:`~PyTypeObject.tp_dictoffset`
288        (see :ref:`PyMemberDef <pymemberdef-offsets>`)
289      * :c:member:`~PyTypeObject.tp_vectorcall_offset`
290        (see :ref:`PyMemberDef <pymemberdef-offsets>`)
291
292      Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
293      problematic on some platforms.
294      To avoid issues, use the *bases* argument of
295      :py:func:`PyType_FromSpecWithBases` instead.
296
297     .. versionchanged:: 3.9
298
299        Slots in :c:type:`PyBufferProcs` may be set in the unlimited API.
300
301     .. versionchanged:: 3.11
302        :c:member:`~PyBufferProcs.bf_getbuffer` and
303        :c:member:`~PyBufferProcs.bf_releasebuffer` are now available
304        under the limited API.
305
306   .. c:member:: void *PyType_Slot.pfunc
307
308      The desired value of the slot. In most cases, this is a pointer
309      to a function.
310
311      Slots other than ``Py_tp_doc`` may not be ``NULL``.
312