Custom Decorator Libraries

Published by Brayan K

Design reusable decorator libraries that power frameworks, APIs, and production systems

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

From one decorator to a library of them

Decorators & Advanced Features built decorators one at a time: a wrapper that takes *args and **kwargs and returns the result, functools.wraps to keep the name and docstring, stacking, decorators that take arguments, and ones that register a function or count its calls. This lesson doesn't repeat that. It's about the decorators you keep in a package of your own and use again in project after project.

A decorator like that meets things a one-off decorator never does: options given or left out, methods as well as functions, async def functions, other decorators above and below it, tools that read a function's parameters, and tests. Each part of this lesson takes a decorator that works in the simple case, shows where it breaks, and fixes it.

Frameworks are built from the same parts. In Flask 3.1.3's source, route() is a decorator that takes an argument: the decorator it returns calls self.add_url_rule(rule, endpoint, f, **options) and then returns f unchanged. That's the registering pattern the registry in this lesson is built on.

Two kinds of decorator have lessons of their own: caching with lru_cache in functools: lru_cache, partial, reduce, and decorators that change a whole class in Metaprogramming & Introspection with inspect. Measuring how long code takes is the subject of Profiling & Optimising Python Performance.

One decorator, with or without brackets

Decorators & Advanced Features showed that @repeat without its brackets fails quietly: the function becomes the decorator, and calling it runs nothing. A library decorator can accept both forms, @shout and @shout(times=2). The function comes first, with None as its default, and the options come after a *, which makes them keyword-only: they can only be given by name.

import functools

def shout(func=None, *, times=1):
    if func is None:
        return functools.partial(shout, times=times)
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return (func(*args, **kwargs).upper() + "!") * times
    return wrapper

@shout
def greet(name):
    return "hi " + name

@shout(times=2)
def cheer(name):
    return "go " + name

print(greet("Ada"))
print(cheer("Ada"))
print(greet.__name__, cheer.__name__)

# ✅ Expected output:
# HI ADA!
# GO ADA!GO ADA!
# greet cheer

With @shout, Python calls shout(greet), so func is the function. With @shout(times=2), it first calls shout(times=2), where func is None, and what that returns must be a decorator. functools.partial(shout, times=2) is one: a new function that, given cheer, calls shout(cheer, times=2). Higher-Order Functions & Function Factories previewed partial, and functools: lru_cache, partial, reduce covers it.

The * is what keeps this safe. Given without its name, an option arrives as the function:

import functools

def shout(func=None, *, times=1):
    if func is None:
        return functools.partial(shout, times=times)
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return (func(*args, **kwargs).upper() + "!") * times
    return wrapper

@shout(2)
def cheer(name):
    return "go " + name

print("defined")
print(cheer("Ada"))

# ✅ Expected error:
# TypeError: 'int' object is not callable

2 isn't None, so shout(2) treats it as the function and returns a wrapper around it straight away. Python then calls that wrapper with cheer, and the wrapper runs 2(cheer). The program stops while the def runs, before defined is printed, with a message that doesn't mention shout at all. The built-in callable(), which is True for functions and anything else that can be called, lets the decorator say what to write instead:

import functools

def shout(func=None, *, times=1):
    if func is None:
        return functools.partial(shout, times=times)
    if not callable(func):
        raise TypeError("use @shout or @shout(times=2), not @shout(2)")
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return (func(*args, **kwargs).upper() + "!") * times
    return wrapper

@shout(2)
def cheer(name):
    return "go " + name

# ✅ Expected error:
# TypeError: use @shout or @shout(times=2), not @shout(2)

Two positional arguments don't get that far: shout(print, 2) stops with TypeError: shout() takes from 0 to 1 positional arguments but 2 were given, because only func can be given by position.

Keeping the signature: what functools.wraps copies

A function's signature is its list of parameters, with their defaults and annotations. help() shows it, and inspect.signature() returns it as an object, which Building Command-Line Tools with argparse & Typer used to show what Typer reads. A wrapper's own signature is (*args, **kwargs), and without functools.wraps that's all inspect.signature() reports for the decorated function. With it:

import functools
import inspect

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@logged
def area(width: float, height: float = 1.0) -> float:
    return width * height

print(inspect.signature(area))
print(inspect.signature(area, follow_wrapped=False))
print(area.__wrapped__(3, 2))
print(area.__wrapped__.__name__, area.__wrapped__ is area)

# ✅ Expected output:
# (width: float, height: float = 1.0) -> float
# (*args, **kwargs) -> float
# 6
# area False

wraps copies the original's name, qualified name, module, docstring and annotations onto the wrapper, and adds __wrapped__, which points at the original. inspect.signature() follows __wrapped__ and reports the original's parameters. With follow_wrapped=False it shows the wrapper's own (*args, **kwargs), plus the -> float it was given. area.__wrapped__ is the undecorated function, so calling it skips the wrapper, and it's a different object from area, which is the wrapper.

With decorators stacked, each __wrapped__ points one layer down, and inspect.unwrap() follows them all the way to the original. Introspection with inspect covers signature() in more depth.

wraps copies the signature even when it's no longer true. This decorator passes the first argument itself, so callers mustn't, but the signature still lists it:

import functools
import inspect

def with_user(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func("ada", *args, **kwargs)
    return wrapper

@with_user
def greet(user, greeting="Hello"):
    return greeting + ", " + user

print(inspect.signature(greet))
print(greet())
print(greet("Hi"))
greet("ada", "Hi")

# ✅ Expected output:
# (user, greeting='Hello')
# Hello, ada
# Hi, ada

# ✅ Expected error:
# TypeError: greet() takes from 1 to 2 positional arguments but 3 were given

A caller who trusts the signature passes "ada" as well, and the original receives three arguments. A wrapper that changes the parameters should say so. inspect.signature() uses a function's __signature__ attribute when it has one, and stops following __wrapped__ there. sig.replace(parameters=...) makes a copy of a signature with a different list of parameters:

import functools
import inspect

def with_user(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func("ada", *args, **kwargs)
    sig = inspect.signature(func)
    params = list(sig.parameters.values())[1:]
    wrapper.__signature__ = sig.replace(parameters=params)
    return wrapper

@with_user
def greet(user, greeting="Hello"):
    return greeting + ", " + user

print(inspect.signature(greet))
print(greet("Hi"))

# ✅ Expected output:
# (greeting='Hello')
# Hi, ada

wraps also copies the original's __dict__, the attributes stored on the function, and it does that once, when the decorator runs. An attribute that a lower decorator keeps changing goes stale in the layer above:

import functools

def count_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        wrapper.calls += 1
        return func(*args, **kwargs)
    wrapper.calls = 0
    return wrapper

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("calling", func.__name__)
        return func(*args, **kwargs)
    return wrapper

@logged
@count_calls
def ping():
    return "pong"

ping()
ping()
print(ping.calls)
print(ping.__wrapped__.calls)

# ✅ Expected output:
# calling ping
# calling ping
# 0
# 2

ping.calls is the copy logged made while the counter was 0. The counting happens on count_calls' own wrapper, which is ping.__wrapped__. With @count_calls on top instead, it's the outer layer, and ping.calls gives 2.

Decorators written as classes, and decorators on methods

A decorator can be a class. @CountCalls calls CountCalls(ping), and the object that makes replaces the function. The object needs a __call__ method, from Magic Methods & the Python Data Model, so it can be called as the function was, and it keeps its state in ordinary attributes. functools.update_wrapper(self, func) does for the object what @functools.wraps(func) does for a wrapper function; wraps is a shortcut for it.

import functools

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        return self.func(*args, **kwargs)

@CountCalls
def ping():
    return "pong"

print(ping(), ping())
print(ping.calls, ping.__name__, type(ping).__name__)

# ✅ Expected output:
# pong pong
# 2 ping CountCalls

On a function that works. On a method it doesn't:

import functools

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        return self.func(*args, **kwargs)

class Account:
    def __init__(self):
        self.balance = 0

    @CountCalls
    def deposit(self, amount):
        self.balance += amount
        return self.balance

acct = Account()
print(acct.deposit(10))

# ✅ Expected error:
# TypeError: Account.deposit() missing 1 required positional argument: 'amount'

A function written in a class body becomes a method because functions have a __get__ method: looking up acct.deposit calls it, and it returns a bound method that puts acct in front of the arguments. A CountCalls object has no __get__, so acct.deposit is the object itself, and the call passes just 10, which lands in self. Giving the class a __get__ fixes it. types.MethodType(self, obj) makes the bound method: calling it calls the CountCalls object with obj first. Looked up on the class itself, obj is None, and __get__ returns the object, counter and all:

import functools
import types

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        return self.func(*args, **kwargs)

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return types.MethodType(self, obj)

class Account:
    def __init__(self):
        self.balance = 0

    @CountCalls
    def deposit(self, amount):
        self.balance += amount
        return self.balance

a = Account()
b = Account()
print(a.deposit(10), a.deposit(5), b.deposit(1))
print(Account.deposit.calls)

# ✅ Expected output:
# 10 15 1
# 3

There's one CountCalls object, made when the class was, so its counter counts the calls of every account: 3. __get__ belongs to the descriptor protocol, which Properties & Descriptors covers. A decorator written as a function, like count_calls in Decorators & Advanced Features, needs none of this: it returns a function, and functions bind.

Where a decorator sits next to @classmethod matters too. Above it, the decorator receives a classmethod object rather than a function:

import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("calling", func.__name__)
        return func(*args, **kwargs)
    return wrapper

class Temperature:
    def __init__(self, celsius):
        self.celsius = celsius

    @logged
    @classmethod
    def from_fahrenheit(cls, f):
        return cls((f - 32) * 5 / 9)

print(Temperature.from_fahrenheit(212).celsius)

# ✅ Expected output:
# calling from_fahrenheit

# ✅ Expected error:
# TypeError: 'classmethod' object is not callable

The wrapper ran, printed its line and called what it had been given, but a classmethod object can't be called: looking it up on a class is what gives you something to call. Next to the def, below @classmethod, the decorator wraps the plain function, and @classmethod then wraps the wrapper:

import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("calling", func.__name__)
        return func(*args, **kwargs)
    return wrapper

class Temperature:
    def __init__(self, celsius):
        self.celsius = celsius

    @classmethod
    @logged
    def from_fahrenheit(cls, f):
        return cls((f - 32) * 5 / 9)

print(Temperature.from_fahrenheit(212).celsius)

# ✅ Expected output:
# calling from_fahrenheit
# 100.0

Above @staticmethod, the same decorator works only when the method is called on the class, because Python 3.10 made staticmethod objects callable. Called on an instance, it fails: the wrapper is a plain function in the class body, so it binds like any method, the instance arrives as an extra argument, and the call stops with a TypeError. Next to the def, under @staticmethod or @classmethod, the decorator works whether the method is called on the class or on an instance.

A decorator that checks arguments has one more problem with methods: self moves every argument along one place, and callers can pass any of them by name. inspect.signature(func).bind(*args, **kwargs) matches a call's arguments to the parameters the way Python does, so the check can ask for amount by name on a function and on a method alike:

import functools
import inspect

def positive(*names):
    def decorator(func):
        sig = inspect.signature(func)
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            bound = sig.bind(*args, **kwargs)
            for name in names:
                value = bound.arguments.get(name)
                if value is not None and value <= 0:
                    raise ValueError(f"{func.__name__}(): {name} must be positive, got {value}")
            return func(*args, **kwargs)
        return wrapper
    return decorator

@positive("amount")
def deposit(balance, amount):
    return balance + amount

class Account:
    def __init__(self):
        self.balance = 0

    @positive("amount")
    def deposit(self, amount):
        self.balance += amount
        return self.balance

print(deposit(10, amount=5), deposit(10, 5))
print(Account().deposit(7))
try:
    Account().deposit(amount=-2)
except ValueError as e:
    print(e)
deposit(10, 0)

# ✅ Expected output:
# 15 15
# 7
# deposit(): amount must be positive, got -2

# ✅ Expected error:
# ValueError: deposit(): amount must be positive, got 0

bound.arguments maps each parameter's name to the value it received, however it was passed. The signature is read once, when the decorator runs, not on every call.

Stacking order decides what each decorator sees

Decorators & Advanced Features gave the rule: the decorator nearest the def wraps first, and when the function is called the outermost wrapper runs first. In a library that decides what each decorator sees. functools.cache, which is lru_cache(maxsize=None), keeps every result. On top, it answers a repeated call before anything below it runs; underneath a logger, it only saves the work:

import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args):
        print("  computing", func.__name__, args)
        return func(*args)
    return wrapper

@functools.cache
@logged
def square(n):
    return n * n

@logged
@functools.cache
def cube(n):
    return n * n * n

print(square(3), square(3))
print(cube(3), cube(3))

# ✅ Expected output:
#   computing square (3,)
# 9 9
#   computing cube (3,)
#   computing cube (3,)
# 27 27

The second square(3) never reached logged. Both cube(3) calls did, and only the first reached the multiplication. The same goes for retries: a logger above retry sees one call, and below it, every attempt:

import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("log:", func.__name__)
        return func(*args, **kwargs)
    return wrapper

def retry(times=3):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except ConnectionError:
                    if attempt == times:
                        raise
        return wrapper
    return decorator

replies = ["timeout", "timeout", "ok"]

@logged
@retry(times=3)
def load():
    reply = replies.pop(0)
    if reply != "ok":
        raise ConnectionError(reply)
    return reply

print(load())
replies = ["timeout", "timeout", "ok"]

@retry(times=3)
@logged
def load2():
    reply = replies.pop(0)
    if reply != "ok":
        raise ConnectionError(reply)
    return reply

print(load2())

# ✅ Expected output:
# log: load
# ok
# log: load2
# log: load2
# log: load2
# ok

So a decorator that should run on every attempt goes below retry, and one that should run once per call goes above it.

Retry only what can work next time, and let the caller choose how to wait

The retry in Decorators & Advanced Features tried again straight away and caught only ConnectionError. In a library it's tempting to catch everything:

import functools

def retry(times=3):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    print(f"attempt {attempt} failed: {e!r}")
        return wrapper
    return decorator

@retry(times=3)
def total(prices):
    return sum(prices)

print(total(["2", "3"]))

# ✅ Expected output:
# attempt 1 failed: TypeError("unsupported operand type(s) for +: 'int' and 'str'")
# attempt 2 failed: TypeError("unsupported operand type(s) for +: 'int' and 'str'")
# attempt 3 failed: TypeError("unsupported operand type(s) for +: 'int' and 'str'")
# None

sum() starts from 0, and 0 + "2" is a bug that fails the same way every time. (!r prints the error's repr, its class and message.) Catching every Exception ran it three times, then the loop ended, and a function that ends without return gives None: the caller got a wrong answer instead of an error.

A library retry takes the errors worth retrying as an option, waits longer after each failure, and re-raises the last error. The waiting is the part that a test, or this page, can't afford, so the function that waits is a parameter too. It defaults to time.sleep, and the examples pass waits.append, which records each wait instead of waiting:

import functools
import time

def retry(times=3, delay=1.0, *, on=(ConnectionError,), sleep=time.sleep):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            wait = delay
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except on as e:
                    if attempt == times:
                        raise
                    print(f"attempt {attempt} failed: {e}; waiting {wait}s")
                    sleep(wait)
                    wait *= 2
        return wrapper
    return decorator

waits = []
replies = ["timeout", "timeout", "ok"]

@retry(times=3, delay=0.5, sleep=waits.append)
def load():
    reply = replies.pop(0)
    if reply != "ok":
        raise ConnectionError(reply)
    return "data"

print(load())
print(waits)

# ✅ Expected output:
# attempt 1 failed: timeout; waiting 0.5s
# attempt 2 failed: timeout; waiting 1.0s
# data
# [0.5, 1.0]

except on as e catches any of the error classes in the tuple on, and wait doubles after each failure. When every attempt fails, the last error goes to the caller, and an error that isn't in on isn't retried at all:

import functools
import time

def retry(times=3, delay=1.0, *, on=(ConnectionError,), sleep=time.sleep):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            wait = delay
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except on as e:
                    if attempt == times:
                        raise
                    print(f"attempt {attempt} failed: {e}; waiting {wait}s")
                    sleep(wait)
                    wait *= 2
        return wrapper
    return decorator

waits = []

@retry(times=3, delay=0.5, sleep=waits.append)
def load():
    raise ConnectionError("timeout")

try:
    load()
except ConnectionError as e:
    print("gave up:", e)
print(waits)

@retry(times=3, sleep=waits.append)
def total(prices):
    return sum(prices)

print(total(["2", "3"]))

# ✅ Expected output:
# attempt 1 failed: timeout; waiting 0.5s
# attempt 2 failed: timeout; waiting 1.0s
# gave up: timeout
# [0.5, 1.0]

# ✅ Expected error:
# TypeError: unsupported operand type(s) for +: 'int' and 'str'

Three attempts and two waits: nothing waits after the last attempt. The bare raise re-raises the error being handled, so the caller catches the original ConnectionError. The TypeError from total() went straight through on the first attempt, with its own message.

Deprecation warnings that point at the caller

When a library renames a function, the old name can stay for a while and warn whoever still calls it. warnings.warn(message, DeprecationWarning, stacklevel=2) does that, and stacklevel=2 makes the warning name the line that called the wrapper, the line the caller has to change. Warnings normally go to the error output. warnings.catch_warnings(record=True) collects them in a list instead, and warnings.simplefilter("always") inside it makes sure each one is kept, so the example can print them:

import functools
import warnings

def deprecated(instead):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            warnings.warn(
                f"{func.__name__}() is deprecated; use {instead}() instead",
                DeprecationWarning,
                stacklevel=2,
            )
            return func(*args, **kwargs)
        return wrapper
    return decorator

@deprecated("total")
def add_up(prices):
    return sum(prices)

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    print(add_up([2, 3]))

for w in caught:
    print(w.category.__name__, "-", w.message, "- line", w.lineno)

# ✅ Expected output:
# 5
# DeprecationWarning - add_up() is deprecated; use total() instead - line 23

Line 23 is print(add_up([2, 3])). With stacklevel=1, the default, the warning names the warnings.warn( line inside the wrapper instead, which tells the caller nothing.

In a library, stacklevel=1 can hide the warning altogether. Outside catch_warnings, Python's default filters show a DeprecationWarning only when the line it names is in __main__, the program you ran, and with stacklevel=1 that line is inside the library. The warnings Module covers filters and the rest of the module.

What a plain decorator does to an async def function

Calling an async def function doesn't run it: it returns a coroutine, which runs when it's awaited, as AsyncIO: Event Loop, Tasks & Futures showed. A plain wrapper calls the function, gets the coroutine back and returns it, all before the body has started:

import asyncio
import functools
import inspect

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("before", func.__name__)
        result = func(*args, **kwargs)
        print("after", func.__name__)
        return result
    return wrapper

@logged
async def download(n):
    print("downloading", n)
    await asyncio.sleep(0)
    return n * 2

print(inspect.iscoroutinefunction(download))

async def main():
    print(await download(21))

asyncio.run(main())

# ✅ Expected output:
# False
# before download
# after download
# downloading 21
# 42

Both of the wrapper's lines print before downloading 21, so a logger or timer written this way reports on nothing. And inspect.iscoroutinefunction(download) is False: download is now the wrapper, a plain function, so code that asks whether it has to await download gets the wrong answer. For the same reason, a try in the wrapper never sees the coroutine's errors:

import asyncio
import functools

def retry(times=3):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except ConnectionError as e:
                    print("attempt", attempt, "failed:", e)
        return wrapper
    return decorator

@retry(times=3)
async def download():
    raise ConnectionError("timeout")

async def main():
    try:
        await download()
    except ConnectionError as e:
        print("not retried:", e)

asyncio.run(main())

# ✅ Expected output:
# not retried: timeout

The error happened when main() awaited the coroutine, after the wrapper had returned. The fix is a second wrapper, written with async def, that awaits the function. The decorator picks it when it's given a coroutine function:

import asyncio
import functools
import inspect

def logged(func):
    if inspect.iscoroutinefunction(func):
        @functools.wraps(func)
        async def async_wrapper(*args, **kwargs):
            print("before", func.__name__)
            result = await func(*args, **kwargs)
            print("after", func.__name__)
            return result
        return async_wrapper

    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("before", func.__name__)
        result = func(*args, **kwargs)
        print("after", func.__name__)
        return result
    return wrapper

@logged
async def download(n):
    print("downloading", n)
    await asyncio.sleep(0)
    return n * 2

@logged
def double(n):
    return n * 2

print(inspect.iscoroutinefunction(download), inspect.iscoroutinefunction(double))
print(double(4))

async def main():
    print(await download(21))

asyncio.run(main())

# ✅ Expected output:
# True False
# before double
# after double
# 8
# before download
# downloading 21
# after download
# 42

Now after download comes after the body, and iscoroutinefunction() says True. Python 3.12 added inspect.markcoroutinefunction(), which marks a plain function as a coroutine function; 3.11 and this site's editor don't have it.

Registries: decorators that collect functions

A registering decorator stores the function somewhere and returns it unchanged, as the commands dictionary in Decorators & Advanced Features did. In a library the registry works better as an object: each program can make its own, and the decorator can refuse a name that's already taken.

class Registry:
    def __init__(self):
        self.items = {}

    def register(self, name):
        def decorator(func):
            if name in self.items:
                raise ValueError(f"{name!r} is already registered to {self.items[name].__name__}()")
            self.items[name] = func
            return func
        return decorator

    def run(self, name, *args):
        if name not in self.items:
            raise KeyError(f"no command {name!r}; choose from {sorted(self.items)}")
        return self.items[name](*args)

commands = Registry()

@commands.register("add")
def add(a, b):
    return a + b

@commands.register("neg")
def negate(a):
    return -a

print(sorted(commands.items))
print(commands.run("add", 2, 3), commands.run("neg", 4))
print(add(1, 1))

@commands.register("add")
def plus(a, b):
    return a + b

# ✅ Expected output:
# ['add', 'neg']
# 5 -4
# 2

# ✅ Expected error:
# ValueError: 'add' is already registered to add()

commands.register("add") returns the decorator, so @commands.register("add") is a decorator that takes an argument. add(1, 1) still works because the function came back unchanged. Without the check, the second "add" would have replaced the first without a word.

Registration happens when the decorator runs. That's when the def runs, which is when the module it's in is imported, so a plugin module that nothing imports registers nothing:

from pathlib import Path

Path("registry.py").write_text("""
handlers = {}

def handler(name):
    def decorator(func):
        handlers[name] = func
        return func
    return decorator
""", encoding="utf-8")
Path("email_plugin.py").write_text("""
from registry import handler

@handler("email")
def send_email(to):
    return "email to " + to
""", encoding="utf-8")

import registry
print(sorted(registry.handlers))
import email_plugin
print(sorted(registry.handlers))
print(registry.handlers["email"]("[email protected]"))

# ✅ Expected output:
# []
# ['email']
# email to [email protected]

A program that collects plugins this way has to import every plugin module, for example from a list of their names, before it looks in the registry.

The decorators as a package

A decorator file copied into each project has to be fixed in each copy. A package gives the decorators one home: a module for each decorator or group of them, and an __init__.py that imports the public names and lists them in __all__, as Module & Package Architecture for Large Codebases laid out. For this lesson's decorators:

decorlib/
├── __init__.py
├── deprecation.py
├── registry.py
└── retrying.py
tests/
└── test_retrying.py

This example writes the package with retrying.py in it, the way Modules and Packages wrote its files, and uses it:

from pathlib import Path

Path("decorlib").mkdir(exist_ok=True)
Path("decorlib/retrying.py").write_text("""
import functools
import time

def retry(times=3, delay=1.0, *, on=(ConnectionError,), sleep=time.sleep):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            wait = delay
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except on:
                    if attempt == times:
                        raise
                    sleep(wait)
                    wait *= 2
        return wrapper
    return decorator
""", encoding="utf-8")
Path("decorlib/__init__.py").write_text("""
from .retrying import retry

__all__ = ["retry"]
""", encoding="utf-8")

from decorlib import retry

waits = []
replies = ["timeout", "ok"]

@retry(times=2, sleep=waits.append)
def load():
    reply = replies.pop(0)
    if reply != "ok":
        raise ConnectionError(reply)
    return "data"

print(load(), waits)
print(load.__module__, load.__qualname__)
print(retry.__module__)

# ✅ Expected output:
# data [1.0]
# __main__ load
# decorlib.retrying

retry lives in decorlib.retrying, but users write from decorlib import retry, so the modules inside can be rearranged later without breaking anyone's imports. The decorated load still says __main__, the module it was written in, because wraps copied the original's __module__: it looks like the user's function, not part of the library. Packaging & Publishing Python Libraries to PyPI turns a package like this into something pip installs.

Testing the decorators with pytest

A library's decorators get tests of their own, one for each promise: what's retried, what isn't, how long it waits, and that the name survives. Because retry takes sleep as a parameter, the tests pass waits.append and finish at once. This example writes decorlib and tests/test_retrying.py where the tree above puts them, and the test file imports retry from the package, as a user would. The lines after the test file are the harness from Testing with pytest: Fixtures, Parametrisation & Mocks, which prints a line for each test:

flaky(2) makes a new function that fails twice and then works, so no test depends on what another one left behind. test_keeps_the_name also calls load.__wrapped__(), the undecorated function: that's how a test checks a decorated function's own work with the decorator out of the way.

Practice: finish a tag decorator that takes an optional name

Fill in the three blanks so that tag works both as @tag and as @tag(name="i"), and the decorated functions keep their names and docstrings. The hint lines under the code give the answers, one per blank, in order.

import functools

def tag(func=None, *, name="b"):
    if func is ___:
        return functools.partial(tag, name=name)
    @functools.___(func)
    def wrapper(*args, **kwargs):
        return f"<{name}>{func(*args, **kwargs)}</{name}>"
    return wrapper

@tag
def greet(who):
    """Say hi."""
    return "hi " + who

@tag(___="i")
def shout(who):
    return "HI " + who

print(greet("Ada"))
print(shout("Ada"))
print(greet.__name__, "-", greet.__doc__)

# 👉 replace ___ with None
# 👉 replace ___ with wraps
# 👉 replace ___ with name

# ✅ Expected output:
# <b>hi Ada</b>
# <i>HI Ada</i>
# greet - Say hi.

On your own: a retry that works with or without options

Write retry so it works both bare, as @retry, and with options given by name, as @retry(times=2, sleep=waits.append). It calls the function up to times times (3 unless told otherwise) while it raises one of the errors in on (ConnectionError unless told otherwise), calls sleep(1), sleep(2), sleep(4) and so on between attempts, re-raises the last error, and keeps the function's name. sleep defaults to time.sleep. Try it on a load() that fails twice, on an always_down() with times=2, and as a bare @retry on a parse() that raises ValueError; pass waits.append wherever a wait could happen.

import functools
import time

def retry(func=None, *, times=3, on=(ConnectionError,), sleep=time.sleep):
    if func is None:
        return functools.partial(retry, times=times, on=on, sleep=sleep)

    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        wait = 1
        for attempt in range(1, times + 1):
            try:
                return func(*args, **kwargs)
            except on:
                if attempt == times:
                    raise
                sleep(wait)
                wait *= 2
    return wrapper

waits = []
replies = ["timeout", "timeout", "data"]

@retry(sleep=waits.append)
def load():
    reply = replies.pop(0)
    if reply == "timeout":
        raise ConnectionError(reply)
    return reply

print(load(), waits)

waits.clear()

@retry(times=2, sleep=waits.append)
def always_down():
    raise ConnectionError("timeout")

try:
    always_down()
except ConnectionError as e:
    print("gave up:", e, waits)

calls = []

@retry
def parse(text):
    calls.append(text)
    return int(text)

try:
    parse("ten")
except ValueError as e:
    print("calls:", len(calls), "-", type(e).__name__)
print(load.__name__, always_down.__name__, parse.__name__)

# ✅ Expected output:
# data [1, 2]
# gave up: timeout [1]
# calls: 1 - ValueError
# load always_down parse

Practice quiz

shout(func=None, *, times=1) returns functools.partial(shout, times=times) when func is None, and otherwise a wrapper made with functools.wraps(func). @shout(2) sits above def cheer(name): return "go " + name, and the program then runs print(cheer("Ada")). What happens?

  • It prints GO ADA!GO ADA!
  • It prints GO ADA!
  • It stops while the def runs, with TypeError: 'int' object is not callable, and prints nothing
  • It stops with TypeError: shout() takes 0 positional arguments but 1 was given

Answer: It stops while the def runs, with TypeError: 'int' object is not callable, and prints nothing. Given without its name, 2 arrives as func. It isn't None, so shout(2) returns a wrapper around 2 at once, and Python then calls that wrapper with cheer, which runs 2(cheer). Written as @shout(times=2), it prints GO ADA!GO ADA!

logged's wrapper takes (*args, **kwargs) and is made with @functools.wraps(func). It decorates def area(width: float, height: float = 1.0) -> float. What does print(inspect.signature(area)) show?

  • (*args, **kwargs)
  • (width: float, height: float = 1.0) -> float
  • (*args, **kwargs) -> float
  • It stops with a ValueError

Answer: (width: float, height: float = 1.0) -> float. wraps gives the wrapper a __wrapped__ attribute that points at the original, and inspect.signature() follows it. With follow_wrapped=False you'd see the wrapper's own (*args, **kwargs) -> float.

count_calls keeps a counter in wrapper.calls, set to 0, and adds 1 on every call. logged is a plain wrapper. Both use functools.wraps, and @logged sits above @count_calls on def ping(). After two calls to ping(), what does print(ping.calls) show?

  • 2
  • It stops with AttributeError
  • 1
  • 0

Answer: 0. wraps copied the inner wrapper's __dict__, with calls = 0, onto logged's wrapper once, when the decorators ran. The counting happens on count_calls' own wrapper, ping.__wrapped__, whose calls is 2.

class CountCalls stores func in __init__, and its __call__(self, *args, **kwargs) returns self.func(*args, **kwargs). @CountCalls decorates def deposit(self, amount) inside class Account. What does Account().deposit(10) do?

  • It returns 10
  • It stops with TypeError: 'CountCalls' object is not callable
  • It stops with TypeError: Account.deposit() missing 1 required positional argument: 'amount'
  • It returns 1

Answer: It stops with TypeError: Account.deposit() missing 1 required positional argument: 'amount'. A CountCalls object has no __get__ method, so looking it up on an account doesn't bind it: the object is called with 10 alone, and 10 becomes deposit's self. A __get__ that returns types.MethodType(self, obj) fixes it.

retry(times=3)'s wrapper catches every Exception, prints "attempt N failed:" with the error, and tries again. Nothing follows the loop. It decorates def total(prices): return sum(prices). What does print(total(["2", "3"])) show?

  • Three attempt lines with the same TypeError, then None
  • One attempt line, then the TypeError stops the program
  • One attempt line, then 5
  • 23

Answer: Three attempt lines with the same TypeError, then None. sum() starts from 0, and 0 + "2" raises the same TypeError every time: a bug no retry can fix. After the third attempt the loop ends, and a function that ends without return gives None.

logged's plain def wrapper prints "before", calls func, prints "after" and returns the result. It decorates async def download(n), which prints "downloading" and n, awaits asyncio.sleep(0) and returns n * 2. Inside main(), run with asyncio.run(main()), what does print(await download(21)) show?

  • before download, downloading 21, after download, 42
  • downloading 21, before download, after download, 42
  • before download, after download, 42
  • before download, after download, downloading 21, 42

Answer: before download, after download, downloading 21, 42. Calling an async def function only makes a coroutine; its body runs when it's awaited. The wrapper prints both its lines and returns the coroutine, and await then runs download's body.

logged prints "computing" with the function's name and arguments before it calls the function. @functools.cache sits above @logged on def square(n): return n * n. What does print(square(3), square(3)) show?

  • computing square (3,) twice, then 9 9
  • computing square (3,) once, then 9 9
  • 9 9 only
  • computing square (3,), 9, computing square (3,), 9

Answer: computing square (3,) once, then 9 9. The cache is the outer layer, so the second square(3) is answered from it without reaching logged. With @logged above @functools.cache, logged runs on both calls and prints computing twice.

registry.py holds handlers = {} and a handler(name) decorator that stores the function in handlers and returns it. email_plugin.py puts @handler("email") on def send_email(to). A program runs import registry and print(sorted(registry.handlers)), and never imports email_plugin. What does it print?

  • []
  • ['email']
  • ['send_email']
  • It stops with KeyError: 'email'

Answer: []. A decorator runs when the def under it runs, and email_plugin's def runs only when something imports email_plugin. After import email_plugin, the same line prints ['email'].

Continue this course

Frequently asked questions

How do I type a decorator so editors and mypy still see the parameters?

With ParamSpec from the typing module, which is there on Python 3.10 to 3.14 and in this site's editor. Write P = ParamSpec("P") and R = TypeVar("R"), annotate the decorator as def logged(func: Callable[P, R]) -> Callable[P, R], with Callable from collections.abc, and give the wrapper *args: P.args, **kwargs: P.kwargs and -> R. Measured with mypy 1.19.1 on Python 3.11: with an unannotated logged, mypy took the decorated area to be Any and said nothing about area("3", 4); with the ParamSpec version it reported Argument 1 to "area" has incompatible type "str"; expected "float". Type Hints & Static Typing with mypy covers mypy and Callable, and Advanced Type Hints (Generics, Protocol, TypedDict) covers TypeVar.

Does Python come with a @deprecated decorator?

From Python 3.13, yes: warnings.deprecated(message). Python's documentation says it emits a DeprecationWarning when the decorated function is called, and that static type checkers will also flag uses of it. It isn't there on 3.10 to 3.12 or in this site's editor, where hasattr(warnings, "deprecated") is False. A library that supports those versions writes its own, like the one in this lesson, or uses typing_extensions.deprecated from the typing_extensions package on PyPI, which gives the same DeprecationWarning on 3.10 to 3.12. The warnings Module covers the module in full.

Why give retry a sleep parameter instead of patching time.sleep in the tests?

A default such as sleep=time.sleep is looked up once, when the def line runs, so patching time.sleep afterwards doesn't reach it. Measured: with that default, setting time.sleep to a list's append after retry was defined left retry calling the original time.sleep, and the list stayed empty. A retry that looked time.sleep up on every call could be patched, but the patch would change sleep for any other code running at the time. A parameter keeps the fake to the one decorator. Testing with pytest: Fixtures, Parametrisation & Mocks shows patch and monkeypatch, and why a name is patched where it's looked up.

How do I put a decorator on every method of a class?

With a decorator for the class: it receives the class, wraps each function it finds there, puts the wrapper back with setattr(), and returns the class. Metaprogramming & Introspection with inspect covers decorators that take and return a class.

What exactly does functools.wraps copy?

The attributes named in functools.WRAPPER_ASSIGNMENTS, then the original's __dict__, and then it adds __wrapped__. The list depends on the version: on 3.10 and 3.11, and in this site's editor, it's __module__, __name__, __qualname__, __doc__ and __annotations__; 3.12 and 3.13 add __type_params__; and 3.14 has __annotate__ in place of __annotations__, part of its new way of storing annotations. Python's documentation says an attribute the original doesn't have is skipped, which is why wrapping the number 2 in this lesson raised no error until something called it.

Related lessons