Python Decorators

A decorator is a function that takes another function (or class) as input and returns a modified or wrapped version of it, without permanently changing the original function's source code. Decorators are Python's way of cleanly separating "what a function does" from "extra behavior applied around every call to it," such as logging, timing, access control, or caching.

Decorators rely on the fact that functions are first-class objects in Python — they can be passed around, stored in variables, and returned from other functions just like any other value. The @decorator_name syntax placed above a function definition is simply shorthand for function = decorator_name(function).

Why it matters

Decorators are everywhere in Python frameworks: @app.get("/") in FastAPI, @pytest.fixture, @property, @login_required in Django. They add behaviour such as logging, timing, caching or access checks to a function without touching its code. You cannot read modern Python without understanding the @ line.

Writing a Basic Decorator

A decorator is typically written as a function that defines an inner "wrapper" function, calls the original function from inside that wrapper, and returns the wrapper. Because the wrapper usually needs to accept whatever arguments the original function accepts, it's conventional to define it as def wrapper(*args, **kwargs):, which forwards any positional and keyword arguments through to the wrapped function unchanged.

functools.wraps

Without extra care, wrapping a function replaces its __name__, __doc__, and other metadata with the wrapper function's own metadata — which makes debugging and introspection confusing, since help(my_function) would describe "wrapper" instead of the real function. The standard library's functools.wraps decorator, applied to the inner wrapper function, copies this metadata over from the original function automatically, and is considered a best practice for any decorator you write.

A Practical Example: Timing a Function

One of the most common real-world uses of a decorator is measuring how long a function takes to run, without modifying the function's own code at all — you record a start time before calling the wrapped function, call it, record an end time, and print or log the difference. The same pattern applies to logging (recording that a function was called and with what arguments) or to enforcing access control (checking a permission before allowing the wrapped function to run at all).

Examples

import time
from functools import wraps

def timer(func):
    @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:.4f} seconds")
        return result
    return wrapper

@timer
def slow_square(n):
    total = 0
    for i in range(n):
        total += i * i
    return total

result = slow_square(1000000)
print(result)
print(slow_square.__name__)  # thanks to @wraps, this is "slow_square", not "wrapper"

slow_square took 0.0421 seconds
333332833333500000
slow_square

from functools import wraps

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

@log_calls
def add(a, b):
    return a + b

add(3, 4)

Calling add with args=(3, 4), kwargs={}
add returned 7

Exercise

Write a decorator shout that converts the text returned by a function to upper case. Use functools.wraps so that the decorated function keeps its original name.

Expected output: HELLO, ASHA then greet

from functools import wraps


def shout(function):
    # TODO: define a wrapper that calls the function and returns the result in upper case
    # TODO: return the wrapper
    pass


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


print(greet("asha"))
print(greet.__name__)

from functools import wraps


def shout(function):
    @wraps(function)
    def wrapper(*args, **kwargs):
        return function(*args, **kwargs).upper()

    return wrapper


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


print(greet("asha"))
print(greet.__name__)

Quick quiz

Interview questions