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.

Mapping Object Structures

Sequence Object Structures

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.


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.