Python Decorators

In Python, a function is a value like any other. You can store it in a variable, pass it to another function and return it from a function:

def shout(text):
    return text.upper() + "!"

say = shout             # no brackets: the function itself
print(say("hello"))     # HELLO!

A function can also be defined inside another function. The inner function can use the outer function's variables, even after the outer function has finished. This is called a closure, and it's what lets a decorator remember the function it wraps.

def announce(func):
    def wrapper():
        print("Starting...")
        func()
        print("Done.")
    return wrapper

@announce
def backup():
    print("Backing up files")

@announce is shorthand for backup = announce(backup). The name backup now refers to wrapper, which prints a message, calls the original function, then prints another. Calling backup() prints all three lines.

Real decorators must work with functions that take arguments and return values. Use *args and **kwargs to pass everything through, and return the result:

import functools

def log_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}{args}")
        result = func(*args, **kwargs)
        return result
    return wrapper

@functools.wraps(func) copies the original function's name and docstring onto the wrapper. Without it, every decorated function would be called "wrapper" in error messages and help text.

Here is the three-layer pattern in full. The outer function receives the settings, the middle one receives the function, and the inner wrapper does the work on every call:

import functools

def repeat(times):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def cheer(name):
    print(f"Go {name}!")

cheer("Ada")

This prints Go Ada! three times. @repeat(times=3) first calls repeat(3), which returns decorator; Python then applies that to cheer. Stacked decorators are applied from the bottom up: the one closest to the def wraps the function first.

To give a decorator settings, such as @retry(times=3), add one more layer: a function that takes the settings and returns the decorator. It's three nested functions, which looks complex at first but always follows the same pattern.

Python includes several useful decorators:

• @functools.lru_cache remembers results, so repeat calls with the same arguments return instantly.
• @property lets a method be read like an attribute, as in account.balance.
• @staticmethod and @classmethod change how methods in a class receive their first argument.
• @dataclass writes a class's boilerplate for you, as you'll see in the dataclasses lesson.