Python Ellipsis (...): Placeholder and Slicing Syntax
What you’ll learn
Section titled “What you’ll learn”- What the
...token is and that...is the literal form of theEllipsissingleton. - Using
...as a placeholder instead ofpassor a docstring-only stub. ...in type hints:Callable[..., int]andtuple[int, ...]....in NumPy multi-dimensional slicing, where it means “all remaining axes.”- When to use
...versuspassversusraise NotImplementedError.
Summary
Section titled “Summary”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.
The problem it solves
Section titled “The problem it solves”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.
How it works
Section titled “How it works”... is a literal; Ellipsis is the singleton it produces. They are the same object:
print(... is Ellipsis) # Trueprint(type(...)) # <class 'ellipsis'>As a placeholder:
def ship_order(order_id): ... # TODO: integrate with the carrier API
class OrderRepository: ... # methods to followA 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 intscores: tuple[int, ...] = (1, 2, 3) # any number of intsCallable[..., 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 keptprint(arr[:, :, 0].shape) # (2, 3) -- same, but only because we knew it's 3-Darr[..., 0] keeps working if you later reshape to four or five dimensions; arr[:, :, 0] would break.
Result shape and edge cases worth remembering:
...andEllipsisare interchangeable; pick one and be consistent — style guides increasingly prefer....- A body of exactly
...returnsNone; it does not raise, so callers of a stub silently getNone. Useraise NotImplementedError(...)for a stub that must crash if called. - Returning
...(as opposed to having...as the whole body) returns theEllipsisobject, notNone. - In
tuple[...]type hints, the...must be the last item and means “zero or more of the preceding type.”
Realistic example
Section titled “Realistic example”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.
Production patterns
Section titled “Production patterns”- Use
...as the placeholder in stubs and protocols-to-be, paired with aTODOcomment 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, ...]overtyping.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.
Common mistakes
Section titled “Common mistakes”- Using
...where the function should raise if called — a...body returnsNonesilently; useraise NotImplementedError. - Treating
tuple[int]as “a list of ints” — it means a one-element tuple; the variadic form istuple[int, ...]. - Using
...as a no-op return value — returning...returns theEllipsisobject, notNone. - Assuming
...andpasscarry the same intent for readers — they compile the same but signal different things. - Forgetting that
...in atupletype hint must be the last element.
When to use it and when not to
Section titled “When to use it and when not to”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 NotImplementedErrorinstead. passalready reads correctly (“intentionally empty,” like a no-op__init__).- A normal value or
Noneis what you mean to return.
Compatibility
Section titled “Compatibility”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.
Interview questions
Section titled “Interview questions”-
What is
..., and how does it differ frompass?...is the literal form of theEllipsissingleton. As a function or class body it satisfies the “non-empty body” rule the same waypassdoes, and both returnNoneat runtime. The difference is intent:...reads as “to be implemented,”passreads as “intentionally empty.” Stylistically,...is preferred for stubs. -
What does
tuple[int, ...]mean, and why is the...required rather than optional? It means a tuple of any length whose elements are allint. The...is required becausetuple[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.” -
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.” Soarr[..., 0]indexes the last axis and keeps all leading axes, and it keeps working if the array’s dimensionality changes — unlikearr[:, :, 0], which assumes exactly three dimensions. -
Senior scenario: a teammate stubs a required interface method with
...and a downstream caller getsNoneback and crashes far from the call site. How do you make this fail fast instead? A...body returnsNonesilently, so a caller of an unimplemented method getsNoneand the failure surfaces whereverNoneis used as if it were a real result. To fail fast, replace the...body withraise 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 confusingNonedownstream. Reserve...for stubs that are genuinely optional to call or for protocol declarations; useNotImplementedErrorfor anything a caller is expected to invoke.
Key takeaways
Section titled “Key takeaways”...is the literal for theEllipsissingleton;...andEllipsisare the same object.- As a body,
...is a placeholder that returnsNone;raise NotImplementedErrorfails 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+.
Related pages
Section titled “Related pages”- Type hints —
Callable,tuple, and other hint forms - typing_extensions — backports of newer typing features
- walrus operator — another modern syntax addition
- Magic methods —
__getitem__and slicing internals