These are the notes for Python episode 25. Raju's billing app has fifty functions and has become slow at rush hour. To find the slow one we need to time every function, and copy-pasting the same timing lines into fifty places goes wrong almost immediately. In this episode you invent decorators: functions that wrap extra work (timing, logging, retrying, permission checks) around any function without touching its code. On the way we cover functions as objects, functions that return functions (closures), writing a wrapper by hand, why every wrapper needs *args, **kwargs and return, the @ syntax, functools.wraps, decorators with arguments like @retry(times=3), stacking decorators, and the built-in @lru_cache. Every example below runs as-is in the SyntaxPilot compiler, with its real output from Python 3.13.
The problem: time every function
The obvious way: paste the same three timing lines into every function. time.perf_counter() returns a precise clock reading in seconds; the difference between two readings is how long the code in between took. time.sleep() pauses the program, pretending each function does slow work.
import time
def make_bill(items):
start = time.perf_counter()
time.sleep(0.2)
total = sum(items)
print(f"make_bill took {time.perf_counter() - start:.1f}s")
return total
def send_sms(phone):
start = time.perf_counter()
time.sleep(0.1)
print("SMS sent to", phone)
print(f"send_sms took {time.perf_counter() - start:.1f}s")
def apply_discount(total):
start = time.perf_counter()
time.sleep(0.1)
new_total = total * 0.9
print(f"apply_discount took {time.perf_counter() - start:.1f}s")
bill = make_bill([10, 15, 20])
send_sms("98765")
print("Final:", apply_discount(bill))
Output:
make_bill took 0.2s
SMS sent to 98765
send_sms took 0.1s
apply_discount took 0.1s
Final: None
The final bill should be 40.5, but it's None. While pasting the timer into apply_discount, the return new_total line was lost, and a function with no return gives back None.
Why it fails: the timer is the same job every time, but it is mixed into the code of every function. Fifty copies means fifty chances for a slip, and when Raju also wants logging, that's fifty more edits. We want to write the timer once and wrap it around any function.
Fact 1: a function is an object
A recipe card is not the dish; it's the instructions. A function name without brackets is the recipe card (the function object). With brackets you run it and get the result (the dish). Like a number or a list, a function object can be stored in a variable and passed to another function.
def greet():
return "Namaste!"
say = greet
print(say())
print(say)
def run_twice(func):
func()
func()
def hello():
print("Hello!")
run_twice(hello)
Output (the address will differ on your machine):
Namaste!
<function greet at 0x7f52d63d31a0>
Hello!
Hello!
say = greet doesn't call anything: say is a second name for the same function.
The classic mistake: passing the dish instead of the card
def run_twice(func):
func()
func()
def hello():
print("Hello!")
run_twice(hello())
Output:
Hello!
Traceback (most recent call last):
File "main.py", line 8, in <module>
run_twice(hello())
~~~~~~~~~^^^^^^^^^
File "main.py", line 2, in run_twice
func()
~~~~^^
TypeError: 'NoneType' object is not callable
hello() ran immediately (printing Hello! once) and passed its result, None, into run_twice. Then run_twice tried to call None. Pass hello, not hello(). (Callable means "can be called with ()".)
Fact 2: a function can make and return a function
def make_greeter(shop):
def greet(name):
print(f"Welcome to {shop}, {name}!")
return greet
chai_greet = make_greeter("Raju's Chai")
chai_greet("Asha")
chai_greet("Ravi")
print(chai_greet)
Output:
Welcome to Raju's Chai, Asha!
Welcome to Raju's Chai, Ravi!
<function make_greeter.<locals>.greet at 0x7fc2758a02c0>
make_greeter defines greet inside itself and returns it without calling it. The returned function still remembers shop, even after make_greeter has finished. An inner function that remembers variables from the function around it is called a closure. (<locals> in the name means "defined inside another function".)
Inventing the wrapper
Think of the gift-wrapping counter in a mall: you bring any gift, the gift itself doesn't change, and the counter puts paper around it. Our plan: a function timed that takes any function and returns a wrapped version with the timer around it.
import time
def timed(func):
def wrapper():
start = time.perf_counter()
func()
print(f"{func.__name__} took {time.perf_counter() - start:.1f}s")
return wrapper
def open_shop():
time.sleep(0.2)
print("Shop is open")
open_shop = timed(open_shop)
open_shop()
Output:
Shop is open
open_shop took 0.2s
func.__name__ is the function's name as text. open_shop = timed(open_shop) replaces the function with its wrapped version, and open_shop's own code has no timer in it.
Problem: the wrapper takes no arguments
def make_bill(items):
time.sleep(0.2)
return sum(items)
make_bill = timed(make_bill)
print(make_bill([10, 15, 20]))
Output (after the open_shop lines):
Traceback (most recent call last):
File "main.py", line 22, in <module>
print(make_bill([10, 15, 20]))
~~~~~~~~~^^^^^^^^^^^^^^
TypeError: timed.<locals>.wrapper() takes 0 positional arguments but 1 was given
We called make_bill with a list, but make_bill is now wrapper, and wrapper takes no arguments.
The fix: *args, **kwargs and return result
From episode 14: *args collects any positional arguments into a tuple and **kwargs collects any keyword arguments into a dict; writing func(*args, **kwargs) passes them all on unchanged. And the wrapper must save and return the result, or the caller gets None (exactly the copy-paste bug).
import time
def timed(func):
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
print(f"{func.__name__} took {time.perf_counter() - start:.1f}s")
return result
return wrapper
@timed
def make_bill(items, discount=0):
time.sleep(0.2)
return sum(items) - discount
@timed
def send_sms(phone):
time.sleep(0.1)
print("SMS sent to", phone)
print("Total:", make_bill([10, 15, 20], discount=5))
send_sms("98765")
Output:
make_bill took 0.2s
Total: 40
SMS sent to 98765
send_sms took 0.1s
One timer, written once, wrapped around functions with different arguments. You just invented decorators.
What @ really means
@timed
def make_bill(items): ...
is exactly the same as
def make_bill(items): ...
make_bill = timed(make_bill)
Python does this once, when the function is defined (not on every call). After that, every call goes to the wrapper:
your call make_bill(...) → wrapper: before work → the real make_bill → wrapper: after work → return the result
A decorator is a function that takes a function and returns a new function.
You can see that decorating happens at definition time:
def deco(func):
print("decorating", func.__name__)
return func
@deco
def a():
print("running a")
print("defined")
a()
Output:
decorating a
defined
running a
The trap: the wrapper hides the original's name
A docstring is the text in triple quotes right under a def; it's the function's help text (help(make_bill) shows it, and it's stored in __doc__).
def timed(func):
def wrapper(*args, **kwargs):
"""Times any function."""
return func(*args, **kwargs)
return wrapper
@timed
def make_bill(items):
"""Adds up the items."""
return sum(items)
print(make_bill.__name__)
print(make_bill.__doc__)
Output:
wrapper
Times any function.
After decorating, make_bill is the wrapper, so its name and help text are the wrapper's. Logs, error messages and help() would all say wrapper.
The fix: functools.wraps
wraps (from the standard-library module functools, "tools for functions") is a decorator for your wrapper: it copies the original function's __name__, __doc__ and other details onto it.
from functools import wraps
def timed(func):
@wraps(func)
def wrapper(*args, **kwargs):
"""Times any function."""
return func(*args, **kwargs)
return wrapper
@timed
def make_bill(items):
"""Adds up the items."""
return sum(items)
print(make_bill.__name__)
print(make_bill.__doc__)
Output:
make_bill
Adds up the items.
Always put @wraps(func) on your wrappers. The full pattern to remember:
from functools import wraps
def my_decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
# before
result = func(*args, **kwargs)
# after
return result
return wrapper
Decorators with arguments: @retry(times=3)
When a customer pays by UPI, the bank server is sometimes busy for a moment, and trying again usually works. But how many tries? 3 for UPI, maybe 5 for SMS. So the decorator needs a setting, which needs one more layer: retry(times) returns a decorator, which takes the function and returns the wrapper.
from functools import wraps
def retry(times):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
for attempt in range(1, times + 1):
try:
return func(*args, **kwargs)
except ConnectionError as e:
print(f"Attempt {attempt} failed: {e}")
raise ConnectionError(f"gave up after {times} tries")
return wrapper
return decorator
calls = 0
@retry(times=3)
def pay_upi(amount):
global calls
calls += 1
if calls < 3:
raise ConnectionError("bank server busy")
return f"Paid Rs {amount}"
print(pay_upi(120))
Output:
Attempt 1 failed: bank server busy
Attempt 2 failed: bank server busy
Paid Rs 120
ConnectionError is a built-in exception (episode 18) for network problems; our pretend pay_upi raises it the first two times. global calls lets the function change the module-level calls counter (episode 14). pay_upi itself has no loop at all.
@retry(times=3) means pay_upi = retry(times=3)(pay_upi): first retry(times=3) runs and returns decorator, then decorator(pay_upi) returns the wrapper.
The mistake: forgetting the brackets
@retry
def pay_upi(amount):
return f"Paid Rs {amount}"
print(pay_upi(120))
Output:
<function retry.<locals>.decorator.<locals>.wrapper at 0x7fb6970b1580>
No error, but it printed a function, not a payment. @retry passed pay_upi in as times, so pay_upi became decorator; calling pay_upi(120) then "decorated" the number 120 and returned a wrapper. A decorator with arguments always needs its brackets.
Stacking decorators
def stars(func):
def wrapper():
return "*** " + func() + " ***"
return wrapper
def shout(func):
def wrapper():
return func().upper() + "!"
return wrapper
@stars
@shout
def offer():
return "chai at half price"
print(offer())
Output:
*** CHAI AT HALF PRICE! ***
The decorator closest to the function wraps first: this is offer = stars(shout(offer)). shout is the inner paper, stars the outer paper. Swap them (@shout on top) and you get *** CHAI AT HALF PRICE ***!.
Built-in decorators: @lru_cache
In episode 15 you used @lru_cache to make recursive Fibonacci fast. Now you can see why. How many ways can you climb steps stairs taking 1 or 2 at a time? (It's the Fibonacci pattern again.) We count how many times the function is called.
from functools import lru_cache
calls = 0
def ways(steps):
global calls
calls += 1
if steps <= 1:
return 1
return ways(steps - 1) + ways(steps - 2)
print(ways(25), "ways,", calls, "calls")
calls = 0
@lru_cache
def ways_fast(steps):
global calls
calls += 1
if steps <= 1:
return 1
return ways_fast(steps - 1) + ways_fast(steps - 2)
print(ways_fast(25), "ways,", calls, "calls")
Output:
121393 ways, 242785 calls
121393 ways, 26 calls
lru_cache remembers the result for each argument it has seen (a cache), so each step count is computed only once: 26 calls instead of 242,785. LRU stands for least recently used: if you give it a size limit (@lru_cache(maxsize=128)), it throws away the answers used longest ago first. Arguments must be hashable (numbers, strings, tuples; not lists). Python 3.9+ also has @functools.cache, the same thing with no size limit.
Other built-in decorators you've met or will meet: @property (episode 23), @staticmethod, @classmethod, @dataclass (episode 27) and @contextmanager (episode 26). They're all the same idea: a function that takes a function (or class) and returns a new one.
Common mistakes
| Mistake | What you see | Why | Fix |
|---|---|---|---|
run_twice(hello()) |
TypeError: 'NoneType' object is not callable |
hello() ran and passed None |
run_twice(hello) |
def wrapper(): with no parameters |
TypeError: timed.<locals>.wrapper() takes 0 positional arguments but 1 was given |
the wrapper accepts no arguments | def wrapper(*args, **kwargs): |
func(*args, **kwargs) without return |
no error: the result is None |
the wrapper drops the result | return func(*args, **kwargs) |
no @wraps(func) |
no error: __name__ is 'wrapper', docstring lost |
the wrapper replaces the original | @wraps(func) from functools |
@retry instead of @retry(times=3) |
no error: prints <function retry.<locals>.decorator.<locals>.wrapper at 0x...> |
the function went in as times |
always use the brackets |
return wrapper() in the decorator |
the function runs once at definition, and the name becomes its result | called the wrapper instead of returning it | return wrapper |
| wrong stacking order | output wrapped the wrong way round | the bottom decorator wraps first | put the inner job closest to def |
@lru_cache on a function taking a list |
TypeError: unhashable type: 'list' |
the cache key must be hashable | pass a tuple |
Mini project: guard the refund
Raju wants a log line every time anyone calls a function, and a rule that only the owner can give a refund, not the cashier. Two decorators: log_calls, and require_role(role), which takes a setting. PermissionError is a built-in exception meaning "not allowed".
from functools import wraps
current_user = {"name": "Ravi", "role": "cashier"}
def require_role(role):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
if current_user["role"] != role:
raise PermissionError(f"{func.__name__} needs {role}")
return func(*args, **kwargs)
return wrapper
return decorator
def log_calls(func):
@wraps(func)
def wrapper(*args, **kwargs):
print(f"LOG: {current_user['name']} called {func.__name__}{args}")
return func(*args, **kwargs)
return wrapper
@log_calls
def make_bill(*items):
return sum(items)
@log_calls
@require_role("owner")
def refund(amount):
return f"Refunded Rs {amount}"
print(make_bill(10, 15, 20))
current_user["role"] = "owner"
print(refund(50))
current_user["role"] = "cashier"
print(refund(50))
Output:
LOG: Ravi called make_bill(10, 15, 20)
45
LOG: Ravi called refund(50,)
Refunded Rs 50
LOG: Ravi called refund(50,)
Traceback (most recent call last):
File "main.py", line 35, in <module>
print(refund(50))
~~~~~~^^^^
File "main.py", line 19, in wrapper
return func(*args, **kwargs)
File "main.py", line 10, in wrapper
raise PermissionError(f"{func.__name__} needs {role}")
PermissionError: refund needs owner
log_calls is on the outside, so even a blocked attempt is logged. Thanks to @wraps, require_role still sees the name refund. ((50,) is how Python prints a one-item tuple.) Frameworks like Flask and Django use exactly this pattern: @login_required, @app.route("/").
Practice
1. Write @count_calls, which counts how many times a function has been called.
Solution
from functools import wraps
def count_calls(func):
@wraps(func)
def wrapper(*args, **kwargs):
wrapper.calls += 1
print(f"{func.__name__} call #{wrapper.calls}")
return func(*args, **kwargs)
wrapper.calls = 0
return wrapper
@count_calls
def make_bill(*items):
return sum(items)
make_bill(10, 15)
make_bill(20)
print("Total calls:", make_bill.calls)
Output:
make_bill call #1
make_bill call #2
Total calls: 2
Functions are objects, so they can have attributes: wrapper.calls stores the count on the wrapper itself.
2. Write @slow_warning, which prints a warning only if a call takes more than 0.1 seconds.
Solution
import time
from functools import wraps
def slow_warning(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
result = func(*args, **kwargs)
took = time.perf_counter() - start
if took > 0.1:
print(f"WARNING: {func.__name__} took {took:.1f}s")
return result
return wrapper
@slow_warning
def quick():
return "done"
@slow_warning
def slow():
time.sleep(0.3)
return "done"
print(quick())
print(slow())
Output:
done
WARNING: slow took 0.3s
done
3. Write @repeat(n), which runs a function n times.
Solution
from functools import wraps
def repeat(n):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
result = None
for _ in range(n):
result = func(*args, **kwargs)
return result
return wrapper
return decorator
@repeat(3)
def ring_bell():
print("Ding!")
ring_bell()
Output:
Ding!
Ding!
Ding!
4. Swap @stars and @shout from the stacking example. Predict the output, then run it.
Solution
@shout
@stars
def offer():
return "chai at half price"
print(offer())
Output:
*** CHAI AT HALF PRICE ***!
Now stars wraps first (inner) and shout upper-cases the starred text and adds ! at the very end.
Quick quiz
1. The video's quiz: what does this print?
def twice(func):
def wrapper():
func()
func()
return wrapper
@twice
def hi():
print("Hi")
hi()
Answer
Hi
Hi
@twice means hi = twice(hi). Calling hi() runs the wrapper, which calls the original hi two times.
2. Which is the same as @a above @b above def f? (a) f = a(b(f)) (b) f = b(a(f))
Answer
(a) f = a(b(f)): the bottom decorator wraps first.
3. True or false: the code inside a decorator (not inside the wrapper) runs every time the function is called.
Answer
False. The decorator runs once, when the function is defined. Only the wrapper runs on every call.
Interview questions
- What is a decorator? A callable that takes a function (or class) and returns a replacement, usually a wrapper that adds behaviour before/after the original.
@dabovedef fmeansf = d(f). - Why are functions "first-class objects" in Python? They can be assigned to variables, passed as arguments, returned from functions and stored in data structures, just like any other value.
- What is a closure? An inner function that remembers variables from the enclosing function's scope after that function has returned (e.g.
funcinside a decorator's wrapper). - Why use
*args, **kwargsin a wrapper? So the wrapper accepts any arguments and passes them through unchanged, making the decorator work on any function. - What does
functools.wrapsdo? Copies__name__,__doc__,__module__,__qualname__and more from the wrapped function to the wrapper, and sets__wrapped__, so introspection, logging and debugging show the original. - How do you write a decorator that takes arguments? Three levels: an outer function takes the arguments and returns a decorator; the decorator takes the function and returns the wrapper.
- In what order are stacked decorators applied? Bottom to top (closest to
deffirst); when called, the outermost wrapper runs first. - When does decoration happen? At function definition time (import time for module-level functions), once.
- What does
lru_cachedo, and when shouldn't you use it? Memoizes results by arguments. Avoid it for functions with side effects, results that change over time, or unhashable arguments. - Real uses of decorators? Timing, logging, caching, retries, access control (
@login_required), registering routes (@app.route), validation,@property,@staticmethod,@classmethod,@dataclass.
Glossary
| Term | Meaning | Example |
|---|---|---|
| Decorator | A function that takes a function and returns a new (wrapped) one | @timed |
| Wrapper | The inner function a decorator returns; runs extra code around the original | def wrapper(*args, **kwargs): |
@ syntax |
Shortcut: @d above def f means f = d(f) |
@timed |
| First-class function | A function that can be stored, passed and returned like any value | say = greet |
| Function object | The function itself, without calling it (no brackets) | greet vs greet() |
| Callable | Anything you can call with () |
functions, classes |
| Higher-order function | A function that takes or returns a function | run_twice(func) |
| Inner (nested) function | A function defined inside another function | greet inside make_greeter |
| Closure | An inner function that remembers variables from its enclosing function | chai_greet remembers shop |
__name__ |
A function's name as text | make_bill.__name__ → 'make_bill' |
Docstring / __doc__ |
The help text in triple quotes under a def |
"""Adds up the items.""" |
*args, **kwargs |
Collect any positional / keyword arguments, and pass them on | func(*args, **kwargs) |
functools |
Standard-library module of tools for functions | from functools import wraps |
functools.wraps |
Copies the original's name and docstring onto the wrapper | @wraps(func) |
| Decorator factory | A function that takes settings and returns a decorator | retry(times=3) |
| Stacking | Using several decorators on one function; bottom wraps first | @stars over @shout |
| Cache / memoization | Remembering results so they're not computed again | @lru_cache |
lru_cache |
Built-in caching decorator; LRU = least recently used | @lru_cache |
time.perf_counter() |
A precise clock reading in seconds, for timing code | start = time.perf_counter() |
ConnectionError |
Built-in exception for network/connection failures | raise ConnectionError("bank server busy") |
PermissionError |
Built-in exception meaning "not allowed" | raise PermissionError(...) |
| Retry | Trying a failed operation again a few times | @retry(times=3) |
global |
Lets a function change a module-level variable | global calls |
Summary
- Copy-pasting the same extra code into every function drifts and breaks (
Final: None). - Functions are objects: store them, pass them (pass
hello, nothello()). - A function can return a new function; an inner function that remembers outer variables is a closure.
- A decorator takes a function and returns a wrapper that does work before and after calling it.
- Every wrapper needs
*args, **kwargs,return resultand@wraps(func). @timedmeansf = timed(f), done once at definition time.- Decorators with settings need three levels and brackets:
@retry(times=3). - Stacked decorators apply bottom first;
@lru_cacheremembers results (242,785 calls → 26).
Next episode: a crash in the middle of saving leaves Raju's sales file open and empty. We invent context managers and find out what with really does.