Decorators, Protocols & Metaprogramming

Decorators are functions that take another function as an argument, augment its behavior, and return a new function. They are the foundation of authentication guards, caching layers, rate limiters, and telemetry tracking in modern web frameworks.

@log_calls
def greet(): ...

# is EXACTLY:
def greet(): ...
greet = log_calls(greet)

Python's historic motto has always been "If it walks like a duck and quacks like a duck, it is a duck". With PEP 544 (typing.Protocol), Python introduced structural subtyping. You can define an interface, and any class that implements the required methods satisfies the type checker—without needing to inherit from a rigid base class!

from typing import Protocol

class StorageBackend(Protocol):
    """Any object with these 3 methods satisfies this type!"""
    def read(self, key: str) -> bytes: ...
    def write(self, key: str, data: bytes) -> None: ...
    def delete(self, key: str) -> None: ...

def backup_database(storage: StorageBackend) -> None:
    # Completely decoupled from concrete AWS or disk classes!
    storage.write("backup.sql", b"DATA")

class S3BlobStorage:
    # Notice: ZERO inheritance from StorageBackend!
    def read(self, key: str) -> bytes:
        return s3_client.get_object(Key=key)["Body"].read()

    def write(self, key: str, data: bytes) -> None:
        s3_client.put_object(Key=key, Body=data)

    def delete(self, key: str) -> None:
        s3_client.delete_object(Key=key)

from abc import ABC, abstractmethod

class BaseStorage(ABC):
    @abstractmethod
    def read(self): ...

# MUST explicitly inherit:
class S3(BaseStorage):
    def read(self): ...

from typing import Protocol

class Storage(Protocol):
    def read(self) -> bytes: ...

# Zero inheritance required!
class S3:
    def read(self) -> bytes: ...

Have you ever wondered how @property works, or how Pydantic validates fields, or how SQLAlchemy maps database columns to class attributes? The answer is Descriptors: objects that define any of __get__, __set__, or __set_name__.

class PositiveInt:
    def __set_name__(self, owner, name):
        self.storage_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return getattr(instance, self.storage_name, 0)

    def __set__(self, instance, value):
        if not isinstance(value, int) or value <= 0:
            raise ValueError(f"'{self.storage_name}' must be > 0")
        setattr(instance, self.storage_name, value)

class Product:
    price = PositiveInt()  # Descriptor instance on class

Writing a class with __enter__ and __exit__ can be verbose. The standard library's @contextlib.contextmanager decorator allows you to turn a simple generator function into a bulletproof context manager using a try / yield / finally block.

from contextlib import contextmanager

@contextmanager
def db_transaction(db_pool):
    # 1. SETUP (Before yield)
    conn = db_pool.acquire()
    print("BEGIN TRANSACTION")
    try:
        # 2. YIELD to with body
        yield conn
        # 4a. SUCCESS COMMIT
        conn.commit()
    except Exception:
        # 4b. ROLLBACK ON ERROR
        conn.rollback()
        raise
    finally:
        # 4c. GUARANTEED CLEANUP
        conn.close()

Metaprogramming gives you the ability to reshape Python's syntax and execution model. Review the four most common pitfalls before building framework-level code.

def my_decorator(fn):
    def wrapper(*args, **kwargs):
        return fn(*args, **kwargs)
    return wrapper

@my_decorator
def calculate_vat():
    """Calculates EU VAT."""
    pass

print(calculate_vat.__name__)  # Prints 'wrapper'!
print(calculate_vat.__doc__)   # Prints None! Breaks documentation generators!

from functools import wraps

def my_decorator(fn):
    @wraps(fn)  # Copies __name__, __doc__, and annotations!
    def wrapper(*args, **kwargs):
        return fn(*args, **kwargs)
    return wrapper

print(calculate_vat.__name__)  # 'calculate_vat'
print(calculate_vat.__doc__)   # 'Calculates EU VAT.'

Test your understanding of decorator lifecycles, structural protocols, descriptor attribute binding, and contextlib exception handling. Score 5/5 to complete the entire Python Mastery Series!

def announce(func):
    def wrapper(*args, **kwargs):
        print("Calling", func.__name__)
        return func(*args, **kwargs)
    return wrapper

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

print(greet("Ada"))

1def announce(func):
2    def wrapper(*args, **kwargs):
3        print("Calling", func.__name__)
4        return func(*args, **kwargs)
5    return wrapper
6 
7@announce
8def greet(name):
9    return f"Hello, {name}!"
10 
11print(greet("Ada"))

Run the code to see its output.

Run and experiment with the full metaprogramming framework in the Python Playground (code preloaded).

• Higher-Order Decorators: Wrap function execution cleanly; always decorate your inner wrapper with @functools.wraps.
• Import vs Call Time: Remember that outer decorator code runs once on import; wrapper code runs on invocation.
• typing.Protocol: Leverage modern static duck typing to decouple interfaces from concrete implementations.
• Descriptors: Use __get__, __set__, and __set_name__ to build reusable attribute validators and ORM fields.
• @contextmanager: Use generators with try ... yield ... finally to guarantee resource cleanup.