▸ Level Up: Python Skills

# ⭐ BEST PRACTICE: Production-ready class
# ✓ Type hints for all parameters and return values
# ✓ Docstrings explaining purpose and usage
# ✓ Input validation to prevent invalid data
# ✓ Clean, readable, maintainable code

class Player:
    """
    Represents a game player with a name and level.
    
    Attributes:
        name (str): The player's display name
        level (int): The player's current level (1-100)
    
    Example:
        >>> player = Player('Ada', level=5)
        >>> player.power()
        15
    """
    
    def __init__(self, name: str, level: int = 1) -> None:
        """Initialize a new Player instance."""
        # Validate inputs to catch bugs early
        if not name:
            raise ValueError("Name cannot be empty")
        if not 1 <= level <= 100:
            raise ValueError("Level must be between 1 and 100")
        
        self.name = name
        self.level = level
    
    def power(self) -> int:
        """Calculate the player's attack power."""
        return self.level * 3
    
    def __repr__(self) -> str:
        return f"Player(name='{self.name}', level={self.level})"

# Usage
p = Player('Ada', level=5)
print(p)
print(f"{p.name} attacks with power {p.power()}")

newbie = Player('Bob')
print(newbie)

# This would raise an error (uncomment to test):
# bad_player = Player('', level=999)  # ValueError!

# ⭐ BEST PRACTICE: Use @dataclass for data-focused classes
# dataclass auto-generates __init__, __repr__, __eq__, etc.

from dataclasses import dataclass

@dataclass
class Item:
    """An item that can be bought or sold."""
    name: str
    price: float
    quantity: int = 1  # Default value
    
    def total_value(self) -> float:
        """Calculate total value of this item stack."""
        return self.price * self.quantity

# dataclass auto-generates:
#   __init__(self, name, price, quantity=1)
#   __repr__(self) -> "Item(name='...', price=..., quantity=...)"
#   __eq__(self, other) -> compares all fields

potion = Item('Potion', 9.99, quantity=3)
print(potion)  # Automatic nice output!
print(f"Total value: ${potion.total_value():.2f}")

# ⭐ BEST PRACTICE: Preserve function metadata
# ✓ @wraps preserves __name__, __doc__, etc.
# ✓ Type hints for the decorator
# ✓ Logs arguments for debugging

from functools import wraps
from typing import Callable, Any

def log(func: Callable) -> Callable:
    """Decorator that logs function calls with arguments."""
    
    @wraps(func)  # This copies __name__, __doc__, etc. from func to wrapper
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        # Log the call with all arguments for debugging
        print(f"[LOG] Calling {func.__name__} with args={args} kwargs={kwargs}")
        return func(*args, **kwargs)
    
    return wrapper

@log
def greet(name: str) -> None:
    """Greet someone by name."""
    print(f"Hello, {name}!")

greet('Ada')

# Now the function keeps its original identity!
print(f"Function name: {greet.__name__}")  # "greet" not "wrapper"
print(f"Docstring: {greet.__doc__}")  # Preserved!

# ⭐ BEST PRACTICE: Production-ready timing decorator
import time
from functools import wraps
from typing import Callable, Any

def timer(func: Callable) -> Callable:
    """
    Decorator that measures and prints function execution time.
    
    Uses time.perf_counter() for high-precision timing.
    """
    @wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        # perf_counter() is more accurate than time.time()
        start = time.perf_counter()
        try:
            result = func(*args, **kwargs)
            return result
        finally:
            # 'finally' ensures timing runs even if function raises error
            elapsed = time.perf_counter() - start
            print(f"[⏱️ TIMER] {func.__name__} completed in {elapsed*1000:.2f}ms")
    return wrapper

@timer
def slow_function() -> str:
    """Simulate a slow operation."""
    time.sleep(0.5)
    return "Done!"

print(f"Result: {slow_function()}")

# ⭐ BEST PRACTICE: Comprehension with condition
# ✓ Transform AND filter in one expression
# ✓ Highly readable when you know the pattern

nums = range(10)  # 0, 1, 2, ..., 9

# Square only the ODD numbers
# Read as: "n squared FOR each n IN nums IF n is odd"
odd_squares = [n * n for n in nums if n % 2 == 1]

print(odd_squares)

# Multiple examples:
names = ['Ada', 'Bob', 'Grace', 'Al']

# Names longer than 2 characters, uppercased
long_names = [name.upper() for name in names if len(name) > 2]
# Result: ['ADA', 'BOB', 'GRACE']

# Anatomy with condition:
# [expression for var in iterable if condition]
#                                  └────────────┘
#                                   FILTER (optional)

# ⭐ BEST PRACTICE: Use a closure to create specialized functions
# ✓ Each function "remembers" its own factor
# ✓ No global state, no repeated parameters

def make_multiplier(factor):
    """
    Factory function that creates customized multiplier functions.
    
    Args:
        factor: The number to multiply by
    
    Returns:
        A function that multiplies its input by factor
    """
    # This inner function "closes over" the 'factor' variable
    def multiply(x):
        return x * factor  # 'factor' is remembered!
    
    return multiply  # Return the function itself

# Create specialized functions
double = make_multiplier(2)  # double remembers factor=2
triple = make_multiplier(3)  # triple remembers factor=3

# Each function has its own "memory"
print(f"double(5) = {double(5)}")  # 10
print(f"triple(5) = {triple(5)}")  # 15
print(f"double(7) = {double(7)}")  # 14
print(f"triple(7) = {triple(7)}")  # 21