c
Perhaps one of the most important structures of the Python object system is the structure that defines a new type: the :cPyTypeObject
structure. Type objects can be handled using any of the :cPyObject_\*
or :cPyType_\*
functions, but do not offer much that's interesting to most Python applications. These objects are fundamental to how objects behave, so they are very important to the interpreter itself and to any extension module that implements new types.
Type objects are fairly large compared to most of the standard types. The reason for the size is that each type object stores a large number of values, mostly C function pointers, each of which implements a small part of the type's functionality. The fields of the type object are examined in detail in this section. The fields will be described in the order in which they occur in the structure.
Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, reprfunc, hashfunc
The structure definition for :cPyTypeObject
can be found in Include/object.h
. For convenience of reference, this repeats the definition found there:
../includes/typestruct.h
The type object structure extends the :cPyVarObject
structure. The ob_size
field is used for dynamic types (created by type_new
, usually called from a class statement). Note that :cPyType_Type
(the metatype) initializes tp_itemsize
, which means that its instances (i.e. type objects) must have the ob_size
field.
These fields are only present when the macro
Py_TRACE_REFS
is defined. Their initialization to NULL is taken care of by thePyObject_HEAD_INIT
macro. For statically allocated objects, these fields always remain NULL. For dynamically allocated objects, these two fields are used to link the object into a doubly-linked list of all live objects on the heap. This could be used for various debugging purposes; currently the only use is to print the objects that are still alive at the end of a run when the environment variablePYTHONDUMPREFS
is set.These fields are not inherited by subtypes.
These fields allow calculating the size in bytes of instances of the type.
There are two kinds of types: types with fixed-length instances have a zero
tp_itemsize
field, types with variable-length instances have a non-zerotp_itemsize
field. For a type with fixed-length instances, all instances have the same size, given intp_basicsize
.For a type with variable-length instances, the instances must have an
ob_size
field, and the instance size istp_basicsize
plus N timestp_itemsize
, where N is the "length" of the object. The value of N is typically stored in the instance'sob_size
field. There are exceptions: for example, ints use a negativeob_size
to indicate a negative number, and N isabs(ob_size)
there. Also, the presence of anob_size
field in the instance layout doesn't mean that the instance structure is variable-length (for example, the structure for the list type has fixed-length instances, yet those instances have a meaningfulob_size
field).The basic size includes the fields in the instance declared by the macro :c
PyObject_HEAD
or :cPyObject_VAR_HEAD
(whichever is used to declare the instance struct) and this in turn includes the_ob_prev
and_ob_next
fields if they are present. This means that the only correct way to get an initializer for thetp_basicsize
is to use thesizeof
operator on the struct used to declare the instance layout. The basic size does not include the GC header size.These fields are inherited separately by subtypes. If the base type has a non-zero
tp_itemsize
, it is generally not safe to settp_itemsize
to a different non-zero value in a subtype (though this depends on the implementation of the base type).A note about alignment: if the variable items require a particular alignment, this should be taken care of by the value of
tp_basicsize
. Example: suppose a type implements an array ofdouble
.tp_itemsize
issizeof(double)
. It is the programmer's responsibility thattp_basicsize
is a multiple ofsizeof(double)
(assuming this is the alignment requirement fordouble
).
The remaining fields are only defined if the feature test macro COUNT_ALLOCS
is defined, and are for internal use only. They are documented here for completeness. None of these fields are inherited by subtypes.
Also, note that, in a garbage collected Python, tp_dealloc may be called from any Python thread, not just the thread which created the object (if the object becomes part of a refcount cycle, that cycle might be collected by a garbage collection on any thread). This is not a problem for Python API calls, since the thread on which tp_dealloc is called will own the Global Interpreter Lock (GIL). However, if the object being destroyed in turn destroys objects from some other C or C++ library, care should be taken to ensure that destroying those objects on the thread which called tp_dealloc will not violate any assumptions of the library.
Amaury Forgeot d'Arc
Amaury Forgeot d'Arc
Amaury Forgeot d'Arc
Greg J. Stein <greg@lyra.org>
Benjamin Peterson
Stefan Krah