Python Method Decorator: A Practical Guide
Learn how to write and use python method decorators effectively—covering syntax, metadata preservation, arguments, class-based decorators, and practical pitfalls.

A Python method decorator is a callable that takes a method as its argument and returns a modified method. The @decorator syntax is syntactic sugar for method = decorator(method). This pattern lets you wrap behavior around existing methods without changing their source code, which is useful for logging, timing, access control, or input validation.
What a Method Decorator Does in Python
When you apply a decorator to a method, Python evaluates the decorator expression at function definition time. The decorator receives the original method object and returns a new callable that typically replaces it. The new callable can run code before and after the original method, modify arguments, or change the return value.
Consider a simple decorator that prints a message before the method runs:
def log_call(method):
def wrapper(*args, **kwargs):
print(f"Calling {method.__name__}")
return method(*args, **kwargs)
return wrapper
class Service:
@log_call
def fetch(self, url):
return f"data from {url}"Here, fetch is replaced by wrapper. When you call Service().fetch("/api"), the wrapper prints the method name and then delegates to the original method. The decorator works on instance methods because self is passed as the first positional argument to wrapper.
Writing a Basic Method Decorator
The simplest decorator pattern takes only the method and returns a wrapper. The wrapper must accept *args and **kwargs to handle any method signature. It should return the result of the original method so the caller sees the same behavior.
def time_it(method):
import time
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = method(*args, **kwargs)
elapsed = time.perf_counter() - start
print(f"{method.__name__} took {elapsed:.4f} seconds")
return result
return wrapper
class Report:
@time_it
def generate(self, rows):
return sum(row for row in rows)This decorator measures execution time and prints it. It does not change the return value. If the original method raises an exception, the wrapper propagates it, so the decorator does not alter error behavior unless you explicitly catch exceptions.
Preserving Function Metadata with functools.wraps
Without care, a decorator replaces the original method's name, docstring, and other metadata with those of the wrapper. This breaks tools that rely on introspection, such as debuggers, documentation generators, and some testing frameworks. The functools.wraps helper copies the original method's metadata onto the wrapper.
from functools import wraps
def log_call(method):
@wraps(method)
def wrapper(*args, **kwargs):
print(f"Calling {method.__name__}")
return method(*args, **kwargs)
return wrapper
class Service:
@log_call
def fetch(self, url):
"""Fetch data from the given URL."""
return f"data from {url}"
print(Service.fetch.__name__) # fetch
print(Service.fetch.__doc__) # Fetch data from the given URL.Using @wraps also updates __module__, __annotations__, and __dict__. It is considered a best practice for any decorator that wraps a function or method, because it preserves the original callable's identity.
Decorators That Accept Arguments
Sometimes you need to parameterize a decorator, such as specifying a log level or a retry count. This requires an extra layer of indirection: the decorator factory returns the actual decorator.
def retry(max_attempts):
def decorator(method):
@wraps(method)
def wrapper(*args, **kwargs):
for attempt in range(max_attempts):
try:
return method(*args, **kwargs)
except Exception:
if attempt == max_attempts - 1:
raise
return wrapper
return decorator
class Client:
@retry(max_attempts=3)
def send(self, payload):
# network call that may fail
return "ok"When you write @retry(max_attempts=3), Python first calls retry(3) to get decorator, then applies decorator to send. The wrapper now has access to max_attempts via closure. This pattern is common for configuration-driven behavior.
Using Class-Based Decorators for Stateful Behavior
A class can work as a decorator when it implements __call__. This is useful when the decorator needs to maintain state across multiple calls, such as counting invocations or caching results. To use this pattern on an instance method, the decorator class also needs __get__ so Python can bind the instance as the first argument, just as it does for a normal method.
from functools import partial
class CountCalls:
def __init__(self, method):
self.method = method
self.count = 0
def __get__(self, instance, owner):
if instance is None:
return self
return partial(self, instance)
def __call__(self, instance, *args, **kwargs):
self.count += 1
print(f"Call {self.count} of {self.method.__name__}")
return self.method(instance, *args, **kwargs)
class API:
@CountCalls
def get(self, endpoint):
return f"data for {endpoint}"
api = API()
api.get("/users")
api.get("/orders")Here, the CountCalls instance is created once when the method is defined. Accessing api.get triggers __get__, which uses functools.partial to bind the API instance as the first positional argument. Each call then runs __call__, increments the counter, and delegates to the original method. A class-based decorator is more verbose than a function-based one, but it can be clearer when the decorator holds mutable state.
Performance and Maintainability Considerations
Decorators add a layer of indirection, which has a small runtime cost. The overhead of a simple wrapper is usually negligible compared to the method's actual work, but for very hot paths—methods called millions of times in a tight loop—the extra function call and attribute lookups can matter. If you measure and find a bottleneck, consider inlining the logic or using a decorator that only wraps when needed.
Maintainability is more significant. A decorator can obscure the original method's behavior, especially if it modifies arguments or return values. Keep decorators focused on one concern and document them clearly. Overusing decorators can make code harder to debug because the call stack includes multiple wrapper layers. Use them where the cross-cutting concern is genuinely shared across many methods.
Common Pitfalls and How to Avoid Them
One common mistake is forgetting to use @wraps, which breaks introspection. Another is writing a decorator that does not accept *args and **kwargs, causing errors when the method has parameters. Also, be careful when decorating instance methods: self is passed as the first positional argument, so the wrapper must accept it. If you decorate a static method, the wrapper receives no self, which can cause an argument mismatch. If you use a class-based decorator on an instance method, implement __get__; otherwise the wrapper will not receive the instance.
Another subtle issue is the order of multiple decorators. Decorators apply bottom-up, meaning the decorator closest to the method runs first. For example:
@decorator_a
@decorator_b
def method():
passmethod is first wrapped by decorator_b, then the result is passed to decorator_a. If the order matters, you must reason about which wrapper is outermost. This is especially relevant when decorators add behavior like caching or authentication.
Finally, if you need to access the original method from outside the wrapper, you can store a reference to it, but this is rarely necessary. In most cases, the wrapper is the public interface, and the original method is only accessible inside the closure.
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.