📘 Decorators: Class and Method Decorators

🎯 Introduction

Welcome to this exciting tutorial on decorators: class and method decorators! 🎉 In this guide, we’ll explore how to use decorators to enhance your classes and methods with powerful functionality.

You’ll discover how decorators can transform your Python development experience. Whether you’re building web applications 🌐, APIs 🖥️, or libraries 📚, understanding class and method decorators is essential for writing elegant, maintainable code.

By the end of this tutorial, you’ll feel confident using decorators to create clean, reusable code patterns in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Class and Method Decorators

🤔 What are Class and Method Decorators?

Decorators are like gift wrappers for your code 🎁. Think of them as magical enhancements that you can apply to classes and methods to give them superpowers without modifying their core functionality.

In Python terms, decorators are functions that take another function or class as input and extend its behavior. This means you can:

• ✨ Add logging or timing to methods automatically
• 🚀 Validate inputs before a method runs
• 🛡️ Control access to methods based on permissions
• 📊 Cache expensive computations

💡 Why Use Class and Method Decorators?

Here’s why developers love decorators:

1. DRY Principle 🔄: Don’t repeat yourself - apply common functionality once
2. Separation of Concerns 📦: Keep business logic separate from cross-cutting concerns
3. Clean Code 🧹: Make your code more readable and maintainable
4. Flexible Enhancement 🎨: Add or remove features without changing core code

Real-world example: Imagine building an e-commerce API 🛒. With decorators, you can add authentication, logging, and rate limiting to all your endpoints without cluttering the actual business logic!

🔧 Basic Syntax and Usage

📝 Simple Method Decorator

Let’s start with a friendly example:

# 👋 Hello, Decorators!
import time
from functools import wraps

# 🎨 Creating a simple timing decorator
def measure_time(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        start = time.time()  # ⏱️ Start the timer
        result = func(*args, **kwargs)
        end = time.time()  # ⏹️ Stop the timer
        print(f"⏱️ {func.__name__} took {end - start:.2f} seconds")
        return result
    return wrapper

# 🎯 Using our decorator
class DataProcessor:
    @measure_time
    def process_data(self, data):
        # 🔄 Simulate some processing
        time.sleep(0.1)
        return [item * 2 for item in data]

# 🎮 Let's try it!
processor = DataProcessor()
result = processor.process_data([1, 2, 3, 4, 5])
print(f"📊 Result: {result}")

💡 Explanation: The @measure_time decorator wraps our method and automatically measures execution time. Notice how clean the actual method stays!

🎯 Class Decorator Pattern

Here’s how to decorate entire classes:

# 🏗️ Class decorator for adding features
def add_debug_repr(cls):
    """Add a helpful __repr__ method 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

# 🎨 Another useful class decorator
def singleton(cls):
    """Ensure only one instance exists! 🔒"""
    instances = {}
    def get_instance(*args, **kwargs):
        if cls not in instances:
            instances[cls] = cls(*args, **kwargs)
        return instances[cls]
    return get_instance

# 🎮 Using class decorators
@add_debug_repr
@singleton
class DatabaseConnection:
    def __init__(self, host="localhost", port=5432):
        self.host = host
        self.port = port
        print(f"🔌 Connecting to {host}:{port}")

# 🧪 Test it out!
db1 = DatabaseConnection()
db2 = DatabaseConnection()  # Same instance!
print(f"Same instance? {db1 is db2} ✅")
print(db1)  # Nice repr! 🎨

💡 Practical Examples

🛒 Example 1: E-commerce Permission System

Let’s build something real:

# 🛍️ Permission decorator for e-commerce
from functools import wraps
from enum import Enum

class Role(Enum):
    CUSTOMER = "customer"
    ADMIN = "admin"
    SELLER = "seller"

# 🎭 Current user simulation
class User:
    def __init__(self, name, role):
        self.name = name
        self.role = role

current_user = None  # 👤 Will be set during "login"

# 🔐 Permission decorator
def requires_role(*allowed_roles):
    def decorator(func):
        @wraps(func)
        def wrapper(self, *args, **kwargs):
            if not current_user:
                print("❌ Error: Not logged in!")
                return None
            
            if current_user.role not in allowed_roles:
                print(f"🚫 Permission denied for {current_user.name}!")
                return None
            
            print(f"✅ Access granted for {current_user.name}")
            return func(self, *args, **kwargs)
        return wrapper
    return decorator

# 🛒 E-commerce system
class EcommerceSystem:
    def __init__(self):
        self.products = {
            "1": {"name": "Python Book", "price": 29.99, "emoji": "📘"},
            "2": {"name": "Coffee Mug", "price": 12.99, "emoji": "☕"},
            "3": {"name": "Mechanical Keyboard", "price": 89.99, "emoji": "⌨️"}
        }
        self.orders = []
    
    @requires_role(Role.CUSTOMER, Role.ADMIN)
    def view_products(self):
        print("\n🛍️ Available Products:")
        for id, product in self.products.items():
            print(f"  {product['emoji']} {product['name']} - ${product['price']}")
    
    @requires_role(Role.ADMIN)
    def add_product(self, name, price, emoji="📦"):
        new_id = str(len(self.products) + 1)
        self.products[new_id] = {"name": name, "price": price, "emoji": emoji}
        print(f"✨ Added new product: {emoji} {name}")
    
    @requires_role(Role.ADMIN)
    def view_all_orders(self):
        print(f"\n📊 Total orders: {len(self.orders)}")
        for order in self.orders:
            print(f"  📦 Order by {order['user']}: {order['items']}")
    
    @requires_role(Role.CUSTOMER, Role.SELLER)
    def place_order(self, product_ids):
        items = [self.products[pid]['name'] for pid in product_ids if pid in self.products]
        self.orders.append({"user": current_user.name, "items": items})
        print(f"🎉 Order placed successfully! Items: {items}")

# 🎮 Let's test our system!
shop = EcommerceSystem()

# 🧪 Test as customer
print("👤 Testing as Customer:")
current_user = User("Alice", Role.CUSTOMER)
shop.view_products()     # ✅ Allowed
shop.place_order(["1", "2"])  # ✅ Allowed
shop.add_product("New Item", 99.99)  # ❌ Denied

# 🧪 Test as admin
print("\n👑 Testing as Admin:")
current_user = User("Bob", Role.ADMIN)
shop.add_product("Gaming Mouse", 59.99, "🖱️")  # ✅ Allowed
shop.view_all_orders()  # ✅ Allowed

🎯 Try it yourself: Add a @log_action decorator that records all method calls!

🎮 Example 2: Game State Management

Let’s make it fun with a game system:

# 🏆 Game state management with decorators
import json
from datetime import datetime

# 💾 Auto-save decorator
def auto_save(func):
    """Automatically save game state after important actions! 💾"""
    @wraps(func)
    def wrapper(self, *args, **kwargs):
        result = func(self, *args, **kwargs)
        self.save_game()
        return result
    return wrapper

# 🎯 Validate game state
def validate_state(func):
    """Ensure game state is valid before actions! 🛡️"""
    @wraps(func)
    def wrapper(self, *args, **kwargs):
        if self.player_health <= 0:
            print("💀 Game Over! Cannot perform actions when dead!")
            return None
        if self.level < 1:
            print("⚠️ Invalid game state!")
            return None
        return func(self, *args, **kwargs)
    return wrapper

# 🏆 Achievement tracker
def achievement_tracker(achievement_name, condition_func):
    """Track and unlock achievements! 🌟"""
    def decorator(func):
        @wraps(func)
        def wrapper(self, *args, **kwargs):
            result = func(self, *args, **kwargs)
            if condition_func(self) and achievement_name not in self.achievements:
                self.achievements.append(achievement_name)
                print(f"🏆 Achievement Unlocked: {achievement_name}!")
            return result
        return wrapper
    return decorator

# 🎮 Our game class
@add_debug_repr  # Reusing our earlier decorator!
class RPGGame:
    def __init__(self, player_name):
        self.player_name = player_name
        self.level = 1
        self.player_health = 100
        self.experience = 0
        self.inventory = ["🗡️ Wooden Sword", "🛡️ Basic Shield"]
        self.achievements = ["🌟 First Steps"]
        self.gold = 50
        print(f"🎮 Welcome to the adventure, {player_name}!")
    
    @auto_save
    @validate_state
    @achievement_tracker("💰 Rich Player", lambda self: self.gold >= 1000)
    def collect_treasure(self, amount):
        """Find treasure! 💎"""
        self.gold += amount
        print(f"💰 Found {amount} gold! Total: {self.gold}")
        return self.gold
    
    @auto_save
    @validate_state
    @achievement_tracker("⚔️ Dragon Slayer", lambda self: self.experience >= 1000)
    def defeat_monster(self, monster_name, exp_reward, damage_taken):
        """Battle monsters! ⚔️"""
        self.player_health -= damage_taken
        self.experience += exp_reward
        
        print(f"⚔️ Defeated {monster_name}!")
        print(f"📊 Gained {exp_reward} XP | Health: {self.player_health}/100")
        
        # Level up check
        if self.experience >= self.level * 100:
            self.level_up()
        
        return self.experience
    
    @auto_save
    def level_up(self):
        """Level up! 📈"""
        self.level += 1
        self.player_health = 100  # Full heal on level up!
        print(f"🎉 LEVEL UP! You are now level {self.level}!")
        print(f"💚 Health restored to full!")
    
    def save_game(self):
        """Save game state 💾"""
        save_data = {
            "player": self.player_name,
            "level": self.level,
            "health": self.player_health,
            "exp": self.experience,
            "gold": self.gold,
            "achievements": self.achievements,
            "timestamp": datetime.now().isoformat()
        }
        # In real game, save to file
        print(f"💾 Game saved! (Level {self.level}, {self.gold} gold)")

# 🎮 Play the game!
game = RPGGame("Hero")
game.collect_treasure(100)  # Find some gold
game.defeat_monster("🐺 Wolf", 50, 10)  # Fight!
game.defeat_monster("🐉 Dragon", 500, 30)  # Epic battle!
game.collect_treasure(950)  # Big treasure!

print(f"\n🏆 Achievements: {', '.join(game.achievements)}")

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Parameterized Decorators

When you’re ready to level up, try parameterized decorators:

# 🎯 Advanced caching decorator with TTL
import time
from functools import wraps

def cache_with_ttl(ttl_seconds=60):
    """Cache results with time-to-live! ⏰"""
    def decorator(func):
        cache = {}
        cache_time = {}
        
        @wraps(func)
        def wrapper(*args, **kwargs):
            # Create cache key
            key = str(args) + str(kwargs)
            
            # Check if cached and not expired
            if key in cache:
                if time.time() - cache_time[key] < ttl_seconds:
                    print(f"✨ Cache hit for {func.__name__}!")
                    return cache[key]
                else:
                    print(f"⏰ Cache expired for {func.__name__}")
            
            # Calculate and cache result
            result = func(*args, **kwargs)
            cache[key] = result
            cache_time[key] = time.time()
            return result
        
        # Add cache control methods
        wrapper.clear_cache = lambda: (cache.clear(), cache_time.clear())
        wrapper.cache_info = lambda: {"size": len(cache), "keys": list(cache.keys())}
        
        return wrapper
    return decorator

# 🌐 API client with caching
class WeatherAPI:
    @cache_with_ttl(ttl_seconds=300)  # 5 minute cache
    def get_weather(self, city):
        """Fetch weather data (expensive operation) 🌤️"""
        print(f"🔍 Fetching weather for {city}...")
        time.sleep(1)  # Simulate API call
        # Mock weather data
        return {
            "city": city,
            "temp": "72°F",
            "condition": "Sunny ☀️",
            "humidity": "45%"
        }
    
    @cache_with_ttl(ttl_seconds=3600)  # 1 hour cache
    def get_forecast(self, city, days=7):
        """Get extended forecast 📅"""
        print(f"📊 Fetching {days}-day forecast for {city}...")
        time.sleep(2)  # Simulate longer API call
        return {"city": city, "days": days, "forecast": "Mostly sunny 🌞"}

# 🧪 Test caching
api = WeatherAPI()
print(api.get_weather("New York"))  # First call - slow
print(api.get_weather("New York"))  # Cached - fast!
print(f"📊 Cache info: {api.get_weather.cache_info()}")

🏗️ Advanced Topic 2: Decorator Factories and Class Decorators

For the brave developers:

# 🚀 Advanced decorator factory pattern
def create_validator(**validations):
    """Create custom validation decorators! 🛡️"""
    def decorator(func):
        @wraps(func)
        def wrapper(self, **kwargs):
            # Validate each parameter
            for param, validator in validations.items():
                if param in kwargs:
                    value = kwargs[param]
                    if not validator(value):
                        raise ValueError(f"❌ Invalid {param}: {value}")
            
            return func(self, **kwargs)
        return wrapper
    return decorator

# 🏗️ Advanced class decorator with metaclass features
def dataclass_lite(cls):
    """Simple dataclass decorator! 📦"""
    # Get annotations
    annotations = getattr(cls, '__annotations__', {})
    
    # Create __init__ method
    def __init__(self, **kwargs):
        for field, field_type in annotations.items():
            if field in kwargs:
                setattr(self, field, kwargs[field])
            else:
                # Set default values
                default = None
                if field_type == int:
                    default = 0
                elif field_type == str:
                    default = ""
                elif field_type == list:
                    default = []
                setattr(self, field, default)
    
    # Create __repr__ method
    def __repr__(self):
        fields = ', '.join(f"{k}={getattr(self, k)}" for k in annotations)
        return f"{cls.__name__}({fields}) 🎯"
    
    # Create __eq__ method
    def __eq__(self, other):
        if not isinstance(other, cls):
            return False
        return all(getattr(self, k) == getattr(other, k) for k in annotations)
    
    # Apply methods
    cls.__init__ = __init__
    cls.__repr__ = __repr__
    cls.__eq__ = __eq__
    
    return cls

# 🎮 Using our advanced decorators
@dataclass_lite
class Player:
    name: str
    level: int
    health: int
    mana: int
    inventory: list

class GameCharacter:
    @create_validator(
        level=lambda x: 1 <= x <= 100,
        health=lambda x: x >= 0,
        name=lambda x: len(x) > 0
    )
    def update_stats(self, **stats):
        """Update character stats with validation! 📊"""
        for stat, value in stats.items():
            setattr(self, stat, value)
            print(f"✅ Updated {stat} to {value}")

# 🧪 Test advanced features
player1 = Player(name="Hero", level=5, health=100)
player2 = Player(name="Hero", level=5, health=100)
print(player1)  # Nice repr!
print(f"Equal? {player1 == player2}")  # True!

character = GameCharacter()
character.level = 1
character.health = 100
character.name = "Warrior"
character.update_stats(level=10, health=150)  # Valid
# character.update_stats(level=150)  # Would raise error!

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Losing Method Metadata

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

@bad_decorator
def important_function():
    """This documentation will be lost! 😢"""
    pass

print(important_function.__name__)  # 'wrapper' - Wrong!

# ✅ Correct way - preserve metadata!
from functools import wraps

def good_decorator(func):
    @wraps(func)  # 🛡️ Preserves metadata
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@good_decorator
def important_function():
    """This documentation is preserved! 🎉"""
    pass

print(important_function.__name__)  # 'important_function' - Correct!

🤯 Pitfall 2: Decorator Order Matters

# ❌ Wrong order - may not work as expected!
@measure_time
@validate_state  # Validation happens AFTER timing starts
def process_data(self):
    pass

# ✅ Correct order - validate first, then time!
@validate_state  # Check validity first
@measure_time    # Then measure time
def process_data(self):
    pass

# 💡 Remember: decorators apply bottom-to-top!

🐛 Pitfall 3: Class Decorators and Inheritance

# ❌ Problem - decorator may not work with inheritance
@singleton
class BaseClass:
    pass

class DerivedClass(BaseClass):  # 😱 Not a singleton!
    pass

# ✅ Solution - apply decorator to each class
@singleton
class BaseClass:
    pass

@singleton
class DerivedClass(BaseClass):
    pass

🛠️ Best Practices

1. 🎯 Use @wraps: Always preserve function metadata
2. 📝 Document Decorators: Explain what your decorator does
3. 🛡️ Handle Exceptions: Don’t let decorators hide errors
4. 🎨 Keep It Simple: One decorator, one responsibility
5. ✨ Make Decorators Reusable: Design for flexibility
6. 🔄 Consider Performance: Cache when appropriate
7. 📊 Add Introspection: Provide ways to inspect decorator state

🧪 Hands-On Exercise

🎯 Challenge: Build a Web Framework Mini-Router

Create a mini web framework with decorators:

📋 Requirements:

• ✅ Route decorator to map URLs to methods
• 🏷️ Method decorators for GET/POST/PUT/DELETE
• 👤 Authentication decorator
• 📊 Rate limiting decorator
• 🎨 JSON response decorator

🚀 Bonus Points:

• Add middleware support
• Implement request validation
• Create response caching

💡 Solution

# 🎯 Mini web framework with decorators!
from functools import wraps
import json
import time
from collections import defaultdict

# 🌐 Route registry
routes = {
    'GET': {},
    'POST': {},
    'PUT': {},
    'DELETE': {}
}

# 📊 Rate limiting storage
rate_limit_storage = defaultdict(list)

# 🎨 Route decorator
def route(path, method='GET'):
    def decorator(func):
        routes[method][path] = func
        return func
    return decorator

# 🔒 Authentication decorator
def requires_auth(func):
    @wraps(func)
    def wrapper(request, *args, **kwargs):
        auth_token = request.get('headers', {}).get('Authorization')
        if not auth_token or auth_token != 'Bearer secret-token':
            return {
                'status': 401,
                'body': {'error': 'Unauthorized 🚫'}
            }
        return func(request, *args, **kwargs)
    return wrapper

# 🚦 Rate limiting decorator
def rate_limit(max_requests=10, window_seconds=60):
    def decorator(func):
        @wraps(func)
        def wrapper(request, *args, **kwargs):
            client_ip = request.get('ip', 'unknown')
            current_time = time.time()
            
            # Clean old entries
            rate_limit_storage[client_ip] = [
                t for t in rate_limit_storage[client_ip] 
                if current_time - t < window_seconds
            ]
            
            # Check rate limit
            if len(rate_limit_storage[client_ip]) >= max_requests:
                return {
                    'status': 429,
                    'body': {'error': 'Rate limit exceeded! 🚦'}
                }
            
            # Record request
            rate_limit_storage[client_ip].append(current_time)
            return func(request, *args, **kwargs)
        return wrapper
    return decorator

# 📋 JSON response decorator
def json_response(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        if isinstance(result, dict) and 'body' in result:
            result['headers'] = result.get('headers', {})
            result['headers']['Content-Type'] = 'application/json'
            result['body'] = json.dumps(result['body'])
        return result
    return wrapper

# 🎮 Mini web application
class TodoAPI:
    def __init__(self):
        self.todos = []
        self.next_id = 1
    
    @route('/todos', 'GET')
    @json_response
    @rate_limit(max_requests=100)
    def list_todos(self, request):
        """List all todos 📋"""
        return {
            'status': 200,
            'body': {
                'todos': self.todos,
                'count': len(self.todos)
            }
        }
    
    @route('/todos', 'POST')
    @json_response
    @requires_auth
    @rate_limit(max_requests=10)
    def create_todo(self, request):
        """Create a new todo ✨"""
        data = request.get('body', {})
        if 'title' not in data:
            return {
                'status': 400,
                'body': {'error': 'Title required! 📝'}
            }
        
        todo = {
            'id': self.next_id,
            'title': data['title'],
            'completed': False,
            'emoji': data.get('emoji', '📌')
        }
        self.todos.append(todo)
        self.next_id += 1
        
        return {
            'status': 201,
            'body': {'message': 'Todo created! 🎉', 'todo': todo}
        }
    
    @route('/todos/<id>', 'PUT')
    @json_response
    @requires_auth
    def update_todo(self, request, id):
        """Update a todo ✏️"""
        todo_id = int(id)
        data = request.get('body', {})
        
        for todo in self.todos:
            if todo['id'] == todo_id:
                if 'completed' in data:
                    todo['completed'] = data['completed']
                if 'title' in data:
                    todo['title'] = data['title']
                
                return {
                    'status': 200,
                    'body': {'message': 'Updated! ✅', 'todo': todo}
                }
        
        return {
            'status': 404,
            'body': {'error': 'Todo not found! 🔍'}
        }
    
    @route('/todos/<id>', 'DELETE')
    @json_response
    @requires_auth
    def delete_todo(self, request, id):
        """Delete a todo 🗑️"""
        todo_id = int(id)
        self.todos = [t for t in self.todos if t['id'] != todo_id]
        return {
            'status': 200,
            'body': {'message': 'Deleted! 🗑️'}
        }

# 🧪 Test our framework
def handle_request(method, path, request=None):
    """Simple request handler 🌐"""
    request = request or {}
    
    # Find matching route
    for route_path, handler in routes[method].items():
        if route_path == path:
            return handler(api, request)
        
        # Simple parameter matching
        if '<' in route_path:
            parts = route_path.split('/')
            path_parts = path.split('/')
            if len(parts) == len(path_parts):
                params = {}
                match = True
                for i, part in enumerate(parts):
                    if part.startswith('<') and part.endswith('>'):
                        param_name = part[1:-1]
                        params[param_name] = path_parts[i]
                    elif part != path_parts[i]:
                        match = False
                        break
                
                if match:
                    return handler(api, request, **params)
    
    return {'status': 404, 'body': 'Not found 🔍'}

# 🎮 Test the API!
api = TodoAPI()

# Public endpoints
print("📋 GET /todos:")
print(handle_request('GET', '/todos'))

# Authenticated endpoints
auth_request = {
    'headers': {'Authorization': 'Bearer secret-token'},
    'body': {'title': 'Learn decorators', 'emoji': '🎓'}
}
print("\n✨ POST /todos (with auth):")
print(handle_request('POST', '/todos', auth_request))

# Test rate limiting
print("\n🚦 Testing rate limit:")
for i in range(12):
    result = handle_request('GET', '/todos', {'ip': 'test-client'})
    if result['status'] == 429:
        print(f"Rate limited after {i} requests!")
        break

🎓 Key Takeaways

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

• ✅ Create method decorators with confidence 💪
• ✅ Build class decorators for powerful enhancements 🏗️
• ✅ Use parameterized decorators for flexibility 🎯
• ✅ Avoid common pitfalls that trip up beginners 🛡️
• ✅ Apply best practices in real projects 🚀

Remember: Decorators are powerful tools that make your code cleaner and more maintainable. Use them wisely! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered class and method decorators!

Here’s what to do next:

1. 💻 Practice with the exercises above
2. 🏗️ Add decorators to your existing projects
3. 📚 Explore Python’s built-in decorators (@property, @staticmethod, @classmethod)
4. 🌟 Share your decorator creations with the community!

Remember: Every Python expert started with their first decorator. Keep coding, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨