.. highlightlang:: c

.. _type-structs:

Type Objects

============

Perhaps one of the most important structures of the Python object system is the

structure that defines a new type: the :ctype:`PyTypeObject` structure.  Type

objects can be handled using any of the :cfunc:`PyObject_\*` or

:cfunc:`PyType_\*` 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, coercion, intargfunc,

intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,

freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,

cmpfunc, reprfunc, hashfunc

The structure definition for :ctype:`PyTypeObject` can be found in

:file:`Include/object.h`.  For convenience of reference, this repeats the

definition found there:

.. literalinclude:: ../includes/typestruct.h

The type object structure extends the :ctype:`PyVarObject` structure. The

:attr:`ob_size` field is used for dynamic types (created by  :func:`type_new`,

usually called from a class statement). Note that :cdata:`PyType_Type` (the

metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.

type objects) *must* have the :attr:`ob_size` field.

.. cmember:: PyObject* PyObject._ob_next

             PyObject* PyObject._ob_prev

   These fields are only present when the macro ``Py_TRACE_REFS`` is defined.

   Their initialization to *NULL* is taken care of by the ``PyObject_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 variable

   :envvar:`PYTHONDUMPREFS` is set.

   These fields are not inherited by subtypes.

.. cmember:: Py_ssize_t PyObject.ob_refcnt

   This is the type object's reference count, initialized to ``1`` by the

   ``PyObject_HEAD_INIT`` macro.  Note that for statically allocated type objects,

   the type's instances (objects whose :attr:`ob_type` points back to the type) do

   *not* count as references.  But for dynamically allocated type objects, the

   instances *do* count as references.

   This field is not inherited by subtypes.

.. cmember:: PyTypeObject* PyObject.ob_type

   This is the type's type, in other words its metatype.  It is initialized by the

   argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be

   ``&PyType_Type``.  However, for dynamically loadable extension modules that must

   be usable on Windows (at least), the compiler complains that this is not a valid

   initializer.  Therefore, the convention is to pass *NULL* to the

   ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the

   start of the module's initialization function, before doing anything else.  This

   is typically done like this::

      Foo_Type.ob_type = &PyType_Type;

   This should be done before any instances of the type are created.

   :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,

   initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1

   and later it is initialized to the :attr:`ob_type` field of the base class.

   :cfunc:`PyType_Ready` will not change this field if it is non-zero.

   In Python 2.2, this field is not inherited by subtypes.  In 2.2.1, and in 2.3

   and beyond, it is inherited by subtypes.

.. cmember:: Py_ssize_t PyVarObject.ob_size

   For statically allocated type objects, this should be initialized to zero.  For

   dynamically allocated type objects, this field has a special internal meaning.

   This field is not inherited by subtypes.

.. cmember:: char* PyTypeObject.tp_name

   Pointer to a NUL-terminated string containing the name of the type. For types

   that are accessible as module globals, the string should be the full module

   name, followed by a dot, followed by the type name; for built-in types, it

   should be just the type name.  If the module is a submodule of a package, the

   full package name is part of the full module name.  For example, a type named

   :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`

   should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.

   For dynamically allocated type objects, this should just be the type name, and

   the module name explicitly stored in the type dict as the value for key

   ``'__module__'``.

   For statically allocated type objects, the tp_name field should contain a dot.

   Everything before the last dot is made accessible as the :attr:`__module__`

   attribute, and everything after the last dot is made accessible as the

   :attr:`__name__` attribute.

   If no dot is present, the entire :attr:`tp_name` field is made accessible as the

   :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined

   (unless explicitly set in the dictionary, as explained above).  This means your

   type will be impossible to pickle.

   This field is not inherited by subtypes.

.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize

             Py_ssize_t PyTypeObject.tp_itemsize

   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

   :attr:`tp_itemsize` field, types with variable-length instances have a non-zero

   :attr:`tp_itemsize` field.  For a type with fixed-length instances, all

   instances have the same size, given in :attr:`tp_basicsize`.

   For a type with variable-length instances, the instances must have an

   :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N

   times :attr:`tp_itemsize`, where N is the "length" of the object.  The value of

   N is typically stored in the instance's :attr:`ob_size` field.  There are

   exceptions:  for example, long ints use a negative :attr:`ob_size` to indicate a

   negative number, and N is ``abs(ob_size)`` there.  Also, the presence of an

   :attr:`ob_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 meaningful :attr:`ob_size`

   field).

   The basic size includes the fields in the instance declared by the macro

   :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to

   declare the instance struct) and this in turn includes the :attr:`_ob_prev` and

   :attr:`_ob_next` fields if they are present.  This means that the only correct

   way to get an initializer for the :attr:`tp_basicsize` is to use the

   ``sizeof`` operator on the struct used to declare the instance layout.

   The basic size does not include the GC header size (this is new in Python 2.2;

   in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).

   These fields are inherited separately by subtypes.  If the base type has a

   non-zero :attr:`tp_itemsize`, it is generally not safe to set

   :attr:`tp_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 :attr:`tp_basicsize`.  Example:

   suppose a type implements an array of ``double``. :attr:`tp_itemsize` is

   ``sizeof(double)``. It is the programmer's responsibility that

   :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the

   alignment requirement for ``double``).

.. cmember:: destructor PyTypeObject.tp_dealloc

   A pointer to the instance destructor function.  This function must be defined

   unless the type guarantees that its instances will never be deallocated (as is

   the case for the singletons ``None`` and ``Ellipsis``).

   The destructor function is called by the :cfunc:`Py_DECREF` and

   :cfunc:`Py_XDECREF` macros when the new reference count is zero.  At this point,

   the instance is still in existence, but there are no references to it.  The

   destructor function should free all references which the instance owns, free all

   memory buffers owned by the instance (using the freeing function corresponding

   to the allocation function used to allocate the buffer), and finally (as its

   last action) call the type's :attr:`tp_free` function.  If the type is not

   subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is

   permissible to call the object deallocator directly instead of via

   :attr:`tp_free`.  The object deallocator should be the one used to allocate the

   instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated

   using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or

   :cfunc:`PyObject_GC_Del` if the instance was allocated using

   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.

   This field is inherited by subtypes.

.. cmember:: printfunc PyTypeObject.tp_print

   An optional pointer to the instance print function.

   The print function is only called when the instance is printed to a *real* file;

   when it is printed to a pseudo-file (like a :class:`StringIO` instance), the

   instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to

   a string.  These are also called when the type's :attr:`tp_print` field is

   *NULL*.  A type should never implement :attr:`tp_print` in a way that produces

   different output than :attr:`tp_repr` or :attr:`tp_str` would.

   The print function is called with the same signature as :cfunc:`PyObject_Print`:

   ``int tp_print(PyObject *self, FILE *file, int flags)``.  The *self* argument is

   the instance to be printed.  The *file* argument is the stdio file to which it

   is to be printed.  The *flags* argument is composed of flag bits. The only flag

   bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`

   flag bit is set, the instance should be printed the same way as :attr:`tp_str`

   would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance

   should be printed the same was as :attr:`tp_repr` would format it. It should

   return ``-1`` and set an exception condition when an error occurred during the

   comparison.

   It is possible that the :attr:`tp_print` field will be deprecated. In any case,

   it is recommended not to define :attr:`tp_print`, but instead to rely on

   :attr:`tp_repr` and :attr:`tp_str` for printing.

   This field is inherited by subtypes.

.. cmember:: getattrfunc PyTypeObject.tp_getattr

   An optional pointer to the get-attribute-string function.

   This field is deprecated.  When it is defined, it should point to a function

   that acts the same as the :attr:`tp_getattro` function, but taking a C string

   instead of a Python string object to give the attribute name.  The signature is

   the same as for :cfunc:`PyObject_GetAttrString`.

   This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype

   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when

   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.

.. cmember:: setattrfunc PyTypeObject.tp_setattr

   An optional pointer to the set-attribute-string function.

   This field is deprecated.  When it is defined, it should point to a function

   that acts the same as the :attr:`tp_setattro` function, but taking a C string

   instead of a Python string object to give the attribute name.  The signature is

   the same as for :cfunc:`PyObject_SetAttrString`.

   This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype

   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when

   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.

.. cmember:: cmpfunc PyTypeObject.tp_compare

   An optional pointer to the three-way comparison function.

   The signature is the same as for :cfunc:`PyObject_Compare`. The function should

   return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to

   *other*, and ``-1`` if *self* less than *other*.  It should return ``-1`` and

   set an exception condition when an error occurred during the comparison.

   This field is inherited by subtypes together with :attr:`tp_richcompare` and

   :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`,

   :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's

   :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.

.. cmember:: reprfunc PyTypeObject.tp_repr

   .. index:: builtin: repr

   An optional pointer to a function that implements the built-in function

   :func:`repr`.

   The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string

   or a Unicode object.  Ideally, this function should return a string that, when

   passed to :func:`eval`, given a suitable environment, returns an object with the

   same value.  If this is not feasible, it should return a string starting with

   ``'<'`` and ending with ``'>'`` from which both the type and the value of the

   object can be deduced.

   When this field is not set, a string of the form ``<%s object at %p>`` is

   returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's

   memory address.

   This field is inherited by subtypes.

.. cmember:: PyNumberMethods* tp_as_number

   Pointer to an additional structure that contains fields relevant only to

   objects which implement the number protocol.  These fields are documented in

   :ref:`number-structs`.

   The :attr:`tp_as_number` field is not inherited, but the contained fields are

   inherited individually.

.. cmember:: PySequenceMethods* tp_as_sequence

   Pointer to an additional structure that contains fields relevant only to

   objects which implement the sequence protocol.  These fields are documented

   in :ref:`sequence-structs`.

   The :attr:`tp_as_sequence` field is not inherited, but the contained fields

   are inherited individually.

.. cmember:: PyMappingMethods* tp_as_mapping

   Pointer to an additional structure that contains fields relevant only to

   objects which implement the mapping protocol.  These fields are documented in

   :ref:`mapping-structs`.

   The :attr:`tp_as_mapping` field is not inherited, but the contained fields

   are inherited individually.

.. cmember:: hashfunc PyTypeObject.tp_hash

   .. index:: builtin: hash

   An optional pointer to a function that implements the built-in function

   :func:`hash`.

   The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C

   long.  The value ``-1`` should not be returned as a normal return value; when an

   error occurs during the computation of the hash value, the function should set

   an exception and return ``-1``.

   This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to

   block inheritance of the hash method from a parent type. This is interpreted

   as the equivalent of ``__hash__ = None`` at the Python level, causing

   ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note

   that the converse is also true - setting ``__hash__ = None`` on a class at

   the Python level will result in the ``tp_hash`` slot being set to

   :cfunc:`PyObject_HashNotImplemented`.

   When this field is not set, two possibilities exist: if the :attr:`tp_compare`

   and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on

   the object's address is returned; otherwise, a :exc:`TypeError` is raised.

   This field is inherited by subtypes together with :attr:`tp_richcompare` and

   :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,

   :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's

   :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.

.. cmember:: ternaryfunc PyTypeObject.tp_call

   An optional pointer to a function that implements calling the object.  This

   should be *NULL* if the object is not callable.  The signature is the same as

   for :cfunc:`PyObject_Call`.

   This field is inherited by subtypes.

.. cmember:: reprfunc PyTypeObject.tp_str

   An optional pointer to a function that implements the built-in operation

   :func:`str`.  (Note that :class:`str` is a type now, and :func:`str` calls the

   constructor for that type.  This constructor calls :cfunc:`PyObject_Str` to do

   the actual work, and :cfunc:`PyObject_Str` will call this handler.)

   The signature is the same as for :cfunc:`PyObject_Str`; it must return a string

   or a Unicode object.  This function should return a "friendly" string

   representation of the object, as this is the representation that will be used by

   the print statement.

   When this field is not set, :cfunc:`PyObject_Repr` is called to return a string

   representation.

   This field is inherited by subtypes.

.. cmember:: getattrofunc PyTypeObject.tp_getattro

   An optional pointer to the get-attribute function.

   The signature is the same as for :cfunc:`PyObject_GetAttr`.  It is usually

   convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which

   implements the normal way of looking for object attributes.

   This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype

   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when

   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.

.. cmember:: setattrofunc PyTypeObject.tp_setattro

   An optional pointer to the set-attribute function.

   The signature is the same as for :cfunc:`PyObject_SetAttr`.  It is usually

   convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which

   implements the normal way of setting object attributes.

   This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype

   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when

   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.

.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer

   Pointer to an additional structure that contains fields relevant only to objects

   which implement the buffer interface.  These fields are documented in

   :ref:`buffer-structs`.

   The :attr:`tp_as_buffer` field is not inherited, but the contained fields are

   inherited individually.

.. cmember:: long PyTypeObject.tp_flags

   This field is a bit mask of various flags.  Some flags indicate variant

   semantics for certain situations; others are used to indicate that certain

   fields in the type object (or in the extension structures referenced via

   :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and

   :attr:`tp_as_buffer`) that were historically not always present are valid; if

   such a flag bit is clear, the type fields it guards must not be accessed and

   must be considered to have a zero or *NULL* value instead.

   Inheritance of this field is complicated.  Most flag bits are inherited

   individually, i.e. if the base type has a flag bit set, the subtype inherits

   this flag bit.  The flag bits that pertain to extension structures are strictly

   inherited if the extension structure is inherited, i.e. the base type's value of

   the flag bit is copied into the subtype together with a pointer to the extension

   structure.  The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with

   the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the

   :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the

   :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as

   indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*

   values.

   The following bit masks are currently defined; these can be ORed together using

   the ``|`` operator to form the value of the :attr:`tp_flags` field.  The macro

   :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and

   checks whether ``tp->tp_flags & f`` is non-zero.

   .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER

      If this bit is set, the :ctype:`PyBufferProcs` struct referenced by

      :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.

   .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN

      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by

      :attr:`tp_as_sequence` has the :attr:`sq_contains` field.

   .. data:: Py_TPFLAGS_GC

      This bit is obsolete.  The bit it used to name is no longer in use.  The symbol

      is now defined as zero.

   .. data:: Py_TPFLAGS_HAVE_INPLACEOPS

      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by

      :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by

      :attr:`tp_as_number` contain the fields for in-place operators. In particular,

      this means that the :ctype:`PyNumberMethods` structure has the fields

      :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,

      :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,

      :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,

      :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,

      :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the

      :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and

      :attr:`sq_inplace_repeat`.

   .. data:: Py_TPFLAGS_CHECKTYPES

      If this bit is set, the binary and ternary operations in the

      :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept

      arguments of arbitrary object types, and do their own type conversions if

      needed.  If this bit is clear, those operations require that all arguments have

      the current type as their type, and the caller is supposed to perform a coercion

      operation first.  This applies to :attr:`nb_add`, :attr:`nb_subtract`,

      :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,

      :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,

      :attr:`nb_xor`, and :attr:`nb_or`.

   .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE

      If this bit is set, the type object has the :attr:`tp_richcompare` field, as

      well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.

   .. data:: Py_TPFLAGS_HAVE_WEAKREFS

      If this bit is set, the :attr:`tp_weaklistoffset` field is defined.  Instances

      of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field

      has a value greater than zero.

   .. data:: Py_TPFLAGS_HAVE_ITER

      If this bit is set, the type object has the :attr:`tp_iter` and

      :attr:`tp_iternext` fields.

   .. data:: Py_TPFLAGS_HAVE_CLASS

      If this bit is set, the type object has several new fields defined starting in

      Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,

      :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,

      :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,

      :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,

      :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.

   .. data:: Py_TPFLAGS_HEAPTYPE

      This bit is set when the type object itself is allocated on the heap.  In this

      case, the :attr:`ob_type` field of its instances is considered a reference to

      the type, and the type object is INCREF'ed when a new instance is created, and

      DECREF'ed when an instance is destroyed (this does not apply to instances of

      subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or

      DECREF'ed).

   .. data:: Py_TPFLAGS_BASETYPE

      This bit is set when the type can be used as the base type of another type.  If

      this bit is clear, the type cannot be subtyped (similar to a "final" class in

      Java).

   .. data:: Py_TPFLAGS_READY