Python Decorator Patterns: Build retry, timer, and cache Decorators
Decorator factories that take arguments. Build @retry(max_attempts=3), @timer, and @cache from scratch. See the three-level nesting in action.
I was reading the payment processor code this morning. There's this decorator: @retry(max_attempts=3). Wait — the decorator takes an argument? How does that work?
Because the decorator isn't a function — it's a function that returns a function that returns a function. Three levels of nesting.
That's... a lot of nesting. Walk me through it.
Okay. Yesterday you learned that a decorator is a function that takes a function, wraps it, and returns the wrapper. That's level one: decorator(function) → wrapper.
Now if you want the decorator itself to take arguments, you need a layer above the decorator. A function that returns a decorator.
So @retry(max_attempts=3) calls retry(max_attempts=3) first, and that returns the decorator?
Exactly. It's confusing because the syntax hides the nesting. Let me show you step by step.
# Without arguments, a decorator is simple:
def timer(func):
def wrapper(*args, **kwargs):
print(f"Calling {func.__name__}")
result = func(*args, **kwargs)
print(f"Done")
return result
return wrapper
@timer
def fetch_user(user_id):
return f"User {user_id}"
# When you use @timer, Python does this:
# fetch_user = timer(fetch_user)
That's level one.
Okay so the decorator is applied at definition time. The function gets passed to the decorator, the decorator returns a wrapper, and that wrapper is what fetch_user becomes.
Right. Now what if you want to customize the decorator? What if you want some calls to timer to log, others to time, others to both?
You'd add a parameter to the decorator?
You'd add a parameter to a function that creates the decorator. Like this:
def timer(label=None):
def decorator(func):
def wrapper(*args, **kwargs):
if label:
print(f"[{label}] Calling {func.__name__}")
result = func(*args, **kwargs)
if label:
print(f"[{label}] Done")
return result
return wrapper
return decorator
@timer(label="api_call")
def fetch_user(user_id):
return f"User {user_id}"
Now when Python sees @timer(label="api_call"), it does three things:
- Call timer(label="api_call") → returns decorator function
- Call decorator(fetch_user) → returns wrapper function
- Set fetch_user = wrapper
Three levels. The outer function takes arguments. It returns the decorator. The decorator takes the function. The decorator returns the wrapper.
That's the pattern. The outer function is a decorator factory. It creates customized decorators.
But why not just pass all the arguments to the decorator directly? Like def timer(func, label=None):?
Because Python's @ syntax assumes the decorator is a callable that takes one argument — the function. If you wrote @timer(fetch_user, label="api_call") that would be weird. The three-level pattern lets you write @timer(label="api_call") and it feels natural.
Okay so the outer function (timer) is a factory. It takes the configuration. It returns a decorator. The decorator takes the function and wraps it.
That's it.
Show me retry.
Retry is a decorator that calls the function up to N times. If it fails, retry. If it succeeds, return the result. If all retries fail, raise the last exception.
def retry(max_attempts=3):
def decorator(func):
def wrapper(*args, **kwargs):
last_exception = None
for attempt in range(max_attempts):
try:
result = func(*args, **kwargs)
print(f"Success on attempt {attempt + 1}")
return result
except Exception as e:
last_exception = e
print(f"Attempt {attempt + 1} failed: {e}")
raise last_exception
return wrapper
return decorator
@retry(max_attempts=3)
def flaky_api_call():
import random
if random.random() < 0.7:
raise ConnectionError("Network error")
return "success"
Now flaky_api_call is wrapped. When you call it, the wrapper tries up to 3 times. If all fail, the last exception gets raised.
So the wrapper is a state machine. Try once. If it fails, try again. If it fails again, try again. If all three fail, give up.
Yes. And the original function is never called directly — it's always called from inside the wrapper.
And the last_exception variable in the outer scope... the wrapper uses it?
Yes. That's a closure. The wrapper function has access to last_exception because it was defined in the retry function's scope. When you raise last_exception at the end, you're raising the exception from the last failed attempt.
What if all attempts succeed on the first try? Does it just return?
Yes. If the first call succeeds, it prints "Success on attempt 1" and returns immediately. The loop breaks, the function exits.
Okay so I understand retry now. What's timer?
Timer measures how long a function takes:
import time
def timer(label=None):
def decorator(func):
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
elapsed = time.time() - start
if label:
print(f"[{label}] {elapsed:.2f}s")
else:
print(f"{func.__name__}: {elapsed:.2f}s")
return result
return wrapper
return decorator
@timer(label="database_query")
def fetch_orders():
time.sleep(1) # Simulate slow query
return []
When you call fetch_orders(), the wrapper times the execution and prints how long it took.
So it's like a stopwatch decorator.
Exactly. You're measuring function performance without changing the function's code.
And the label is optional. If you don't provide one, it uses the function name.
Right. That's why the outer function takes label=None. If you don't care about a label, you can write @timer() and it works.
What about cache?
Cache stores the result of a function so you don't have to call it again with the same arguments.
def cache(func):
store = {} # Dictionary to hold cached results
def wrapper(*args, **kwargs):
# Create a key from the arguments
key = (args, tuple(sorted(kwargs.items())))
if key in store:
print(f"Cache hit: {func.__name__}")
return store[key]
print(f"Cache miss: computing {func.__name__}")
result = func(*args, **kwargs)
store[key] = result
return result
return wrapper
@cache
def expensive_calculation(n):
print(f"Really computing for {n}")
return n * n
print(expensive_calculation(5)) # Cache miss, computes
print(expensive_calculation(5)) # Cache hit, returns stored result
print(expensive_calculation(6)) # Cache miss, new argument
So the wrapper checks if the arguments have been seen before. If yes, return the stored result. If no, call the function and store the result.
Exactly. The store dict persists across calls because it's in the wrapper's closure. Every time wrapper is called, it checks the same store.
Wait, cache doesn't take arguments like retry and timer do. Why?
Because cache doesn't need customization. It's simple: store results, check before computing. Retry needs max_attempts. Timer needs an optional label. Cache doesn't need any configuration.
But I could write a cache factory if I wanted to, like, clear the cache after a certain time?
Yes! That's a good idea. You could write:
def cache(ttl=None):
store = {}
timestamps = {}
def decorator(func):
def wrapper(*args, **kwargs):
key = (args, tuple(sorted(kwargs.items())))
import time
now = time.time()
if key in store and (ttl is None or now - timestamps[key] < ttl):
return store[key]
result = func(*args, **kwargs)
store[key] = result
timestamps[key] = now
return result
return wrapper
return decorator
@cache(ttl=60) # Cache for 60 seconds
def expensive_calculation(n):
return n * n
Now cache is a factory too. It takes ttl (time to live) and returns a decorator.
So the pattern is: if the decorator needs configuration, make it a factory. If it doesn't, just make it a function that takes the function.
That's the rule.
What's the simplest example of this? Like, the bare minimum three-level thing?
Here:
def decorator_factory(config):
def decorator(func):
def wrapper(*args, **kwargs):
print(f"Config: {config}")
return func(*args, **kwargs)
return wrapper
return decorator
@decorator_factory(config="hello")
def greet(name):
return f"Hello {name}"
Three levels: factory takes config, returns decorator. Decorator takes func, returns wrapper. Wrapper calls func.
And the syntax @decorator_factory(config="hello") calls the factory first, gets the decorator, applies the decorator to greet.
Right. By the time Python assigns greet, it's already been through both the factory and the decorator.
So when I see @retry(max_attempts=3) in the codebase, I know: retry is a factory. It takes max_attempts and returns a decorator. The decorator takes a function and returns a wrapper that retries up to max_attempts times.
And the wrapper is called every time you invoke the decorated function.
What happens if I use retry without arguments? Like @retry?
It breaks. Because @retry would pass the function directly to retry(), and retry() expects max_attempts, not a function. You have to write @retry(max_attempts=3) or the factory won't work.
Unless you make max_attempts optional and provide a default?
Yes! That's why I showed def retry(max_attempts=3). Now @retry() works with the default, and @retry(max_attempts=5) customizes it.
Okay I think I get it. The three levels are confusing at first but once you see the pattern — factory, decorator, wrapper — it clicks.
And tomorrow you'll see functools.wraps and functools.lru_cache, which are built-in versions of these patterns. You're building them by hand today so you understand how they work.
So functools.lru_cache is basically the cache decorator I just learned?
Functionally, yes. But it's more robust — it handles corner cases, it's optimized, it's production-ready. Today you learned the core idea. Tomorrow we see how the standard library does it.
I'm going to build the retry decorator for our order processor. We have flaky API calls and we're catching them in a try-except every time. A @retry decorator would be cleaner.
Amir's going to ask you to explain it. This time you'll actually be able to.
Practice your skills
Sign up to write and run code in this lesson.
Python Decorator Patterns: Build retry, timer, and cache Decorators
Decorator factories that take arguments. Build @retry(max_attempts=3), @timer, and @cache from scratch. See the three-level nesting in action.
I was reading the payment processor code this morning. There's this decorator: @retry(max_attempts=3). Wait — the decorator takes an argument? How does that work?
Because the decorator isn't a function — it's a function that returns a function that returns a function. Three levels of nesting.
That's... a lot of nesting. Walk me through it.
Okay. Yesterday you learned that a decorator is a function that takes a function, wraps it, and returns the wrapper. That's level one: decorator(function) → wrapper.
Now if you want the decorator itself to take arguments, you need a layer above the decorator. A function that returns a decorator.
So @retry(max_attempts=3) calls retry(max_attempts=3) first, and that returns the decorator?
Exactly. It's confusing because the syntax hides the nesting. Let me show you step by step.
# Without arguments, a decorator is simple:
def timer(func):
def wrapper(*args, **kwargs):
print(f"Calling {func.__name__}")
result = func(*args, **kwargs)
print(f"Done")
return result
return wrapper
@timer
def fetch_user(user_id):
return f"User {user_id}"
# When you use @timer, Python does this:
# fetch_user = timer(fetch_user)
That's level one.
Okay so the decorator is applied at definition time. The function gets passed to the decorator, the decorator returns a wrapper, and that wrapper is what fetch_user becomes.
Right. Now what if you want to customize the decorator? What if you want some calls to timer to log, others to time, others to both?
You'd add a parameter to the decorator?
You'd add a parameter to a function that creates the decorator. Like this:
def timer(label=None):
def decorator(func):
def wrapper(*args, **kwargs):
if label:
print(f"[{label}] Calling {func.__name__}")
result = func(*args, **kwargs)
if label:
print(f"[{label}] Done")
return result
return wrapper
return decorator
@timer(label="api_call")
def fetch_user(user_id):
return f"User {user_id}"
Now when Python sees @timer(label="api_call"), it does three things:
- Call timer(label="api_call") → returns decorator function
- Call decorator(fetch_user) → returns wrapper function
- Set fetch_user = wrapper
Three levels. The outer function takes arguments. It returns the decorator. The decorator takes the function. The decorator returns the wrapper.
That's the pattern. The outer function is a decorator factory. It creates customized decorators.
But why not just pass all the arguments to the decorator directly? Like def timer(func, label=None):?
Because Python's @ syntax assumes the decorator is a callable that takes one argument — the function. If you wrote @timer(fetch_user, label="api_call") that would be weird. The three-level pattern lets you write @timer(label="api_call") and it feels natural.
Okay so the outer function (timer) is a factory. It takes the configuration. It returns a decorator. The decorator takes the function and wraps it.
That's it.
Show me retry.
Retry is a decorator that calls the function up to N times. If it fails, retry. If it succeeds, return the result. If all retries fail, raise the last exception.
def retry(max_attempts=3):
def decorator(func):
def wrapper(*args, **kwargs):
last_exception = None
for attempt in range(max_attempts):
try:
result = func(*args, **kwargs)
print(f"Success on attempt {attempt + 1}")
return result
except Exception as e:
last_exception = e
print(f"Attempt {attempt + 1} failed: {e}")
raise last_exception
return wrapper
return decorator
@retry(max_attempts=3)
def flaky_api_call():
import random
if random.random() < 0.7:
raise ConnectionError("Network error")
return "success"
Now flaky_api_call is wrapped. When you call it, the wrapper tries up to 3 times. If all fail, the last exception gets raised.
So the wrapper is a state machine. Try once. If it fails, try again. If it fails again, try again. If all three fail, give up.
Yes. And the original function is never called directly — it's always called from inside the wrapper.
And the last_exception variable in the outer scope... the wrapper uses it?
Yes. That's a closure. The wrapper function has access to last_exception because it was defined in the retry function's scope. When you raise last_exception at the end, you're raising the exception from the last failed attempt.
What if all attempts succeed on the first try? Does it just return?
Yes. If the first call succeeds, it prints "Success on attempt 1" and returns immediately. The loop breaks, the function exits.
Okay so I understand retry now. What's timer?
Timer measures how long a function takes:
import time
def timer(label=None):
def decorator(func):
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
elapsed = time.time() - start
if label:
print(f"[{label}] {elapsed:.2f}s")
else:
print(f"{func.__name__}: {elapsed:.2f}s")
return result
return wrapper
return decorator
@timer(label="database_query")
def fetch_orders():
time.sleep(1) # Simulate slow query
return []
When you call fetch_orders(), the wrapper times the execution and prints how long it took.
So it's like a stopwatch decorator.
Exactly. You're measuring function performance without changing the function's code.
And the label is optional. If you don't provide one, it uses the function name.
Right. That's why the outer function takes label=None. If you don't care about a label, you can write @timer() and it works.
What about cache?
Cache stores the result of a function so you don't have to call it again with the same arguments.
def cache(func):
store = {} # Dictionary to hold cached results
def wrapper(*args, **kwargs):
# Create a key from the arguments
key = (args, tuple(sorted(kwargs.items())))
if key in store:
print(f"Cache hit: {func.__name__}")
return store[key]
print(f"Cache miss: computing {func.__name__}")
result = func(*args, **kwargs)
store[key] = result
return result
return wrapper
@cache
def expensive_calculation(n):
print(f"Really computing for {n}")
return n * n
print(expensive_calculation(5)) # Cache miss, computes
print(expensive_calculation(5)) # Cache hit, returns stored result
print(expensive_calculation(6)) # Cache miss, new argument
So the wrapper checks if the arguments have been seen before. If yes, return the stored result. If no, call the function and store the result.
Exactly. The store dict persists across calls because it's in the wrapper's closure. Every time wrapper is called, it checks the same store.
Wait, cache doesn't take arguments like retry and timer do. Why?
Because cache doesn't need customization. It's simple: store results, check before computing. Retry needs max_attempts. Timer needs an optional label. Cache doesn't need any configuration.
But I could write a cache factory if I wanted to, like, clear the cache after a certain time?
Yes! That's a good idea. You could write:
def cache(ttl=None):
store = {}
timestamps = {}
def decorator(func):
def wrapper(*args, **kwargs):
key = (args, tuple(sorted(kwargs.items())))
import time
now = time.time()
if key in store and (ttl is None or now - timestamps[key] < ttl):
return store[key]
result = func(*args, **kwargs)
store[key] = result
timestamps[key] = now
return result
return wrapper
return decorator
@cache(ttl=60) # Cache for 60 seconds
def expensive_calculation(n):
return n * n
Now cache is a factory too. It takes ttl (time to live) and returns a decorator.
So the pattern is: if the decorator needs configuration, make it a factory. If it doesn't, just make it a function that takes the function.
That's the rule.
What's the simplest example of this? Like, the bare minimum three-level thing?
Here:
def decorator_factory(config):
def decorator(func):
def wrapper(*args, **kwargs):
print(f"Config: {config}")
return func(*args, **kwargs)
return wrapper
return decorator
@decorator_factory(config="hello")
def greet(name):
return f"Hello {name}"
Three levels: factory takes config, returns decorator. Decorator takes func, returns wrapper. Wrapper calls func.
And the syntax @decorator_factory(config="hello") calls the factory first, gets the decorator, applies the decorator to greet.
Right. By the time Python assigns greet, it's already been through both the factory and the decorator.
So when I see @retry(max_attempts=3) in the codebase, I know: retry is a factory. It takes max_attempts and returns a decorator. The decorator takes a function and returns a wrapper that retries up to max_attempts times.
And the wrapper is called every time you invoke the decorated function.
What happens if I use retry without arguments? Like @retry?
It breaks. Because @retry would pass the function directly to retry(), and retry() expects max_attempts, not a function. You have to write @retry(max_attempts=3) or the factory won't work.
Unless you make max_attempts optional and provide a default?
Yes! That's why I showed def retry(max_attempts=3). Now @retry() works with the default, and @retry(max_attempts=5) customizes it.
Okay I think I get it. The three levels are confusing at first but once you see the pattern — factory, decorator, wrapper — it clicks.
And tomorrow you'll see functools.wraps and functools.lru_cache, which are built-in versions of these patterns. You're building them by hand today so you understand how they work.
So functools.lru_cache is basically the cache decorator I just learned?
Functionally, yes. But it's more robust — it handles corner cases, it's optimized, it's production-ready. Today you learned the core idea. Tomorrow we see how the standard library does it.
I'm going to build the retry decorator for our order processor. We have flaky API calls and we're catching them in a try-except every time. A @retry decorator would be cleaner.
Amir's going to ask you to explain it. This time you'll actually be able to.