# sandbox/morph / Doc / c-api / typeobj.rst

## Type Objects

Perhaps one of the most important structures of the Python object system is the structure that defines a new type: the :c:type:PyTypeObject structure. Type objects can be handled using any of the :c:func:PyObject_\* or :c:func: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 :c:type:PyTypeObject can be found in :file:Include/object.h. For convenience of reference, this repeats the definition found there:

The type object structure extends the :c:type: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 :c:data:PyType_Type (the metatype) initializes :attr:tp_itemsize, which means that its instances (i.e. type objects) must have the :attr:ob_size field.

The following three fields only exist if the :const:Py_TPFLAGS_HAVE_RICHCOMPARE flag bit is set.

The next field only exists if the :const:Py_TPFLAGS_HAVE_WEAKREFS flag bit is set.

The next two fields only exist if the :const:Py_TPFLAGS_HAVE_ITER flag bit is set.

The next fields, up to and including :attr:tp_weaklist, only exist if the :const:Py_TPFLAGS_HAVE_CLASS flag bit is set.

The remaining fields are only defined if the feature test macro :const: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.

## Number Object Structures

Binary and ternary functions may receive different kinds of arguments, depending on the flag bit :const:Py_TPFLAGS_CHECKTYPES:

• If :const:Py_TPFLAGS_CHECKTYPES is not set, the function arguments are guaranteed to be of the object's type; the caller is responsible for calling the coercion method specified by the :attr:nb_coerce member to convert the arguments:
• If the :const:Py_TPFLAGS_CHECKTYPES flag is set, binary and ternary functions must check the type of all their operands, and implement the necessary conversions (at least one of the operands is an instance of the defined type). This is the recommended way; with Python 3.0 coercion will disappear completely.

If the operation is not defined for the given operands, binary and ternary functions must return Py_NotImplemented, if another error occurred they must return NULL and set an exception.

## Buffer Object Structures

The buffer interface exports a model where an object can expose its internal data as a set of chunks of data, where each chunk is specified as a pointer/length pair. These chunks are called :dfn:segments and are presumed to be non-contiguous in memory.

If an object does not export the buffer interface, then its :attr:tp_as_buffer member in the :c:type:PyTypeObject structure should be NULL. Otherwise, the :attr:tp_as_buffer will point to a :c:type:PyBufferProcs structure.

Note

It is very important that your :c:type:PyTypeObject structure uses :const:Py_TPFLAGS_DEFAULT for the value of the :attr:tp_flags member rather than 0. This tells the Python runtime that your :c:type:PyBufferProcs structure contains the :attr:bf_getcharbuffer slot. Older versions of Python did not have this member, so a new Python interpreter using an old extension needs to be able to test for its presence before using it.