Common Object Structures¶

There are a large number of structures which are used in the definition of object types for Python. This section describes these structures and how they are used.

Base object types and macros¶

All Python objects ultimately share a small number of fields at the beginning of the object’s representation in memory. These are represented by the PyObject and PyVarObject types, which are defined, in turn, by the expansions of some macros also used, whether directly or indirectly, in the definition of all other Python objects. Additional macros can be found under reference counting.

type PyObject¶

Part of the Limited API. (Only some members are part of the stable ABI.)

All object types are extensions of this type. This is a type which contains the information Python needs to treat a pointer to an object as an object. In a normal “release” build, it contains only the object’s reference count and a pointer to the corresponding type object. Nothing is actually declared to be a PyObject, but every pointer to a Python object can be cast to a PyObject*.

The members must not be accessed directly; instead use macros such as Py_REFCNT and Py_TYPE.

Py_ssize_t ob_refcnt¶

Part of the Stable ABI.

The object’s reference count, as returned by Py_REFCNT. Do not use this field directly; instead use functions and macros such as Py_REFCNT, Py_INCREF() and Py_DecRef().

The field type may be different from Py_ssize_t, depending on build configuration and platform.

PyTypeObject *ob_type¶: Part of the Stable ABI.
The object’s type. Do not use this field directly; use Py_TYPE and Py_SET_TYPE() instead.

type PyVarObject¶

Part of the Limited API. (Only some members are part of the stable ABI.)

An extension of PyObject that adds the ob_size field. This is intended for objects that have some notion of length.

As with PyObject, the members must not be accessed directly; instead use macros such as Py_SIZE, Py_REFCNT and Py_TYPE.

Py_ssize_t ob_size¶

Part of the Stable ABI.

A size field, whose contents should be considered an object’s internal implementation detail.

Do not use this field directly; use Py_SIZE instead.

Object creation functions such as PyObject_NewVar() will generally set this field to the requested size (number of items). After creation, arbitrary values can be stored in ob_size using Py_SET_SIZE.

To get an object’s publicly exposed length, as returned by the Python function len(), use PyObject_Length() instead.

PyObject_HEAD¶

This is a macro used when declaring new types which represent objects without a varying length. The PyObject_HEAD macro expands to:

PyObject ob_base;

See documentation of PyObject above.

PyObject_VAR_HEAD¶

This is a macro used when declaring new types which represent objects with a length that varies from instance to instance. The PyObject_VAR_HEAD macro expands to:

PyVarObject ob_base;

See documentation of PyVarObject above.

PyTypeObject PyBaseObject_Type¶: Part of the Stable ABI.
The base class of all other objects, the same as object in Python.

int Py_Is(PyObject *x, PyObject *y)¶: Part of the Stable ABI since version 3.10.
Test if the x object is the y object, the same as x is y in Python.

Added in version 3.10.

int Py_IsNone(PyObject *x)¶: Part of the Stable ABI since version 3.10.
Test if an object is the None singleton, the same as x is None in Python.

Added in version 3.10.

int Py_IsTrue(PyObject *x)¶: Part of the Stable ABI since version 3.10.
Test if an object is the True singleton, the same as x is True in Python.

Added in version 3.10.

int Py_IsFalse(PyObject *x)¶: Part of the Stable ABI since version 3.10.
Test if an object is the False singleton, the same as x is False in Python.

Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)¶

Return value: Borrowed reference. Part of the Stable ABI since version 3.14.

Get the type of the Python object o.

The returned reference is borrowed from o. Do not release it with Py_DECREF() or similar.

Changed in version 3.11: Py_TYPE() is changed to an inline static function. The parameter type is no longer const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)¶: Return non-zero if the object o type is type. Return zero otherwise. Equivalent to: Py_TYPE(o) == type.

Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)¶

Set the type of object o to type, without any checking or reference counting.

This is a very low-level operation. Consider instead setting the Python attribute __class__ using PyObject_SetAttrString() or similar.

Note that assigning an incompatible type can lead to undefined behavior.

If type is a heap type, the caller must create a new reference to it. Similarly, if the old type of o is a heap type, the caller must release a reference to that type.

Added in version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)¶: Get the ob_size field of o.

Changed in version 3.11: Py_SIZE() is changed to an inline static function. The parameter type is no longer const PyVarObject*.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)¶: Set the ob_size field of o to size.

Added in version 3.9.

PyObject_HEAD_INIT(type)