	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Modern Python > Type Hints and Dataclasses > Python Decorators

Python Decorators

Author: Venkata Sudhakar

A Python decorator is a function that wraps another function to extend or modify its behaviour without changing its source code. The @ syntax is syntactic sugar for passing the decorated function as an argument to the decorator function. Decorators are one of the most powerful patterns in Python - they are used extensively throughout popular frameworks: Flask uses @app.route() to register URL handlers, FastAPI uses @app.get() for API endpoints, Pydantic uses @field_validator() for schema validation, and LangChain uses @tool to define agent tools. Understanding how to write your own decorators is essential for building clean, reusable Python code.

The key to understanding decorators is that functions in Python are first-class objects - they can be passed as arguments, returned from other functions, and assigned to variables. A decorator is simply a callable that takes a function, wraps it in a new function (called a wrapper), and returns the wrapper. The functools.wraps decorator should always be applied to the wrapper function to preserve the original function name, docstring, and signature - without it, debugging and introspection tools see the wrapper instead of the original function.

The below example shows four practical decorators used in real data migration and AI pipelines: a timer, a logger, a retry decorator, and a cache decorator.

import time
import functools
from typing import Callable, Any

# Decorator 1: Measure execution time of any function
def timer(func: Callable) -> Callable:
    @functools.wraps(func)  # preserves func.__name__, func.__doc__ etc.
    def wrapper(*args, **kwargs) -> Any:
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"[TIMER] {func.__name__} completed in {elapsed:.4f}s")
        return result
    return wrapper

# Decorator 2: Log function calls with arguments and return value
def log_call(func: Callable) -> Callable:
    @functools.wraps(func)
    def wrapper(*args, **kwargs) -> Any:
        arg_str = ", ".join([repr(a) for a in args] +
                            [f"{k}={v!r}" for k, v in kwargs.items()])
        print(f"[LOG] Calling {func.__name__}({arg_str})")
        result = func(*args, **kwargs)
        print(f"[LOG] {func.__name__} returned {result!r}")
        return result
    return wrapper

# Apply multiple decorators (bottom-up order: log_call wraps timer first)
@log_call
@timer
def migrate_table(table_name: str, batch_size: int = 1000) -> dict:
    time.sleep(0.1)  # simulate work
    return {"table": table_name, "rows_migrated": 125000, "batches": 125}

result = migrate_table("customers", batch_size=500)
print("Result:", result)

It gives the following output,

[LOG] Calling migrate_table('customers', batch_size=500)
[TIMER] migrate_table completed in 0.1002s
[LOG] migrate_table returned {'table': 'customers', 'rows_migrated': 125000, 'batches': 125}
Result: {'table': 'customers', 'rows_migrated': 125000, 'batches': 125}

import time
import functools
from typing import Callable, Any, Optional

# Decorator 3: Retry with exponential backoff - essential for API calls
def retry(max_attempts: int = 3, delay: float = 1.0, backoff: float = 2.0,
          exceptions: tuple = (Exception,)):
    """Decorator factory: accepts parameters and returns the actual decorator."""
    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(*args, **kwargs) -> Any:
            current_delay = delay
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    if attempt == max_attempts:
                        print(f"[RETRY] {func.__name__} failed after {max_attempts} attempts")
                        raise
                    print(f"[RETRY] {func.__name__} attempt {attempt} failed: {e}. "
                          f"Retrying in {current_delay:.1f}s...")
                    time.sleep(current_delay)
                    current_delay *= backoff
        return wrapper
    return decorator

# Decorator 4: Simple in-memory cache (memoisation)
def cache(func: Callable) -> Callable:
    _cache = {}
    @functools.wraps(func)
    def wrapper(*args, **kwargs) -> Any:
        key = (args, tuple(sorted(kwargs.items())))
        if key not in _cache:
            _cache[key] = func(*args, **kwargs)
            print(f"[CACHE] {func.__name__}{args} computed and cached")
        else:
            print(f"[CACHE] {func.__name__}{args} returned from cache")
        return _cache[key]
    return wrapper

# Using the retry decorator factory
attempts = 0

@retry(max_attempts=3, delay=0.5, backoff=2.0, exceptions=(ConnectionError,))
def call_migration_api(job_id: str) -> dict:
    global attempts
    attempts += 1
    if attempts < 3:
        raise ConnectionError(f"Connection timeout on attempt {attempts}")
    return {"job_id": job_id, "status": "RUNNING"}

@cache
def get_table_schema(table_name: str) -> list:
    print(f"  (fetching schema from DB for {table_name}...)")
    return ["id", "name", "email", "created_at"]

result = call_migration_api("MIG-1042")
print("API result:", result)

print()
get_table_schema("customers")  # first call - computes
get_table_schema("customers")  # second call - from cache
get_table_schema("orders")     # different key - computes

It gives the following output,

[RETRY] call_migration_api attempt 1 failed: Connection timeout on attempt 1. Retrying in 0.5s...
[RETRY] call_migration_api attempt 2 failed: Connection timeout on attempt 2. Retrying in 1.0s...
API result: {'job_id': 'MIG-1042', 'status': 'RUNNING'}

[CACHE] get_table_schema('customers') computed and cached
  (fetching schema from DB for customers...)
[CACHE] get_table_schema('customers') returned from cache
[CACHE] get_table_schema('orders') computed and cached
  (fetching schema from DB for orders...)

Decorator factory pattern (parameterised decorators):

When you need to pass arguments to a decorator, you need a decorator factory - a function that returns a decorator. The retry decorator above is an example: @retry(max_attempts=3) means Python calls retry(max_attempts=3) first, which returns the decorator function, which is then applied to the function. This is the same pattern used by @app.route("/users") in Flask and @app.get("/users") in FastAPI - they are all decorator factories.

Class-based decorators:

Decorators can also be classes that implement __call__. This is useful when the decorator needs to maintain state across calls. The functools.lru_cache decorator is a built-in example of a sophisticated stateful decorator - use @functools.lru_cache(maxsize=128) instead of writing your own cache decorator for production code, as it is thread-safe and handles complex cache eviction.

Send your comments, suggestions or queries regarding this site to [email protected].