Python __call__: Making Objects Callable
Learn how Python __call__ makes objects callable like functions, with practical examples covering callbacks, decorators, and stateful callables.

The __call__ method is what makes a Python object callable. When you define it on a class, instances of that class can be invoked with parentheses just like a regular function. This is part of the Python data model, and it is the mechanism behind many standard-library tools and framework APIs. Understanding __call__ behavior helps you design objects that feel natural at the call site.
What __call__ Does in Python
In Python, the call operator is (). When the interpreter evaluates obj(args), it looks up the __call__ method on the type of obj and invokes it with the given arguments. This is the same mechanism that makes functions callable, because function objects have __call__ defined on their type.
The syntax is minimal:
class Counter:
def __init__(self, start=0):
self.count = start
def __call__(self, step=1):
self.count += step
return self.countInstances of Counter now behave like functions that increment and return a stored value:
counter = Counter()
counter() # 1
counter(2) # 3The instance holds state, and each call mutates it. A plain function would need to keep that state somewhere, such as in a closure or an external mutable container.
Minimal Example: Making an Instance Callable
The simplest callable object captures configuration at construction time and uses it on every call:
class Greeter:
def __init__(self, greeting="Hello"):
self.greeting = greeting
def __call__(self, name):
return f"{self.greeting}, {name}!"
greeter = Greeter("Hi")
greeter("Ada") # 'Hi, Ada!'
greeter("Grace") # 'Hi, Grace!'The greeter instance is now interchangeable with a one-argument function. Any code that accepts a callable can accept this object. The configuration (self.greeting) is fixed when the object is created, which makes the call site simpler than passing the greeting on every invocation.
Why Use a Callable Object Instead of a Function
A closure can capture state, but a callable object offers more structure:
- It can expose additional methods and attributes alongside the call behavior.
- It can be reconfigured after construction by setting attributes.
- It can participate in inheritance, so specialized variants share the same call interface.
- It can implement
__repr__to make debugging easier.
Consider a retry wrapper that needs to keep the wrapped function and the attempt count together:
class Retry:
def __init__(self, func, attempts=3):
self.func = func
self.attempts = attempts
def __call__(self, *args, **kwargs):
last_error = None
for _ in range(self.attempts):
try:
return self.func(*args, **kwargs)
except Exception as exc:
last_error = exc
raise last_errorThe Retry instance is a drop-in replacement for the original function at call sites, while keeping the retry policy attached. A closure could do the same, but the class version makes the policy explicit and testable.
Practical Use Cases: Callbacks, Decorators, and Factories
Callbacks
Many libraries accept callables for event handling or configuration. A callable object can carry its own configuration while being passed directly:
class ThresholdLogger:
def __init__(self, threshold):
self.threshold = threshold
def __call__(self, value):
if value > self.threshold:
print(f"Threshold exceeded: {value}")You can pass ThresholdLogger(100) wherever a callback function is expected.
Class-Based Decorators
A decorator implemented as a class uses __call__ to wrap the decorated function:
class LogCalls:
def __init__(self, func):
self.func = func
def __call__(self, *args, **kwargs):
print(f"Calling {self.func.__name__}")
return self.func(*args, **kwargs)The instance stores the wrapped function, and every call to the decorated name goes through __call__.
Factories
A callable object can act as a factory that produces configured instances of another class. Assuming a Connection class is defined elsewhere and accepts host and port, this example returns a new connection on each call:
class ConnectionFactory:
def __init__(self, host, port):
self.host = host
self.port = port
def __call__(self):
return Connection(self.host, self.port)The factory keeps connection parameters in one place and can be passed around as a zero-argument callable.
__call__ vs Closures vs Regular Methods
A closure captures state from an enclosing scope. A callable object stores state on the instance. The choice matters in several situations:
- If you need to inspect or modify the state from outside, the callable object exposes it as attributes; a closure does not.
- If you need multiple independent instances with the same behavior, the class gives you a natural constructor.
- If you need to subclass or compose behavior, the class is the only option that supports inheritance.
A regular method requires the caller to keep a reference to the object and write obj.method(). __call__ removes that extra step: the object itself is the callable. This is useful when a library expects a function but you want the behavior to be configurable.
Runtime and Performance Considerations
Roughly, calling an object that defines __call__ goes through the same dispatch path as a bound method: the interpreter performs a type lookup for __call__ and then invokes it. For most application code this cost is negligible compared to the work inside the method.
The main performance concern is allocation. Creating a new callable instance inside a hot loop repeats object construction and attribute setup. If the callable is stateless or the state does not change, construct it once and reuse it. If the state changes per call, pass the changing value as an argument instead of building a new instance each iteration.
There is no special caching or optimization for __call__ beyond what the interpreter does for any method call. Code that needs to minimize dispatch overhead should consider a plain function or a module-level function, which avoid the instance attribute lookup entirely.
Common Mistakes and Edge Cases
__call__ follows the same return rules as any function. If you omit a return statement, the call evaluates to None. This is a frequent source of bugs when a callable is expected to produce a value.
Defining __call__ does not affect other dunder behaviors. An instance with __call__ is not automatically hashable, comparable, or iterable. Those require separate methods.
A callable with many optional parameters can make the call site hard to read. If the call signature becomes complex, consider whether a regular method with keyword arguments would be clearer.
If __call__ raises an exception, it propagates to the caller normally. There is no implicit wrapping or special handling.
When to Avoid __call__
__call__ is appropriate when the object truly represents a function with attached state or configuration. It is the wrong choice when the object has multiple distinct operations. A class with run(), stop(), and status() methods should not also define __call__, because the call semantics would be ambiguous.
The same applies when the call behavior would surprise readers. If a developer cannot tell from the class name what calling the instance does, a named method is clearer. __call__ trades explicitness for convenience, and that trade is only worth it when the call is the primary purpose of the object.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.