Typed callbacks
A function accepts a callback whose input and output types are known.
Python · Type Alias
Callable
Callable describes the signature of a function or other callable object: its parameter types and return type. Use collections.abc.Callable in modern annotations; typing.Callable is deprecated.
How it works
Use Callable to describe the input types and return type of a function or other callable object. The argument specification is either a list of types, a parameter specification, a concatenation, or an ellipsis when only the return type matters.
Syntax
collections.abc.Callable[[ArgType1, ArgType2, ...], ReturnType]
collections.abc.Callable[..., ReturnType]
collections.abc.Callable[ParamSpec, ReturnType]
collections.abc.Callable[Concatenate[ArgType1, ..., ParamSpec], ReturnType]Parameters
| Name | Type | Description |
|---|---|---|
arg_types | list[type] | ParamSpec | Concatenate[...] | Ellipsis | Argument specification: a list of parameter types, ParamSpec, Concatenate, or ellipsis. |
return_type | type | The callable's result type; it must be one type. |
Returns
The type of the value produced by the callable.
Key points
- Annotate functions and other callable objects with collections.abc.Callable; typing.Callable is deprecated.
- The list inside Callable describes parameter types, followed by the callable's result type.
- Callable supports explicit type lists, ParamSpec, Concatenate, and ellipsis argument specifications.
- Specify exactly one return type after the argument specification.
- ParamSpec preserves relationships between a callable's parameters and another callable passed through an API.
- Use Concatenate when a higher-order callable changes another callable's parameter list.
Common mistakes
- Callable is not suitable for expressing variadic, overloaded, or keyword-only call signatures.
- A parameterized Callable must contain both its argument specification and its return type.
- An unparameterized Callable permits any arguments and return value, so use a specific signature when possible.
Example: Annotating a callback
from collections.abc import Callable
def apply_twice(function: Callable[[int], int], value: int) -> int:
return function(function(value))
print(apply_twice(lambda number: number + 1, 3))The annotation requires a callable that accepts an int and returns an int.
When to use it
Parameter-preserving decorators
A decorator forwards an arbitrary callable's parameters while preserving their relationship.
Signature-transforming decorators
A decorator adds or removes leading parameters from another callable.
Return-type-only contracts
An API accepts any callable but requires a known result type.
Interview questions
QWhat does Callable[[int], str] mean?
Callable[[int], str] describes a callable receiving one int and producing a str. The first subscription value is the argument-type list, and the second is the single return type.
Follow-up: How would you describe a callable with an unknown parameter list but a known result? Use Callable[..., ReturnType], replacing ReturnType with the required result type.
QWhen should an ellipsis be used with Callable?
Callable[..., ReturnType] uses an ellipsis for the argument specification. It records the return type while allowing any number of arguments.
Follow-up: What does an unparameterized Callable mean? It is equivalent to Callable[..., Any], and the documentation also equates it with collections.abc.Callable.
QWhat are the limitations and modern alternative for Callable?
The modern spelling is collections.abc.Callable; typing.Callable is documented as its deprecated alias. Callable also cannot model keyword-only parameters, overloaded functions, or variadic signatures.
Follow-up: How can dependent callable parameters be represented? Use ParamSpec, or Concatenate when parameters are added or removed.
Related
collections.abc.CallableParamSpecConcatenateAny