Python Decorators — From Simple Functions to Class-Based & Parameterised

The Story That Explains Decorators

In Python, functions are first-class objects. You can pass them to other functions, return them from functions, and store them in variables. A decorator is simply a function (or class) that takes another function as input and returns a new function that usually calls the original — but with something extra bolted on before, after, or around it.

The Foundation — Functions Are Objects

Before decorators make sense, you must accept one fact: in Python, a function is just another object. You can assign it to a variable, put it in a list, pass it as an argument, or return it from another function.

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

# 1. Assign the function to a new name (no parentheses!)
say_hi = greet
print(say_hi("Mohit"))       # -> Hello, Mohit!

# 2. Pass a function as an argument
def shout(fn, name):
    return fn(name).upper()

print(shout(greet, "Mohit"))   # -> HELLO, MOHIT!

# 3. Return a function from another function
def make_multiplier(n):
    def multiplier(x):
        return x * n
    return multiplier

double = make_multiplier(2)
print(double(7))               # -> 14

Your First Decorator — Written by Hand

Let's build a decorator that prints a message before and after any function runs. We will do it without the @ syntax first, so you see what's really happening.

def announce(fn):                     # takes a function
    def wrapper():                    # builds a new function
        print("-- before --")
        result = fn()                # call the original
        print("-- after  --")
        return result
    return wrapper                    # returns the wrapper

def say_hello():
    print("Hello!")

# Manually wrap it
say_hello = announce(say_hello)
say_hello()

Now the same thing using the @ syntax — this is pure syntactic sugar for say_hello = announce(say_hello). Nothing more, nothing less.

def announce(fn):
    def wrapper():
        print("-- before --")
        result = fn()
        print("-- after  --")
        return result
    return wrapper

@announce                    # the magic line
def say_hello():
    print("Hello!")

say_hello()

Handling Arguments — *args and **kwargs

Real functions take arguments. To make your decorator work with any function regardless of its signature, use *args, **kwargs in the wrapper. This captures every positional and keyword argument and forwards them intact.

def announce(fn):
    def wrapper(*args, **kwargs):
        print(f"Calling {fn.__name__} with {args} {kwargs}")
        result = fn(*args, **kwargs)
        print(f"{fn.__name__} returned {result!r}")
        return result
    return wrapper

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

@announce
def greet(name, greeting="Hi"):
    return f"{greeting}, {name}!"

add(3, 4)
greet("Mohit", greeting="Namaste")

Preserving Metadata — functools.wraps

When you decorate a function, its __name__, __doc__, and other introspection attributes get replaced by the wrapper's. This confuses debuggers, IDEs, and documentation tools. The fix is one line: @functools.wraps(fn).

from functools import wraps

def announce(fn):
    @wraps(fn)                     # preserves metadata
    def wrapper(*args, **kwargs):
        print(f"Calling {fn.__name__}")
        return fn(*args, **kwargs)
    return wrapper

@announce
def add(a, b):
    """Add two numbers."""
    return a + b

print(add.__name__)              # -> add (not 'wrapper')
print(add.__doc__)               # -> Add two numbers.

Visual Diagram — How a Decorator Wraps a Function

This is the mental model. The original function is the gift; the decorator is the wrapping paper. Once wrapped, every call goes through the wrapper — which does its "before" work, calls the inner function, does its "after" work, and returns the result.

Execution Timeline — What Happens When You Write @decorator

Decorators That Take Arguments

What if you want @repeat(3) to run a function three times, or @retry(times=5) to retry on failure? Now the decorator itself needs arguments. This requires three levels of nested functions:

Call Flow: @repeat(3) → greet("Mohit")

from functools import wraps

def repeat(times):                              # Layer 1 — takes decorator args
    def decorator(fn):                          # Layer 2 — real decorator
        @wraps(fn)
        def wrapper(*args, **kwargs):            # Layer 3 — runtime
            result = None
            for _ in range(times):
                result = fn(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(3)                                        # note: @repeat(3), not @repeat
def greet(name):
    print(f"Hi, {name}!")

greet("Mohit")

Practical Example — @timer, @retry, @cache

@timer — measure execution time

import time
from functools import wraps

def timer(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = fn(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{fn.__name__} took {elapsed*1000:.2f} ms")
        return result
    return wrapper

@timer
def slow_sum(n):
    return sum(range(n))

slow_sum(1_000_000)

@retry — auto-retry on exception (takes arguments)

import time, random
from functools import wraps

def retry(times=3, delay=1.0):
    def decorator(fn):
        @wraps(fn)
        def wrapper(*args, **kwargs):
            last_error = None
            for attempt in range(1, times + 1):
                try:
                    return fn(*args, **kwargs)
                except Exception as e:
                    last_error = e
                    print(f"[attempt {attempt}] failed: {e}")
                    time.sleep(delay)
            raise last_error
        return wrapper
    return decorator

@retry(times=3, delay=0.5)
def flaky_api_call():
    if random.random() < 0.7:
        raise ConnectionError("server busy")
    return "OK"

print(flaky_api_call())

@cache — memoise expensive results

from functools import wraps

def cache(fn):
    stored = {}
    @wraps(fn)
    def wrapper(*args):
        if args not in stored:
            stored[args] = fn(*args)
        return stored[args]
    return wrapper

@cache
def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

print(fib(50))                # instant, without cache would hang

Class-Based Decorators

A decorator doesn't have to be a function — any callable works. A class becomes a decorator by implementing __init__ (receives the function) and __call__ (runs when the decorated function is invoked).

CountCalls — a class-based decorator with state

from functools import wraps

class CountCalls:
    def __init__(self, fn):
        wraps(fn)(self)              # preserve metadata
        self.fn    = fn
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.fn.__name__} call #{self.count}")
        return self.fn(*args, **kwargs)

    def reset(self):
        self.count = 0

@CountCalls
def say_hi(name):
    print(f"Hi, {name}!")

say_hi("Mohit")
say_hi("Aarav")
say_hi("Priya")
print(f"Total: {say_hi.count} calls")   # -> 3
say_hi.reset()
print(f"After reset: {say_hi.count}") # -> 0

Class-based decorator that takes arguments

from functools import wraps

class Repeat:
    def __init__(self, times):        # Layer 1 — receives args
        self.times = times

    def __call__(self, fn):           # Layer 2 — receives fn
        @wraps(fn)
        def wrapper(*args, **kwargs):  # Layer 3 — runtime
            result = None
            for _ in range(self.times):
                result = fn(*args, **kwargs)
            return result
        return wrapper

@Repeat(2)
def shout(msg):
    print(msg.upper())

shout("hello")

Function vs Class-Based — When to Use Which

Stacking Multiple Decorators

You can stack decorators. They apply bottom-up — the decorator closest to the function wraps it first, then the next one wraps that, and so on. But the wrappers execute top-down when the function is called.

def bold(fn):
    def wrapper(*a, **k):
        return f"<b>{fn(*a, **k)}</b>"
    return wrapper

def italic(fn):
    def wrapper(*a, **k):
        return f"<i>{fn(*a, **k)}</i>"
    return wrapper

@bold                          # applied SECOND — outermost
@italic                        # applied FIRST  — innermost
def say(msg):
    return msg

print(say("hello"))
# Equivalent to: say = bold(italic(say))

Real-World Example — @login_required

Now let's build the classic authentication decorator. In web frameworks like Flask and Django, @login_required is the canonical use case for decorators — it guards view functions so only authenticated users can call them.

Version 1 — Simple @login_required

from functools import wraps

# Fake session — in a real app this comes from Flask/Django
current_session = {"user": None}

def login_required(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        user = current_session.get("user")
        if user is None:
            raise PermissionError("Login required")
        return fn(*args, **kwargs)
    return wrapper

@login_required
def view_dashboard():
    return f"Welcome, {current_session['user']['name']}!"

# --- Try it without logging in ---
try:
    view_dashboard()
except PermissionError as e:
    print(f"Blocked: {e}")

# --- Log in and try again ---
current_session["user"] = {"name": "Mohit", "role": "admin"}
print(view_dashboard())

Version 2 — @requires_role("admin") with arguments

Now let's parameterise it. We want @requires_role("admin") to only allow users whose role matches. This uses the three-layer pattern from Section 07.

from functools import wraps

current_session = {"user": None}

def requires_role(*allowed_roles):        # Layer 1 — decorator args
    def decorator(fn):                    # Layer 2 — real decorator
        @wraps(fn)
        def wrapper(*args, **kwargs):      # Layer 3 — runtime
            user = current_session.get("user")
            if user is None:
                raise PermissionError("Login required")
            if user["role"] not in allowed_roles:
                raise PermissionError(
                    f"Role '{user['role']}' not in {allowed_roles}"
                )
            return fn(*args, **kwargs)
        return wrapper
    return decorator

@requires_role("admin")
def delete_all_users():
    return "All users deleted!"

@requires_role("admin", "editor")
def publish_article(title):
    return f"Published: {title}"

# --- Editor tries admin-only action ---
current_session["user"] = {"name": "Priya", "role": "editor"}
try:
    delete_all_users()
except PermissionError as e:
    print(f"Blocked: {e}")

print(publish_article("Python Decorators"))

# --- Admin can do both ---
current_session["user"] = {"name": "Mohit", "role": "admin"}
print(delete_all_users())

Version 3 — Class-Based @LoginRequired with Audit Log

Class-based version — persistent state lets us log every attempt and expose statistics.

from functools import wraps
from datetime import datetime

current_session = {"user": None}

class LoginRequired:
    def __init__(self, fn):
        wraps(fn)(self)
        self.fn      = fn
        self.granted = 0
        self.denied  = 0
        self.log     = []

    def __call__(self, *args, **kwargs):
        user = current_session.get("user")
        ts   = datetime.now().strftime("%H:%M:%S")
        if user is None:
            self.denied += 1
            self.log.append((ts, "DENIED", self.fn.__name__))
            raise PermissionError("Login required")
        self.granted += 1
        self.log.append((ts, "GRANTED", user["name"]))
        return self.fn(*args, **kwargs)

    def stats(self):
        return {"granted": self.granted, "denied": self.denied}

@LoginRequired
def view_profile():
    return f"Profile of {current_session['user']['name']}"

# Simulate a mix of logged-in and logged-out attempts
for user in [None, {"name": "Mohit"}, None, {"name": "Aarav"}]:
    current_session["user"] = user
    try:
        view_profile()
    except PermissionError:
        pass

print(view_profile.stats())
for entry in view_profile.log:
    print(entry)

Built-in Decorators You Should Know

class User:
    def __init__(self, first, last):
        self._first = first
        self._last  = last

    @property                          # access as attribute
    def full_name(self):
        return f"{self._first} {self._last}"

    @classmethod                        # alternative constructor
    def from_string(cls, s):
        first, last = s.split(" ", 1)
        return cls(first, last)

    @staticmethod                       # utility, no self/cls
    def is_valid_name(s):
        return len(s.split()) >= 2

u = User.from_string("Mohit Kumar")
print(u.full_name)                    # -> Mohit Kumar (no parens!)
print(User.is_valid_name("Mohit Kumar"))

Common Pitfalls

Golden Rules