.. highlight:: c

.. _common-structs:

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

:c:type:`PyObject` and :c:type:`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 :ref:`reference counting <countingrefs>`.

.. c:type:: PyObject

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 :c:type:`PyObject`, but every pointer

to a Python object can be cast to a :c:expr:`PyObject*`.

The members must not be accessed directly; instead use macros such as

:c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`.

In the :ref:`Stable ABI <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

:c:member:`!ob_refcnt` and :c:member:`!ob_type` fields are available,

but using them directly is discouraged.

.. c:member:: Py_ssize_t ob_refcnt

The object's reference count, as returned by :c:macro:`Py_REFCNT`.

Do not use this field directly; instead use functions and macros such as

:c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`.

The field type may be different from ``Py_ssize_t``, depending on

build configuration and platform.

.. c:member:: PyTypeObject* ob_type

The object's type.

Do not use this field directly; use :c:macro:`Py_TYPE` and

:c:func:`Py_SET_TYPE` instead.

.. c:member:: PyMutex ob_mutex

A :ref:`per-object lock <per-object-locks>`, present only in the :term:`free-threaded <free threading>`

build (when :c:macro:`Py_GIL_DISABLED` is defined).

This field is **reserved for use by the critical section API**

(:c:macro:`Py_BEGIN_CRITICAL_SECTION` / :c:macro:`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 :c:type:`PyMutex`

field to your object struct.

.. versionadded:: 3.13

.. c:type:: PyVarObject

An extension of :c:type:`PyObject` that adds the

:c:member:`~PyVarObject.ob_size` field.

This is intended for objects that have some notion of *length*.

As with :c:type:`!PyObject`, the members must not be accessed directly;

instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and

:c:macro:`Py_TYPE`.

In the :ref:`Stable ABI <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

:c:member:`!ob_base` and :c:member:`!ob_size` fields are available,

but using them directly is discouraged.

.. c:member:: PyObject ob_base

Common object header.

Typically, this field is not accessed directly; instead

:c:type:`!PyVarObject` can be cast to :c:type:`PyObject`.

.. c:member:: Py_ssize_t ob_size

A size field, whose contents should be considered an object's internal

implementation detail.

Do not use this field directly; use :c:macro:`Py_SIZE` instead.

Object creation functions such as :c:func:`PyObject_NewVar` will

generally set this field to the requested size (number of items).

After creation, arbitrary values can be stored in :c:member:`!ob_size`

using :c:macro:`Py_SET_SIZE`.

To get an object's publicly exposed length, as returned by

the Python function :py:func:`len`, use :c:func:`PyObject_Length`

instead.

.. c:macro:: PyObject_HEAD

This is a macro used when declaring new types which represent objects

without a varying length. The PyObject_HEAD macro expands to::

See documentation of :c:type:`PyObject` above.

.. c:macro:: 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::

See documentation of :c:type:`PyVarObject` above.

.. c:var:: PyTypeObject PyBaseObject_Type

The base class of all other objects, the same as :class:`object` in Python.

.. c:function:: int Py_Is(PyObject *x, PyObject *y)