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 Stable ABI (see below).

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.

In the Stable ABI for Free-Threaded Builds (abi3t), this struct is opaque; its size and layout may change between Python versions. In Stable ABI for non-free-threaded builds (abi3), the ob_refcnt and ob_type fields are available, but using them directly is discouraged.

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.

PyMutex ob_mutex

A per-object lock, present only in the free-threaded build (when Py_GIL_DISABLED is defined).

This field is reserved for use by the critical section API (Py_BEGIN_CRITICAL_SECTION / Py_END_CRITICAL_SECTION). Do not lock it directly with PyMutex_Lock; doing so can cause deadlocks. If you need your own lock, add a separate PyMutex field to your object struct.

Added in version 3.13.

type PyVarObject

Part of the Stable ABI (see below).

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.

In the Stable ABI for Free-Threaded Builds (abi3t), this struct is opaque; its size and layout may change between Python versions. In Stable ABI for non-free-threaded builds (abi3), the ob_base and ob_size fields are available, but using them directly is discouraged.

PyObject ob_base

Part of the Stable ABI.

Common object header. Typically, this field is not accessed directly; instead PyVarObject can be cast to PyObject.

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(