CPython's Ellipsis Implementation in C

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

Python’s Ellipsis is the object spelled .... It is a singleton: there is exactly one instance, and type(Ellipsis) is types.EllipsisType. In CPython it lives in Objects/sliceobject.c alongside slice, and is implemented as a statically allocated, immortal PyObject whose type is PyEllipsis_Type. This article traces that implementation through the 3.15 source.

The singleton: `_Py_EllipsisObject`

The entire object is a single global struct with no payload beyond the object header:

 c
 
 
// Objects/sliceobject.c
PyObject _Py_EllipsisObject = _PyObject_HEAD_INIT(&PyEllipsis_Type);

There is no tp_alloc, no freelist, and no _PyObject_GC_New. The object exists for the lifetime of the interpreter because it is a file-scope (static storage) variable. Its initializer uses _PyObject_HEAD_INIT, which, on 64-bit builds, sets an immortal reference count and the static flag bits:

 c
 
 
// Include/internal/pycore_object.h
#if SIZEOF_VOID_P > 4
#define _PyObject_HEAD_INIT(type) \
 { \
 .ob_refcnt = _Py_IMMORTAL_INITIAL_REFCNT, \
 .ob_flags = _Py_STATIC_FLAG_BITS, \
 .ob_type = (type) \
 }
#endif

_Py_IMMORTAL_INITIAL_REFCNT is (3ULL << 30), a value chosen to be far above any realistic reference count so that increment/decrement operations never reach zero. The object is therefore immortal from the moment the module is loaded – no runtime call is needed to “make” it immortal.

The type: `PyEllipsis_Type`

PyEllipsis_Type is a plain (non-GC) type with a zero basic size, since no instances are ever allocated:

 c
 
 
// Objects/sliceobject.c
PyTypeObject PyEllipsis_Type = {
 PyVarObject_HEAD_INIT(&PyType_Type, 0)
 "ellipsis", /* tp_name */
 0, /* tp_basicsize */
 0, /* tp_itemsize */
 ellipsis_dealloc, /* tp_dealloc */
 ...
 ellipsis_repr, /* tp_repr */
 ...
 PyObject_GenericGetAttr, /* tp_getattro */
 ...
 Py_TPFLAGS_DEFAULT, /* tp_flags */
 ellipsis_doc, /* tp_doc */
 ...
 ellipsis_methods, /* tp_methods */
 ...
 ellipsis_new, /* tp_new */
};

Key points:

tp_basicsize is 0 because instances are never created through tp_alloc; the only instance is the static _Py_EllipsisObject.
tp_flags is just Py_TPFLAGS_DEFAULT – no Py_TPFLAGS_HAVE_GC, so the singleton is not tracked by the garbage collector.
tp_getattro is PyObject_GenericGetAttr, so attribute lookup works normally (e.g. Ellipsis.__reduce__).
tp_hash is 0, meaning the default identity-based hash is used; because there is only one instance this is effectively a constant.
tp_richcompare is 0. Equality falls back to identity, so Ellipsis == Ellipsis is True and Ellipsis == 42 is False.

The type is exported to Python as types.EllipsisType via Modules/_typesmodule.c:

 c
 
 
// Modules/_typesmodule.c
EXPORT_STATIC_TYPE("EllipsisType", PyEllipsis_Type);

Construction: `ellipsis_new`

Calling EllipsisType() (or type(Ellipsis)()) must return the singleton rather than allocate a new object. ellipsis_new enforces that no arguments are passed and returns Py_Ellipsis:

 c
 
 
// Objects/sliceobject.c
static PyObject *
ellipsis_new(PyTypeObject *type, PyObject *args, PyObject *kwargs)
{
 if (PyTuple_GET_SIZE(args) || (kwargs && PyDict_GET_SIZE(kwargs))) {
 PyErr_SetString(PyExc_TypeError, "EllipsisType takes no arguments");
 return NULL;
 }
 return Py_Ellipsis;
}

This is why type(Ellipsis)() produces the same singleton, as documented in the standard library docs. ellipsis_new does not touch reference counts; it returns a borrowed reference in the CPython convention used by tp_new.

Dealloc guard: `ellipsis_dealloc`

Because the object is immortal, tp_dealloc should never run. It exists only as a safety net in case a bug drives the reference count to zero. Instead of freeing memory (which would be catastrophic for a static object), it re-immortalizes the object:

 c
 
 
// Objects/sliceobject.c
static void
ellipsis_dealloc(PyObject *ellipsis)
{
 /* This should never get called, but we also don't want to SEGV if
 * we accidentally decref Ellipsis out of existence. Instead,
 * since Ellipsis is an immortal object, re-set the reference count.
 */
 _Py_SetImmortal(ellipsis);
}

_Py_SetImmortal untracks the object from the GC (if it were tracked) and resets ob_refcnt/ob_flags to the immortal values. The same pattern is used by none_dealloc and notimplemented_dealloc for None and NotImplemented.

Repr and pickling

 c
 
 
// Objects/sliceobject.c
static PyObject *
ellipsis_repr(PyObject *op)
{
 return PyUnicode_FromString("Ellipsis");
}

static PyObject *
ellipsis_reduce(PyObject *op, PyObject *Py_UNUSED(ignored))
{
 return PyUnicode_FromString("Ellipsis");
}

repr(Ellipsis) and str(Ellipsis) both yield "Ellipsis" (tp_str is 0, so str() falls back to repr()).
__reduce__ returns the string "Ellipsis", which pickles/unpickles by name lookup, so a round-trip produces the same singleton.
The method table exposes only __reduce__:

 c
 
 
// Objects/sliceobject.c
static PyMethodDef ellipsis_methods[] = {
 {"__reduce__", ellipsis_reduce, METH_NOARGS, NULL},
 {NULL, NULL}
};

The public name: `Py_Ellipsis`

How C code obtains the singleton depends on the API mode:

 c
 
 
// Include/sliceobject.h
PyAPI_DATA(PyObject) _Py_EllipsisObject; /* Don't use this directly */

#if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000
# define Py_Ellipsis Py_GetConstantBorrowed(Py_CONSTANT_ELLIPSIS)
#else
# define Py_Ellipsis (&_Py_EllipsisObject)
#endif

In the unlimited (internal) API, Py_Ellipsis is simply the address of the static struct.
In the limited API (3.13+), Py_Ellipsis is fetched from the interpreter’s constants table via Py_GetConstantBorrowed, so extension modules never reference the private _Py_EllipsisObject symbol directly. This is what makes the symbol part of the stable ABI story.

Py_GetConstantBorrowed returns the same pointer every time; all constants are immortal by construction:

 c
 
 
// Objects/object.c
PyObject*
Py_GetConstantBorrowed(unsigned int constant_id)
{
 // All constants are immortal
 return Py_GetConstant(constant_id);
}

The constants table

The limited-API path resolves to a slot in a static array in Objects/object.c:

 c
 
 
// Objects/object.c
static PyObject* constants[] = {
 &_Py_NoneStruct, // Py_CONSTANT_NONE
 (PyObject*)(&_Py_FalseStruct), // Py_CONSTANT_FALSE
 (PyObject*)(&_Py_TrueStruct), // Py_CONSTANT_TRUE
 &_Py_EllipsisObject, // Py_CONSTANT_ELLIPSIS
 &_Py_NotImplementedStruct, // Py_CONSTANT_NOT_IMPLEMENTED
 NULL, // Py_CONSTANT_ZERO
 ...
};

void
_Py_GetConstant_Init(void)
{
 constants[Py_CONSTANT_ZERO] = _PyLong_GetZero();
 constants[Py_CONSTANT_EMPTY_STR] = PyUnicode_New(0, 0);
 ...
#ifndef NDEBUG
 for (size_t i=0; i < Py_ARRAY_LENGTH(constants); i++) {
 assert(constants[i] != NULL);
 assert(_Py_IsImmortal(constants[i]));
 }
#endif
}

So _Py_EllipsisObject is both a standalone global and the value stored at Py_CONSTANT_ELLIPSIS. In debug builds the interpreter asserts that every constant, including Ellipsis, is immortal before startup completes.

Immortality in practice

Because _Py_EllipsisObject is statically allocated with an immortal refcount:

Py_INCREF(Py_Ellipsis) / Py_DECREF(Py_Ellipsis) are effectively no-ops (the refcount never reaches zero).
It is not GC-tracked, so it never participates in collection cycles.
PyUnstable_Object_EnableDeferredRefcount / deferred refcounting does not apply to it (it is not a GC object).
Its identity is stable for the whole process: Ellipsis is ... is True, and id(Ellipsis) never changes.

The same immortality is what lets the compiler treat Ellipsis specially in constant folding. In Python/compile.c, None and Ellipsis are detected by identity and used directly as constant keys without going through _PyCode_ConstantKey:

 c
 
 
// Python/compile.c
// None and Ellipsis are immortal objects, and key is the singleton.
// No need to merge object and key.
if (o == Py_None || o == Py_Ellipsis) {
 return o;
}

Uses of `Py_Ellipsis` in the core

A few places in the C core rely on the singleton identity:

Objects/memoryview.c and Objects/genericaliasobject.c compare pointers against Py_Ellipsis to detect ... in slicing/subscripting contexts.
Objects/typevarobject.c checks p == Py_Ellipsis when unpacking type variables (the ... “unbounded” marker).
Objects/codeobject.c treats Py_Ellipsis (alongside Py_None) as a singleton when serializing code constants.

Memory layout

_Py_EllipsisObject is just an object header – no extra fields:

text

_Py_EllipsisObject (static storage, 16 bytes on 64-bit)
+----------------------------+
| ob_refcnt (immortal) | <- _Py_IMMORTAL_INITIAL_REFCNT
+----------------------------+
| ob_flags (static bits) |
+----------------------------+
| ob_type -> &PyEllipsis_Type |
+----------------------------+

The ABI data file records its size as 16 bytes (Doc/data/python3.15.abi), matching sizeof(PyObject) on 64-bit. There is no tp_traverse, no tp_clear, and no GC tracking, because there are no owned references to visit.

Key takeaways

Ellipsis is a statically allocated, immortal PyObject named _Py_EllipsisObject, defined in Objects/sliceobject.c.
Its type PyEllipsis_Type has tp_basicsize == 0 and no GC flags; the only instance is the static singleton.
ellipsis_new rejects arguments and returns Py_Ellipsis; ellipsis_dealloc re-immortalizes as a guard.
Repr and __reduce__ both produce "Ellipsis".
Py_Ellipsis resolves to &_Py_EllipsisObject in the internal API, or to Py_GetConstantBorrowed(Py_CONSTANT_ELLIPSIS) in the limited API.
The object is immortal from static initialization, is not GC-tracked, and is used by identity throughout the interpreter and compiler.

Ellipsis on Opensource internals

CPython's Ellipsis Implementation in C

The singleton: `_Py_EllipsisObject`

The type: `PyEllipsis_Type`

Construction: `ellipsis_new`

Dealloc guard: `ellipsis_dealloc`

Repr and pickling

The public name: `Py_Ellipsis`

The constants table

Immortality in practice

Uses of `Py_Ellipsis` in the core

Memory layout

Key takeaways

Further reading

Ellipsis on Opensource internals

CPython's Ellipsis Implementation in C

The singleton: _Py_EllipsisObject

The type: PyEllipsis_Type

Construction: ellipsis_new

Dealloc guard: ellipsis_dealloc

Repr and pickling

The public name: Py_Ellipsis

The constants table

Immortality in practice

Uses of Py_Ellipsis in the core

Memory layout

Key takeaways

Further reading

The singleton: `_Py_EllipsisObject`

The type: `PyEllipsis_Type`

Construction: `ellipsis_new`

Dealloc guard: `ellipsis_dealloc`

The public name: `Py_Ellipsis`

Uses of `Py_Ellipsis` in the core