PyObject

PyObject is the core data structure for all Python objects in the CPython reference implementation. In CPython’s C API, every Python object is represented at the C level as a PyObject or as a struct that begins with the PyObject header. The PyObject structure contains the object's reference count and a pointer to its type object. The type object, implemented as PyTypeObject, defines the object's behavior, including how it is deallocated, compared, converted, and how attributes are accessed.

Concrete Python types (such as lists, dictionaries, strings, or functions) typically define their C structs with PyObject_HEAD to include the standard header fields and then add type-specific fields. This layout allows the runtime to treat all objects uniformly through PyObject pointers while retaining type-specific data.

Memory management relies primarily on reference counting. The API provides macros such as Py_INCREF and Py_DECREF to adjust the reference count. When an object's reference count reaches zero, its tp_dealloc slot is invoked to release resources. CPython also implements a cyclic garbage collector to detect and collect reference cycles; objects participating in cycles implement traversal and clearing hooks (tp_traverse and tp_clear) and can be tracked by the GC via related APIs.

In practice, most C extensions and embedding code manipulate PyObject* pointers. Type information is accessible at runtime through the ob_type field and helpers like Py_TYPE, enabling runtime type checks and safe casting within the CPython type system.

PyObject is defined in Include/object.h, and its header macro usage (such as PyObject_HEAD) standardizes object layout across all built-in and user-defined types. This foundational abstraction underpins Python’s dynamic typing, memory management, and object model in CPython.