Skip to content

Python Ellipsis (...): Placeholder and Slicing Syntax

  • What the ... token is and that ... is the literal form of the Ellipsis singleton.
  • Using ... as a placeholder instead of pass or a docstring-only stub.
  • ... in type hints: Callable[..., int] and tuple[int, ...].
  • ... in NumPy multi-dimensional slicing, where it means “all remaining axes.”
  • When to use ... versus pass versus raise NotImplementedError.

The ... (three dots) token is the literal form of the Ellipsis singleton — a built-in object equal only to itself. It has three practical uses. As a placeholder, it stands in for “not implemented yet” in a function or class body, where it is slightly more explicit than pass. In type hints, it marks “any arguments” (Callable[..., int]) or “any number of repeated items” (tuple[int, ...]). In NumPy, ... in a multi-dimensional index means “all the remaining axes,” letting you slice the last axis without spelling out every leading colon.

A stub function needs a body. pass is the conventional filler, but it reads as “do nothing,” which is misleading for a function that is meant to be implemented later. ... reads as “to be filled in” and is unambiguous. It also satisfies the “non-empty body” requirement the same way pass does, so a function can be syntactically valid while signaling incompleteness.

In type hints, the type system needs a way to say “I do not care about the parameters” or “any number of these items.” There is no clean alternative: Callable[..., int] is far clearer than spelling out an arbitrary parameter list, and tuple[int, ...] is the only way to say “a tuple of any length whose elements are all int” — tuple[int] means a one-element tuple, and tuple[int, int] means exactly two. Without ..., you would lose precision or fall back to the older typing.Tuple and typing.Callable, which use ... anyway.

In NumPy, indexing a high-dimensional array to its last axis requires one colon per leading axis — arr[:, :, :, 0] for a 4-D array. ... expands to “as many colons as needed,” so arr[..., 0] does the same thing and keeps working when the array’s dimensionality changes.

... is a literal; Ellipsis is the singleton it produces. They are the same object:

print(... is Ellipsis) # True
print(type(...)) # <class 'ellipsis'>

As a placeholder:

def ship_order(order_id):
... # TODO: integrate with the carrier API
class OrderRepository:
... # methods to follow

A body of ... is valid and the function returns None when called, exactly like pass. The difference is intent: ... says “incomplete,” pass says “intentionally empty.”

In type hints:

from typing import Callable
Handler = Callable[..., int] # any signature, returns int
scores: tuple[int, ...] = (1, 2, 3) # any number of ints

Callable[..., int] means “a callable with any parameters returning int” — the ... stands in for the entire parameter specification. tuple[int, ...] (lowercase tuple since 3.9) means a tuple of arbitrary length whose elements are all int; the trailing ... is required syntax, not optional. tuple[int] would mean a one-element tuple. The ... must be the last item in the subscription.

In NumPy slicing (requires NumPy installed):

import numpy as np
arr = np.arange(24).reshape(2, 3, 4)
print(arr[..., 0].shape) # (2, 3) -- last axis indexed, leading axes kept
print(arr[:, :, 0].shape) # (2, 3) -- same, but only because we knew it's 3-D

arr[..., 0] keeps working if you later reshape to four or five dimensions; arr[:, :, 0] would break.

Result shape and edge cases worth remembering:

  • ... and Ellipsis are interchangeable; pick one and be consistent — style guides increasingly prefer ....
  • A body of exactly ... returns None; it does not raise, so callers of a stub silently get None. Use raise NotImplementedError(...) for a stub that must crash if called.
  • Returning ... (as opposed to having ... as the whole body) returns the Ellipsis object, not None.
  • In tuple[...] type hints, the ... must be the last item and means “zero or more of the preceding type.”

OrdersPortal defines a CarrierClient with stubbed methods and a webhook handler registry whose handlers take any payload shape and return a status integer.

from typing import Callable
class CarrierClient:
"""Integrates with a shipping carrier. Methods to be implemented."""
def create_shipment(self, order_id: str, address: dict) -> str:
... # returns a tracking number once implemented
def cancel_shipment(self, tracking_number: str) -> bool:
...
# Handlers take any payload shape and return a status int.
Handler = Callable[..., int]
def dispatch(payload: dict, handler: Handler) -> int:
return handler(payload)
def record_event(payload: dict) -> int:
print("event", payload)
return 0
dispatch({"order_id": "ORD-1001"}, record_event)

A typed “any-length list of order ids”:

order_ids: tuple[int, ...] = (1001, 1002, 1003)

This type-checks as a tuple of int of any length, so adding more ids stays valid.

  • Use ... as the placeholder in stubs and protocols-to-be, paired with a TODO comment so the intent is searchable.
  • For “must be overridden” stubs that should fail loudly when called, raise NotImplementedError(...) — the ... reads as “details omitted.”
  • In type hints, prefer tuple[int, ...] over typing.Tuple[int, ...] on 3.9+; the lowercase form is the modern standard.
  • In NumPy, prefer arr[..., 0] over spelling out leading colons so the code survives dimensionality changes.
  • Using ... where the function should raise if called — a ... body returns None silently; use raise NotImplementedError.
  • Treating tuple[int] as “a list of ints” — it means a one-element tuple; the variadic form is tuple[int, ...].
  • Using ... as a no-op return value — returning ... returns the Ellipsis object, not None.
  • Assuming ... and pass carry the same intent for readers — they compile the same but signal different things.
  • Forgetting that ... in a tuple type hint must be the last element.

Use ... when:

  • Stubbing a body that will be implemented (with a TODO).
  • Writing type hints with “any arguments” (Callable[..., T]) or “any number of items” (tuple[T, ...]).
  • Slicing the last axis of a NumPy array of unknown dimensionality.

Avoid ... when:

  • The function should crash if called — raise NotImplementedError instead.
  • pass already reads correctly (“intentionally empty,” like a no-op __init__).
  • A normal value or None is what you mean to return.

The ... literal and the Ellipsis singleton are part of the language since Python 3.0. Callable[..., T] and tuple[T, ...] are supported with the lowercase builtins from Python 3.9 (PEP 585). Variadic generics (TypeVarTuple) require Python 3.11+, but the ... placeholder and ... in Callable/tuple hints work on 3.9 through 3.14. NumPy’s ... indexing is a NumPy feature, independent of the Python version.

  1. What is ..., and how does it differ from pass? ... is the literal form of the Ellipsis singleton. As a function or class body it satisfies the “non-empty body” rule the same way pass does, and both return None at runtime. The difference is intent: ... reads as “to be implemented,” pass reads as “intentionally empty.” Stylistically, ... is preferred for stubs.

  2. What does tuple[int, ...] mean, and why is the ... required rather than optional? It means a tuple of any length whose elements are all int. The ... is required because tuple[int] means a one-element tuple, not a list of ints; the trailing ... is the syntax that says “zero or more of the preceding type.”

  3. How does ... help when indexing a NumPy array? In a multi-dimensional index, ... expands to “as many colons as needed to fill the remaining axes.” So arr[..., 0] indexes the last axis and keeps all leading axes, and it keeps working if the array’s dimensionality changes — unlike arr[:, :, 0], which assumes exactly three dimensions.

  4. Senior scenario: a teammate stubs a required interface method with ... and a downstream caller gets None back and crashes far from the call site. How do you make this fail fast instead? A ... body returns None silently, so a caller of an unimplemented method gets None and the failure surfaces wherever None is used as if it were a real result. To fail fast, replace the ... body with raise NotImplementedError("CarrierClient.create_shipment is not implemented") — the first call to the stub now raises at the exact missing method, with a clear message, instead of producing a confusing None downstream. Reserve ... for stubs that are genuinely optional to call or for protocol declarations; use NotImplementedError for anything a caller is expected to invoke.

  • ... is the literal for the Ellipsis singleton; ... and Ellipsis are the same object.
  • As a body, ... is a placeholder that returns None; raise NotImplementedError fails fast.
  • In type hints, ... means “any args” (Callable[..., T]) or “any number of items” (tuple[T, ...]).
  • In NumPy, ... means “all remaining axes” and survives dimensionality changes.
  • Prefer the lowercase tuple[T, ...] on 3.9+.