What does Callable[[int], str] mean, and how does Callable[..., str] differ?

## The two slots `Callable` is a generic with exactly two subscript positions: `Callable[<parameters>, <return>]`. The first position is a **list** of parameter types, written with real square brackets; the second is a single type for the result. The bracket-inside-bracket shape trips people up constantly, so read it aloud: `Callable[[int], str]` is *"list of parameters: one int; returns: str"*. Concrete forms: ```python Callable[[], None] # takes nothing, returns None Callable[[int], str] # one int parameter, returns str Callable[[int, str], bool] # two positional parameters Callable[..., str] # any parameters whatsoever, returns str ``` A frequent beginner error is `Callable[int, str]` without the inner brackets. That is not a valid annotation and a type checker rejects it; at runtime it may even build an object without complaint, which is exactly why the mistake survives to review. ## What the ellipsis actually means The `...` in `Callable[..., str]` is the real `Ellipsis` object used as a literal token, and it means *the parameter list is unspecified*. It is not "zero or more arguments of any type" in a checked sense — it is an instruction to the checker to stop checking arguments at that call. Any call, with any number of positional or keyword arguments, is accepted; only the `str` result is enforced. That makes it a **gradual-typing escape hatch**, and it has honest uses: a plugin registry that stores heterogeneous factories, a callback whose signature is genuinely decided by the caller, a boundary to third-party code you cannot describe. It is the wrong tool when you *do* know the signature, and it is especially wrong on decorators — a decorator typed `Callable[..., Any] -> Callable[..., Any]` silently erases the signature of every function it wraps, which is the problem `ParamSpec` exists to solve. ## What the bracketed form cannot say The parameter list describes **positional parameters only**. There is no syntax inside `Callable[...]` for: * a keyword parameter (`f(x, *, verbose=False)`), * an optional or defaulted parameter, * `*args` / `**kwargs` forwarding. When you need those, the two answers are a `typing.Protocol` class with a `__call__` method — which spells out a full signature, names and defaults included — or `ParamSpec`, when the signature is not fixed but *copied* from somewhere else. ## Where to import it from Since Python 3.9 (PEP 585) the abstract base classes are subscriptable directly, so the modern import is `from collections.abc import Callable`. `typing.Callable` still works and is an alias, but it has been deprecated since 3.9 and linters flag it in new code. Note the asymmetry that catches people: `collections.abc.Callable` is what you *annotate* with, while the builtin `callable(obj)` is what you *test* with at runtime, and `isinstance(obj, collections.abc.Callable)` only checks that the object defines `__call__` — it can never verify a signature. No runtime check in Python validates that a function matches `Callable[[int], str]`; that is a static claim only. ## Anything callable satisfies it `Callable` is not limited to functions defined with `def`. A lambda, a `functools.partial`, a bound method, a class (calling a class returns an instance, so a class object is `Callable[..., Instance]`), and any object with a `__call__` method all qualify. This is why `Callable[..., MyClass]` is the idiomatic annotation for a factory parameter that may receive either the class itself or a function that builds one. ## In return position and in containers `Callable` is not confined to parameters. A factory helper is annotated `-> Callable[[int], str]` when it builds and returns a function, and a registry of handlers is `dict[str, Callable[[bytes], None]]`. The registry case is where the explicit list pays for itself most visibly: every handler registered into that mapping is checked against one agreed shape, so a handler that takes the wrong argument type is caught where it is registered rather than where it is eventually dispatched. At runtime, subscripting produces a generic alias object rather than anything Python enforces — `collections.abc.Callable[[int], str]` simply evaluates to a description. Since Python 3.14, annotations are not even evaluated when the function is defined unless something asks for them (PEP 649), so an annotation naming a type that does not exist yet no longer raises at definition time. ## Reading it in review Two habits make callable annotations pay off. First, prefer the explicit parameter list wherever the signature is known — it is the only form that catches a caller passing arguments in the wrong order. Second, treat every `Callable[..., X]` in a diff as a question: is the signature genuinely unknowable here, or did someone reach for the ellipsis because writing the list was inconvenient? In a typed codebase the ellipsis is a small hole in the roof, and holes cluster around exactly the higher-order code where mistakes are hardest to spot by eye.