Python: Writing Your Own Decorators for Reusable Function Modifications

Python decorators are one of the most powerful and elegant features of the language, allowing you to modify or enhance functions and classes without permanently altering their structure. This comprehensive guide will teach you how to write custom decorators that make your code more modular, reusable, and maintainable.

Table Of Contents

• What Are Python Decorators?
  • Core Concept
  • Decorator Categories
• Understanding Decorator Syntax
  • The @ Symbol (Syntactic Sugar)
  • Multiple Decorators
• Types of Decorators
  • 1. Simple Function Decorators
  • 2. Decorators with Arguments
  • 3. Class-Based Decorators
• Writing Basic Function Decorators
  • Template for Basic Decorators
  • Essential Components
  • Practical Examples
    • 1. Logging Decorator
    • 2. Caching Decorator
• Advanced Decorator Patterns
  • 1. Decorator with Optional Arguments
  • 2. Retry Decorator
  • 3. Rate Limiting Decorator
• Parameterized Decorators
  • Pattern for Parameterized Decorators
  • Real-World Example: Permissions Decorator
• Class-Based Decorators
  • When to Use Class-Based Decorators
  • Advanced Class-Based Example
• Performance Analysis
  • Decorator Overhead Comparison
  • Performance Results
• Real-World Use Cases
  • 1. API Authentication Decorator
  • 2. Database Transaction Decorator
  • 3. Async Decorator with Circuit Breaker
• Best Practices and Common Pitfalls
  • Best Practices
    • 1. Always Use functools.wraps
    • 2. Handle Arguments Properly
    • 3. Consider Performance Impact
  • Common Pitfalls
    • 1. Forgetting to Return the Result
    • 2. Mutable Default Arguments in Decorator Factories
    • 3. Not Handling Exceptions Properly
  • Decorator Testing Strategies
• Frequently Asked Questions
  • Q1: When should I use a decorator vs a regular function?
  • Q2: How do I debug decorated functions?
  • Q3: Can I apply multiple decorators to the same function?
  • Q4: How do I create a decorator that works with both sync and async functions?
  • Q5: How do I pass arguments to the original function from my decorator?
  • Q6: How do I make a decorator that modifies the return value?
  • Q7: What's the difference between function-based and class-based decorators?
  • Q8: How do I create a decorator that only runs in certain conditions?
• Conclusion
  • Key Takeaways
  • Advanced Applications

What Are Python Decorators?

A decorator is a design pattern that allows you to modify the behavior of a function or class without permanently modifying its code. Decorators are implemented as higher-order functions that take another function as an argument and extend its behavior.

Core Concept

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

def add_enthusiasm(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result + " 🎉"
    return wrapper

greet = add_enthusiasm(greet)
print(greet("Alice"))  # Hello, Alice! 🎉

# With decorator syntax
@add_enthusiasm
def greet(name):
    return f"Hello, {name}!"

print(greet("Bob"))  # Hello, Bob! 🎉

Decorator Categories

Understanding Decorator Syntax

The @ Symbol (Syntactic Sugar)

The @ symbol is syntactic sugar that makes decorator application more readable:

# These are equivalent:

# Method 1: Manual application
def my_function():
    pass
my_function = my_decorator(my_function)

# Method 2: Decorator syntax
@my_decorator
def my_function():
    pass

Multiple Decorators

Decorators can be stacked, and they're applied from bottom to top:

@decorator_a
@decorator_b
@decorator_c
def function():
    pass

# Equivalent to:
# function = decorator_a(decorator_b(decorator_c(function)))

Types of Decorators

1. Simple Function Decorators

import functools
import time

def timer(func):
    """Measure function execution time"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start_time = time.perf_counter()
        result = func(*args, **kwargs)
        end_time = time.perf_counter()
        print(f"{func.__name__} took {end_time - start_time:.4f} seconds")
        return result
    return wrapper

@timer
def slow_function():
    time.sleep(1)
    return "Done!"

slow_function()  # slow_function took 1.0012 seconds

2. Decorators with Arguments

def repeat(times):
    """Repeat function execution multiple times"""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            results = []
            for i in range(times):
                result = func(*args, **kwargs)
                results.append(result)
            return results
        return wrapper
    return decorator

@repeat(3)
def get_random_number():
    import random
    return random.randint(1, 100)

print(get_random_number())  # [42, 17, 83]

3. Class-Based Decorators

class CountCalls:
    """Count how many times a function is called"""
    
    def __init__(self, func):
        self.func = func
        self.count = 0
        functools.update_wrapper(self, func)
    
    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.func.__name__} called {self.count} times")
        return self.func(*args, **kwargs)

@CountCalls
def say_hello(name):
    return f"Hello, {name}!"

say_hello("Alice")  # say_hello called 1 times
say_hello("Bob")    # say_hello called 2 times

Writing Basic Function Decorators

Template for Basic Decorators

import functools

def my_decorator(func):
    """Basic decorator template"""
    
    @functools.wraps(func)  # Preserves original function metadata
    def wrapper(*args, **kwargs):
        # Code to execute before the function
        print(f"Calling {func.__name__}")
        
        # Call the original function
        result = func(*args, **kwargs)
        
        # Code to execute after the function
        print(f"Finished {func.__name__}")
        
        return result
    
    return wrapper

Essential Components

Practical Examples

1. Logging Decorator

import functools
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def log_calls(func):
    """Log function calls with arguments and results"""
    
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # Log function call
        args_str = ', '.join(map(str, args))
        kwargs_str = ', '.join(f"{k}={v}" for k, v in kwargs.items())
        all_args = ', '.join(filter(None, [args_str, kwargs_str]))
        
        logger.info(f"Calling {func.__name__}({all_args})")
        
        try:
            result = func(*args, **kwargs)
            logger.info(f"{func.__name__} returned: {result}")
            return result
        except Exception as e:
            logger.error(f"{func.__name__} raised {type(e).__name__}: {e}")
            raise
    
    return wrapper

@log_calls
def divide(a, b):
    return a / b

divide(10, 2)  # INFO: Calling divide(10, 2)
               # INFO: divide returned: 5.0

2. Caching Decorator

import functools

def simple_cache(func):
    """Basic caching decorator using a dictionary"""
    cache = {}
    
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # Create cache key from arguments
        key = str(args) + str(sorted(kwargs.items()))
        
        if key in cache:
            print(f"Cache hit for {func.__name__}")
            return cache[key]
        
        print(f"Cache miss for {func.__name__}")
        result = func(*args, **kwargs)
        cache[key] = result
        return result
    
    return wrapper

@simple_cache
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))  # Much faster due to caching

Advanced Decorator Patterns

1. Decorator with Optional Arguments

import functools

def validate_types(*expected_types, **expected_kwargs):
    """Validate function argument types"""
    
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # Validate positional arguments
            for i, (arg, expected_type) in enumerate(zip(args, expected_types)):
                if not isinstance(arg, expected_type):
                    raise TypeError(
                        f"Argument {i} must be {expected_type.__name__}, "
                        f"got {type(arg).__name__}"
                    )
            
            # Validate keyword arguments
            for name, expected_type in expected_kwargs.items():
                if name in kwargs and not isinstance(kwargs[name], expected_type):
                    raise TypeError(
                        f"Argument '{name}' must be {expected_type.__name__}, "
                        f"got {type(kwargs[name]).__name__}"
                    )
            
            return func(*args, **kwargs)
        return wrapper
    
    return decorator

@validate_types(str, int, age=int)
def create_user(name, user_id, age=None):
    return f"User: {name}, ID: {user_id}, Age: {age}"

# Valid calls
create_user("Alice", 123, age=25)

# Invalid calls will raise TypeError
# create_user(123, "invalid")  # TypeError

2. Retry Decorator

import functools
import time
import random

def retry(max_attempts=3, delay=1, backoff=2, exceptions=(Exception,)):
    """Retry decorator with exponential backoff"""
    
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            attempts = 0
            current_delay = delay
            
            while attempts < max_attempts:
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    attempts += 1
                    if attempts == max_attempts:
                        raise e
                    
                    print(f"Attempt {attempts} failed: {e}")
                    print(f"Retrying in {current_delay} seconds...")
                    time.sleep(current_delay)
                    current_delay *= backoff
            
        return wrapper
    return decorator

@retry(max_attempts=3, delay=0.5, exceptions=(ConnectionError, TimeoutError))
def unreliable_api_call():
    """Simulate an unreliable API call"""
    if random.random() < 0.7:  # 70% chance of failure
        raise ConnectionError("API connection failed")
    return "Success!"

# Will retry up to 3 times on failure
result = unreliable_api_call()

3. Rate Limiting Decorator

import functools
import time
from collections import defaultdict

def rate_limit(calls_per_second=1):
    """Rate limiting decorator"""
    
    def decorator(func):
        call_times = defaultdict(list)
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            func_name = func.__name__
            
            # Clean old call times
            call_times[func_name] = [
                call_time for call_time in call_times[func_name]
                if now - call_time < 1.0
            ]
            
            # Check rate limit
            if len(call_times[func_name]) >= calls_per_second:
                sleep_time = 1.0 - (now - call_times[func_name][0])
                if sleep_time > 0:
                    print(f"Rate limit hit, sleeping for {sleep_time:.2f}s")
                    time.sleep(sleep_time)
            
            # Record this call
            call_times[func_name].append(time.time())
            
            return func(*args, **kwargs)
        
        return wrapper
    return decorator

@rate_limit(calls_per_second=2)
def api_call(endpoint):
    return f"Called {endpoint}"

Parameterized Decorators

Pattern for Parameterized Decorators

def my_decorator(param1, param2="default"):
    """Decorator factory function"""
    
    def decorator(func):
        """Actual decorator function"""
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            """Wrapper function"""
            # Use param1 and param2 here
            print(f"Parameters: {param1}, {param2}")
            return func(*args, **kwargs)
        
        return wrapper
    return decorator

# Usage
@my_decorator("value1", param2="value2")
def my_function():
    pass

Real-World Example: Permissions Decorator

import functools
from enum import Enum

class Permission(Enum):
    READ = "read"
    WRITE = "write"
    ADMIN = "admin"

def requires_permission(*required_perms):
    """Check if user has required permissions"""
    
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # Get current user (in real app, this would come from session/auth)
            current_user = kwargs.get('user') or getattr(args[0], 'user', None)
            
            if not current_user:
                raise PermissionError("No user context found")
            
            user_perms = getattr(current_user, 'permissions', [])
            
            for perm in required_perms:
                if perm not in user_perms:
                    raise PermissionError(f"Missing permission: {perm.value}")
            
            return func(*args, **kwargs)
        
        return wrapper
    return decorator

# Usage
class User:
    def __init__(self, name, permissions):
        self.name = name
        self.permissions = permissions

@requires_permission(Permission.WRITE, Permission.ADMIN)
def delete_user(user_id, user=None):
    return f"Deleted user {user_id}"

# Create users with different permissions
admin_user = User("Admin", [Permission.READ, Permission.WRITE, Permission.ADMIN])
regular_user = User("User", [Permission.READ])

# This works
delete_user(123, user=admin_user)

# This raises PermissionError
# delete_user(123, user=regular_user)

Class-Based Decorators

When to Use Class-Based Decorators

Advanced Class-Based Example

import functools
import time
import threading
from dataclasses import dataclass
from typing import Dict, Any

@dataclass
class CallStats:
    total_calls: int = 0
    total_time: float = 0.0
    last_called: float = 0.0
    average_time: float = 0.0

class FunctionMonitor:
    """Advanced function monitoring decorator"""
    
    def __init__(self, track_stats=True, log_calls=False):
        self.track_stats = track_stats
        self.log_calls = log_calls
        self.stats: Dict[str, CallStats] = {}
        self._lock = threading.Lock()
    
    def __call__(self, func):
        func_name = func.__name__
        
        if self.track_stats:
            self.stats[func_name] = CallStats()
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start_time = time.perf_counter()
            
            if self.log_calls:
                print(f"Calling {func_name}")
            
            try:
                result = func(*args, **kwargs)
                return result
            finally:
                if self.track_stats:
                    end_time = time.perf_counter()
                    execution_time = end_time - start_time
                    
                    with self._lock:
                        stats = self.stats[func_name]
                        stats.total_calls += 1
                        stats.total_time += execution_time
                        stats.last_called = end_time
                        stats.average_time = stats.total_time / stats.total_calls
        
        return wrapper
    
    def get_stats(self, func_name: str = None) -> Dict[str, Any]:
        """Get statistics for a function or all functions"""
        with self._lock:
            if func_name:
                return {func_name: self.stats.get(func_name)}
            return dict(self.stats)
    
    def reset_stats(self, func_name: str = None):
        """Reset statistics"""
        with self._lock:
            if func_name:
                if func_name in self.stats:
                    self.stats[func_name] = CallStats()
            else:
                self.stats.clear()

# Usage
monitor = FunctionMonitor(track_stats=True, log_calls=True)

@monitor
def calculate_something(n):
    time.sleep(0.1)  # Simulate work
    return n ** 2

# Use the function
for i in range(5):
    calculate_something(i)

# Get statistics
print(monitor.get_stats("calculate_something"))
# CallStats(total_calls=5, total_time=0.5012, last_called=1627..., average_time=0.1002)

Performance Analysis

Decorator Overhead Comparison

import timeit
import functools

# Test functions
def bare_function(x):
    return x * 2

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

def complex_decorator(func):
    call_count = 0
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        nonlocal call_count
        call_count += 1
        start = time.perf_counter()
        result = func(*args, **kwargs)
        end = time.perf_counter()
        return result
    return wrapper

class ClassDecorator:
    def __init__(self, func):
        self.func = func
        self.call_count = 0
        functools.update_wrapper(self, func)
    
    def __call__(self, *args, **kwargs):
        self.call_count += 1
        return self.func(*args, **kwargs)

# Create decorated versions
@simple_decorator
def simple_decorated(x):
    return x * 2

@complex_decorator  
def complex_decorated(x):
    return x * 2

@ClassDecorator
def class_decorated(x):
    return x * 2

Performance Results

Key Insights:

• Simple decorators add minimal overhead (~73%)
• Complex decorators with timing/counting are more expensive
• Class decorators fall between simple and complex function decorators
• For performance-critical code, consider the overhead carefully

Real-World Use Cases

1. API Authentication Decorator

import functools
import jwt
from datetime import datetime, timedelta

def requires_auth(roles=None):
    """Authentication and authorization decorator"""
    roles = roles or []
    
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # Get token from request headers (simplified)
            token = kwargs.get('auth_token')
            if not token:
                raise AuthenticationError("No authentication token provided")
            
            try:
                # Decode JWT token
                payload = jwt.decode(token, "secret", algorithms=["HS256"])
                user_roles = payload.get('roles', [])
                
                # Check authorization
                if roles and not any(role in user_roles for role in roles):
                    raise AuthorizationError(f"Required roles: {roles}")
                
                # Add user info to kwargs
                kwargs['current_user'] = payload
                return func(*args, **kwargs)
                
            except jwt.ExpiredSignatureError:
                raise AuthenticationError("Token has expired")
            except jwt.InvalidTokenError:
                raise AuthenticationError("Invalid token")
        
        return wrapper
    return decorator

@requires_auth(roles=['admin', 'moderator'])
def delete_post(post_id, current_user=None, auth_token=None):
    return f"Post {post_id} deleted by {current_user['username']}"

2. Database Transaction Decorator

import functools
import sqlite3
from contextlib import contextmanager

class DatabaseManager:
    def __init__(self, db_path):
        self.db_path = db_path
    
    @contextmanager
    def get_connection(self):
        conn = sqlite3.connect(self.db_path)
        try:
            yield conn
        finally:
            conn.close()

def transaction(db_manager):
    """Database transaction decorator with automatic rollback"""
    
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            with db_manager.get_connection() as conn:
                try:
                    conn.execute("BEGIN")
                    
                    # Pass connection to the function
                    result = func(conn, *args, **kwargs)
                    
                    conn.commit()
                    return result
                    
                except Exception as e:
                    conn.rollback()
                    raise e
        
        return wrapper
    return decorator

# Usage
db = DatabaseManager("example.db")

@transaction(db)
def transfer_money(conn, from_account, to_account, amount):
    # These operations are atomic
    conn.execute(
        "UPDATE accounts SET balance = balance - ? WHERE id = ?",
        (amount, from_account)
    )
    conn.execute(
        "UPDATE accounts SET balance = balance + ? WHERE id = ?", 
        (amount, to_account)
    )
    return f"Transferred ${amount} from {from_account} to {to_account}"

3. Async Decorator with Circuit Breaker

import asyncio
import functools
import time
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"       # Normal operation
    OPEN = "open"          # Failing, reject calls
    HALF_OPEN = "half_open" # Testing if service recovered

def circuit_breaker(failure_threshold=5, timeout=60):
    """Circuit breaker pattern for async functions"""
    
    def decorator(func):
        state = CircuitState.CLOSED
        failure_count = 0
        last_failure_time = 0
        
        @functools.wraps(func)
        async def wrapper(*args, **kwargs):
            nonlocal state, failure_count, last_failure_time
            
            # Check if we should try again after timeout
            if state == CircuitState.OPEN:
                if time.time() - last_failure_time > timeout:
                    state = CircuitState.HALF_OPEN
                else:
                    raise CircuitBreakerError("Circuit breaker is OPEN")
            
            try:
                result = await func(*args, **kwargs)
                
                # Success - reset circuit breaker
                if state == CircuitState.HALF_OPEN:
                    state = CircuitState.CLOSED
                    failure_count = 0
                
                return result
                
            except Exception as e:
                failure_count += 1
                last_failure_time = time.time()
                
                # Open circuit if threshold reached
                if failure_count >= failure_threshold:
                    state = CircuitState.OPEN
                
                raise e
        
        wrapper.get_state = lambda: state
        wrapper.get_failure_count = lambda: failure_count
        return wrapper
    
    return decorator

@circuit_breaker(failure_threshold=3, timeout=30)
async def external_api_call(endpoint):
    """Simulate calling an external API"""
    # Simulate network call
    await asyncio.sleep(0.1)
    
    # Simulate random failures
    import random
    if random.random() < 0.3:  # 30% failure rate
        raise ConnectionError("API unavailable")
    
    return f"Data from {endpoint}"

Best Practices and Common Pitfalls

Best Practices

1. Always Use functools.wraps

import functools

# ❌ Wrong - loses function metadata
def bad_decorator(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

# ✅ Correct - preserves function metadata
def good_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@bad_decorator
def example_function():
    """This docstring will be lost"""
    pass

print(example_function.__name__)  # "wrapper" instead of "example_function"

@good_decorator
def example_function2():
    """This docstring will be preserved"""
    pass

print(example_function2.__name__)  # "example_function2"
print(example_function2.__doc__)   # "This docstring will be preserved"

2. Handle Arguments Properly

# ✅ Good - handles all argument types
@functools.wraps(func)
def wrapper(*args, **kwargs):
    return func(*args, **kwargs)

# ❌ Bad - doesn't handle keyword arguments
def wrapper(*args):
    return func(*args)

3. Consider Performance Impact

# ✅ Good - minimal overhead for simple cases
def lightweight_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # Minimal processing
        return func(*args, **kwargs)
    return wrapper

# ❌ Bad - expensive operations in every call
def expensive_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # Heavy computation on every call
        complex_operation()
        return func(*args, **kwargs)
    return wrapper

Common Pitfalls

1. Forgetting to Return the Result

# ❌ Wrong - function always returns None
def broken_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        # Forgot to return result!
    return wrapper

# ✅ Correct
def fixed_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result  # Remember to return!
    return wrapper

2. Mutable Default Arguments in Decorator Factories

# ❌ Dangerous - mutable default argument
def configure_decorator(options={}):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # All functions share the same options dict!
            options['calls'] = options.get('calls', 0) + 1
            return func(*args, **kwargs)
        return wrapper
    return decorator

# ✅ Safe approach
def configure_decorator(options=None):
    if options is None:
        options = {}
    
    def decorator(func):
        # Create a copy for this specific decorator instance
        local_options = options.copy()
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            local_options['calls'] = local_options.get('calls', 0) + 1
            return func(*args, **kwargs)
        return wrapper
    return decorator

3. Not Handling Exceptions Properly

# ❌ Wrong - swallows exceptions
def bad_error_handling(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        try:
            return func(*args, **kwargs)
        except:
            print("An error occurred")
            # Exception is lost!
    return wrapper

# ✅ Better - logs and re-raises
def good_error_handling(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        try:
            return func(*args, **kwargs)
        except Exception as e:
            print(f"Error in {func.__name__}: {e}")
            raise  # Re-raise the exception
    return wrapper

Decorator Testing Strategies

import pytest
import functools

def test_decorator_preserves_function():
    """Test that decorator preserves function metadata"""
    
    def my_decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        return wrapper
    
    @my_decorator
    def sample_function():
        """Sample docstring"""
        return "result"
    
    # Test metadata preservation
    assert sample_function.__name__ == "sample_function"
    assert sample_function.__doc__ == "Sample docstring"
    
    # Test functionality
    assert sample_function() == "result"

def test_decorator_with_arguments():
    """Test parameterized decorator"""
    
    def multiplier(factor):
        def decorator(func):
            @functools.wraps(func)
            def wrapper(*args, **kwargs):
                result = func(*args, **kwargs)
                return result * factor
            return wrapper
        return decorator
    
    @multiplier(3)
    def get_number():
        return 5
    
    assert get_number() == 15

def test_decorator_error_handling():
    """Test decorator handles errors correctly"""
    
    def error_logger(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            try:
                return func(*args, **kwargs)
            except ValueError as e:
                print(f"Caught ValueError: {e}")
                raise
        return wrapper
    
    @error_logger
    def failing_function():
        raise ValueError("Test error")
    
    with pytest.raises(ValueError, match="Test error"):
        failing_function()

Frequently Asked Questions

Q1: When should I use a decorator vs a regular function?

Answer: Use decorators when you want to modify or enhance the behavior of functions without changing their core implementation. Decorators are ideal for cross-cutting concerns like logging, authentication, caching, or timing that apply to multiple functions.

# Use decorator for reusable functionality
@timer
@cache
@log_calls
def expensive_calculation(n):
    return fibonacci(n)

# Don't use decorator for one-off modifications
def process_data(data):
    validated_data = validate(data)  # Just call validation directly
    return transform(validated_data)

Q2: How do I debug decorated functions?

Answer: Debugging decorated functions can be tricky. Use these techniques:

import functools

def debug_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} with args={args}, kwargs={kwargs}")
        
        # Set a breakpoint here for debugging
        import pdb; pdb.set_trace()
        
        result = func(*args, **kwargs)
        print(f"{func.__name__} returned {result}")
        return result
    return wrapper

# Access the original function for testing
@debug_decorator
def my_function(x):
    return x * 2

# Get original function if needed
original = my_function.__wrapped__

Q3: Can I apply multiple decorators to the same function?

Answer: Yes! Multiple decorators are applied from bottom to top (innermost to outermost):

@timer           # Applied last (outermost)
@cache           # Applied second
@validate_args   # Applied first (innermost)
def my_function(x):
    return x ** 2

# Equivalent to:
# my_function = timer(cache(validate_args(my_function)))

Q4: How do I create a decorator that works with both sync and async functions?

Answer: You need to detect if the function is async and handle both cases:

import asyncio
import functools

def universal_decorator(func):
    @functools.wraps(func)
    def sync_wrapper(*args, **kwargs):
        print(f"Calling sync {func.__name__}")
        return func(*args, **kwargs)
    
    @functools.wraps(func)
    async def async_wrapper(*args, **kwargs):
        print(f"Calling async {func.__name__}")
        return await func(*args, **kwargs)
    
    if asyncio.iscoroutinefunction(func):
        return async_wrapper
    else:
        return sync_wrapper

@universal_decorator
def sync_function():
    return "sync result"

@universal_decorator
async def async_function():
    return "async result"

Q5: How do I pass arguments to the original function from my decorator?

Answer: Use *args and **kwargs to capture all arguments and pass them through:

def my_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # You can inspect or modify arguments here
        print(f"Arguments: {args}, {kwargs}")
        
        # Pass all arguments to the original function
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def example(a, b, c=None, d=42):
    return f"a={a}, b={b}, c={c}, d={d}"

example(1, 2, c=3, d=4)  # Works with any argument combination

Q6: How do I make a decorator that modifies the return value?

Answer: Capture the result, modify it, then return the modified version:

def format_result(template):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            result = func(*args, **kwargs)
            return template.format(result=result, func_name=func.__name__)
        return wrapper
    return decorator

@format_result("Result from {func_name}: {result}")
def get_number():
    return 42

print(get_number())  # "Result from get_number: 42"

Q7: What's the difference between function-based and class-based decorators?

Answer: Function-based decorators are simpler and more common. Class-based decorators are useful when you need to maintain state or have complex configuration:

# Function-based (simpler)
def simple_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

# Class-based (more powerful)
class StatefulDecorator:
    def __init__(self, config):
        self.config = config
        self.call_count = 0
    
    def __call__(self, func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            self.call_count += 1
            return func(*args, **kwargs)
        return wrapper

Q8: How do I create a decorator that only runs in certain conditions?

Answer: Add conditional logic inside your decorator:

import os

def debug_only(func):
    """Only execute the function if in debug mode"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        if os.environ.get('DEBUG') == 'true':
            return func(*args, **kwargs)
        else:
            print(f"Skipping {func.__name__} (not in debug mode)")
            return None
    return wrapper

@debug_only
def debug_print(message):
    print(f"DEBUG: {message}")

# Only runs if DEBUG=true environment variable is set
debug_print("This is a debug message")

Conclusion

Python decorators are a powerful tool for writing clean, modular, and reusable code. They allow you to separate concerns, reduce code duplication, and implement cross-cutting functionality in an elegant way.

Key Takeaways

When to Use Decorators:

• Cross-cutting concerns (logging, timing, authentication)
• Behavior modification without changing core logic
• Reusable functionality across multiple functions
• Aspect-oriented programming patterns

Best Practices:

• Always use functools.wraps() to preserve function metadata
• Handle all argument types with *args, **kwargs
• Consider performance impact for frequently called functions
• Write comprehensive tests for decorator behavior
• Document decorator side effects and requirements

Common Patterns:

• Simple function wrappers for basic modifications
• Parameterized decorators for configurable behavior
• Class-based decorators for stateful operations
• Stacked decorators for layered functionality

Performance Considerations:

• Simple decorators add minimal overhead (~70-100%)
• Complex decorators with state/timing are more expensive
• Consider decorator overhead in performance-critical code
• Use profiling to measure actual impact

Advanced Applications

Decorators shine in enterprise applications for:

• API frameworks: Authentication, rate limiting, serialization
• Database operations: Transaction management, connection pooling
• Monitoring: Performance tracking, error reporting
• Caching: Memoization, Redis integration
• Security: Input validation, access control

By mastering decorators, you'll write more maintainable, testable, and professional Python code. Start with simple use cases and gradually work up to more complex patterns as your understanding grows.

Remember: decorators are about enhancing functions while keeping their core purpose clear and unchanged. Use them wisely to create more elegant and powerful Python applications.

This guide covers Python 3.6+ features. Some examples use modern Python features like f-strings and dataclasses. Always refer to the official Python documentation for the most current information.