Decorators

Layer 8 begins — optional, bonus sessions beyond the core 44-session curriculum, for anyone who wants to reach further into intermediate Python. You have used four decorators already without ever seeing how one is built.

1. Learning Objective

2. Pre-Coding Quiz

Answer these before reading the concept explanation or writing any code. It is fine to get these wrong — that is the point. You need 4/5 to proceed to the lab.

3. The Concept — Decorators — the General Mechanism

What every decorator you've already used has in common

By Session 44 you had already written @property, @classmethod, and @dataclass — but they were introduced as individual tools, not as one general mechanism. All three (and every decorator, including ones you write yourself) follow the exact same rule: a decorator is a callable that takes the function or class below it and returns something to use in its place.

# You've already seen this shape three times:
class Country:
    @property
    def total_population(self):
        return sum(...)

    @classmethod
    def from_dict(cls, data):
        return cls(**data)

@dataclass
class Country:
    name: str

# All three follow the identical underlying rule:
# @decorator_name
# def or class below it
#
# is equivalent to:
# name = decorator_name(name)

Writing your own decorator

A decorator is just a function that takes a function as its argument and returns a (usually new, wrapped) function. Nothing about this requires special syntax beyond what you already know: def, function calls, and returning a function object.

def shout(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()
    return wrapper

@shout
def greet(name):
    return f"hello {name}"

print(greet("kenya"))  # "HELLO KENYA"

Why *args, **kwargs in the wrapper

Recall Session 09: a decorator should work on ANY function, no matter its specific parameters. The wrapper accepts *args and **kwargs so it can transparently forward whatever arguments the real function actually needs, without the decorator needing to know its exact signature in advance.

def log_call(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} with {args}, {kwargs}")
        return func(*args, **kwargs)
    return wrapper

@log_call
def grow_population(country, amount):
    country.population += amount
    return country.population

# log_call works on grow_population despite never being written with
# grow_population's specific signature in mind

functools.wraps — preserving the original function's identity

Without help, a decorated function's __name__ and docstring show the generic wrapper's identity, not the original's — confusing anyone (including you) inspecting or debugging it later. functools.wraps fixes this in one line.

import functools

def shout(func):
    @functools.wraps(func)   # preserves greet's __name__, docstring, etc.
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()
    return wrapper

@shout
def greet(name):
    """Return a friendly greeting."""
    return f"hello {name}"

print(greet.__name__)  # "greet" — not "wrapper", thanks to functools.wraps
print(greet.__doc__)   # "Return a friendly greeting."

4. Lab

What you will build

A file called decorators_lab.py.

Step-by-step instructions

# decorators_lab.py
import functools
import time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.6f}s")
        return result
    return wrapper

@timed
def total_population(countries):
    return sum(c["population"] for c in countries)

countries = [
    {"name": "Kenya", "population": 54000000},
    {"name": "Ghana", "population": 31000000},
]
print(total_population(countries))

def positive_only(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        for value in list(args) + list(kwargs.values()):
            if isinstance(value, (int, float)) and value < 0:
                raise ValueError(f"{func.__name__} received a negative value: {value}")
        return func(*args, **kwargs)
    return wrapper

@positive_only
def grow_population(current, amount):
    return current + amount

print(grow_population(54000000, 1000000))

try:
    grow_population(54000000, -5)
except ValueError as e:
    print("Rejected:", e)

print(total_population.__name__)   # "total_population", not "wrapper"
print(grow_population.__name__)     # "grow_population", not "wrapper"

5. Expected Files Changed

6. Commit Checkpoint

Once the lab is complete and you can explain every line, make this exact commit:

git add decorators_lab.py docs/sessions/session-45/index.html
git commit -m "session-45: write custom decorators using functools.wraps"

7. Code Review Checklist

Go through your code line by line and check each item:

8. Post-Coding Quiz

Same 5 questions. Take it again now that you have written and run the code. You need 4/5 to mark this session complete.

9. Reflection Questions

Think through these after the post-quiz. No right answer — they are for discussion.

10. What Breaks If This Knowledge Is Missing?

11. What We Learned