Step-by-Step Guide to Python Decorators with Practical Examples

Example 1 The "Auto-String" Injector

Instead of writing __repr__ for every class, we can use a decorator to inject it automatically.

def add_repr(original_class):
    # 1. Define the new method
    def custom_repr(self):
        attrs = ', '.join(
            f"{k}={v!r}" for k, v in self.__dict__.items()
        )
        return f"{original_class.__name__}({attrs})"
    
    # 2. Attach it to the class
    original_class.__repr__ = custom_repr
    
    # 3. Return the modified class
    return original_class

@add_repr
class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

p = Person("Alice", 30)
print(p) # Output: Person(name='Alice', age=30)

Example 2 The Singleton Factory

This is a powerful pattern: ensuring only one instance of a class ever exists (e.g., a Database Connection).

def singleton(original_class):
    instances = {}
    
    def get_instance(*args, **kwargs):
        if original_class not in instances:
            # Create the one and only instance
            instances[original_class] = original_class(*args, **kwargs)
        return instances[original_class]
    
    # Return the factory function, not the class!
    return get_instance

@singleton
class Database:
    def __init__(self):
        print("Connecting...")

db1 = Database()
db2 = Database() # Does NOT print "Connecting..." again
print(db1 is db2) # True

Step-by-Step Construction

Let's build a logging decorator from scratch, incorporating the best practices from earlier sections.

1. Define the decorator function. It must accept the original function as its argument.
2. Inside, define the wrapper function. Use *args, **kwargs so it can forward any arguments to the original function. This makes your decorator universal.
3. Add your logging calls before and after calling original_func(*args, **kwargs).
4. Return the result from original_func so the decorated function's return value isn't lost.
5. Apply @wraps to preserve the original function's name and docstring.
6. Return the wrapper from the decorator. (Don't forget this!)

Testing the Decorator

Apply it to a simple function and observe:

@log_call
def greet(name):
    """Returns a greeting string."""
    return f"Hello, {name}!"

print(greet("Alice"))

Misconception: Decorators Are Only for Functions

While we mostly use them on functions, classes can be decorated too. A class decorator receives the class object itself at definition time. It can modify the class, add methods, or even replace it entirely.

Pitfall 1 The "Tower of Babel" (Overuse)

Stacking too many decorators creates a "decoration tower." You have to mentally unwrap every layer to understand what the function actually does.

Pitfall 2 Ignoring Argument Preservation

The most common bug is writing a wrapper that accepts no arguments, then trying to use it on a function that does take arguments.

Example The Execution Order

When you stack decorators, Python effectively does this: my_func = outer(inner(my_func)).

@outer_decorator
@inner_decorator
def greet():
    print("Hello!")

# When called:
print("Calling...")
greet()

Example Parameterized Decorators with Defaults

Real-world decorators often need configuration. We can pass arguments to the decorator factory, and set defaults so it's flexible.

def repeat(times=1, catch_exceptions=False):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            results = []
            for _ in range(times):
                try:
                    results.append(func(*args, **kwargs))
                except Exception:
                    if catch_exceptions:
                        results.append(None)
                    else:
                        raise
            return results
        return wrapper
    return decorator

Example Class Decorators & State

Class decorators can modify the class itself. This is great for registration patterns or adding shared state (like an instance counter) to every class in a hierarchy.

def register_subclass(cls):
    # Add to global registry
    registry[cls.__name__] = cls
    
    # Add class-level state
    cls._instance_count = 0
    
    # Wrap __init__ to count instances
    original_init = cls.__init__
    def counting_init(self, *args, **kwargs):
        original_init(self, *args, **kwargs)
        cls._instance_count += 1
    
    cls.__init__ = counting_init
    return cls

@register_subclass
class Animal: ...