8
Perhaps one of the most important structures of the Python object system is the
9
structure that defines a new type: the :ctype:`PyTypeObject` structure. Type
10
objects can be handled using any of the :cfunc:`PyObject_\*` or
11
:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most
12
Python applications. These objects are fundamental to how objects behave, so
13
they are very important to the interpreter itself and to any extension module
14
that implements new types.
16
Type objects are fairly large compared to most of the standard types. The reason
17
for the size is that each type object stores a large number of values, mostly C
18
function pointers, each of which implements a small part of the type's
19
functionality. The fields of the type object are examined in detail in this
20
section. The fields will be described in the order in which they occur in the
23
Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc,
24
intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
25
freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
28
The structure definition for :ctype:`PyTypeObject` can be found in
29
:file:`Include/object.h`. For convenience of reference, this repeats the
30
definition found there:
32
.. literalinclude:: ../includes/typestruct.h
35
The type object structure extends the :ctype:`PyVarObject` structure. The
36
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
37
usually called from a class statement). Note that :cdata:`PyType_Type` (the
38
metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
39
type objects) *must* have the :attr:`ob_size` field.
42
.. cmember:: PyObject* PyObject._ob_next
43
PyObject* PyObject._ob_prev
45
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
46
Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT``
47
macro. For statically allocated objects, these fields always remain *NULL*.
48
For dynamically allocated objects, these two fields are used to link the object
49
into a doubly-linked list of *all* live objects on the heap. This could be used
50
for various debugging purposes; currently the only use is to print the objects
51
that are still alive at the end of a run when the environment variable
52
:envvar:`PYTHONDUMPREFS` is set.
54
These fields are not inherited by subtypes.
57
.. cmember:: Py_ssize_t PyObject.ob_refcnt
59
This is the type object's reference count, initialized to ``1`` by the
60
``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
61
the type's instances (objects whose :attr:`ob_type` points back to the type) do
62
*not* count as references. But for dynamically allocated type objects, the
63
instances *do* count as references.
65
This field is not inherited by subtypes.
68
.. cmember:: PyTypeObject* PyObject.ob_type
70
This is the type's type, in other words its metatype. It is initialized by the
71
argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
72
``&PyType_Type``. However, for dynamically loadable extension modules that must
73
be usable on Windows (at least), the compiler complains that this is not a valid
74
initializer. Therefore, the convention is to pass *NULL* to the
75
``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
76
start of the module's initialization function, before doing anything else. This
77
is typically done like this::
79
Foo_Type.ob_type = &PyType_Type;
81
This should be done before any instances of the type are created.
82
:cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
83
initializes it to the :attr:`ob_type` field of the base class.
84
:cfunc:`PyType_Ready` will not change this field if it is non-zero.
86
This field is inherited by subtypes.
89
.. cmember:: Py_ssize_t PyVarObject.ob_size
91
For statically allocated type objects, this should be initialized to zero. For
92
dynamically allocated type objects, this field has a special internal meaning.
94
This field is not inherited by subtypes.
97
.. cmember:: char* PyTypeObject.tp_name
99
Pointer to a NUL-terminated string containing the name of the type. For types
100
that are accessible as module globals, the string should be the full module
101
name, followed by a dot, followed by the type name; for built-in types, it
102
should be just the type name. If the module is a submodule of a package, the
103
full package name is part of the full module name. For example, a type named
104
:class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
105
should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
107
For dynamically allocated type objects, this should just be the type name, and
108
the module name explicitly stored in the type dict as the value for key
111
For statically allocated type objects, the tp_name field should contain a dot.
112
Everything before the last dot is made accessible as the :attr:`__module__`
113
attribute, and everything after the last dot is made accessible as the
114
:attr:`__name__` attribute.
116
If no dot is present, the entire :attr:`tp_name` field is made accessible as the
117
:attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
118
(unless explicitly set in the dictionary, as explained above). This means your
119
type will be impossible to pickle.
121
This field is not inherited by subtypes.
124
.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize
125
Py_ssize_t PyTypeObject.tp_itemsize
127
These fields allow calculating the size in bytes of instances of the type.
129
There are two kinds of types: types with fixed-length instances have a zero
130
:attr:`tp_itemsize` field, types with variable-length instances have a non-zero
131
:attr:`tp_itemsize` field. For a type with fixed-length instances, all
132
instances have the same size, given in :attr:`tp_basicsize`.
134
For a type with variable-length instances, the instances must have an
135
:attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
136
times :attr:`tp_itemsize`, where N is the "length" of the object. The value of
137
N is typically stored in the instance's :attr:`ob_size` field. There are
138
exceptions: for example, ints use a negative :attr:`ob_size` to indicate a
139
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
140
:attr:`ob_size` field in the instance layout doesn't mean that the instance
141
structure is variable-length (for example, the structure for the list type has
142
fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
145
The basic size includes the fields in the instance declared by the macro
146
:cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to
147
declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
148
:attr:`_ob_next` fields if they are present. This means that the only correct
149
way to get an initializer for the :attr:`tp_basicsize` is to use the
150
``sizeof`` operator on the struct used to declare the instance layout.
151
The basic size does not include the GC header size.
153
These fields are inherited separately by subtypes. If the base type has a
154
non-zero :attr:`tp_itemsize`, it is generally not safe to set
155
:attr:`tp_itemsize` to a different non-zero value in a subtype (though this
156
depends on the implementation of the base type).
158
A note about alignment: if the variable items require a particular alignment,
159
this should be taken care of by the value of :attr:`tp_basicsize`. Example:
160
suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
161
``sizeof(double)``. It is the programmer's responsibility that
162
:attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
163
alignment requirement for ``double``).
166
.. cmember:: destructor PyTypeObject.tp_dealloc
168
A pointer to the instance destructor function. This function must be defined
169
unless the type guarantees that its instances will never be deallocated (as is
170
the case for the singletons ``None`` and ``Ellipsis``).
172
The destructor function is called by the :cfunc:`Py_DECREF` and
173
:cfunc:`Py_XDECREF` macros when the new reference count is zero. At this point,
174
the instance is still in existence, but there are no references to it. The
175
destructor function should free all references which the instance owns, free all
176
memory buffers owned by the instance (using the freeing function corresponding
177
to the allocation function used to allocate the buffer), and finally (as its
178
last action) call the type's :attr:`tp_free` function. If the type is not
179
subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
180
permissible to call the object deallocator directly instead of via
181
:attr:`tp_free`. The object deallocator should be the one used to allocate the
182
instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
183
using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
184
:cfunc:`PyObject_GC_Del` if the instance was allocated using
185
:cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
187
This field is inherited by subtypes.
190
.. cmember:: printfunc PyTypeObject.tp_print
192
An optional pointer to the instance print function.
194
The print function is only called when the instance is printed to a *real* file;
195
when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
196
instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
197
a string. These are also called when the type's :attr:`tp_print` field is
198
*NULL*. A type should never implement :attr:`tp_print` in a way that produces
199
different output than :attr:`tp_repr` or :attr:`tp_str` would.
201
The print function is called with the same signature as :cfunc:`PyObject_Print`:
202
``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is
203
the instance to be printed. The *file* argument is the stdio file to which it
204
is to be printed. The *flags* argument is composed of flag bits. The only flag
205
bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
206
flag bit is set, the instance should be printed the same way as :attr:`tp_str`
207
would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
208
should be printed the same was as :attr:`tp_repr` would format it. It should
209
return ``-1`` and set an exception condition when an error occurred during the
212
It is possible that the :attr:`tp_print` field will be deprecated. In any case,
213
it is recommended not to define :attr:`tp_print`, but instead to rely on
214
:attr:`tp_repr` and :attr:`tp_str` for printing.
216
This field is inherited by subtypes.
219
.. cmember:: getattrfunc PyTypeObject.tp_getattr
221
An optional pointer to the get-attribute-string function.
223
This field is deprecated. When it is defined, it should point to a function
224
that acts the same as the :attr:`tp_getattro` function, but taking a C string
225
instead of a Python string object to give the attribute name. The signature is
226
the same as for :cfunc:`PyObject_GetAttrString`.
228
This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
229
inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
230
the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
233
.. cmember:: setattrfunc PyTypeObject.tp_setattr
235
An optional pointer to the set-attribute-string function.
237
This field is deprecated. When it is defined, it should point to a function
238
that acts the same as the :attr:`tp_setattro` function, but taking a C string
239
instead of a Python string object to give the attribute name. The signature is
240
the same as for :cfunc:`PyObject_SetAttrString`.
242
This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
243
inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
244
the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
247
.. cmember:: void* PyTypeObject.tp_reserved
249
Reserved slot, formerly known as tp_compare.
252
.. cmember:: reprfunc PyTypeObject.tp_repr
254
.. index:: builtin: repr
256
An optional pointer to a function that implements the built-in function
259
The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string
260
or a Unicode object. Ideally, this function should return a string that, when
261
passed to :func:`eval`, given a suitable environment, returns an object with the
262
same value. If this is not feasible, it should return a string starting with
263
``'<'`` and ending with ``'>'`` from which both the type and the value of the
264
object can be deduced.
266
When this field is not set, a string of the form ``<%s object at %p>`` is
267
returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
270
This field is inherited by subtypes.
272
.. cmember:: PyNumberMethods* tp_as_number
274
Pointer to an additional structure that contains fields relevant only to
275
objects which implement the number protocol. These fields are documented in
276
:ref:`number-structs`.
278
The :attr:`tp_as_number` field is not inherited, but the contained fields are
279
inherited individually.
282
.. cmember:: PySequenceMethods* tp_as_sequence
284
Pointer to an additional structure that contains fields relevant only to
285
objects which implement the sequence protocol. These fields are documented
286
in :ref:`sequence-structs`.
288
The :attr:`tp_as_sequence` field is not inherited, but the contained fields
289
are inherited individually.
292
.. cmember:: PyMappingMethods* tp_as_mapping
294
Pointer to an additional structure that contains fields relevant only to
295
objects which implement the mapping protocol. These fields are documented in
296
:ref:`mapping-structs`.
298
The :attr:`tp_as_mapping` field is not inherited, but the contained fields
299
are inherited individually.
302
.. cmember:: hashfunc PyTypeObject.tp_hash
304
.. index:: builtin: hash
306
An optional pointer to a function that implements the built-in function
309
The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
310
long. The value ``-1`` should not be returned as a normal return value; when an
311
error occurs during the computation of the hash value, the function should set
312
an exception and return ``-1``.
314
This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to
315
block inheritance of the hash method from a parent type. This is interpreted
316
as the equivalent of ``__hash__ = None`` at the Python level, causing
317
``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
318
that the converse is also true - setting ``__hash__ = None`` on a class at
319
the Python level will result in the ``tp_hash`` slot being set to
320
:cfunc:`PyObject_HashNotImplemented`.
322
When this field is not set, an attempt to take the hash of the
323
object raises :exc:`TypeError`.
325
This field is inherited by subtypes together with
326
:attr:`tp_richcompare`: a subtype inherits both of
327
:attr:`tp_richcompare` and :attr:`tp_hash`, when the subtype's
328
:attr:`tp_richcompare` and :attr:`tp_hash` are both *NULL*.
331
.. cmember:: ternaryfunc PyTypeObject.tp_call
333
An optional pointer to a function that implements calling the object. This
334
should be *NULL* if the object is not callable. The signature is the same as
335
for :cfunc:`PyObject_Call`.
337
This field is inherited by subtypes.
340
.. cmember:: reprfunc PyTypeObject.tp_str
342
An optional pointer to a function that implements the built-in operation
343
:func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
344
constructor for that type. This constructor calls :cfunc:`PyObject_Str` to do
345
the actual work, and :cfunc:`PyObject_Str` will call this handler.)
347
The signature is the same as for :cfunc:`PyObject_Str`; it must return a string
348
or a Unicode object. This function should return a "friendly" string
349
representation of the object, as this is the representation that will be used,
350
among other things, by the :func:`print` function.
352
When this field is not set, :cfunc:`PyObject_Repr` is called to return a string
355
This field is inherited by subtypes.
358
.. cmember:: getattrofunc PyTypeObject.tp_getattro
360
An optional pointer to the get-attribute function.
362
The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually
363
convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which
364
implements the normal way of looking for object attributes.
366
This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
367
inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
368
the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
371
.. cmember:: setattrofunc PyTypeObject.tp_setattro
373
An optional pointer to the set-attribute function.
375
The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually
376
convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which
377
implements the normal way of setting object attributes.
379
This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
380
inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
381
the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
384
.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer
386
Pointer to an additional structure that contains fields relevant only to objects
387
which implement the buffer interface. These fields are documented in
388
:ref:`buffer-structs`.
390
The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
391
inherited individually.
394
.. cmember:: long PyTypeObject.tp_flags
396
This field is a bit mask of various flags. Some flags indicate variant
397
semantics for certain situations; others are used to indicate that certain
398
fields in the type object (or in the extension structures referenced via
399
:attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
400
:attr:`tp_as_buffer`) that were historically not always present are valid; if
401
such a flag bit is clear, the type fields it guards must not be accessed and
402
must be considered to have a zero or *NULL* value instead.
404
Inheritance of this field is complicated. Most flag bits are inherited
405
individually, i.e. if the base type has a flag bit set, the subtype inherits
406
this flag bit. The flag bits that pertain to extension structures are strictly
407
inherited if the extension structure is inherited, i.e. the base type's value of
408
the flag bit is copied into the subtype together with a pointer to the extension
409
structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
410
the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
411
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
412
:attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist and have
415
The following bit masks are currently defined; these can be ORed together using
416
the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro
417
:cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
418
checks whether ``tp->tp_flags & f`` is non-zero.
421
.. data:: Py_TPFLAGS_HEAPTYPE
423
This bit is set when the type object itself is allocated on the heap. In this
424
case, the :attr:`ob_type` field of its instances is considered a reference to
425
the type, and the type object is INCREF'ed when a new instance is created, and
426
DECREF'ed when an instance is destroyed (this does not apply to instances of
427
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
431
.. data:: Py_TPFLAGS_BASETYPE
433
This bit is set when the type can be used as the base type of another type. If
434
this bit is clear, the type cannot be subtyped (similar to a "final" class in
438
.. data:: Py_TPFLAGS_READY
440
This bit is set when the type object has been fully initialized by
441
:cfunc:`PyType_Ready`.
444
.. data:: Py_TPFLAGS_READYING
446
This bit is set while :cfunc:`PyType_Ready` is in the process of initializing
450
.. data:: Py_TPFLAGS_HAVE_GC
452
This bit is set when the object supports garbage collection. If this bit
453
is set, instances must be created using :cfunc:`PyObject_GC_New` and
454
destroyed using :cfunc:`PyObject_GC_Del`. More information in section
455
:ref:`supporting-cycle-detection`. This bit also implies that the
456
GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
460
.. data:: Py_TPFLAGS_DEFAULT
462
This is a bitmask of all the bits that pertain to the existence of certain
463
fields in the type object and its extension structures. Currently, it includes
464
the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`,
465
:const:`Py_TPFLAGS_HAVE_VERSION_TAG`.
468
.. cmember:: char* PyTypeObject.tp_doc
470
An optional pointer to a NUL-terminated C string giving the docstring for this
471
type object. This is exposed as the :attr:`__doc__` attribute on the type and
472
instances of the type.
474
This field is *not* inherited by subtypes.
477
.. cmember:: traverseproc PyTypeObject.tp_traverse
479
An optional pointer to a traversal function for the garbage collector. This is
480
only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information
481
about Python's garbage collection scheme can be found in section
482
:ref:`supporting-cycle-detection`.
484
The :attr:`tp_traverse` pointer is used by the garbage collector to detect
485
reference cycles. A typical implementation of a :attr:`tp_traverse` function
486
simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
487
objects. For example, this is function :cfunc:`local_traverse` from the
488
:mod:`_thread` extension module::
491
local_traverse(localobject *self, visitproc visit, void *arg)
493
Py_VISIT(self->args);
495
Py_VISIT(self->dict);
499
Note that :cfunc:`Py_VISIT` is called only on those members that can participate
500
in reference cycles. Although there is also a ``self->key`` member, it can only
501
be *NULL* or a Python string and therefore cannot be part of a reference cycle.
503
On the other hand, even if you know a member can never be part of a cycle, as a
504
debugging aid you may want to visit it anyway just so the :mod:`gc` module's
505
:func:`get_referents` function will include it.
507
Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to
508
:cfunc:`local_traverse` to have these specific names; don't name them just
511
This field is inherited by subtypes together with :attr:`tp_clear` and the
512
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
513
:attr:`tp_clear` are all inherited from the base type if they are all zero in
517
.. cmember:: inquiry PyTypeObject.tp_clear
519
An optional pointer to a clear function for the garbage collector. This is only
520
used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
522
The :attr:`tp_clear` member function is used to break reference cycles in cyclic
523
garbage detected by the garbage collector. Taken together, all :attr:`tp_clear`
524
functions in the system must combine to break all reference cycles. This is
525
subtle, and if in any doubt supply a :attr:`tp_clear` function. For example,
526
the tuple type does not implement a :attr:`tp_clear` function, because it's
527
possible to prove that no reference cycle can be composed entirely of tuples.
528
Therefore the :attr:`tp_clear` functions of other types must be sufficient to
529
break any cycle containing a tuple. This isn't immediately obvious, and there's
530
rarely a good reason to avoid implementing :attr:`tp_clear`.
532
Implementations of :attr:`tp_clear` should drop the instance's references to
533
those of its members that may be Python objects, and set its pointers to those
534
members to *NULL*, as in the following example::
537
local_clear(localobject *self)
540
Py_CLEAR(self->args);
542
Py_CLEAR(self->dict);
546
The :cfunc:`Py_CLEAR` macro should be used, because clearing references is
547
delicate: the reference to the contained object must not be decremented until
548
after the pointer to the contained object is set to *NULL*. This is because
549
decrementing the reference count may cause the contained object to become trash,
550
triggering a chain of reclamation activity that may include invoking arbitrary
551
Python code (due to finalizers, or weakref callbacks, associated with the
552
contained object). If it's possible for such code to reference *self* again,
553
it's important that the pointer to the contained object be *NULL* at that time,
554
so that *self* knows the contained object can no longer be used. The
555
:cfunc:`Py_CLEAR` macro performs the operations in a safe order.
557
Because the goal of :attr:`tp_clear` functions is to break reference cycles,
558
it's not necessary to clear contained objects like Python strings or Python
559
integers, which can't participate in reference cycles. On the other hand, it may
560
be convenient to clear all contained Python objects, and write the type's
561
:attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
563
More information about Python's garbage collection scheme can be found in
564
section :ref:`supporting-cycle-detection`.
566
This field is inherited by subtypes together with :attr:`tp_traverse` and the
567
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
568
:attr:`tp_clear` are all inherited from the base type if they are all zero in
572
.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
574
An optional pointer to the rich comparison function, whose signature is
575
``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
577
The function should return the result of the comparison (usually ``Py_True``
578
or ``Py_False``). If the comparison is undefined, it must return
579
``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
580
set an exception condition.
584
If you want to implement a type for which only a limited set of
585
comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
586
friends), directly raise :exc:`TypeError` in the rich comparison function.
588
This field is inherited by subtypes together with :attr:`tp_hash`:
589
a subtype inherits :attr:`tp_richcompare` and :attr:`tp_hash` when
590
the subtype's :attr:`tp_richcompare` and :attr:`tp_hash` are both
593
The following constants are defined to be used as the third argument for
594
:attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
596
+----------------+------------+
597
| Constant | Comparison |
598
+================+============+
599
| :const:`Py_LT` | ``<`` |
600
+----------------+------------+
601
| :const:`Py_LE` | ``<=`` |
602
+----------------+------------+
603
| :const:`Py_EQ` | ``==`` |
604
+----------------+------------+
605
| :const:`Py_NE` | ``!=`` |
606
+----------------+------------+
607
| :const:`Py_GT` | ``>`` |
608
+----------------+------------+
609
| :const:`Py_GE` | ``>=`` |
610
+----------------+------------+
613
.. cmember:: long PyTypeObject.tp_weaklistoffset
615
If the instances of this type are weakly referenceable, this field is greater
616
than zero and contains the offset in the instance structure of the weak
617
reference list head (ignoring the GC header, if present); this offset is used by
618
:cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The
619
instance structure needs to include a field of type :ctype:`PyObject\*` which is
620
initialized to *NULL*.
622
Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
623
weak references to the type object itself.
625
This field is inherited by subtypes, but see the rules listed below. A subtype
626
may override this offset; this means that the subtype uses a different weak
627
reference list head than the base type. Since the list head is always found via
628
:attr:`tp_weaklistoffset`, this should not be a problem.
630
When a type defined by a class statement has no :attr:`__slots__` declaration,
631
and none of its base types are weakly referenceable, the type is made weakly
632
referenceable by adding a weak reference list head slot to the instance layout
633
and setting the :attr:`tp_weaklistoffset` of that slot's offset.
635
When a type's :attr:`__slots__` declaration contains a slot named
636
:attr:`__weakref__`, that slot becomes the weak reference list head for
637
instances of the type, and the slot's offset is stored in the type's
638
:attr:`tp_weaklistoffset`.
640
When a type's :attr:`__slots__` declaration does not contain a slot named
641
:attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
644
.. cmember:: getiterfunc PyTypeObject.tp_iter
646
An optional pointer to a function that returns an iterator for the object. Its
647
presence normally signals that the instances of this type are iterable (although
648
sequences may be iterable without this function).
650
This function has the same signature as :cfunc:`PyObject_GetIter`.
652
This field is inherited by subtypes.
655
.. cmember:: iternextfunc PyTypeObject.tp_iternext
657
An optional pointer to a function that returns the next item in an iterator.
658
When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
659
exception may or may not be set. When another error occurs, it must return
660
*NULL* too. Its presence signals that the instances of this type are
663
Iterator types should also define the :attr:`tp_iter` function, and that
664
function should return the iterator instance itself (not a new iterator
667
This function has the same signature as :cfunc:`PyIter_Next`.
669
This field is inherited by subtypes.
672
.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
674
An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`
675
structures, declaring regular methods of this type.
677
For each entry in the array, an entry is added to the type's dictionary (see
678
:attr:`tp_dict` below) containing a method descriptor.
680
This field is not inherited by subtypes (methods are inherited through a
681
different mechanism).
684
.. cmember:: struct PyMemberDef* PyTypeObject.tp_members
686
An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef`
687
structures, declaring regular data members (fields or slots) of instances of
690
For each entry in the array, an entry is added to the type's dictionary (see
691
:attr:`tp_dict` below) containing a member descriptor.
693
This field is not inherited by subtypes (members are inherited through a
694
different mechanism).
697
.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset
699
An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef`
700
structures, declaring computed attributes of instances of this type.
702
For each entry in the array, an entry is added to the type's dictionary (see
703
:attr:`tp_dict` below) containing a getset descriptor.
705
This field is not inherited by subtypes (computed attributes are inherited
706
through a different mechanism).
708
Docs for PyGetSetDef (XXX belong elsewhere)::
710
typedef PyObject *(*getter)(PyObject *, void *);
711
typedef int (*setter)(PyObject *, PyObject *, void *);
713
typedef struct PyGetSetDef {
714
char *name; /* attribute name */
715
getter get; /* C function to get the attribute */
716
setter set; /* C function to set the attribute */
717
char *doc; /* optional doc string */
718
void *closure; /* optional additional data for getter and setter */
722
.. cmember:: PyTypeObject* PyTypeObject.tp_base
724
An optional pointer to a base type from which type properties are inherited. At
725
this level, only single inheritance is supported; multiple inheritance require
726
dynamically creating a type object by calling the metatype.
728
This field is not inherited by subtypes (obviously), but it defaults to
729
``&PyBaseObject_Type`` (which to Python programmers is known as the type
733
.. cmember:: PyObject* PyTypeObject.tp_dict
735
The type's dictionary is stored here by :cfunc:`PyType_Ready`.
737
This field should normally be initialized to *NULL* before PyType_Ready is
738
called; it may also be initialized to a dictionary containing initial attributes
739
for the type. Once :cfunc:`PyType_Ready` has initialized the type, extra
740
attributes for the type may be added to this dictionary only if they don't
741
correspond to overloaded operations (like :meth:`__add__`).
743
This field is not inherited by subtypes (though the attributes defined in here
744
are inherited through a different mechanism).
747
.. cmember:: descrgetfunc PyTypeObject.tp_descr_get
749
An optional pointer to a "descriptor get" function.
751
The function signature is ::
753
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
757
This field is inherited by subtypes.
760
.. cmember:: descrsetfunc PyTypeObject.tp_descr_set
762
An optional pointer to a "descriptor set" function.
764
The function signature is ::
766
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
768
This field is inherited by subtypes.
773
.. cmember:: long PyTypeObject.tp_dictoffset
775
If the instances of this type have a dictionary containing instance variables,
776
this field is non-zero and contains the offset in the instances of the type of
777
the instance variable dictionary; this offset is used by
778
:cfunc:`PyObject_GenericGetAttr`.
780
Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
781
attributes of the type object itself.
783
If the value of this field is greater than zero, it specifies the offset from
784
the start of the instance structure. If the value is less than zero, it
785
specifies the offset from the *end* of the instance structure. A negative
786
offset is more expensive to use, and should only be used when the instance
787
structure contains a variable-length part. This is used for example to add an
788
instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
789
that the :attr:`tp_basicsize` field should account for the dictionary added to
790
the end in that case, even though the dictionary is not included in the basic
791
object layout. On a system with a pointer size of 4 bytes,
792
:attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
793
at the very end of the structure.
795
The real dictionary offset in an instance can be computed from a negative
796
:attr:`tp_dictoffset` as follows::
798
dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
799
if dictoffset is not aligned on sizeof(void*):
800
round up to sizeof(void*)
802
where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
803
taken from the type object, and :attr:`ob_size` is taken from the instance. The
804
absolute value is taken because ints use the sign of :attr:`ob_size` to
805
store the sign of the number. (There's never a need to do this calculation
806
yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)
808
This field is inherited by subtypes, but see the rules listed below. A subtype
809
may override this offset; this means that the subtype instances store the
810
dictionary at a difference offset than the base type. Since the dictionary is
811
always found via :attr:`tp_dictoffset`, this should not be a problem.
813
When a type defined by a class statement has no :attr:`__slots__` declaration,
814
and none of its base types has an instance variable dictionary, a dictionary
815
slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
818
When a type defined by a class statement has a :attr:`__slots__` declaration,
819
the type inherits its :attr:`tp_dictoffset` from its base type.
821
(Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
822
not have the expected effect, it just causes confusion. Maybe this should be
823
added as a feature just like :attr:`__weakref__` though.)
826
.. cmember:: initproc PyTypeObject.tp_init
828
An optional pointer to an instance initialization function.
830
This function corresponds to the :meth:`__init__` method of classes. Like
831
:meth:`__init__`, it is possible to create an instance without calling
832
:meth:`__init__`, and it is possible to reinitialize an instance by calling its
833
:meth:`__init__` method again.
835
The function signature is ::
837
int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
839
The self argument is the instance to be initialized; the *args* and *kwds*
840
arguments represent positional and keyword arguments of the call to
843
The :attr:`tp_init` function, if not *NULL*, is called when an instance is
844
created normally by calling its type, after the type's :attr:`tp_new` function
845
has returned an instance of the type. If the :attr:`tp_new` function returns an
846
instance of some other type that is not a subtype of the original type, no
847
:attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
848
subtype of the original type, the subtype's :attr:`tp_init` is called.
850
This field is inherited by subtypes.
853
.. cmember:: allocfunc PyTypeObject.tp_alloc
855
An optional pointer to an instance allocation function.
857
The function signature is ::
859
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
861
The purpose of this function is to separate memory allocation from memory
862
initialization. It should return a pointer to a block of memory of adequate
863
length for the instance, suitably aligned, and initialized to zeros, but with
864
:attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
865
the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
866
should be initialized to *nitems* and the length of the allocated memory block
867
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
868
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
869
should be :attr:`tp_basicsize`.
871
Do not use this function to do any other instance initialization, not even to
872
allocate additional memory; that should be done by :attr:`tp_new`.
874
This field is inherited by static subtypes, but not by dynamic subtypes
875
(subtypes created by a class statement); in the latter, this field is always set
876
to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
877
That is also the recommended value for statically defined types.
880
.. cmember:: newfunc PyTypeObject.tp_new
882
An optional pointer to an instance creation function.
884
If this function is *NULL* for a particular type, that type cannot be called to
885
create new instances; presumably there is some other way to create instances,
886
like a factory function.
888
The function signature is ::
890
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
892
The subtype argument is the type of the object being created; the *args* and
893
*kwds* arguments represent positional and keyword arguments of the call to the
894
type. Note that subtype doesn't have to equal the type whose :attr:`tp_new`
895
function is called; it may be a subtype of that type (but not an unrelated
898
The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
899
to allocate space for the object, and then do only as much further
900
initialization as is absolutely necessary. Initialization that can safely be
901
ignored or repeated should be placed in the :attr:`tp_init` handler. A good
902
rule of thumb is that for immutable types, all initialization should take place
903
in :attr:`tp_new`, while for mutable types, most initialization should be
904
deferred to :attr:`tp_init`.
906
This field is inherited by subtypes, except it is not inherited by static types
907
whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.
910
.. cmember:: destructor PyTypeObject.tp_free
912
An optional pointer to an instance deallocation function. Its signature is
917
An initializer that is compatible with this signature is :cfunc:`PyObject_Free`.
919
This field is inherited by static subtypes, but not by dynamic subtypes
920
(subtypes created by a class statement); in the latter, this field is set to a
921
deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the
922
:const:`Py_TPFLAGS_HAVE_GC` flag bit.
925
.. cmember:: inquiry PyTypeObject.tp_is_gc
927
An optional pointer to a function called by the garbage collector.
929
The garbage collector needs to know whether a particular object is collectible
930
or not. Normally, it is sufficient to look at the object's type's
931
:attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
932
some types have a mixture of statically and dynamically allocated instances, and
933
the statically allocated instances are not collectible. Such types should
934
define this function; it should return ``1`` for a collectible instance, and
935
``0`` for a non-collectible instance. The signature is ::
937
int tp_is_gc(PyObject *self)
939
(The only example of this are types themselves. The metatype,
940
:cdata:`PyType_Type`, defines this function to distinguish between statically
941
and dynamically allocated types.)
943
This field is inherited by subtypes.
946
.. cmember:: PyObject* PyTypeObject.tp_bases
950
This is set for types created by a class statement. It should be *NULL* for
951
statically defined types.
953
This field is not inherited.
956
.. cmember:: PyObject* PyTypeObject.tp_mro
958
Tuple containing the expanded set of base types, starting with the type itself
959
and ending with :class:`object`, in Method Resolution Order.
961
This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.
964
.. cmember:: PyObject* PyTypeObject.tp_cache
966
Unused. Not inherited. Internal use only.
969
.. cmember:: PyObject* PyTypeObject.tp_subclasses
971
List of weak references to subclasses. Not inherited. Internal use only.
974
.. cmember:: PyObject* PyTypeObject.tp_weaklist
976
Weak reference list head, for weak references to this type object. Not
977
inherited. Internal use only.
979
The remaining fields are only defined if the feature test macro
980
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
981
documented here for completeness. None of these fields are inherited by
985
.. cmember:: Py_ssize_t PyTypeObject.tp_allocs
987
Number of allocations.
990
.. cmember:: Py_ssize_t PyTypeObject.tp_frees
995
.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc
997
Maximum simultaneously allocated objects.
1000
.. cmember:: PyTypeObject* PyTypeObject.tp_next
1002
Pointer to the next type object with a non-zero :attr:`tp_allocs` field.
1004
Also, note that, in a garbage collected Python, tp_dealloc may be called from
1005
any Python thread, not just the thread which created the object (if the object
1006
becomes part of a refcount cycle, that cycle might be collected by a garbage
1007
collection on any thread). This is not a problem for Python API calls, since
1008
the thread on which tp_dealloc is called will own the Global Interpreter Lock
1009
(GIL). However, if the object being destroyed in turn destroys objects from some
1010
other C or C++ library, care should be taken to ensure that destroying those
1011
objects on the thread which called tp_dealloc will not violate any assumptions
1017
Number Object Structures
1018
========================
1020
.. sectionauthor:: Amaury Forgeot d'Arc
1023
.. ctype:: PyNumberMethods
1025
This structure holds pointers to the functions which an object uses to
1026
implement the number protocol. Each function is used by the function of
1027
similar name documented in the :ref:`number` section.
1029
Here is the structure definition::
1033
binaryfunc nb_subtract;
1034
binaryfunc nb_multiply;
1035
binaryfunc nb_remainder;
1036
binaryfunc nb_divmod;
1037
ternaryfunc nb_power;
1038
unaryfunc nb_negative;
1039
unaryfunc nb_positive;
1040
unaryfunc nb_absolute;
1042
unaryfunc nb_invert;
1043
binaryfunc nb_lshift;
1044
binaryfunc nb_rshift;
1052
binaryfunc nb_inplace_add;
1053
binaryfunc nb_inplace_subtract;
1054
binaryfunc nb_inplace_multiply;
1055
binaryfunc nb_inplace_divide;
1056
binaryfunc nb_inplace_remainder;
1057
ternaryfunc nb_inplace_power;
1058
binaryfunc nb_inplace_lshift;
1059
binaryfunc nb_inplace_rshift;
1060
binaryfunc nb_inplace_and;
1061
binaryfunc nb_inplace_xor;
1062
binaryfunc nb_inplace_or;
1064
binaryfunc nb_floor_divide;
1065
binaryfunc nb_true_divide;
1066
binaryfunc nb_inplace_floor_divide;
1067
binaryfunc nb_inplace_true_divide;
1074
Binary and ternary functions must check the type of all their operands,
1075
and implement the necessary conversions (at least one of the operands is
1076
an instance of the defined type). If the operation is not defined for the
1077
given operands, binary and ternary functions must return
1078
``Py_NotImplemented``, if another error occurred they must return ``NULL``
1079
and set an exception.
1083
The :cdata:`nb_reserved` field should always be ``NULL``. It
1084
was previously called :cdata:`nb_long`, and was renamed in
1088
.. _mapping-structs:
1090
Mapping Object Structures
1091
=========================
1093
.. sectionauthor:: Amaury Forgeot d'Arc
1096
.. ctype:: PyMappingMethods
1098
This structure holds pointers to the functions which an object uses to
1099
implement the mapping protocol. It has three members:
1101
.. cmember:: lenfunc PyMappingMethods.mp_length
1103
This function is used by :cfunc:`PyMapping_Length` and
1104
:cfunc:`PyObject_Size`, and has the same signature. This slot may be set to
1105
*NULL* if the object has no defined length.
1107
.. cmember:: binaryfunc PyMappingMethods.mp_subscript
1109
This function is used by :cfunc:`PyObject_GetItem` and has the same
1110
signature. This slot must be filled for the :cfunc:`PyMapping_Check`
1111
function to return ``1``, it can be *NULL* otherwise.
1113
.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript
1115
This function is used by :cfunc:`PyObject_SetItem` and has the same
1116
signature. If this slot is *NULL*, the object does not support item
1120
.. _sequence-structs:
1122
Sequence Object Structures
1123
==========================
1125
.. sectionauthor:: Amaury Forgeot d'Arc
1128
.. ctype:: PySequenceMethods
1130
This structure holds pointers to the functions which an object uses to
1131
implement the sequence protocol.
1133
.. cmember:: lenfunc PySequenceMethods.sq_length
1135
This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`,
1136
and has the same signature.
1138
.. cmember:: binaryfunc PySequenceMethods.sq_concat
1140
This function is used by :cfunc:`PySequence_Concat` and has the same
1141
signature. It is also used by the ``+`` operator, after trying the numeric
1142
addition via the :attr:`tp_as_number.nb_add` slot.
1144
.. cmember:: ssizeargfunc PySequenceMethods.sq_repeat
1146
This function is used by :cfunc:`PySequence_Repeat` and has the same
1147
signature. It is also used by the ``*`` operator, after trying numeric
1148
multiplication via the :attr:`tp_as_number.nb_mul` slot.
1150
.. cmember:: ssizeargfunc PySequenceMethods.sq_item
1152
This function is used by :cfunc:`PySequence_GetItem` and has the same
1153
signature. This slot must be filled for the :cfunc:`PySequence_Check`
1154
function to return ``1``, it can be *NULL* otherwise.
1156
Negative indexes are handled as follows: if the :attr:`sq_length` slot is
1157
filled, it is called and the sequence length is used to compute a positive
1158
index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*,
1159
the index is passed as is to the function.
1161
.. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item
1163
This function is used by :cfunc:`PySequence_SetItem` and has the same
1164
signature. This slot may be left to *NULL* if the object does not support
1167
.. cmember:: objobjproc PySequenceMethods.sq_contains
1169
This function may be used by :cfunc:`PySequence_Contains` and has the same
1170
signature. This slot may be left to *NULL*, in this case
1171
:cfunc:`PySequence_Contains` simply traverses the sequence until it finds a
1174
.. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat
1176
This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same
1177
signature. It should modify its first operand, and return it.
1179
.. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
1181
This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same
1182
signature. It should modify its first operand, and return it.
1184
.. XXX need to explain precedence between mapping and sequence
1185
.. XXX explains when to implement the sq_inplace_* slots
1190
Buffer Object Structures
1191
========================
1193
.. sectionauthor:: Greg J. Stein <greg@lyra.org>
1194
.. sectionauthor:: Benjamin Peterson
1197
The buffer interface exports a model where an object can expose its internal
1200
If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
1201
member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the
1202
:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure.
1205
.. ctype:: PyBufferProcs
1207
Structure used to hold the function pointers which define an implementation of
1208
the buffer protocol.
1210
.. cmember:: getbufferproc bf_getbuffer
1212
This should fill a :ctype:`Py_buffer` with the necessary data for
1213
exporting the type. The signature of :data:`getbufferproc` is ``int
1214
(PyObject *obj, PyObject *view, int flags)``. *obj* is the object to
1215
export, *view* is the :ctype:`Py_buffer` struct to fill, and *flags* gives
1216
the conditions the caller wants the memory under. (See
1217
:cfunc:`PyObject_GetBuffer` for all flags.) :cmember:`bf_getbuffer` is
1218
responsible for filling *view* with the appropriate information.
1219
(:cfunc:`PyBuffer_FillView` can be used in simple cases.) See
1220
:ctype:`Py_buffer`\s docs for what needs to be filled in.
1223
.. cmember:: releasebufferproc bf_releasebuffer
1225
This should release the resources of the buffer. The signature of
1226
:cdata:`releasebufferproc` is ``void (PyObject *obj, Py_buffer *view)``.
1227
If the :cdata:`bf_releasebuffer` function is not provided (i.e. it is
1228
*NULL*), then it does not ever need to be called.
1230
The exporter of the buffer interface must make sure that any memory
1231
pointed to in the :ctype:`Py_buffer` structure remains valid until
1232
releasebuffer is called. Exporters will need to define a
1233
:cdata:`bf_releasebuffer` function if they can re-allocate their memory,
1234
strides, shape, suboffsets, or format variables which they might share
1235
through the struct bufferinfo.
1237
See :cfunc:`PyBuffer_Release`.
added
removed
Doc/c-api/typeobj.rst
