Ever find yourself writing the same setup or teardown code around multiple functions? Maybe it's logging, timing a function's execution, or checking user permissions. You copy, you paste, and a little piece of your soul withers away. We’ve all been there. It feels messy, violates the DRY (Don't Repeat Yourself) principle, and makes future updates a nightmare.
This is exactly the problem Python decorators were born to solve. At first, that little @ symbol can seem like cryptic magic. But what if I told you it's just a clever disguise? Underneath the hood, a decorator is simply a function that takes another function as an argument, adds some functionality, and returns a new, enhanced function. It’s like gift-wrapping your code—the original gift is still inside, but now it has an extra, useful layer on the outside.
So, let's pull back the curtain. We're going to move past the simple "Hello, World" examples and dive into seven powerful decorator tricks that will not only make your code cleaner and more efficient but will also make you a more confident, "Pythonic" developer.
First, A Quick Refresher: What's a Decorator, Really?
Before we jump into the advanced stuff, let's make sure we're on the same page. The secret to understanding decorators is remembering that in Python, functions are first-class citizens. This means you can pass them around like any other variable—to other functions, for instance.
A decorator is a callable (usually a function, but we'll see classes later) that takes a function as input and returns a new function.
Manually, it looks like this:
def my_decorator(func):
def wrapper():
print("Something is happening before the function is called.")
func()
print("Something is happening after the function is called.")
return wrapper
def say_whee():
print("Whee!")
# This is the "decorating" step
say_whee = my_decorator(say_whee)
say_whee()
The @ symbol is just syntactic sugar for that last line. It makes the whole process cleaner.
@my_decorator
def say_whee():
print("Whee!")
say_whee()
Both code blocks do the exact same thing. Now that we've demystified the syntax, let's get to the fun part.
Trick 1: Time Your Functions Without the Clutter
You've written a new function, and you're curious about its performance. How long does it take to run? The common approach is to sprinkle time.time() calls before and after your function call. It works, but it clutters your business logic with performance-monitoring code.
A @timer decorator is a much cleaner solution.
The Code: A Simple Timer Decorator
Let's build a decorator that measures and prints the execution time of any function it wraps.
import time
import functools
def timer(func):
"""A decorator that prints the time a function takes to run."""
@functools.wraps(func) # We'll cover this in Trick #5!
def wrapper_timer(*args, **kwargs):
start_time = time.perf_counter()
value = func(*args, **kwargs)
end_time = time.perf_counter()
run_time = end_time - start_time
print(f"Finished {func.__name__!r} in {run_time:.4f} secs")
return value
return wrapper_timer
@timer
def waste_some_time(num_times):
for _ in range(num_times):
sum([i**2 for i in range(10000)])
waste_some_time(1)
waste_some_time(999)
Now, any time you want to benchmark a function, you just add @timer above it. The timing logic is completely separate from the function's actual job. When you're done, just remove the decorator. It's clean, reusable, and incredibly practical.
Trick 2: Effortless Debugging with a Logging Decorator
Ever filled a function with print() statements just to see what arguments it received and what it returned? We all have. A debugging decorator can automate this for you, giving you a clear trace of your function calls.
This is perfect for development when you want to see the flow of data through your application.
The Code: A @debug Decorator
This decorator will print the function's name, its arguments (args and kwargs), and its return value every time it's called.
import functools
def debug(func):
"""Print the function signature and return value"""
@functools.wraps(func)
def wrapper_debug(*args, **kwargs):
# Create a string of the arguments
args_repr = [repr(a) for a in args]
kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
signature = ", ".join(args_repr + kwargs_repr)
print(f"Calling {func.__name__}({signature})")
value = func(*args, **kwargs)
print(f"{func.__name__!r} returned {value!r}")
return value
return wrapper_debug
@debug
def make_greeting(name, age=None):
if age is None:
return f"Howdy {name}!"
else:
return f"Whoa {name}! {age} already, you're growing up!"
make_greeting("Benjamin")
make_greeting("Alice", age=30)
Slap @debug on any function, and you instantly get valuable insight without modifying a single line of its internal code.
Trick 3: Stack 'Em Up! Using Multiple Decorators
What if you want to both time and debug a function? Simple. You can stack decorators! The key thing to remember is that they are applied from the bottom up.
Think of it like this: the decorator closest to the function definition (@debug in the example below) gets applied first.
@timer
@debug
def waste_some_time(num_times):
for _ in range(num_times):
sum([i**2 for i in range(10000)])
waste_some_time(5)
When you run this, you'll first see the output from @debug (the "Calling..." message), then the function will run, and then you'll see the rest of the output from @debug ("...returned...") followed by the output from @timer. The @timer decorator is wrapping the already decorated function from @debug.
Trick 4: Power-Up with Decorators That Accept Arguments
Okay, this is where decorators go from "neat trick" to "superpower." What if you wanted a decorator that could be customized? For example, a @repeat(num_times=3) decorator that runs a function a specific number of times.
To do this, we need an extra layer of nesting. We need a function that creates our decorator. This is often called a decorator factory.
The Code: A @repeat Decorator Factory
The structure looks a bit intimidating at first, but let's break it down.
repeat(num_times): This is our factory. It takes the arguments we want to pass to the decorator. It will return the actual decorator.decorator_repeat(func): This is the decorator itself. It takes the function to be wrapped.wrapper(*args, **kwargs): This is the wrapper that contains the new logic.
import functools
def repeat(num_times):
def decorator_repeat(func):
@functools.wraps(func)
def wrapper_repeat(*args, **kwargs):
for _ in range(num_times):
value = func(*args, **kwargs)
return value
return wrapper_repeat
return decorator_repeat
@repeat(num_times=4)
def greet(name):
print(f"Hello {name}")
greet("World")
This pattern unlocks a huge range of possibilities. You could create a decorator to check for specific user roles (@require_role("admin")) or a rate-limiting decorator (@rate_limit(requests=5, per_minute=1)).
Trick 5: Stop Losing Your Function's Identity with functools.wraps
You may have noticed @functools.wraps(func) in the previous examples. This isn't just for show; it's critically important.
When you decorate a function, you're essentially replacing it with the wrapper function. This means the original function's metadata—like its name (__name__) and its docstring (__doc__)—gets lost.
# Without functools.wraps
def my_decorator(func):
def wrapper():
"""This is the wrapper's docstring."""
print("Wrapper executing!")
return func()
return wrapper
@my_decorator
def my_function():
"""This is my function's docstring."""
print("Function executing!")
print(my_function.__name__) # Output: 'wrapper'
print(my_function.__doc__) # Output: 'This is the wrapper's docstring.'
This is a problem for debugging, introspection, and documentation tools. functools.wraps is a decorator itself that you apply to your wrapper function. It copies the lost metadata from the original function over to the wrapper, preserving its identity. It's a small addition that makes your decorators robust and professional.
Trick 6: Level Up to Class-Based Decorators for State
Sometimes, you need a decorator that remembers things between calls. For example, what if you want to count how many times a function has been called? A function-based decorator can't easily hold this kind of state.
This is a perfect use case for a class-based decorator. By implementing the __init__ and __call__ methods, a class instance can behave just like a function, but with the added benefit of being able to store state in its attributes.
The Code: A Stateful Call Counter
import functools
class Counter:
def __init__(self, func):
functools.update_wrapper(self, func)
self.func = func
self.num_calls = 0
def __call__(self, *args, **kwargs):
self.num_calls += 1
print(f"Call {self.num_calls} of {self.func.__name__!r}")
return self.func(*args, **kwargs)
@Counter
def say_hello():
print("Hello!")
say_hello()
say_hello()
say_hello()
Each time say_hello() is called, the __call__ method of our Counter instance is invoked. It increments self.num_calls and then executes the original function. The state (num_calls) persists across calls because it's stored on the class instance.
Trick 7: The Ultimate Trick - Caching with functools.lru_cache
One of the most powerful real-world applications of decorators is memoization, or caching. If you have an expensive function (like a complex calculation or a network request) that gets called repeatedly with the same arguments, you can save a ton of time by caching the results.
While you could write your own caching decorator (and it's a great exercise!), Python's standard library provides a production-ready, highly optimized one right out of the box: functools.lru_cache.
LRU stands for "Least Recently Used," which describes the cache's eviction policy: when the cache is full, it discards the least recently used items first.
The Code: Supercharging a Slow Function
Imagine a "slow" function that simulates a database call or a complex computation.
import time
import functools
@functools.lru_cache(maxsize=None) # maxsize=None means unlimited cache size
def slow_fibonacci(n):
"""A very inefficient recursive Fibonacci function."""
if n < 2:
return n
return slow_fibonacci(n-1) + slow_fibonacci(n-2)
# First call is very slow as it computes and caches everything
start = time.perf_counter()
print(slow_fibonacci(35))
end = time.perf_counter()
print(f"First call took {end - start:.4f} seconds")
# Second call is nearly instantaneous because the result is in the cache
start = time.perf_counter()
print(slow_fibonacci(35))
end = time.perf_counter()
print(f"Second call took {end - start:.4f} seconds")
With a single line of code—@lru_cache—we've dramatically optimized our function. This is the magic of decorators: adding powerful, complex behavior in a way that is readable, declarative, and completely separate from the core logic of the function itself.
More Than Just Syntax
As you can see, decorators are far more than just a quirky bit of Python syntax. They are a fundamental tool for writing clean, reusable, and maintainable code. They encourage a separation of concerns, allowing you to isolate cross-cutting logic like logging, timing, and caching from your core business logic.
The next time you find yourself writing repetitive code across several functions, take a moment and ask, "Could this be a decorator?" The answer will often be yes, and learning to reach for this tool will fundamentally change the way you write and structure your Python applications for the better.
