CPython's object Implementation in C

Jay Hubbert — Tue, 20 Oct 2026 09:00:00 +0000

Every Python value is a PyObject *. The type that defines what that pointer points at is object itself, implemented in CPython as PyBaseObject_Type in Objects/typeobject.c. Its instances are the smallest possible Python objects: just a reference count and a type pointer. This article traces that representation and the default behavior that every other type inherits from it.

The PyObject struct

The layout is defined in Include/object.h. In a normal (non-free-threaded) build with 64-bit pointers, it is:

 c
 
 
// Include/object.h
struct _object {
 _Py_ANONYMOUS union {
#if SIZEOF_VOID_P > 4
 int64_t ob_refcnt_full;
 struct {
# if PY_BIG_ENDIAN
 uint16_t ob_flags;
 uint16_t ob_overflow;
 uint32_t ob_refcnt;
# else
 uint32_t ob_refcnt;
 uint16_t ob_overflow;
 uint16_t ob_flags;
# endif
 };
#else
 Py_ssize_t ob_refcnt;
#endif
 _Py_ALIGNED_DEF(_PyObject_MIN_ALIGNMENT, char) _aligner;
 };
 PyTypeObject *ob_type;
};

Two fields matter. ob_refcnt is the reference count; ob_type is the pointer to the object’s type. PyObject_HEAD expands to PyObject ob_base;, so every concrete struct (PyLongObject, PyFloatObject, …) begins with exactly these fields, which is what makes the cast between PyObject * and a more specific pointer valid.

The reference count is manipulated by Py_INCREF/Py_DECREF. Py_DECREF calls the type’s tp_dealloc when the count reaches zero. New objects get their count set to one by _Py_NewReference, which PyObject_Init (and the inline _PyObject_Init) calls after storing the type pointer:

 c
 
 
// Include/internal/pycore_object.h
static inline void
_PyObject_Init(PyObject *op, PyTypeObject *typeobj)
{
 assert(op != NULL);
 Py_SET_TYPE(op, typeobj); // op->ob_type = typeobj
 _Py_INCREF_TYPE(typeobj);
 _Py_NewReference(op); // sets ob_refcnt to 1
}

Immortal objects (such as None, True, False, and static types) use a sentinel refcount (_Py_IMMORTAL_INITIAL_REFCNT) so Py_INCREF/Py_DECREF become no-ops for them.

Identity is just pointer equality:

 c
 
 
// Include/object.h
#define Py_Is(x, y) ((x) == (y))

and id(obj) in Python returns that pointer value (cast to an integer).

ob_size for variable-size objects

Objects whose size is determined at allocation time carry an extra ob_size field. These are PyVarObjects:

 c
 
 
// Include/object.h
struct PyVarObject {
 PyObject ob_base;
 Py_ssize_t ob_size; // Number of items in variable part
};
#define PyObject_VAR_HEAD PyVarObject ob_base;

ob_size is an element count, not a byte count. Types such as list, tuple, bytes and str start with PyObject_VAR_HEAD and allocate tp_basicsize + nitems * tp_itemsize bytes via _PyObject_NewVar:

 c
 
 
// Objects/object.c
PyVarObject *
_PyObject_NewVar(PyTypeObject *tp, Py_ssize_t nitems)
{
 PyVarObject *op;
 const size_t size = _PyObject_VAR_SIZE(tp, nitems);
 op = (PyVarObject *) PyObject_Malloc(size);
 if (op == NULL) {
 return (PyVarObject *) PyErr_NoMemory();
 }
 _PyObject_InitVar(op, tp, nitems); // sets ob_size = nitems
 return op;
}

_PyObject_InitVar stores the count with Py_SET_SIZE, and Py_SIZE(ob) reads it back (with an assertion that the object is not an int/bool, whose ob_size is overloaded for the sign/magnitude representation).

PyBaseObject_Type

The base type table is in Objects/typeobject.c:

 c
 
 
// Objects/typeobject.c
PyTypeObject PyBaseObject_Type = {
 PyVarObject_HEAD_INIT(&PyType_Type, 0)
 "object",
 sizeof(PyObject), /* tp_basicsize */
 0, /* tp_itemsize */
 object_dealloc, /* tp_dealloc */
 0, /* tp_vectorcall_offset */
 0, /* tp_getattr */
 0, /* tp_setattr */
 0, /* tp_as_async */
 object_repr, /* tp_repr */
 0, /* tp_as_number */
 0, /* tp_as_sequence */
 0, /* tp_as_mapping */
 PyObject_GenericHash, /* tp_hash */
 0, /* tp_call */
 object_str, /* tp_str */
 PyObject_GenericGetAttr, /* tp_getattro */
 PyObject_GenericSetAttr, /* tp_setattro */
 0, /* tp_as_buffer */
 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
 object_doc,
 0, /* tp_traverse */
 0, /* tp_clear */
 object_richcompare, /* tp_richcompare */
 ...
 object_methods, /* tp_methods */
 0, /* tp_members */
 object_getsets, /* tp_getset */
 0, /* tp_base */
 ...
 0, /* tp_dictoffset */
 object_init, /* tp_init */
 PyType_GenericAlloc, /* tp_alloc */
 object_new, /* tp_new */
 PyObject_Free, /* tp_free */
};

Key facts: tp_basicsize is sizeof(PyObject) (16 bytes on 64-bit), tp_itemsize is 0 (fixed size), there is no tp_base (it is the root), and Py_TPFLAGS_BASETYPE allows subclassing. Because tp_dictoffset is zero, a plain object() instance has no instance dictionary and cannot be given attributes.

Default behaviors

Allocation: `object_new`

 c
 
 
// Objects/typeobject.c
static PyObject *
object_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
 if (excess_args(args, kwds)) {
 if (type->tp_new != object_new) {
 /* subclass overrode __new__: complain here */
 ...
 }
 if (type->tp_init == object_init) {
 PyErr_Format(PyExc_TypeError, "%.200s() takes no arguments",
 type->tp_name);
 return NULL;
 }
 }
 if (type->tp_flags & Py_TPFLAGS_IS_ABSTRACT) {
 /* error: can't instantiate abstract class */
 ...
 }
 PyObject *obj = type->tp_alloc(type, 0); // PyType_GenericAlloc
 if (obj == NULL) {
 return NULL;
 }
 return obj;
}

So object() accepts no arguments; a subclass that overrides neither __new__ nor __init__ gets “takes no arguments”. Abstract classes (those with unimplemented abstract methods) are rejected here.

Initialization: `object_init`

 c
 
 
// Objects/typeobject.c
static int
object_init(PyObject *self, PyObject *args, PyObject *kwds)
{
 PyTypeObject *type = Py_TYPE(self);
 if (excess_args(args, kwds)) {
 if (type->tp_init != object_init) {
 PyErr_SetString(PyExc_TypeError,
 "object.__init__() takes exactly one argument ...");
 return -1;
 }
 if (type->tp_new == object_new) {
 /* __new__ not overridden: complain */
 ...
 }
 }
 return 0;
}

The default __init__ is a no-op; it only enforces the argument rules.

Deallocation: `object_dealloc`

 c
 
 
// Objects/typeobject.c
static void
object_dealloc(PyObject *self)
{
 Py_TYPE(self)->tp_free(self); // PyObject_Free for base object
}

repr: `object_repr`

 c
 
 
// Objects/typeobject.c
static PyObject *
object_repr(PyObject *self)
{
 PyTypeObject *type = Py_TYPE(self);
 PyObject *mod = type_module(type);
 ...
 PyObject *name = type_qualname((PyObject *)type, NULL);
 if (mod != NULL && !_PyUnicode_Equal(mod, &_Py_ID(builtins)))
 rtn = PyUnicode_FromFormat("<%U.%U object at %p>", mod, name, self);
 else
 rtn = PyUnicode_FromFormat("<%s object at %p>", type->tp_name, self);
 ...
 return rtn;
}

A plain instance prints as <object object at 0x...>; types outside builtins are qualified with their module name.

str: `object_str`

 c
 
 
// Objects/typeobject.c
static PyObject *
object_str(PyObject *self)
{
 unaryfunc f = Py_TYPE(self)->tp_repr;
 if (f == NULL)
 f = object_repr;
 return f(self);
}

Unless a subclass overrides __repr__/__str__, str(obj) falls back to repr(obj).

Hash: `PyObject_GenericHash`

 c
 
 
// Python/pyhash.c
Py_hash_t
PyObject_GenericHash(PyObject *obj)
{
 return Py_HashPointer(obj);
}

Py_hash_t
Py_HashPointer(const void *ptr)
{
 Py_hash_t hash = _Py_HashPointerRaw(ptr);
 if (hash == -1) {
 hash = -2;
 }
 return hash;
}

The default hash is derived from the object’s address, so two distinct instances have different hashes and object is hashable. Subclasses that define __eq__ typically set tp_hash = PyObject_HashNotImplemented (or override) to stay consistent.

Rich comparison: `object_richcompare`

 c
 
 
// Objects/typeobject.c
static PyObject *
object_richcompare(PyObject *self, PyObject *other, int op)
{
 switch (op) {
 case Py_EQ:
 res = Py_NewRef((self == other) ? Py_True : Py_NotImplemented);
 break;
 case Py_NE:
 if (Py_TYPE(self)->tp_richcompare == NULL) {
 res = Py_NewRef(Py_NotImplemented);
 break;
 }
 res = (*Py_TYPE(self)->tp_richcompare)(self, other, Py_EQ);
 if (res != NULL && res != Py_NotImplemented) {
 int ok = PyObject_IsTrue(res);
 Py_DECREF(res);
 res = ok ? Py_NewRef(Py_False) : Py_NewRef(Py_True);
 }
 break;
 default:
 res = Py_NewRef(Py_NotImplemented);
 break;
 }
 return res;
}

__eq__ returns True only for the exact same object, otherwise NotImplemented (letting the other operand or the default identity rule decide). __ne__ delegates to __eq__ and inverts. Ordering operators return NotImplemented, so <, >, etc. raise TypeError by default.

Attribute access: `PyObject_GenericGetAttr` / `PyObject_GenericSetAttr`

 c
 
 
// Objects/object.c
PyObject *
PyObject_GenericGetAttr(PyObject *obj, PyObject *name)
{
 return _PyObject_GenericGetAttrWithDict(obj, name, NULL, 0);
}

The generic getter looks up descriptors on the type, then the instance __dict__ (if tp_dictoffset is set). Because object has no tp_dictoffset, instances of object itself have no attributes at all; obj.x = 1 raises AttributeError. Subclasses that need attributes get a dict offset (or managed dicts) from the type machinery.

The one attribute always available is __class__, provided by the object_getsets table:

 c
 
 
// Objects/typeobject.c
static PyGetSetDef object_getsets[] = {
 {"__class__", object_get_class, object_set_class,
 PyDoc_STR("the object's class")},
 {0}
};

`sizeof`

 c
 
 
// Objects/typeobject.c
static PyObject *
object___sizeof___impl(PyObject *self)
{
 Py_ssize_t res, isize;
 res = 0;
 isize = Py_TYPE(self)->tp_itemsize;
 if (isize > 0) {
 res = _PyVarObject_CAST(self)->ob_size * isize;
 }
 res += Py_TYPE(self)->tp_basicsize;
 return PyLong_FromSsize_t(res);
}

So sys.getsizeof(obj) reports tp_basicsize + ob_size * tp_itemsize, i.e. the allocated size of the instance.

Summary

object is the root of the hierarchy: a 16-byte (on 64-bit) struct holding only ob_refcnt and ob_type, with ob_size added for variable-size subtypes. PyBaseObject_Type fills in sensible defaults – identity-based equality and hashing, a pointer-based repr, generic attribute access, no-op init, abstract-class checking in __new__, and PyObject_Free as the deallocator – that every other type either inherits or overrides. All of Python’s object model rests on these two fields and this one type table.

Object on Opensource internals

CPython's object Implementation in C

The PyObject struct

ob_size for variable-size objects

PyBaseObject_Type

Default behaviors

Allocation: object_new

Initialization: object_init

Deallocation: object_dealloc

repr: object_repr

str: object_str

Hash: PyObject_GenericHash

Rich comparison: object_richcompare

Attribute access: PyObject_GenericGetAttr / PyObject_GenericSetAttr

__sizeof__