Python ellipsis

Python ellipsis (...) is a literal value representing an undefined, incomplete, or indeterminate result. It's most commonly used as a placeholder in function stubs, but it's a real object with special semantics in slicing, type hints, and protocol definitions.

Use ellipsis as a sentinel value, placeholder in development, or to represent “all remaining dimensions” in NumPy arrays.

This example shows ellipsis in various contexts.

# run: python3 ellipsis.py
# description: ellipsis as placeholder and sentinel
 
# Ellipsis as placeholder in stubs
def function_todo():
    """Not implemented yet."""
    ...
 
# Check that it's a real object
print(f"Ellipsis value: {Ellipsis}")
print(f"... is Ellipsis: {... is Ellipsis}")
print(f"Type: {type(...)}")
 
# Ellipsis in slicing (NumPy use case)
# a[...] means "all dimensions"
# a[..., 0] means "all dimensions, then index 0 on last"
 
class Matrix:
    def __init__(self, data):
        self.data = data
 
    def __getitem__(self, key):
        if key is ...:
            return self.data
        return self.data[key]
 
m = Matrix([[1, 2], [3, 4]])
print(f"\nMatrix with ellipsis: {m[...]}")
 
# Ellipsis in type hints
def process(value: int | str | ... = ...) -> int | ...:
    """Function that can return int or undefined."""
    if isinstance(value, int):
        return value
    return ...
 
print(f"Process result: {process(42)}")
print(f"Process undefined: {process('skip')}")
 
# Ellipsis as sentinel for "do nothing"
def maybe_process(data, transform=...):
    if transform is ...:
        return data
    return transform(data)
 
print(f"No transform: {maybe_process([1, 2, 3])}")
print(f"With transform: {maybe_process([1, 2, 3], lambda x: [i*2 for i in x])}")

Placeholder in stubs:

• def func(): ...: common in abstract base classes, type stubs
• Cleaner than pass, signals “intentionally empty”
• Same as pass at runtime; purely stylistic

In slicing (NumPy arrays, pandas):

• array[...]: select all dimensions
• array[..., 0]: all dimensions, then index 0 on last dimension
• array[1, ..., 2]: index first dim, all middle dims, index last dim

In type hints:

• value: int | ...: value can be int or indeterminate
• -> int | ...: return type can be int or indeterminate (rarely used)
• Mostly for compatibility with NumPy's typing

As a sentinel value:

• def f(x=...):: distinguish “not provided” from None
• More explicit than None for optional parameters with semantic meaning
• Useful when None is a valid value

Representing incomplete results:

• Function returns ... to mean “computation incomplete”
• More readable than custom sentinel objects
• Part of Python protocol for special values

Comparison:

• ... is Ellipsis: true; there's only one ellipsis object
• ... == Ellipsis: also true
• Not comparable to other values: ... < 5 raises TypeError