SyntaxPilot
Courses/Python/Lesson 25

Python · Lesson 25 of 40 · 14 min

Decorators

queued

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

  1. 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. @d above def f means f = d(f).
  2. 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.
  3. What is a closure? An inner function that remembers variables from the enclosing function's scope after that function has returned (e.g. func inside a decorator's wrapper).
  4. Why use *args, **kwargs in a wrapper? So the wrapper accepts any arguments and passes them through unchanged, making the decorator work on any function.
  5. What does functools.wraps do? 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.
  6. 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.
  7. In what order are stacked decorators applied? Bottom to top (closest to def first); when called, the outermost wrapper runs first.
  8. When does decoration happen? At function definition time (import time for module-level functions), once.
  9. What does lru_cache do, 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.
  10. 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, not hello()).
  • 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 result and @wraps(func).
  • @timed means f = timed(f), done once at definition time.
  • Decorators with settings need three levels and brackets: @retry(times=3).
  • Stacked decorators apply bottom first; @lru_cache remembers 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.