📘 Multiple Decorators: Chaining Decorators

🎯 Introduction

Welcome to this exciting tutorial on multiple decorators! 🎉 In this guide, we’ll explore how to chain decorators in Python to create powerful, composable functions.

You’ll discover how combining decorators can transform your Python development experience. Whether you’re building web applications 🌐, creating APIs 🖥️, or developing automation tools 📚, understanding decorator chaining is essential for writing elegant, maintainable code.

By the end of this tutorial, you’ll feel confident using multiple decorators in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Multiple Decorators

🤔 What is Decorator Chaining?

Decorator chaining is like adding layers to a gift 🎁. Think of it as wrapping a present multiple times - each wrapper adds its own special touch to the final package!

In Python terms, multiple decorators allow you to apply several modifications to a function, with each decorator adding its own functionality. This means you can:

• ✨ Add multiple behaviors without modifying the original function
• 🚀 Create reusable, composable function enhancements
• 🛡️ Keep your code clean and organized

💡 Why Use Multiple Decorators?

Here’s why developers love decorator chaining:

1. Separation of Concerns 🔒: Each decorator handles one specific task
2. Reusability 💻: Mix and match decorators as needed
3. Clean Code 📖: Avoid complex nested logic
4. Flexibility 🔧: Add or remove features easily

Real-world example: Imagine building a web API 🛒. With multiple decorators, you can add authentication, logging, and rate limiting to your endpoints with just a few lines!

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a friendly example:

# 👋 Hello, Multiple Decorators!
def bold(func):
    """Makes text bold 💪"""
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return f"**{result}**"
    return wrapper

def italic(func):
    """Makes text italic 🎨"""
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return f"*{result}*"
    return wrapper

# 🎯 Using multiple decorators
@bold
@italic
def greet(name):
    return f"Hello, {name}! 👋"

# Let's test it!
print(greet("Python"))  # Output: ***Hello, Python! 👋***

💡 Explanation: Notice how decorators are applied from bottom to top! First italic wraps the function, then bold wraps the italic version.

🎯 Common Patterns

Here are patterns you’ll use daily:

# 🏗️ Pattern 1: Timing and logging
import time
import functools

def timer(func):
    """⏱️ Times function execution"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        print(f"⏱️ {func.__name__} took {end - start:.4f} seconds")
        return result
    return wrapper

def logger(func):
    """📝 Logs function calls"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"📝 Calling {func.__name__} with args: {args}, kwargs: {kwargs}")
        result = func(*args, **kwargs)
        print(f"✅ {func.__name__} returned: {result}")
        return result
    return wrapper

# 🎨 Pattern 2: Authentication and validation
def authenticate(func):
    """🔐 Check if user is authenticated"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # Simulating authentication check
        if "user" in kwargs and kwargs["user"]:
            print(f"🔐 User {kwargs['user']} authenticated!")
            return func(*args, **kwargs)
        else:
            return "❌ Authentication required!"
    return wrapper

def validate_positive(func):
    """✔️ Validate positive numbers"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        if all(arg > 0 for arg in args if isinstance(arg, (int, float))):
            return func(*args, **kwargs)
        else:
            return "❌ All numbers must be positive!"
    return wrapper

💡 Practical Examples

🛒 Example 1: E-commerce Order Processing

Let’s build something real:

# 🛍️ E-commerce order processing with multiple decorators
import json
from datetime import datetime

def log_order(func):
    """📋 Log order details"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        order_id = kwargs.get('order_id', 'Unknown')
        print(f"📋 Processing order {order_id} at {datetime.now()}")
        result = func(*args, **kwargs)
        print(f"✅ Order {order_id} processed successfully!")
        return result
    return wrapper

def validate_payment(func):
    """💳 Validate payment method"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        payment = kwargs.get('payment_method', '')
        valid_methods = ['credit_card', 'debit_card', 'paypal']
        
        if payment in valid_methods:
            print(f"💳 Payment method '{payment}' validated!")
            return func(*args, **kwargs)
        else:
            return {"status": "error", "message": "❌ Invalid payment method!"}
    return wrapper

def apply_discount(func):
    """🎁 Apply discount if eligible"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        total = kwargs.get('total', 0)
        if total > 100:
            discount = total * 0.1
            kwargs['total'] = total - discount
            print(f"🎁 Applied 10% discount! Saved ${discount:.2f}")
        return func(*args, **kwargs)
    return wrapper

# 🛒 Using all decorators together!
@log_order
@validate_payment
@apply_discount
def process_order(**order_details):
    """Process an e-commerce order"""
    return {
        "status": "success",
        "order_id": order_details['order_id'],
        "total": order_details['total'],
        "message": "🎉 Order placed successfully!"
    }

# 🎮 Let's use it!
order = process_order(
    order_id="ORD-12345",
    payment_method="credit_card",
    total=150.00,
    items=["📱 Phone Case", "🎧 Headphones"]
)
print(json.dumps(order, indent=2))

🎯 Try it yourself: Add a check_inventory decorator that verifies items are in stock!

🎮 Example 2: Game Character Abilities

Let’s make it fun:

# 🏆 Game character with stackable abilities
class GameCharacter:
    def __init__(self, name, health=100):
        self.name = name
        self.health = health
        self.mana = 50
        self.damage = 10
    
    def __str__(self):
        return f"🎮 {self.name} | ❤️ {self.health} | 💙 {self.mana} | ⚔️ {self.damage}"

def requires_mana(cost):
    """💙 Check if character has enough mana"""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(self, *args, **kwargs):
            if self.mana >= cost:
                self.mana -= cost
                print(f"💙 Used {cost} mana!")
                return func(self, *args, **kwargs)
            else:
                print(f"❌ Not enough mana! Need {cost}, have {self.mana}")
                return None
        return wrapper
    return decorator

def cooldown(seconds):
    """⏰ Add cooldown to ability"""
    def decorator(func):
        func._last_used = 0
        @functools.wraps(func)
        def wrapper(self, *args, **kwargs):
            current_time = time.time()
            if current_time - func._last_used >= seconds:
                func._last_used = current_time
                return func(self, *args, **kwargs)
            else:
                remaining = seconds - (current_time - func._last_used)
                print(f"⏰ Ability on cooldown! Wait {remaining:.1f} seconds")
                return None
        return wrapper
    return decorator

def boost_damage(multiplier):
    """⚔️ Boost damage for special attacks"""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(self, *args, **kwargs):
            original_damage = self.damage
            self.damage *= multiplier
            print(f"⚔️ Damage boosted by {multiplier}x!")
            result = func(self, *args, **kwargs)
            self.damage = original_damage
            return result
        return wrapper
    return decorator

# 🎯 Create a character with abilities
class Wizard(GameCharacter):
    @requires_mana(20)
    @cooldown(3)
    @boost_damage(2)
    def fireball(self, target):
        """🔥 Cast a powerful fireball!"""
        print(f"🔥 {self.name} casts Fireball at {target}!")
        print(f"💥 Dealt {self.damage} damage!")
        return self.damage
    
    @requires_mana(10)
    @cooldown(1)
    def heal(self):
        """💚 Heal yourself"""
        heal_amount = 25
        self.health += heal_amount
        print(f"💚 {self.name} healed for {heal_amount} HP!")
        return heal_amount

# 🎮 Let's play!
wizard = Wizard("Gandalf")
print(wizard)

# Cast some spells!
wizard.fireball("Dragon 🐉")
wizard.heal()
wizard.fireball("Goblin 👺")  # This will be on cooldown!

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Decorator Factory with Parameters

When you’re ready to level up, try this advanced pattern:

# 🎯 Advanced decorator factory
def rate_limit(max_calls, period):
    """🚦 Rate limit function calls"""
    def decorator(func):
        calls = []
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            # Remove old calls outside the period
            calls[:] = [call_time for call_time in calls if now - call_time < period]
            
            if len(calls) >= max_calls:
                print(f"🚦 Rate limit exceeded! Max {max_calls} calls per {period}s")
                return None
            
            calls.append(now)
            return func(*args, **kwargs)
        return wrapper
    return decorator

def cache_result(expiry_seconds):
    """💾 Cache function results"""
    def decorator(func):
        cache = {}
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            key = str(args) + str(kwargs)
            
            if key in cache:
                result, timestamp = cache[key]
                if time.time() - timestamp < expiry_seconds:
                    print(f"💾 Cache hit! Returning cached result")
                    return result
            
            result = func(*args, **kwargs)
            cache[key] = (result, time.time())
            return result
        return wrapper
    return decorator

# 🪄 Using advanced decorators
@rate_limit(max_calls=3, period=10)
@cache_result(expiry_seconds=5)
def expensive_api_call(endpoint):
    """Simulate an API call"""
    print(f"🌐 Making API call to {endpoint}...")
    time.sleep(1)  # Simulate network delay
    return f"Response from {endpoint}"

🏗️ Advanced Topic 2: Class Decorators

For the brave developers:

# 🚀 Combining function and class decorators
def add_repr(cls):
    """🎨 Add a nice __repr__ to any class"""
    def __repr__(self):
        attrs = ', '.join(f"{k}={v}" for k, v in self.__dict__.items())
        return f"{cls.__name__}({attrs}) ✨"
    cls.__repr__ = __repr__
    return cls

def track_instances(cls):
    """📊 Track all instances of a class"""
    cls._instances = []
    original_init = cls.__init__
    
    def new_init(self, *args, **kwargs):
        original_init(self, *args, **kwargs)
        cls._instances.append(self)
    
    cls.__init__ = new_init
    cls.get_instance_count = classmethod(lambda cls: len(cls._instances))
    return cls

# 🎯 Apply multiple decorators to a class
@add_repr
@track_instances
class Player:
    def __init__(self, name, score=0):
        self.name = name
        self.score = score
        self.achievements = []
    
    @timer
    @logger
    def add_achievement(self, achievement):
        """🏆 Add an achievement"""
        self.achievements.append(achievement)
        self.score += 10
        return f"🏆 Unlocked: {achievement}"

# 🎮 Test it out!
player1 = Player("Alice", 100)
player2 = Player("Bob", 200)
print(player1)  # Nice repr from decorator!
print(f"📊 Total players: {Player.get_instance_count()}")

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Wrong Decorator Order

# ❌ Wrong way - order matters!
@validate_positive  # This runs second
@logger            # This runs first
def calculate(x, y):
    return x + y

# If logger runs first, it might log invalid inputs!

# ✅ Correct way - validate first, then log
@logger            # This runs second
@validate_positive # This runs first
def calculate(x, y):
    return x + y

🤯 Pitfall 2: Forgetting functools.wraps

# ❌ Dangerous - loses function metadata!
def bad_decorator(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper  # Lost __name__, __doc__, etc!

# ✅ Safe - preserves metadata!
def good_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper  # Keeps all metadata! ✨

🛠️ Best Practices

1. 🎯 Order Matters: Apply decorators from bottom to top thoughtfully
2. 📝 Use functools.wraps: Always preserve function metadata
3. 🛡️ Keep It Simple: Each decorator should do one thing well
4. 🎨 Name Clearly: @authenticate not @auth
5. ✨ Document Behavior: Explain what each decorator does

🧪 Hands-On Exercise

🎯 Challenge: Build a Web API Endpoint System

Create a decorator system for web API endpoints:

📋 Requirements:

• ✅ Authentication decorator (check API key)
• 🏷️ Validation decorator (validate request data)
• 📊 Analytics decorator (track API usage)
• 🚦 Rate limiting decorator
• 🎨 Each endpoint needs proper error handling!

🚀 Bonus Points:

• Add response caching
• Implement role-based permissions
• Create decorator for API versioning

💡 Solution

# 🎯 Our decorator-based API system!
import json
from functools import wraps
from datetime import datetime

# 🔐 Authentication decorator
def require_api_key(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        api_key = kwargs.get('headers', {}).get('api_key')
        if api_key == "secret-key-123":
            print("🔐 API key validated!")
            return func(*args, **kwargs)
        else:
            return {"error": "❌ Invalid API key!", "status": 401}
    return wrapper

# ✅ Validation decorator
def validate_request(required_fields):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            data = kwargs.get('data', {})
            missing = [field for field in required_fields if field not in data]
            
            if missing:
                return {"error": f"❌ Missing fields: {missing}", "status": 400}
            
            print(f"✅ Request validated! Has all fields: {required_fields}")
            return func(*args, **kwargs)
        return wrapper
    return decorator

# 📊 Analytics decorator
def track_usage(func):
    if not hasattr(track_usage, 'calls'):
        track_usage.calls = {}
    
    @wraps(func)
    def wrapper(*args, **kwargs):
        endpoint = func.__name__
        track_usage.calls[endpoint] = track_usage.calls.get(endpoint, 0) + 1
        
        print(f"📊 {endpoint} called {track_usage.calls[endpoint]} times")
        result = func(*args, **kwargs)
        
        # Add analytics to response
        if isinstance(result, dict):
            result['_analytics'] = {
                'endpoint': endpoint,
                'timestamp': datetime.now().isoformat(),
                'call_count': track_usage.calls[endpoint]
            }
        return result
    return wrapper

# 🚦 Rate limiting
def rate_limit_api(max_calls=10, window=60):
    def decorator(func):
        calls = []
        
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            # Clean old calls
            calls[:] = [t for t in calls if now - t < window]
            
            if len(calls) >= max_calls:
                return {
                    "error": f"🚦 Rate limit exceeded! Max {max_calls} calls per {window}s",
                    "status": 429
                }
            
            calls.append(now)
            return func(*args, **kwargs)
        return wrapper
    return decorator

# 🎯 Example API endpoints
class UserAPI:
    @require_api_key
    @rate_limit_api(max_calls=5, window=60)
    @track_usage
    @validate_request(['username', 'email'])
    def create_user(self, **request):
        """Create a new user 👤"""
        data = request['data']
        return {
            "status": 201,
            "message": f"✅ User {data['username']} created!",
            "user_id": f"usr_{int(time.time())}",
            "emoji": "🎉"
        }
    
    @require_api_key
    @track_usage
    def get_user(self, user_id, **request):
        """Get user details 🔍"""
        return {
            "status": 200,
            "user_id": user_id,
            "username": "awesome_user",
            "emoji": "😎"
        }

# 🎮 Test our API!
api = UserAPI()

# Valid request
response = api.create_user(
    headers={'api_key': 'secret-key-123'},
    data={'username': 'pythonista', 'email': '[email protected]'}
)
print(json.dumps(response, indent=2))

# Get usage stats
print(f"\n📊 API Usage Stats: {track_usage.calls}")

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

• ✅ Chain multiple decorators with confidence 💪
• ✅ Understand decorator execution order and avoid common mistakes 🛡️
• ✅ Create powerful decorator combinations for real projects 🎯
• ✅ Debug decorator issues like a pro 🐛
• ✅ Build awesome decorator-based systems with Python! 🚀

Remember: Decorators are like LEGO blocks - you can combine them in countless ways to build amazing things! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered multiple decorators!

Here’s what to do next:

1. 💻 Practice with the exercises above
2. 🏗️ Build a decorator library for your projects
3. 📚 Explore class decorators and metaclasses
4. 🌟 Share your creative decorator combinations!

Remember: Every Python expert started with simple decorators. Keep experimenting, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨