"""
============================================================
Example: Composition vs Inheritance — Side-by-Side
Pattern: Foundations
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
We're building a notification system for an e-commerce platform.
Notifications can be sent via Email, SMS, or Push. They can also
be urgent, scheduled, or batched. With inheritance, this creates
a combinatorial explosion of subclasses. With composition, it's
clean and extensible.

KEY INSIGHT:
------------
Inheritance creates a rigid hierarchy that explodes with every
new axis of variation. Composition lets you mix and match
behaviors like LEGO bricks — independently and at runtime.

============================================================
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, runtime_checkable


# ════════════════════════════════════════════════════════════
# ❌ INHERITANCE APPROACH — The Combinatorial Explosion
# ════════════════════════════════════════════════════════════

# Level 1: Base
class NotificationBad(ABC):
    @abstractmethod
    def send(self, message: str) -> None: ...


# Level 2: Channel (3 subclasses)
class EmailNotificationBad(NotificationBad):
    def send(self, message: str) -> None:
        print(f"  📧 Email: {message}")


class SMSNotificationBad(NotificationBad):
    def send(self, message: str) -> None:
        print(f"  📱 SMS: {message}")


class PushNotificationBad(NotificationBad):
    def send(self, message: str) -> None:
        print(f"  🔔 Push: {message}")


# Level 3: Urgency × Channel = 6 MORE subclasses (explosion begins!)
class UrgentEmailNotificationBad(EmailNotificationBad):
    def send(self, message: str) -> None:
        print(f"  🚨📧 URGENT Email: {message}")


class UrgentSMSNotificationBad(SMSNotificationBad):
    def send(self, message: str) -> None:
        print(f"  🚨📱 URGENT SMS: {message}")


class ScheduledEmailNotificationBad(EmailNotificationBad):
    def send(self, message: str) -> None:
        print(f"  ⏰📧 Scheduled Email: {message}")


# ... and it keeps growing:
# BatchedEmailNotificationBad, BatchedSMSNotificationBad,
# ScheduledPushNotificationBad, UrgentBatchedEmailNotificationBad...
#
# With 3 channels × 3 urgency types × 3 delivery modes = 27 classes!
# Add logging? 54 classes. Add encryption? 108 classes. 💀

# ════════════════════════════════════════════════════════════
# ✅ COMPOSITION APPROACH — Mix and Match Like LEGO
# ════════════════════════════════════════════════════════════

# ─── Step 1: Define small, focused behaviors (protocols) ──

@runtime_checkable
class Channel(Protocol):
    """HOW to deliver the notification."""
    def deliver(self, message: str) -> None: ...


@runtime_checkable
class UrgencyFormatter(Protocol):
    """HOW to format the urgency."""
    def format(self, message: str) -> str: ...


class DeliveryMode(Protocol):
    """WHEN to deliver the notification."""
    def schedule(self, message: str) -> str: ...


# ─── Step 2: Implement each axis independently ────────────

# Channels (3 classes)
class EmailChannel:
    def deliver(self, message: str) -> None:
        print(f"  📧 Email: {message}")


class SMSChannel:
    def deliver(self, message: str) -> None:
        print(f"  📱 SMS: {message}")


class PushChannel:
    def deliver(self, message: str) -> None:
        print(f"  🔔 Push: {message}")


# Urgency Formatters (3 classes)
class NormalUrgency:
    def format(self, message: str) -> str:
        return message


class UrgentUrgency:
    def format(self, message: str) -> str:
        return f"🚨 URGENT: {message}"


class LowPriorityUrgency:
    def format(self, message: str) -> str:
        return f"ℹ️ FYI: {message}"


# Delivery Modes (3 classes)
class ImmediateDelivery:
    def schedule(self, message: str) -> str:
        return f"[NOW] {message}"


class ScheduledDelivery:
    def schedule(self, message: str) -> str:
        return f"[SCHEDULED 9AM] {message}"


class BatchedDelivery:
    def schedule(self, message: str) -> str:
        return f"[BATCHED] {message}"


# ─── Step 3: Compose them ─────────────────────────────────

@dataclass
class Notification:
    """
    Composes channel + urgency + delivery mode.

    Instead of 27+ subclasses, we have:
    - 3 channels + 3 urgency types + 3 delivery modes = 9 classes
    - And 3 × 3 × 3 = 27 COMBINATIONS without any new classes!

    Adding a new channel? Just 1 new class (not N × M new subclasses).
    """
    channel: Channel
    urgency: UrgencyFormatter
    delivery: DeliveryMode

    def send(self, message: str) -> None:
        formatted = self.urgency.format(message)
        scheduled = self.delivery.schedule(formatted)
        self.channel.deliver(scheduled)


# ════════════════════════════════════════════════════════════
# COMPARISON TABLE (printed at runtime)
# ════════════════════════════════════════════════════════════

COMPARISON = """
╔══════════════════════════╦══════════════════════════════╗
║     INHERITANCE          ║     COMPOSITION              ║
╠══════════════════════════╬══════════════════════════════╣
║ 27+ classes for 3×3×3    ║ 9 classes + 1 compositor     ║
║ Adding channel = N new   ║ Adding channel = 1 new class ║
║ Fixed at class definition║ Swappable at runtime         ║
║ Deep hierarchy = fragile ║ Flat, independent components ║
║ Hard to test in isolation║ Each component testable alone ║
╚══════════════════════════╩══════════════════════════════╝
"""


# ════════════════════════════════════════════════════════════
# DEMO
# ════════════════════════════════════════════════════════════
if __name__ == "__main__":
    print("=" * 60)
    print("❌ INHERITANCE APPROACH")
    print("=" * 60)
    print("  (Showing just 3 of the 27+ subclasses needed)")
    EmailNotificationBad().send("Your order shipped!")
    UrgentEmailNotificationBad().send("Payment failed!")
    ScheduledEmailNotificationBad().send("Weekly digest")
    print()

    print("=" * 60)
    print("✅ COMPOSITION APPROACH")
    print("=" * 60)
    print("  (Same 3 combinations — ZERO new subclasses)")

    # Combination 1: Normal email, immediate
    n1 = Notification(
        channel=EmailChannel(),
        urgency=NormalUrgency(),
        delivery=ImmediateDelivery(),
    )
    n1.send("Your order shipped!")

    # Combination 2: Urgent email, immediate
    n2 = Notification(
        channel=EmailChannel(),
        urgency=UrgentUrgency(),
        delivery=ImmediateDelivery(),
    )
    n2.send("Payment failed!")

    # Combination 3: Normal email, scheduled
    n3 = Notification(
        channel=EmailChannel(),
        urgency=NormalUrgency(),
        delivery=ScheduledDelivery(),
    )
    n3.send("Weekly digest")

    print()
    print("  🔄 Runtime swap — same Notification, different channel:")
    # Swap channel at RUNTIME — impossible with inheritance!
    n4 = Notification(
        channel=SMSChannel(),
        urgency=UrgentUrgency(),
        delivery=ImmediateDelivery(),
    )
    n4.send("Server is down!")

    n5 = Notification(
        channel=PushChannel(),
        urgency=LowPriorityUrgency(),
        delivery=BatchedDelivery(),
    )
    n5.send("New blog post available")

    print()
    print(COMPARISON)

    # Verify that our objects satisfy the protocols
    assert isinstance(EmailChannel(), Channel)  # type: ignore[arg-type]
    assert isinstance(UrgentUrgency(), UrgencyFormatter)  # type: ignore[arg-type]

    print("✅ Composition vs Inheritance demonstrated successfully!")

"""
============================================================
Example: SOLID Principles — Violation → Fix
Pattern: Foundations
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
We model a simple e-commerce system with users, orders, emails,
and reports. Each SOLID principle is demonstrated by first showing
the VIOLATION (bad code), then the FIX (good code).

KEY INSIGHT:
------------
SOLID isn't abstract theory — it's the difference between code
that's a joy to extend and code that makes you dread Monday mornings.

============================================================
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Protocol, runtime_checkable


# ════════════════════════════════════════════════════════════
# S — SINGLE RESPONSIBILITY PRINCIPLE (SRP)
# ════════════════════════════════════════════════════════════

# ❌ BAD: One class does EVERYTHING
class UserManagerBad:
    """Handles user CRUD, emails, reports, AND logging. Too many jobs!"""

    def create_user(self, name: str, email: str) -> dict:
        user = {"name": name, "email": email}
        # ... save to database ...
        self._send_welcome_email(email)  # SRP violation: why is email logic here?
        self._log(f"Created user {name}")  # SRP violation: why is logging here?
        return user

    def _send_welcome_email(self, email: str) -> None:
        print(f"Sending welcome email to {email}")

    def _log(self, message: str) -> None:
        print(f"LOG: {message}")

    def generate_user_report(self) -> str:
        # SRP violation: report generation has nothing to do with user management
        return "User Report: ..."


# ✅ GOOD: Each class has ONE reason to change
class UserService:
    """Responsible ONLY for user business logic."""

    def __init__(self, email_service: "EmailService", logger: "AppLogger") -> None:
        self._email_service = email_service
        self._logger = logger

    def create_user(self, name: str, email: str) -> dict:
        user = {"name": name, "email": email}
        # Delegates email and logging to dedicated services
        self._email_service.send_welcome(email)
        self._logger.log(f"Created user {name}")
        return user


class EmailService:
    """Responsible ONLY for sending emails."""

    def send_welcome(self, email: str) -> None:
        print(f"  📧 Sending welcome email to {email}")


class AppLogger:
    """Responsible ONLY for logging."""

    def log(self, message: str) -> None:
        print(f"  📝 LOG: {message}")


class ReportService:
    """Responsible ONLY for generating reports."""

    def generate_user_report(self) -> str:
        return "  📊 User Report: ..."


# ════════════════════════════════════════════════════════════
# O — OPEN/CLOSED PRINCIPLE (OCP)
# ════════════════════════════════════════════════════════════

# ❌ BAD: Adding a new discount type requires modifying existing code
def calculate_discount_bad(customer_type: str, amount: float) -> float:
    """Every new customer type = another elif branch = modification."""
    if customer_type == "gold":
        return amount * 0.10
    elif customer_type == "silver":
        return amount * 0.05
    elif customer_type == "platinum":  # ← had to MODIFY this function
        return amount * 0.15
    else:
        return 0.0


# ✅ GOOD: New discount types = new classes, zero modification to existing code
class DiscountStrategy(ABC):
    """Abstract interface — closed for modification."""

    @abstractmethod
    def calculate(self, amount: float) -> float: ...


class GoldDiscount(DiscountStrategy):
    def calculate(self, amount: float) -> float:
        return amount * 0.10


class SilverDiscount(DiscountStrategy):
    def calculate(self, amount: float) -> float:
        return amount * 0.05


class PlatinumDiscount(DiscountStrategy):
    """New type — added WITHOUT touching any existing class."""

    def calculate(self, amount: float) -> float:
        return amount * 0.15


def calculate_discount_good(strategy: DiscountStrategy, amount: float) -> float:
    """Open for extension (new strategies), closed for modification."""
    return strategy.calculate(amount)


# ════════════════════════════════════════════════════════════
# L — LISKOV SUBSTITUTION PRINCIPLE (LSP)
# ════════════════════════════════════════════════════════════

# ❌ BAD: Square breaks Rectangle's contract
class RectangleBad:
    def __init__(self, width: int, height: int) -> None:
        self._width = width
        self._height = height

    @property
    def width(self) -> int:
        return self._width

    @width.setter
    def width(self, value: int) -> None:
        self._width = value

    @property
    def height(self) -> int:
        return self._height

    @height.setter
    def height(self, value: int) -> None:
        self._height = value

    def area(self) -> int:
        return self._width * self._height


class SquareBad(RectangleBad):
    """❌ Violates LSP: setting width also sets height (surprise!)."""

    @RectangleBad.width.setter
    def width(self, value: int) -> None:
        self._width = value
        self._height = value  # ← SURPRISE! Breaks Rectangle's expected behavior

    @RectangleBad.height.setter
    def height(self, value: int) -> None:
        self._width = value  # ← SURPRISE!
        self._height = value


# ✅ GOOD: Separate abstractions that don't violate each other's contracts
@runtime_checkable
class Shape(Protocol):
    """Both Rectangle and Square implement Shape without pretending to be each other."""

    def area(self) -> int: ...


@dataclass
class Rectangle:
    width: int
    height: int

    def area(self) -> int:
        return self.width * self.height


@dataclass
class Square:
    side: int

    def area(self) -> int:
        return self.side * self.side


def print_area(shape: Shape) -> None:
    """Works with ANY Shape — no surprises, no broken contracts."""
    print(f"  📐 Area = {shape.area()}")


# ════════════════════════════════════════════════════════════
# I — INTERFACE SEGREGATION PRINCIPLE (ISP)
# ════════════════════════════════════════════════════════════

# ❌ BAD: Fat interface forces irrelevant method implementations
class IWorkerBad(ABC):
    @abstractmethod
    def work(self) -> str: ...

    @abstractmethod
    def eat(self) -> str: ...

    @abstractmethod
    def sleep(self) -> str: ...


class RobotBad(IWorkerBad):
    def work(self) -> str:
        return "Working..."

    def eat(self) -> str:
        raise NotImplementedError("Robots don't eat!")  # ← Forced to implement nonsense

    def sleep(self) -> str:
        raise NotImplementedError("Robots don't sleep!")  # ← Forced to implement nonsense


# ✅ GOOD: Lean interfaces — each client depends only on what it needs
class Workable(Protocol):
    def work(self) -> str: ...


class Feedable(Protocol):
    def eat(self) -> str: ...


class Sleepable(Protocol):
    def sleep(self) -> str: ...


class HumanWorker:
    """Implements all three — because humans work, eat, AND sleep."""

    def work(self) -> str:
        return "Human working"

    def eat(self) -> str:
        return "Human eating"

    def sleep(self) -> str:
        return "Human sleeping"


class RobotWorker:
    """Implements ONLY Workable — no nonsensical eat()/sleep()."""

    def work(self) -> str:
        return "Robot working"


def assign_task(worker: Workable) -> str:
    """Only cares about work() — doesn't force eat() or sleep()."""
    return worker.work()


# ════════════════════════════════════════════════════════════
# D — DEPENDENCY INVERSION PRINCIPLE (DIP)
# ════════════════════════════════════════════════════════════

# ❌ BAD: High-level module directly depends on low-level module
class MySQLDatabase:
    def save(self, data: dict) -> None:
        print(f"  💾 Saving to MySQL: {data}")


class OrderServiceBad:
    def __init__(self) -> None:
        self._db = MySQLDatabase()  # ← Hardcoded dependency on MySQL

    def place_order(self, order: dict) -> None:
        self._db.save(order)


# ✅ GOOD: Both depend on an abstraction (Protocol)
class Database(Protocol):
    """The abstraction both high-level and low-level modules depend on."""

    def save(self, data: dict) -> None: ...


class MySQLDB:
    def save(self, data: dict) -> None:
        print(f"  💾 Saving to MySQL: {data}")


class PostgresDB:
    def save(self, data: dict) -> None:
        print(f"  💾 Saving to PostgreSQL: {data}")


class InMemoryDB:
    """Perfect for testing — swap in without changing OrderService."""

    def __init__(self) -> None:
        self.store: list[dict] = []

    def save(self, data: dict) -> None:
        self.store.append(data)
        print(f"  💾 Saving to InMemory: {data}")


class OrderService:
    """Depends on Database PROTOCOL, not a specific implementation."""

    def __init__(self, db: Database) -> None:
        self._db = db  # ← Injected abstraction

    def place_order(self, order: dict) -> None:
        self._db.save(order)


# ════════════════════════════════════════════════════════════
# DEMO
# ════════════════════════════════════════════════════════════
if __name__ == "__main__":
    print("=" * 60)
    print("S — SINGLE RESPONSIBILITY PRINCIPLE")
    print("=" * 60)
    email_svc = EmailService()
    logger = AppLogger()
    user_svc = UserService(email_svc, logger)
    user = user_svc.create_user("Alice", "alice@example.com")
    print(f"  Created: {user}")
    print()

    print("=" * 60)
    print("O — OPEN/CLOSED PRINCIPLE")
    print("=" * 60)
    amount = 100.0
    for strategy in [GoldDiscount(), SilverDiscount(), PlatinumDiscount()]:
        discount = calculate_discount_good(strategy, amount)
        print(f"  {strategy.__class__.__name__}: ${amount} → discount ${discount:.2f}")
    print()

    print("=" * 60)
    print("L — LISKOV SUBSTITUTION PRINCIPLE")
    print("=" * 60)
    shapes: list[Shape] = [Rectangle(5, 10), Square(7)]
    for s in shapes:
        print(f"  {s.__class__.__name__}:", end="")
        print_area(s)
    print()

    print("=" * 60)
    print("I — INTERFACE SEGREGATION PRINCIPLE")
    print("=" * 60)
    human = HumanWorker()
    robot = RobotWorker()
    print(f"  {assign_task(human)}")
    print(f"  {assign_task(robot)}")
    print()

    print("=" * 60)
    print("D — DEPENDENCY INVERSION PRINCIPLE")
    print("=" * 60)
    # Swap database implementation without changing OrderService
    for db in [MySQLDB(), PostgresDB(), InMemoryDB()]:
        order_svc = OrderService(db)
        order_svc.place_order({"item": "Widget", "qty": 3})
    print()

    print("✅ All SOLID principles demonstrated successfully!")

"""
============================================================
Example: Classic Singleton with __new__ Override
Pattern: Singleton (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
An application needs a single AppConfig object that loads settings
from environment variables ONCE and is shared across all modules.
Creating multiple AppConfig instances would waste memory and risk
inconsistent state.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Singleton → AppConfig (overrides __new__)
- _instance → class-level reference to the single object

KEY INSIGHT:
------------
__new__ controls object CREATION (before __init__). By overriding
it, we intercept the construction process and return the existing
instance instead of creating a new one.

============================================================
"""

import os


class AppConfig:
    """
    Application configuration — guaranteed single instance.

    Uses __new__ to intercept object creation. The _initialized
    flag prevents __init__ from re-running on subsequent calls.
    """

    _instance: "AppConfig | None" = None

    def __new__(cls) -> "AppConfig":
        # __new__ is called BEFORE __init__ — this is where we
        # control whether a new object is actually created
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._initialized = False
        return cls._instance

    def __init__(self) -> None:
        # __init__ is called EVERY time AppConfig() is invoked,
        # even when __new__ returns the existing instance.
        # The _initialized flag prevents re-initialization.
        if self._initialized:
            return

        # Expensive initialization — runs only ONCE
        self.debug: bool = os.getenv("DEBUG", "false").lower() == "true"
        self.db_host: str = os.getenv("DB_HOST", "localhost")
        self.db_port: int = int(os.getenv("DB_PORT", "5432"))
        self.app_name: str = "MyApplication"
        self._initialized = True
        print(f"  ⚙️  AppConfig initialized (debug={self.debug}, db={self.db_host}:{self.db_port})")

    @classmethod
    def _reset(cls) -> None:
        """For testing only — destroys the singleton to allow re-creation."""
        cls._instance = None

    def __repr__(self) -> str:
        return f"AppConfig(app={self.app_name}, db={self.db_host}:{self.db_port})"


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("CLASSIC SINGLETON — __new__ Override")
    print("=" * 60)

    # First call → creates the instance
    config1 = AppConfig()
    print(f"  config1: {config1}")
    print(f"  id(config1): {id(config1)}")
    print()

    # Second call → returns the SAME instance (no re-init message)
    config2 = AppConfig()
    print(f"  config2: {config2}")
    print(f"  id(config2): {id(config2)}")
    print()

    # Proof: they are the SAME object
    print(f"  config1 is config2: {config1 is config2}")
    assert config1 is config2, "Singleton contract violated!"

    # Mutating one affects the other (same object)
    config1.app_name = "ModifiedApp"
    assert config2.app_name == "ModifiedApp", "Shared state broken!"
    print(f"  After mutation: config2.app_name = '{config2.app_name}'")
    print()

    # Reset for testing
    AppConfig._reset()
    config3 = AppConfig()
    print(f"  After reset: config3 is config1? {config3 is config1}")
    assert config3 is not config1, "Reset should create a new instance!"

    print()
    print("✅ Classic Singleton demonstrated successfully!")

"""
============================================================
Example: Thread-Safe Singleton with Double-Checked Locking
Pattern: Singleton (Creational)
Framework: Pure Python (threading)
============================================================

REAL-WORLD SCENARIO:
--------------------
A connection pool manager in a multi-threaded web server. Multiple
request threads may try to create the pool simultaneously on startup.
Without thread safety, two pools could be created — wasting resources
and causing subtle bugs.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Singleton → ConnectionPool (thread-safe __new__)
- _lock → threading.Lock (guards first creation)
- _instance → the single pool object

KEY INSIGHT:
------------
Double-checked locking: the outer check avoids the lock overhead on
every call (fast path), while the inner check prevents race conditions
during first creation (safe path).

============================================================
"""

import threading
import time


class ConnectionPool:
    """
    Thread-safe Singleton connection pool.

    Uses double-checked locking to minimize lock overhead:
    - Outer check: fast path — no lock acquired if instance exists
    - Inner check: safe path — prevents two threads from both creating
    """

    _instance: "ConnectionPool | None" = None
    _lock: threading.Lock = threading.Lock()

    def __new__(cls, pool_size: int = 5) -> "ConnectionPool":
        if cls._instance is None:                  # Fast path (no lock)
            with cls._lock:                         # Acquire lock
                if cls._instance is None:           # Double-check (safe path)
                    instance = super().__new__(cls)
                    instance._initialized = False
                    cls._instance = instance
        return cls._instance

    def __init__(self, pool_size: int = 5) -> None:
        if self._initialized:
            return

        # Simulate expensive pool creation
        self.pool_size = pool_size
        self.connections: list[str] = [
            f"conn_{i}" for i in range(pool_size)
        ]
        self._initialized = True
        print(f"  🔗 ConnectionPool created with {pool_size} connections (thread: {threading.current_thread().name})")

    def get_connection(self) -> str:
        """Get a connection from the pool."""
        if self.connections:
            return self.connections.pop()
        raise RuntimeError("No connections available!")

    def return_connection(self, conn: str) -> None:
        """Return a connection to the pool."""
        self.connections.append(conn)

    @classmethod
    def _reset(cls) -> None:
        """For testing only."""
        cls._instance = None

    def __repr__(self) -> str:
        return f"ConnectionPool(size={self.pool_size}, available={len(self.connections)})"


def worker(worker_id: int, results: dict[int, int]) -> None:
    """Simulate a worker thread accessing the singleton."""
    pool = ConnectionPool(pool_size=10)
    results[worker_id] = id(pool)
    # Small sleep to increase chance of race condition in naive impl
    time.sleep(0.01)


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("THREAD-SAFE SINGLETON — Double-Checked Locking")
    print("=" * 60)

    # Launch 10 threads simultaneously — all should get the SAME instance
    results: dict[int, int] = {}
    threads = [
        threading.Thread(target=worker, args=(i, results), name=f"Worker-{i}")
        for i in range(10)
    ]

    print("\n  Launching 10 threads simultaneously...")
    for t in threads:
        t.start()
    for t in threads:
        t.join()

    # Verify ALL threads got the same instance
    unique_ids = set(results.values())
    print(f"\n  Thread results (object IDs): {list(results.values())[:5]}...")
    print(f"  Unique instances created: {len(unique_ids)}")
    assert len(unique_ids) == 1, f"Thread safety violated! Got {len(unique_ids)} instances"
    print(f"  All 10 threads share the same instance ✅")

    # Verify the pool works
    pool = ConnectionPool()
    print(f"\n  Pool state: {pool}")
    conn = pool.get_connection()
    print(f"  Got connection: {conn}")
    pool.return_connection(conn)
    print(f"  Returned: {conn}")

    print("\n✅ Thread-Safe Singleton demonstrated successfully!")

"""
============================================================
Example: Singleton via Metaclass (Reusable)
Pattern: Singleton (Creational)
Framework: Pure Python (simulating Django-style settings)
============================================================

REAL-WORLD SCENARIO:
--------------------
Django's settings module exposes a single LazySettings object that
wraps the project's settings. Here we simulate the same concept:
a Settings class that loads configuration lazily (on first access)
and is guaranteed to be a singleton via a reusable metaclass.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- SingletonMeta → metaclass that enforces single-instance per class
- Settings → the singleton class (analogous to Django's LazySettings)
- CacheManager → another singleton using the SAME metaclass

KEY INSIGHT:
------------
A metaclass-based Singleton is REUSABLE — any class can become a
singleton by simply declaring `metaclass=SingletonMeta`. No code
duplication. The metaclass stores instances in a per-class dict,
so subclasses get their own instances (fixing the inheritance bug).

============================================================
"""

import threading


class SingletonMeta(type):
    """
    Metaclass that makes any class a thread-safe Singleton.

    Usage:
        class MyService(metaclass=SingletonMeta):
            pass

    How it works:
    - type.__call__ is what runs when you write MyClass()
    - We override __call__ to check if an instance already exists
    - Stores instances in a per-class dict, so subclasses work correctly
    """

    _instances: dict[type, object] = {}
    _lock: threading.Lock = threading.Lock()

    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            with cls._lock:
                if cls not in cls._instances:
                    instance = super().__call__(*args, **kwargs)
                    cls._instances[cls] = instance
        return cls._instances[cls]

    def _reset(cls) -> None:
        """Remove the stored instance (for testing)."""
        cls._instances.pop(cls, None)


# ─── Django-Style Settings Singleton ───────────────

class Settings(metaclass=SingletonMeta):
    """
    Simulates Django's settings object.

    In Django: django.conf.settings is a LazySettings singleton.
    Here we demonstrate the same concept with a metaclass.
    """

    def __init__(self) -> None:
        # This runs only ONCE (metaclass prevents re-creation)
        self.DEBUG: bool = True
        self.DATABASE: dict = {
            "ENGINE": "django.db.backends.postgresql",
            "HOST": "localhost",
            "PORT": 5432,
            "NAME": "myapp_db",
        }
        self.SECRET_KEY: str = "super-secret-key-do-not-share"
        self.INSTALLED_APPS: list[str] = [
            "django.contrib.auth",
            "django.contrib.admin",
            "myapp.core",
        ]
        print(f"  ⚙️  Settings loaded (DEBUG={self.DEBUG})")

    def __repr__(self) -> str:
        return f"Settings(DEBUG={self.DEBUG}, DB={self.DATABASE['NAME']})"


class CacheManager(metaclass=SingletonMeta):
    """
    Another singleton using the SAME metaclass.
    Demonstrates reusability — no code duplication!
    """

    def __init__(self, backend: str = "redis") -> None:
        self.backend = backend
        self._cache: dict[str, object] = {}
        print(f"  💾 CacheManager initialized (backend={backend})")

    def set(self, key: str, value: object) -> None:
        self._cache[key] = value

    def get(self, key: str) -> object | None:
        return self._cache.get(key)

    def __repr__(self) -> str:
        return f"CacheManager(backend={self.backend}, entries={len(self._cache)})"


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("METACLASS SINGLETON — Reusable Across Classes")
    print("=" * 60)

    # Settings singleton
    print("\n--- Settings ---")
    s1 = Settings()
    s2 = Settings()
    print(f"  s1: {s1}")
    print(f"  s2: {s2}")
    print(f"  s1 is s2: {s1 is s2}")
    assert s1 is s2, "Settings singleton violated!"

    # CacheManager singleton (SAME metaclass, DIFFERENT instance)
    print("\n--- CacheManager ---")
    c1 = CacheManager(backend="redis")
    c2 = CacheManager(backend="memcached")  # Ignored — already created
    print(f"  c1: {c1}")
    print(f"  c2: {c2}")
    print(f"  c1 is c2: {c1 is c2}")
    print(f"  c2.backend: '{c2.backend}'  (still 'redis' — init ran only once)")
    assert c1 is c2, "CacheManager singleton violated!"

    # Settings and CacheManager are DIFFERENT singletons
    print("\n--- Cross-Class Independence ---")
    print(f"  Settings is CacheManager? {s1 is c1}")
    assert s1 is not c1, "Different classes should have different instances!"

    # Cache actually works
    c1.set("user:123", {"name": "Alice"})
    result = c2.get("user:123")
    print(f"  Cache set via c1, get via c2: {result}")
    assert result == {"name": "Alice"}, "Shared state broken!"

    print("\n✅ Metaclass Singleton demonstrated successfully!")

"""
============================================================
Example: Borg / Monostate Pattern (Singleton Alternative)
Pattern: Singleton (Creational) — Variant
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A logging configuration where multiple Logger instances are fine
(different identity / id()), but they MUST share the same state
(same log level, same handlers, same formatter). Borg achieves
this by sharing __dict__ across all instances.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Borg base class → shares __dict__ across all instances
- LoggerConfig → concrete Borg that shares logging state

KEY INSIGHT:
------------
Singleton: same IDENTITY (same object, same id())
Borg:      same STATE   (different objects, shared __dict__)

Borg is more Pythonic and subclass-friendly. It also plays nicer
with pickling and copying since instances are "real" objects.

============================================================
"""

from typing import Any


class Borg:
    """
    The Borg pattern (a.k.a. Monostate).

    All instances share the SAME __dict__, so they have the same
    state even though they are different objects (different id()).

    Named after the Star Trek Borg: "We are one. Resistance is futile."
    """

    _shared_state: dict[str, Any] = {}

    def __init__(self) -> None:
        # Point this instance's __dict__ to the shared state
        # This is the magic — all instances now share attributes
        self.__dict__ = self._shared_state


class LoggerConfig(Borg):
    """
    Shared logging configuration using Borg pattern.

    Every LoggerConfig instance sees the same log_level, handlers,
    and formatter — because they all share __dict__.
    """

    def __init__(
        self,
        log_level: str = "INFO",
        formatter: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    ) -> None:
        super().__init__()

        # Only initialize if not already set (first instance)
        if not hasattr(self, "_initialized"):
            self.log_level = log_level
            self.formatter = formatter
            self.handlers: list[str] = ["console"]
            self._initialized = True
            print(f"  📋 LoggerConfig initialized (level={log_level})")

    def add_handler(self, handler: str) -> None:
        if handler not in self.handlers:
            self.handlers.append(handler)
            print(f"  ➕ Added handler: {handler}")

    def set_level(self, level: str) -> None:
        self.log_level = level
        print(f"  🔧 Log level changed to: {level}")

    def __repr__(self) -> str:
        return f"LoggerConfig(level={self.log_level}, handlers={self.handlers})"


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("BORG / MONOSTATE PATTERN")
    print("=" * 60)

    # Create first instance
    logger1 = LoggerConfig(log_level="DEBUG")
    print(f"  logger1: {logger1}")
    print(f"  id(logger1): {id(logger1)}")
    print()

    # Create second instance — shares state with first
    logger2 = LoggerConfig()
    print(f"  logger2: {logger2}")
    print(f"  id(logger2): {id(logger2)}")
    print()

    # Key difference from Singleton: DIFFERENT objects, SAME state
    print(f"  logger1 is logger2: {logger1 is logger2}")  # False!
    print(f"  logger1.__dict__ is logger2.__dict__: {logger1.__dict__ is logger2.__dict__}")  # True!
    assert logger1 is not logger2, "Borg creates different objects"
    assert logger1.__dict__ is logger2.__dict__, "Borg shares __dict__"
    print()

    # Mutating one affects the other (shared state)
    logger1.add_handler("file")
    logger1.set_level("WARNING")
    print(f"\n  After logger1 mutations:")
    print(f"  logger2.log_level: {logger2.log_level}")
    print(f"  logger2.handlers: {logger2.handlers}")
    assert logger2.log_level == "WARNING", "Shared state broken!"
    assert "file" in logger2.handlers, "Shared state broken!"

    # Comparison table
    print()
    print("  ╔════════════════════╦═══════════════════════════╗")
    print("  ║                    ║  Singleton vs Borg        ║")
    print("  ╠════════════════════╬═══════════════════════════╣")
    print("  ║ Identity (is)      ║  Same obj  vs  Diff objs  ║")
    print("  ║ State (__dict__)   ║  Same      vs  Same       ║")
    print(f"  ║ id(a) == id(b)     ║  True      vs  {id(logger1) == id(logger2):<14}║")
    print("  ║ Subclass-friendly  ║  Tricky    vs  Easy       ║")
    print("  ║ Pickle/Copy        ║  Tricky    vs  Works      ║")
    print("  ╚════════════════════╩═══════════════════════════╝")

    print("\n✅ Borg / Monostate pattern demonstrated successfully!")

"""
============================================================
Example: Basic Factory with Registry Pattern
Pattern: Factory Method (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A document processing system that needs to parse files in multiple
formats (JSON, XML, CSV, YAML). The format is determined at runtime
from the file extension. Adding new formats should require zero
changes to existing code.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Product → Parser (Protocol)
- ConcreteProducts → JSONParser, XMLParser, CSVParser
- Factory → ParserFactory (registry-based)

KEY INSIGHT:
------------
The registry pattern (dict mapping) is the most Pythonic factory.
New parsers self-register via decorator — zero changes to the factory.

============================================================
"""

from typing import Protocol, Any
import json
import csv
import io


# ─── Product Interface ─────────────────────────────

class Parser(Protocol):
    """All parsers must implement this interface."""

    def parse(self, raw_data: str) -> Any: ...
    def file_extensions(self) -> list[str]: ...


# ─── Concrete Products ─────────────────────────────

class JSONParser:
    """Parses JSON strings into Python dicts/lists."""

    def parse(self, raw_data: str) -> Any:
        return json.loads(raw_data)

    def file_extensions(self) -> list[str]:
        return [".json"]


class CSVParser:
    """Parses CSV strings into list of dicts."""

    def parse(self, raw_data: str) -> list[dict]:
        reader = csv.DictReader(io.StringIO(raw_data))
        return list(reader)

    def file_extensions(self) -> list[str]:
        return [".csv"]


class XMLParser:
    """Simple XML tag extractor (lightweight, no external deps)."""

    def parse(self, raw_data: str) -> dict[str, str]:
        # Minimal XML parsing using string operations
        # In production you'd use xml.etree.ElementTree
        import re
        tags = re.findall(r"<(\w+)>(.*?)</\1>", raw_data)
        return dict(tags)

    def file_extensions(self) -> list[str]:
        return [".xml"]


# ─── Factory (Registry-Based) ──────────────────────

class ParserFactory:
    """
    Registry-based factory.

    Parsers register themselves by format name. The factory creates
    the right parser based on the requested format. Adding new
    formats requires ZERO changes to this class (OCP).
    """

    _registry: dict[str, type] = {}

    @classmethod
    def register(cls, fmt: str, parser_class: type) -> None:
        """Register a parser class for a format name."""
        cls._registry[fmt.lower()] = parser_class

    @classmethod
    def create(cls, fmt: str) -> Parser:
        """Create a parser instance for the given format."""
        fmt_lower = fmt.lower().lstrip(".")
        if fmt_lower not in cls._registry:
            available = ", ".join(sorted(cls._registry.keys()))
            raise ValueError(
                f"Unknown format: '{fmt}'. Available: {available}"
            )
        return cls._registry[fmt_lower]()

    @classmethod
    def available_formats(cls) -> list[str]:
        """List all registered formats."""
        return sorted(cls._registry.keys())


# Register built-in parsers
ParserFactory.register("json", JSONParser)
ParserFactory.register("csv", CSVParser)
ParserFactory.register("xml", XMLParser)


# ─── Adding a NEW format (zero changes to factory!) ─

class INIParser:
    """Parses simple INI-style key=value strings."""

    def parse(self, raw_data: str) -> dict[str, str]:
        result = {}
        for line in raw_data.strip().splitlines():
            line = line.strip()
            if "=" in line and not line.startswith("#"):
                key, value = line.split("=", 1)
                result[key.strip()] = value.strip()
        return result

    def file_extensions(self) -> list[str]:
        return [".ini", ".cfg"]


# Just register — factory code untouched!
ParserFactory.register("ini", INIParser)


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("FACTORY METHOD — Registry-Based Parser Factory")
    print("=" * 60)

    # Test data for each format
    test_data = {
        "json": '{"name": "Alice", "age": 30, "city": "NYC"}',
        "csv": "name,age,city\nAlice,30,NYC\nBob,25,LA",
        "xml": "<name>Alice</name><age>30</age><city>NYC</city>",
        "ini": "name = Alice\nage = 30\ncity = NYC",
    }

    print(f"\n  Available formats: {ParserFactory.available_formats()}")

    for fmt, data in test_data.items():
        parser = ParserFactory.create(fmt)
        result = parser.parse(data)
        print(f"\n  [{fmt.upper()}] {parser.__class__.__name__}")
        print(f"    Input:  {data[:50]}...")
        print(f"    Output: {result}")

    # Error handling for unknown format
    print()
    try:
        ParserFactory.create("yaml")
    except ValueError as e:
        print(f"  ⚠️  Expected error: {e}")

    # Verify OCP: we added INI without touching ParserFactory
    assert "ini" in ParserFactory.available_formats()
    ini_parser = ParserFactory.create("ini")
    result = ini_parser.parse("host = localhost\nport = 5432")
    assert result == {"host": "localhost", "port": "5432"}

    print("\n✅ Factory Method demonstrated successfully!")

"""
============================================================
Example: Serializer Factory — Multi-Format Serialization
Pattern: Factory Method (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
An API needs to serialize response data in different formats
(JSON, XML, YAML-like) based on the Accept header. Each format
has its own serializer, but the API handler shouldn't know about
the concrete serializer classes.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Product → Serializer (ABC)
- ConcreteProducts → JSONSerializer, XMLSerializer, PlainTextSerializer
- Creator → SerializerFactory (classmethod-based)

KEY INSIGHT:
------------
The factory method here is a @classmethod alternative constructor
pattern — very Pythonic. `Serializer.for_content_type("application/json")`
reads like natural English.

============================================================
"""

from abc import ABC, abstractmethod
from typing import Any


# ─── Product (Abstract) ────────────────────────────

class Serializer(ABC):
    """Abstract serializer — all formats implement this."""

    @abstractmethod
    def serialize(self, data: dict[str, Any]) -> str:
        """Convert a dict to a formatted string."""
        ...

    @abstractmethod
    def content_type(self) -> str:
        """Return the MIME content type."""
        ...

    # ─── Factory Method (classmethod) ──────────────
    @classmethod
    def for_content_type(cls, content_type: str) -> "Serializer":
        """
        Factory method: create the right serializer for a content type.

        This is the Pythonic 'alternative constructor' pattern.
        """
        registry: dict[str, type[Serializer]] = {
            "application/json": JSONSerializer,
            "text/xml": XMLSerializer,
            "application/xml": XMLSerializer,
            "text/plain": PlainTextSerializer,
        }
        normalized = content_type.lower().strip()
        if normalized not in registry:
            raise ValueError(
                f"Unsupported content type: '{content_type}'. "
                f"Supported: {list(registry.keys())}"
            )
        return registry[normalized]()


# ─── Concrete Products ─────────────────────────────

class JSONSerializer(Serializer):
    """Serializes data as JSON."""

    def serialize(self, data: dict[str, Any]) -> str:
        import json
        return json.dumps(data, indent=2)

    def content_type(self) -> str:
        return "application/json"


class XMLSerializer(Serializer):
    """Serializes data as simple XML."""

    def serialize(self, data: dict[str, Any]) -> str:
        lines = ["<response>"]
        for key, value in data.items():
            lines.append(f"  <{key}>{value}</{key}>")
        lines.append("</response>")
        return "\n".join(lines)

    def content_type(self) -> str:
        return "text/xml"


class PlainTextSerializer(Serializer):
    """Serializes data as key=value plain text."""

    def serialize(self, data: dict[str, Any]) -> str:
        return "\n".join(f"{k}: {v}" for k, v in data.items())

    def content_type(self) -> str:
        return "text/plain"


# ─── Simulated API Handler ─────────────────────────

def handle_request(data: dict[str, Any], accept_header: str) -> str:
    """
    Simulated API endpoint.

    The handler doesn't know about JSONSerializer, XMLSerializer, etc.
    It only talks to the Serializer interface through the factory method.
    """
    serializer = Serializer.for_content_type(accept_header)
    body = serializer.serialize(data)
    return f"Content-Type: {serializer.content_type()}\n\n{body}"


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("FACTORY METHOD — Serializer Factory")
    print("=" * 60)

    sample_data = {
        "id": 42,
        "name": "Alice",
        "email": "alice@example.com",
        "active": True,
    }

    # Simulate different clients requesting different formats
    accept_headers = [
        "application/json",
        "text/xml",
        "text/plain",
    ]

    for accept in accept_headers:
        print(f"\n  --- Request: Accept: {accept} ---")
        response = handle_request(sample_data, accept)
        print(f"{response}")

    # Error handling
    print("\n  --- Request: Accept: text/html ---")
    try:
        handle_request(sample_data, "text/html")
    except ValueError as e:
        print(f"  ⚠️  {e}")

    # Verify polymorphism: handler never imports concrete classes
    s1 = Serializer.for_content_type("application/json")
    s2 = Serializer.for_content_type("text/xml")
    assert isinstance(s1, JSONSerializer)
    assert isinstance(s2, XMLSerializer)
    assert s1.content_type() != s2.content_type()

    print("\n✅ Serializer Factory demonstrated successfully!")

"""
============================================================
Example: FastAPI-Style Dependency Injection as Factory
Pattern: Factory Method (Creational)
Framework: FastAPI-inspired (pure Python simulation)
============================================================

REAL-WORLD SCENARIO:
--------------------
In FastAPI, `Depends()` is essentially a factory method — you
declare WHAT dependency you need, and the framework creates it
for you. This example simulates how FastAPI's DI works under
the hood, showing that Depends() IS the Factory Method pattern.

PATTERN PARTICIPANTS IN THIS EXAMPLE:
--------------------------------------
- Product → Database session, AuthService, etc.
- Factory → Dependency functions (get_db, get_auth_service)
- Creator → The DI framework that calls the factories

KEY INSIGHT:
------------
FastAPI's Depends() is Factory Method in disguise. The dependency
function IS the factory — it creates and yields the right resource.
The endpoint never knows HOW the resource was created.

============================================================
"""

from dataclasses import dataclass, field
from typing import Any, Callable, Generator
from contextlib import contextmanager


# ─── Simulated Database ────────────────────────────

@dataclass
class DatabaseSession:
    """Simulates a database session (like SQLAlchemy Session)."""
    db_url: str
    _queries: list[str] = field(default_factory=list)
    _committed: bool = False

    def execute(self, query: str) -> str:
        self._queries.append(query)
        return f"Result of: {query}"

    def commit(self) -> None:
        self._committed = True

    def close(self) -> None:
        pass  # Cleanup

    def __repr__(self) -> str:
        return f"DBSession(url={self.db_url}, queries={len(self._queries)})"


# ─── Dependency Factories (the "factory methods") ──

def get_db() -> Generator[DatabaseSession, None, None]:
    """
    Factory that creates a database session.

    This IS the Factory Method — FastAPI calls this function,
    gets a session, injects it into the endpoint, and cleans
    up after the request.
    """
    db = DatabaseSession(db_url="postgresql://localhost/myapp")
    try:
        yield db
        db.commit()
    finally:
        db.close()


@dataclass
class AuthService:
    """Simulates an authentication service."""
    secret_key: str = "my-jwt-secret"

    def verify_token(self, token: str) -> dict[str, Any]:
        # Simplified — in reality, decode JWT
        if token == "valid-token":
            return {"user_id": 42, "role": "admin"}
        raise PermissionError("Invalid token")


def get_auth_service() -> AuthService:
    """Factory for AuthService — no cleanup needed, so no generator."""
    return AuthService(secret_key="production-secret-key")


@dataclass
class CurrentUser:
    user_id: int
    role: str


def get_current_user(
    token: str = "valid-token",
    auth: AuthService | None = None,
) -> CurrentUser:
    """
    Factory that DEPENDS ON another factory (chained DI).

    In FastAPI: Depends(get_current_user) which itself uses
    Depends(get_auth_service). Factories composing factories!
    """
    if auth is None:
        auth = get_auth_service()
    payload = auth.verify_token(token)
    return CurrentUser(user_id=payload["user_id"], role=payload["role"])


# ─── Simulated DI Container ────────────────────────

class DependencyInjector:
    """
    Simplified version of how FastAPI's Depends() works internally.

    This IS the Factory Method pattern: the injector calls factory
    functions and provides their results to the endpoint.
    """

    def __init__(self) -> None:
        self._overrides: dict[Callable, Callable] = {}

    def override(self, original: Callable, replacement: Callable) -> None:
        """Override a dependency (for testing)."""
        self._overrides[original] = replacement

    def resolve(self, factory: Callable) -> Any:
        """
        Resolve a dependency by calling its factory.

        If overridden (for testing), call the override instead.
        """
        actual_factory = self._overrides.get(factory, factory)
        result = actual_factory()

        # Handle generators (like get_db which yields)
        if hasattr(result, "__next__"):
            return next(result)
        return result


# ─── Simulated FastAPI Endpoints ───────────────────

def list_users_endpoint(db: DatabaseSession, user: CurrentUser) -> dict:
    """
    Simulated endpoint.

    In FastAPI this would be:
        @app.get("/users")
        def list_users(db: Session = Depends(get_db),
                       user: CurrentUser = Depends(get_current_user)):

    The endpoint doesn't know HOW db or user were created.
    It just USES them. That's Factory Method + DI.
    """
    if user.role != "admin":
        return {"error": "Forbidden"}

    result = db.execute("SELECT * FROM users")
    return {"data": result, "requested_by": user.user_id}


# ─── Usage / Demo ──────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("FACTORY METHOD — FastAPI-Style Dependency Injection")
    print("=" * 60)

    injector = DependencyInjector()

    # Resolve dependencies using factories
    print("\n  --- Production Dependencies ---")
    db = injector.resolve(get_db)
    print(f"  DB: {db}")

    auth = injector.resolve(get_auth_service)
    print(f"  Auth: {auth}")

    user = injector.resolve(get_current_user)
    print(f"  User: {user}")

    # Call endpoint with injected dependencies
    response = list_users_endpoint(db=db, user=user)
    print(f"  Response: {response}")

    # ── Testing: Override factories ──────────────────
    print("\n  --- Test Dependencies (Overridden) ---")

    # Create test doubles
    def get_test_db() -> DatabaseSession:
        return DatabaseSession(db_url="sqlite:///:memory:")

    def get_test_user() -> CurrentUser:
        return CurrentUser(user_id=999, role="tester")

    injector.override(get_db, get_test_db)
    injector.override(get_current_user, get_test_user)

    test_db = injector.resolve(get_db)
    test_user = injector.resolve(get_current_user)
    print(f"  Test DB: {test_db}")
    print(f"  Test User: {test_user}")

    assert test_db.db_url == "sqlite:///:memory:", "Override should use test DB"
    assert test_user.role == "tester", "Override should use test user"

    print("\n  Key insight: Depends() IS Factory Method!")
    print("  The dependency function = the factory")
    print("  The framework = the client that calls the factory")
    print("  Override for testing = swap the factory, not the product")

    print("\n✅ FastAPI-Style Dependency Factory demonstrated successfully!")

"""
============================================================
Example: Cross-Platform GUI Toolkit Factory
Pattern: Abstract Factory (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A cross-platform desktop app needs to render native-looking UI
widgets (buttons, checkboxes, text inputs) for Windows, macOS,
and Linux. Each platform has its own look and feel, but all widgets
must come from the SAME platform — no mixing Mac buttons with
Windows checkboxes.

KEY INSIGHT:
------------
Abstract Factory guarantees family consistency. Swap the factory,
and ALL products change together. The client code never knows
which platform it's running on.

============================================================
"""

from abc import ABC, abstractmethod
from typing import Protocol
import sys


# ─── Abstract Products ─────────────────────────────

class Button(Protocol):
    def render(self) -> str: ...
    def on_click(self, handler: str) -> str: ...

class Checkbox(Protocol):
    def render(self) -> str: ...
    def toggle(self) -> str: ...

class TextInput(Protocol):
    def render(self) -> str: ...
    def set_value(self, text: str) -> str: ...


# ─── Abstract Factory ──────────────────────────────

class GUIFactory(ABC):
    """Abstract factory — declares creation methods for each widget type."""

    @abstractmethod
    def create_button(self, label: str) -> Button: ...

    @abstractmethod
    def create_checkbox(self, label: str) -> Checkbox: ...

    @abstractmethod
    def create_text_input(self, placeholder: str) -> TextInput: ...


# ─── macOS Family ───────────────────────────────────

class MacButton:
    def __init__(self, label: str) -> None:
        self.label = label

    def render(self) -> str:
        return f"  🍎 [  {self.label}  ] (rounded macOS button)"

    def on_click(self, handler: str) -> str:
        return f"  🍎 Button '{self.label}' → {handler}"


class MacCheckbox:
    def __init__(self, label: str) -> None:
        self.label = label
        self.checked = False

    def render(self) -> str:
        icon = "☑" if self.checked else "☐"
        return f"  🍎 {icon} {self.label} (macOS checkbox)"

    def toggle(self) -> str:
        self.checked = not self.checked
        return self.render()


class MacTextInput:
    def __init__(self, placeholder: str) -> None:
        self.placeholder = placeholder
        self.value = ""

    def render(self) -> str:
        display = self.value or self.placeholder
        return f"  🍎 ╭─────────────────╮\n     │ {display:<15} │ (macOS input)\n     ╰─────────────────╯"

    def set_value(self, text: str) -> str:
        self.value = text
        return self.render()


class MacFactory(GUIFactory):
    def create_button(self, label: str) -> Button:
        return MacButton(label)

    def create_checkbox(self, label: str) -> Checkbox:
        return MacCheckbox(label)

    def create_text_input(self, placeholder: str) -> TextInput:
        return MacTextInput(placeholder)


# ─── Windows Family ────────────────────────────────

class WinButton:
    def __init__(self, label: str) -> None:
        self.label = label

    def render(self) -> str:
        return f"  🪟 [ {self.label} ] (flat Windows button)"

    def on_click(self, handler: str) -> str:
        return f"  🪟 Button '{self.label}' → {handler}"


class WinCheckbox:
    def __init__(self, label: str) -> None:
        self.label = label
        self.checked = False

    def render(self) -> str:
        icon = "[x]" if self.checked else "[ ]"
        return f"  🪟 {icon} {self.label} (Windows checkbox)"

    def toggle(self) -> str:
        self.checked = not self.checked
        return self.render()


class WinTextInput:
    def __init__(self, placeholder: str) -> None:
        self.placeholder = placeholder
        self.value = ""

    def render(self) -> str:
        display = self.value or self.placeholder
        return f"  🪟 |{display:<17}| (Windows input)"

    def set_value(self, text: str) -> str:
        self.value = text
        return self.render()


class WindowsFactory(GUIFactory):
    def create_button(self, label: str) -> Button:
        return WinButton(label)

    def create_checkbox(self, label: str) -> Checkbox:
        return WinCheckbox(label)

    def create_text_input(self, placeholder: str) -> TextInput:
        return WinTextInput(placeholder)


# ─── Factory Selector ──────────────────────────────

def get_factory(platform: str = "") -> GUIFactory:
    """Select the right factory based on platform."""
    if not platform:
        platform = sys.platform
    factories: dict[str, type[GUIFactory]] = {
        "darwin": MacFactory,
        "mac": MacFactory,
        "win32": WindowsFactory,
        "windows": WindowsFactory,
    }
    factory_class = factories.get(platform, MacFactory)
    return factory_class()


# ─── Application (Client) ──────────────────────────

def render_login_form(factory: GUIFactory) -> None:
    """
    The application code doesn't know which platform's widgets
    it's using. It only talks to the abstract factory + products.
    """
    print("  ── Login Form ──")
    username = factory.create_text_input("Enter username")
    password = factory.create_text_input("Enter password")
    remember = factory.create_checkbox("Remember me")
    submit = factory.create_button("Sign In")

    print(username.render())
    print(password.render())
    print(remember.render())
    print(submit.render())


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("ABSTRACT FACTORY — Cross-Platform GUI Toolkit")
    print("=" * 60)

    for platform in ["mac", "windows"]:
        print(f"\n  ═══ Platform: {platform.upper()} ═══")
        factory = get_factory(platform)
        render_login_form(factory)

    # Key point: the SAME render_login_form() code works with
    # BOTH factories — zero platform-specific code in the client
    print()
    assert isinstance(get_factory("mac"), MacFactory)
    assert isinstance(get_factory("windows"), WindowsFactory)

    print("✅ Abstract Factory demonstrated successfully!")

"""
============================================================
Example: Database Connector Abstract Factory
Pattern: Abstract Factory (Creational)
Framework: SQLAlchemy-inspired
============================================================

REAL-WORLD SCENARIO:
--------------------
An ORM needs to support multiple databases (PostgreSQL, SQLite).
Each database requires matching components: connection, cursor,
and query compiler. Mixing a PostgreSQL connection with a SQLite
compiler would be catastrophic. Abstract Factory ensures all
components come from the same database family.

KEY INSIGHT:
------------
SQLAlchemy's dialect system IS an Abstract Factory. create_engine()
selects the right dialect, which then produces matching connections,
type objects, and SQL compilers.

============================================================
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass


# ─── Abstract Products ─────────────────────────────

class Connection(ABC):
    @abstractmethod
    def connect(self) -> str: ...
    @abstractmethod
    def close(self) -> str: ...

class Cursor(ABC):
    @abstractmethod
    def execute(self, query: str) -> str: ...

class QueryCompiler(ABC):
    @abstractmethod
    def compile_select(self, table: str, columns: list[str]) -> str: ...
    @abstractmethod
    def compile_insert(self, table: str, data: dict) -> str: ...


# ─── PostgreSQL Family ─────────────────────────────

class PostgresConnection(Connection):
    def connect(self) -> str:
        return "  🐘 Connected to PostgreSQL on port 5432"
    def close(self) -> str:
        return "  🐘 PostgreSQL connection closed"

class PostgresCursor(Cursor):
    def execute(self, query: str) -> str:
        return f"  🐘 PG executing: {query}"

class PostgresCompiler(QueryCompiler):
    def compile_select(self, table: str, columns: list[str]) -> str:
        cols = ", ".join(columns)
        return f'SELECT {cols} FROM "{table}"'  # PG uses double quotes

    def compile_insert(self, table: str, data: dict) -> str:
        cols = ", ".join(data.keys())
        vals = ", ".join(f"'{v}'" for v in data.values())
        return f'INSERT INTO "{table}" ({cols}) VALUES ({vals}) RETURNING id'


# ─── SQLite Family ──────────────────────────────────

class SQLiteConnection(Connection):
    def connect(self) -> str:
        return "  💾 Connected to SQLite (file: ./app.db)"
    def close(self) -> str:
        return "  💾 SQLite connection closed"

class SQLiteCursor(Cursor):
    def execute(self, query: str) -> str:
        return f"  💾 SQLite executing: {query}"

class SQLiteCompiler(QueryCompiler):
    def compile_select(self, table: str, columns: list[str]) -> str:
        cols = ", ".join(columns)
        return f"SELECT {cols} FROM [{table}]"  # SQLite uses brackets

    def compile_insert(self, table: str, data: dict) -> str:
        cols = ", ".join(data.keys())
        vals = ", ".join(f"'{v}'" for v in data.values())
        return f"INSERT INTO [{table}] ({cols}) VALUES ({vals})"


# ─── Abstract Factory ──────────────────────────────

class DatabaseFactory(ABC):
    """Abstract factory for database component families."""

    @abstractmethod
    def create_connection(self) -> Connection: ...

    @abstractmethod
    def create_cursor(self) -> Cursor: ...

    @abstractmethod
    def create_compiler(self) -> QueryCompiler: ...


class PostgresFactory(DatabaseFactory):
    def create_connection(self) -> Connection:
        return PostgresConnection()
    def create_cursor(self) -> Cursor:
        return PostgresCursor()
    def create_compiler(self) -> QueryCompiler:
        return PostgresCompiler()


class SQLiteFactory(DatabaseFactory):
    def create_connection(self) -> Connection:
        return SQLiteConnection()
    def create_cursor(self) -> Cursor:
        return SQLiteCursor()
    def create_compiler(self) -> QueryCompiler:
        return SQLiteCompiler()


# ─── Engine (like SQLAlchemy's create_engine) ──────

def create_engine(url: str) -> DatabaseFactory:
    """
    Simulates SQLAlchemy's create_engine().

    The URL determines which abstract factory (dialect) to use.
    All components produced by that factory are guaranteed to
    be compatible with each other.
    """
    scheme = url.split("://")[0].lower()
    factories: dict[str, type[DatabaseFactory]] = {
        "postgresql": PostgresFactory,
        "postgres": PostgresFactory,
        "sqlite": SQLiteFactory,
    }
    if scheme not in factories:
        raise ValueError(f"Unsupported database: {scheme}")
    return factories[scheme]()


# ─── ORM-like Client ───────────────────────────────

def run_queries(factory: DatabaseFactory) -> None:
    """
    Client code — doesn't know if it's talking to PG or SQLite.
    All components come from the same family (abstract factory).
    """
    conn = factory.create_connection()
    cursor = factory.create_cursor()
    compiler = factory.create_compiler()

    print(conn.connect())

    # Compile and execute a SELECT
    select_sql = compiler.compile_select("users", ["id", "name", "email"])
    print(cursor.execute(select_sql))

    # Compile and execute an INSERT
    insert_sql = compiler.compile_insert("users", {"name": "Alice", "email": "alice@example.com"})
    print(cursor.execute(insert_sql))

    print(conn.close())


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("ABSTRACT FACTORY — Database Connector (SQLAlchemy-style)")
    print("=" * 60)

    for url in ["postgresql://localhost/myapp", "sqlite:///./app.db"]:
        print(f"\n  ═══ Engine: {url} ═══")
        engine = create_engine(url)
        run_queries(engine)

    # The SAME run_queries() function works with both databases
    # because it only depends on the abstract factory interface
    assert isinstance(create_engine("postgresql://x"), PostgresFactory)
    assert isinstance(create_engine("sqlite:///x"), SQLiteFactory)

    print("\n✅ Database Abstract Factory demonstrated successfully!")

"""
============================================================
Example: SQL Query Builder with Fluent API
Pattern: Builder (Creational)
Framework: Pure Python (SQLAlchemy-inspired)
============================================================

REAL-WORLD SCENARIO:
--------------------
Building SQL queries programmatically. A query has many optional
parts (WHERE, ORDER BY, LIMIT, JOIN, GROUP BY). Using a builder
with method chaining makes construction readable and prevents
SQL injection through parameterized values.

KEY INSIGHT:
------------
Each method returns `self`, enabling fluent chaining:
QueryBuilder("users").select("name").where("active=true").limit(10).build()

============================================================
"""

from dataclasses import dataclass, field
from typing import Self


@dataclass
class Query:
    """The product — an immutable SQL query."""
    sql: str
    params: dict[str, object] = field(default_factory=dict)

    def __str__(self) -> str:
        return f"SQL: {self.sql}\nParams: {self.params}"


class QueryBuilder:
    """
    Fluent SQL query builder.

    Each method returns `self` (using `Self` type hint from Python 3.11+)
    to enable method chaining. The build() method produces the final Query.
    """

    def __init__(self, table: str) -> None:
        self._table = table
        self._columns: list[str] = ["*"]
        self._conditions: list[str] = []
        self._order: list[str] = []
        self._limit: int | None = None
        self._offset: int | None = None
        self._joins: list[str] = []
        self._group_by: list[str] = []
        self._params: dict[str, object] = {}

    def select(self, *columns: str) -> Self:
        """Set columns to select."""
        self._columns = list(columns)
        return self

    def where(self, condition: str, **params: object) -> Self:
        """Add a WHERE condition with optional named parameters."""
        self._conditions.append(condition)
        self._params.update(params)
        return self

    def join(self, table: str, on: str) -> Self:
        """Add a JOIN clause."""
        self._joins.append(f"JOIN {table} ON {on}")
        return self

    def order_by(self, column: str, desc: bool = False) -> Self:
        """Add ORDER BY clause."""
        direction = "DESC" if desc else "ASC"
        self._order.append(f"{column} {direction}")
        return self

    def group_by(self, *columns: str) -> Self:
        """Add GROUP BY clause."""
        self._group_by = list(columns)
        return self

    def limit(self, n: int) -> Self:
        """Set LIMIT."""
        self._limit = n
        return self

    def offset(self, n: int) -> Self:
        """Set OFFSET."""
        self._offset = n
        return self

    def build(self) -> Query:
        """Assemble and return the final Query product."""
        parts = [f"SELECT {', '.join(self._columns)}"]
        parts.append(f"FROM {self._table}")

        if self._joins:
            parts.extend(self._joins)
        if self._conditions:
            parts.append(f"WHERE {' AND '.join(self._conditions)}")
        if self._group_by:
            parts.append(f"GROUP BY {', '.join(self._group_by)}")
        if self._order:
            parts.append(f"ORDER BY {', '.join(self._order)}")
        if self._limit is not None:
            parts.append(f"LIMIT {self._limit}")
        if self._offset is not None:
            parts.append(f"OFFSET {self._offset}")

        return Query(sql="\n".join(parts), params=self._params)


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("BUILDER — SQL Query Builder with Fluent API")
    print("=" * 60)

    # Simple query
    print("\n  --- Simple SELECT ---")
    q1 = QueryBuilder("users").select("id", "name", "email").build()
    print(f"  {q1.sql}")

    # Complex query with all options
    print("\n  --- Complex Query ---")
    q2 = (
        QueryBuilder("orders")
        .select("orders.id", "users.name", "orders.total")
        .join("users", "users.id = orders.user_id")
        .where("orders.status = :status", status="completed")
        .where("orders.total > :min_total", min_total=100)
        .order_by("orders.total", desc=True)
        .limit(20)
        .offset(0)
        .build()
    )
    print(f"  {q2}")

    # Aggregation query
    print("\n  --- Aggregation ---")
    q3 = (
        QueryBuilder("products")
        .select("category", "COUNT(*) as count", "AVG(price) as avg_price")
        .where("active = true")
        .group_by("category")
        .order_by("count", desc=True)
        .limit(5)
        .build()
    )
    print(f"  {q3.sql}")

    # Verify builder produces correct SQL
    assert "SELECT id, name, email" in q1.sql
    assert "JOIN users ON" in q2.sql
    assert "WHERE" in q2.sql
    assert "LIMIT 20" in q2.sql
    assert q2.params == {"status": "completed", "min_total": 100}
    assert "GROUP BY category" in q3.sql

    print("\n✅ Query Builder demonstrated successfully!")

"""
============================================================
Example: HTTP Request Builder
Pattern: Builder (Creational)
Framework: Pure Python (requests-inspired)
============================================================

REAL-WORLD SCENARIO:
--------------------
Building HTTP requests with many optional parts: URL, method,
headers, query parameters, body, timeout, authentication.
A builder makes this readable and prevents argument-order confusion.

KEY INSIGHT:
------------
The builder validates constraints at build() time, not during
individual set calls. This allows flexible construction order
while ensuring the final product is always valid.

============================================================
"""

from dataclasses import dataclass, field
from typing import Any, Self
import json


@dataclass(frozen=True)
class HTTPRequest:
    """Immutable HTTP request product."""
    method: str
    url: str
    headers: dict[str, str]
    params: dict[str, str]
    body: str | None
    timeout: int
    auth: tuple[str, str] | None

    def __str__(self) -> str:
        lines = [f"{self.method} {self.url}"]
        if self.params:
            qs = "&".join(f"{k}={v}" for k, v in self.params.items())
            lines[0] += f"?{qs}"
        for k, v in self.headers.items():
            lines.append(f"  {k}: {v}")
        if self.body:
            lines.append(f"  Body: {self.body[:80]}...")
        return "\n".join(lines)


class RequestBuilder:
    """Fluent HTTP request builder."""

    def __init__(self, url: str) -> None:
        self._url = url
        self._method = "GET"
        self._headers: dict[str, str] = {}
        self._params: dict[str, str] = {}
        self._body: str | None = None
        self._timeout = 30
        self._auth: tuple[str, str] | None = None

    def method(self, m: str) -> Self:
        self._method = m.upper()
        return self

    def get(self) -> Self:
        return self.method("GET")

    def post(self) -> Self:
        return self.method("POST")

    def put(self) -> Self:
        return self.method("PUT")

    def delete(self) -> Self:
        return self.method("DELETE")

    def header(self, key: str, value: str) -> Self:
        self._headers[key] = value
        return self

    def content_type(self, ct: str) -> Self:
        return self.header("Content-Type", ct)

    def accept(self, ct: str) -> Self:
        return self.header("Accept", ct)

    def bearer_token(self, token: str) -> Self:
        return self.header("Authorization", f"Bearer {token}")

    def param(self, key: str, value: str) -> Self:
        self._params[key] = value
        return self

    def json_body(self, data: dict[str, Any]) -> Self:
        self._body = json.dumps(data)
        self.content_type("application/json")
        return self

    def timeout(self, seconds: int) -> Self:
        self._timeout = seconds
        return self

    def basic_auth(self, username: str, password: str) -> Self:
        self._auth = (username, password)
        return self

    def build(self) -> HTTPRequest:
        # Validation at build time
        if not self._url:
            raise ValueError("URL is required")
        if self._method in ("POST", "PUT", "PATCH") and not self._body:
            raise ValueError(f"{self._method} requires a body")

        return HTTPRequest(
            method=self._method,
            url=self._url,
            headers=dict(self._headers),
            params=dict(self._params),
            body=self._body,
            timeout=self._timeout,
            auth=self._auth,
        )


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("BUILDER — HTTP Request Builder")
    print("=" * 60)

    # Simple GET request
    print("\n  --- Simple GET ---")
    req1 = (
        RequestBuilder("https://api.example.com/users")
        .get()
        .accept("application/json")
        .param("page", "1")
        .param("limit", "20")
        .timeout(10)
        .build()
    )
    print(f"  {req1}")

    # Authenticated POST request
    print("\n  --- Authenticated POST ---")
    req2 = (
        RequestBuilder("https://api.example.com/orders")
        .post()
        .bearer_token("eyJ0eXAiOiJKV1QiLCJhbG...")
        .json_body({"item": "Widget", "qty": 3, "price": 29.99})
        .timeout(30)
        .build()
    )
    print(f"  {req2}")

    # Validation: POST without body should fail
    print("\n  --- Validation ---")
    try:
        RequestBuilder("https://api.example.com/bad").post().build()
    except ValueError as e:
        print(f"  ⚠️  Expected error: {e}")

    assert req1.method == "GET"
    assert req2.method == "POST"
    assert "Bearer" in req2.headers.get("Authorization", "")
    assert req1.timeout == 10

    print("\n✅ HTTP Request Builder demonstrated successfully!")

"""
============================================================
Example: Document Cloning with Deep Copy
Pattern: Prototype (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A document management system where users create documents from
templates. Instead of building each document from scratch (loading
fonts, styles, headers, footers), clone a template and customize.

KEY INSIGHT:
------------
Deep copy creates a fully independent clone. Modifying the clone
has ZERO effect on the original (or any other clones).

============================================================
"""

import copy
from dataclasses import dataclass, field


@dataclass
class Style:
    font: str = "Arial"
    size: int = 12
    color: str = "#000000"
    bold: bool = False


@dataclass
class Document:
    """A document that can be cloned from a template."""
    title: str
    content: str
    author: str
    styles: dict[str, Style] = field(default_factory=dict)
    tags: list[str] = field(default_factory=list)
    metadata: dict[str, str] = field(default_factory=dict)

    def clone(self) -> "Document":
        """Prototype method — deep copy to ensure full independence."""
        return copy.deepcopy(self)

    def __str__(self) -> str:
        styles_str = ", ".join(f"{k}:{v.font}/{v.size}" for k, v in self.styles.items())
        return (
            f"Document('{self.title}' by {self.author}, "
            f"tags={self.tags}, styles=[{styles_str}])"
        )


# ─── Template Registry ─────────────────────────────

class TemplateRegistry:
    """Registry of document templates (prototypes)."""

    _templates: dict[str, Document] = {}

    @classmethod
    def register(cls, name: str, template: Document) -> None:
        cls._templates[name] = template

    @classmethod
    def create_from(cls, name: str, **overrides: str) -> Document:
        """Clone a template and apply overrides."""
        if name not in cls._templates:
            raise ValueError(f"Template '{name}' not found")
        doc = cls._templates[name].clone()
        for key, value in overrides.items():
            setattr(doc, key, value)
        return doc


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("PROTOTYPE — Document Cloning")
    print("=" * 60)

    # Create a rich template (expensive to build from scratch)
    report_template = Document(
        title="Quarterly Report Template",
        content="[Report content placeholder]",
        author="Template",
        styles={
            "heading": Style(font="Helvetica", size=24, bold=True),
            "body": Style(font="Georgia", size=11, color="#333333"),
            "footer": Style(font="Arial", size=8, color="#999999"),
        },
        tags=["report", "quarterly"],
        metadata={"version": "1.0", "department": "Engineering"},
    )
    TemplateRegistry.register("report", report_template)

    # Clone and customize — much faster than rebuilding from scratch
    print("\n  --- Cloning from template ---")
    q1_report = TemplateRegistry.create_from(
        "report", title="Q1 2025 Report", author="Alice"
    )
    q1_report.tags.append("Q1")
    q1_report.metadata["quarter"] = "Q1"
    print(f"  Clone 1: {q1_report}")

    q2_report = TemplateRegistry.create_from(
        "report", title="Q2 2025 Report", author="Bob"
    )
    q2_report.tags.append("Q2")
    q2_report.styles["heading"].color = "#0066cc"
    print(f"  Clone 2: {q2_report}")

    # Verify deep independence
    print("\n  --- Independence check ---")
    print(f"  Template tags: {report_template.tags}")
    print(f"  Q1 tags:       {q1_report.tags}")
    print(f"  Q2 tags:       {q2_report.tags}")
    print(f"  Template heading color: {report_template.styles['heading'].color}")
    print(f"  Q2 heading color:       {q2_report.styles['heading'].color}")

    assert "Q1" not in report_template.tags, "Template should be unmodified!"
    assert "Q2" not in q1_report.tags, "Q1 should be independent of Q2!"
    assert report_template.styles["heading"].color == "#000000", "Template style unchanged!"
    assert q2_report.styles["heading"].color == "#0066cc", "Clone style changed!"

    print("\n✅ Document Cloning demonstrated successfully!")

"""
============================================================
Example: Game Object Prototypes Registry
Pattern: Prototype (Creational)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A game engine needs to spawn thousands of enemies, items, and
terrain tiles. Each type starts from a prototype (template) with
base stats, then gets randomized variations. Building each from
scratch with full initialization (loading sprites, calculating
stats) is too slow. Clone and customize instead.

KEY INSIGHT:
------------
A prototype registry (like a spawner catalog) lets you register
base objects once, then rapidly clone + customize. This is how
real game engines handle object pooling and spawning.

============================================================
"""

import copy
import random
from dataclasses import dataclass, field


@dataclass
class Stats:
    health: int
    attack: int
    defense: int
    speed: float


@dataclass
class GameObject:
    name: str
    category: str
    stats: Stats
    abilities: list[str] = field(default_factory=list)
    loot_table: dict[str, float] = field(default_factory=dict)
    position: tuple[float, float] = (0.0, 0.0)

    def clone(self) -> "GameObject":
        return copy.deepcopy(self)

    def randomize(self, variance: float = 0.2) -> "GameObject":
        """Add random variance to stats (for mob variety)."""
        s = self.stats
        factor = lambda: 1.0 + random.uniform(-variance, variance)
        self.stats = Stats(
            health=int(s.health * factor()),
            attack=int(s.attack * factor()),
            defense=int(s.defense * factor()),
            speed=round(s.speed * factor(), 1),
        )
        return self

    def __str__(self) -> str:
        s = self.stats
        return (
            f"{self.name} [{self.category}] "
            f"HP:{s.health} ATK:{s.attack} DEF:{s.defense} SPD:{s.speed} "
            f"@ {self.position}"
        )


class GameObjectSpawner:
    """Prototype registry — stores base prototypes, spawns clones."""

    _prototypes: dict[str, GameObject] = {}

    @classmethod
    def register(cls, key: str, prototype: GameObject) -> None:
        cls._prototypes[key] = prototype

    @classmethod
    def spawn(
        cls,
        key: str,
        position: tuple[float, float] = (0.0, 0.0),
        randomize: bool = True,
    ) -> GameObject:
        if key not in cls._prototypes:
            raise ValueError(f"Unknown prototype: '{key}'")
        obj = cls._prototypes[key].clone()
        obj.position = position
        if randomize:
            obj.randomize()
        return obj

    @classmethod
    def spawn_group(
        cls,
        key: str,
        count: int,
        area: tuple[float, float, float, float],
    ) -> list[GameObject]:
        """Spawn multiple clones in a rectangular area."""
        x_min, y_min, x_max, y_max = area
        return [
            cls.spawn(
                key,
                position=(
                    round(random.uniform(x_min, x_max), 1),
                    round(random.uniform(y_min, y_max), 1),
                ),
            )
            for _ in range(count)
        ]


# ─── Register prototypes ──────────────────────────
GameObjectSpawner.register("goblin", GameObject(
    name="Goblin",
    category="enemy",
    stats=Stats(health=50, attack=10, defense=5, speed=1.2),
    abilities=["slash", "dodge"],
    loot_table={"gold": 0.8, "potion": 0.3, "dagger": 0.05},
))

GameObjectSpawner.register("dragon", GameObject(
    name="Dragon",
    category="boss",
    stats=Stats(health=500, attack=80, defense=40, speed=0.8),
    abilities=["fire_breath", "tail_swipe", "fly"],
    loot_table={"gold": 1.0, "legendary_sword": 0.1, "dragon_scale": 0.5},
))

GameObjectSpawner.register("health_potion", GameObject(
    name="Health Potion",
    category="item",
    stats=Stats(health=0, attack=0, defense=0, speed=0),
    abilities=["heal_50"],
    loot_table={},
))


# ─── Demo ──────────────────────────────────────────
if __name__ == "__main__":
    random.seed(42)  # For reproducible demo output

    print("=" * 60)
    print("PROTOTYPE — Game Object Spawner")
    print("=" * 60)

    # Spawn individual enemies
    print("\n  --- Single Spawns ---")
    g1 = GameObjectSpawner.spawn("goblin", position=(10.0, 20.0))
    g2 = GameObjectSpawner.spawn("goblin", position=(15.0, 22.0))
    boss = GameObjectSpawner.spawn("dragon", position=(100.0, 100.0))
    print(f"  {g1}")
    print(f"  {g2}")
    print(f"  {boss}")

    # Verify independence (different stats due to randomization)
    assert g1.stats.health != g2.stats.health or g1.stats.attack != g2.stats.attack, \
        "Clones should have randomized stats"
    assert g1.position != g2.position, "Clones at different positions"

    # Spawn a group of goblins in an area
    print("\n  --- Group Spawn (5 goblins) ---")
    patrol = GameObjectSpawner.spawn_group("goblin", 5, (0, 0, 50, 50))
    for g in patrol:
        print(f"  {g}")

    # Verify prototype is unmodified
    print("\n  --- Prototype integrity check ---")
    proto = GameObjectSpawner._prototypes["goblin"]
    print(f"  Original prototype: {proto}")
    assert proto.stats.health == 50, "Prototype should be unchanged!"
    assert proto.position == (0.0, 0.0), "Prototype position unchanged!"

    # Items don't need randomization
    print("\n  --- Item spawn (no randomization) ---")
    potion = GameObjectSpawner.spawn("health_potion", position=(5, 5), randomize=False)
    print(f"  {potion}")

    print("\n✅ Game Object Spawner demonstrated successfully!")

"""
============================================================
Example: Object Adapter (Composition)
Pattern: Adapter (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a modern data analytics application that expects all
incoming data in JSON format. However, you need to integrate
a legacy third-party library that only exports data in XML.
You cannot change the analytics app (it expects a specific interface)
and you cannot change the 3rd party library (it's closed source).

You create an Adapter that wraps the legacy library, translates
the XML to JSON, and passes it to the analytics app.

KEY INSIGHT:
------------
This is the "Object Adapter" pattern, which uses composition.
The adapter holds a reference to the Adaptee (the legacy object).
This is generally preferred over Class Adapters (inheritance)
because it's more flexible and follows "Favor Composition over Inheritance".

============================================================
"""

from typing import Protocol
import json

# ─── Target (The interface the client expects) ─────────

class JSONProvider(Protocol):
    """The modern interface expected by our client."""
    def get_json_data(self) -> str: ...


# ─── Client (Our modern application) ───────────────────

class AnalyticsApp:
    """A modern app that only speaks JSON."""
    
    def process_data(self, provider: JSONProvider) -> None:
        print("  📊 AnalyticsApp is requesting data...")
        json_data = provider.get_json_data()
        
        # Parse the JSON just to prove it worked
        parsed = json.loads(json_data)
        print(f"  ✅ AnalyticsApp successfully processed: {parsed}")


# ─── Adaptee (The legacy / 3rd party component) ────────

class LegacyXMLAPI:
    """A legacy system that only speaks XML. We cannot modify this class."""
    
    def fetch_xml_records(self) -> str:
        print("  📻 LegacyXMLAPI generating XML...")
        return "<person><name>Alice</name><age>30</age></person>"


# ─── Adapter (The bridge between them) ─────────────────

class XMLToJSONAdapter:
    """
    Object Adapter using COMPOSITION.
    
    Implements the Target interface (JSONProvider) but routes
    the actual work to the wrapped Adaptee (LegacyXMLAPI).
    """
    
    def __init__(self, adaptee: LegacyXMLAPI) -> None:
        self._adaptee = adaptee
        
    def get_json_data(self) -> str:
        """Translate the Adaptee's interface into the Target interface."""
        print("  🔌 Adapter intercepting call to get_json_data()...")
        
        # 1. Call the adaptee
        xml_data = self._adaptee.fetch_xml_records()
        
        # 2. Translate the data (simulating XML parsing)
        print(f"  🔌 Adapter converting XML to JSON: {xml_data}")
        
        # Extremely simplified XML-to-JSON for demonstration purposes
        import re
        name_match = re.search(r"<name>(.*?)</name>", xml_data)
        age_match = re.search(r"<age>(.*?)</age>", xml_data)
        
        data_dict = {
            "name": name_match.group(1) if name_match else "Unknown",
            "age": int(age_match.group(1)) if age_match else 0
        }
        
        # 3. Return what the client expects
        return json.dumps(data_dict)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("OBJECT ADAPTER (Composition)")
    print("=" * 60)
    
    # 1. We have our client
    app = AnalyticsApp()
    
    # 2. We have the incompatible legacy object
    legacy_api = LegacyXMLAPI()
    
    # app.process_data(legacy_api)  <-- THIS WOULD CRASH (AttributeError)
    
    # 3. We wrap the legacy object in the adapter
    adapter = XMLToJSONAdapter(legacy_api)
    
    # 4. Client happily processes data, unaware of the XML under the hood
    app.process_data(adapter)
    
    print("\n✅ Object Adapter demonstrated successfully!")

"""
============================================================
Example: Class Adapter (Multiple Inheritance)
Pattern: Adapter (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a notification system that expects objects to have a
`send_alert(msg)` method. You have a third-party `TwilioSMS`
class that has a `dispatch_text_message(text)` method.

Instead of wrapping the Twilio object (Object Adapter), you create
a new class that inherits from BOTH the target interface and the
third-party class.

KEY INSIGHT:
------------
This is the "Class Adapter" pattern. It relies on Multiple Inheritance,
which is natively supported in Python. It does not require wrapping an
instance, but it tightly couples the adapter to the specific Adaptee class.
Because it uses inheritance, it cannot adapt subclasses of the Adaptee.

============================================================
"""

from typing import Protocol

# ─── Target (The interface the client expects) ─────────

class AlertSystem(Protocol):
    """The interface our system uses to send alerts."""
    def send_alert(self, message: str) -> None: ...


# ─── Client ────────────────────────────────────────────

def notify_admin(alerter: AlertSystem, message: str) -> None:
    """Client function that relies on the AlertSystem interface."""
    print("  🚨 System issue detected! Triggering alert...")
    alerter.send_alert(message)


# ─── Adaptee (The 3rd party class) ─────────────────────

class TwilioSMS:
    """Third-party SMS service with an incompatible API."""
    
    def dispatch_text_message(self, text: str) -> None:
        print(f"  📱 [Twilio API] Dispatching SMS: '{text}'")


# ─── Adapter (The bridge via Multiple Inheritance) ─────

class TwilioClassAdapter(TwilioSMS):
    """
    Class Adapter using MULTIPLE INHERITANCE (implicit Protocol implementation).
    
    Inherits from the Adaptee (TwilioSMS).
    Implements the Target interface (`send_alert`).
    """
    
    def send_alert(self, message: str) -> None:
        """Translates the Target interface to the Adaptee interface."""
        print("  🔌 Class Adapter intercepting send_alert()...")
        # Because we INHERIT from TwilioSMS, we just call `self`
        formatted_msg = f"URGENT: {message}"
        self.dispatch_text_message(formatted_msg)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("CLASS ADAPTER (Multiple Inheritance)")
    print("=" * 60)
    
    # We instantiate the ADAPTER directly.
    # We don't create a TwilioSMS object and pass it in.
    adapter = TwilioClassAdapter()
    
    # The client works with the adapter seamlessly
    notify_admin(adapter, "Database connection lost!")
    
    print()
    print("  Note: TwilioClassAdapter is a subclass of TwilioSMS.")
    print(f"  isinstance(adapter, TwilioSMS): {isinstance(adapter, TwilioSMS)}")
    
    print("\n✅ Class Adapter demonstrated successfully!")

"""
============================================================
Example: Device & Remote Control Bridge
Pattern: Bridge (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have devices (TV, Radio) and remote controls (Basic, Advanced).
Instead of creating `BasicTVRemote`, `AdvancedTVRemote`, `BasicRadioRemote`,
you separate them into two hierarchies connected by a bridge.

- Abstraction: Remote Control (High-level operations like toggle_power)
- Implementation: Device (Low-level operations like set_volume, enable)

KEY INSIGHT:
------------
You can add a new Device (e.g., SmartSpeaker) without touching ANY Remote code.
You can add a new Remote (e.g., VoiceRemote) without touching ANY Device code.
They vary completely independently.

============================================================
"""

from typing import Protocol

# ─── IMPLEMENTATION HIERARCHY (Low-Level) ───────────────

class Device(Protocol):
    """The Implementation interface."""
    def is_enabled(self) -> bool: ...
    def enable(self) -> None: ...
    def disable(self) -> None: ...
    def get_volume(self) -> int: ...
    def set_volume(self, percent: int) -> None: ...
    def get_channel(self) -> int: ...
    def set_channel(self, channel: int) -> None: ...


class TV:
    """Concrete Implementation 1"""
    def __init__(self) -> None:
        self._on = False
        self._volume = 30
        self._channel = 1
        
    def is_enabled(self) -> bool:
        return self._on
        
    def enable(self) -> None:
        self._on = True
        
    def disable(self) -> None:
        self._on = False
        
    def get_volume(self) -> int:
        return self._volume
        
    def set_volume(self, percent: int) -> None:
        self._volume = max(0, min(100, percent))
        
    def get_channel(self) -> int:
        return self._channel
        
    def set_channel(self, channel: int) -> None:
        self._channel = channel
        
    def __str__(self) -> str:
        state = "ON" if self._on else "OFF"
        return f"📺 TV is {state} (Vol: {self._volume}, Ch: {self._channel})"


class Radio:
    """Concrete Implementation 2"""
    def __init__(self) -> None:
        self._on = False
        self._volume = 50
        self._frequency = 88.1  # MHz instead of channels, but adapted to the interface
        
    def is_enabled(self) -> bool:
        return self._on
        
    def enable(self) -> None:
        self._on = True
        
    def disable(self) -> None:
        self._on = False
        
    def get_volume(self) -> int:
        return self._volume
        
    def set_volume(self, percent: int) -> None:
        self._volume = max(0, min(100, percent))
        
    def get_channel(self) -> int:
        return int(self._frequency * 10)
        
    def set_channel(self, channel: int) -> None:
        self._frequency = channel / 10.0
        
    def __str__(self) -> str:
        state = "ON" if self._on else "OFF"
        return f"📻 Radio is {state} (Vol: {self._volume}, Freq: {self._frequency}MHz)"


# ─── ABSTRACTION HIERARCHY (High-Level) ─────────────────

class RemoteControl:
    """
    The Base Abstraction.
    It holds a reference to the Implementation (Device) -- THIS IS THE BRIDGE!
    """
    def __init__(self, device: Device) -> None:
        self.device = device  # <--- The Bridge
        
    def toggle_power(self) -> None:
        if self.device.is_enabled():
            self.device.disable()
        else:
            self.device.enable()
            
    def volume_down(self) -> None:
        self.device.set_volume(self.device.get_volume() - 10)
        
    def volume_up(self) -> None:
        self.device.set_volume(self.device.get_volume() + 10)
        
    def channel_down(self) -> None:
        self.device.set_channel(self.device.get_channel() - 1)
        
    def channel_up(self) -> None:
        self.device.set_channel(self.device.get_channel() + 1)


class AdvancedRemoteControl(RemoteControl):
    """
    Refined Abstraction.
    Adds new features without touching the Device interface.
    """
    def mute(self) -> None:
        self.device.set_volume(0)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("BRIDGE PATTERN")
    print("=" * 60)
    
    # 1. Use Basic Remote with TV
    tv = TV()
    remote = RemoteControl(tv)
    
    print("  [Using Basic Remote with TV]")
    remote.toggle_power()
    remote.volume_up()
    print(f"  {tv}")
    
    print("\n  [Switching to Advanced Remote for the SAME TV]")
    advanced_remote = AdvancedRemoteControl(tv)
    advanced_remote.mute()
    print(f"  {tv}")
    
    # 2. Use Advanced Remote with Radio
    print("\n  [Using Advanced Remote with Radio]")
    radio = Radio()
    radio_remote = AdvancedRemoteControl(radio)
    
    radio_remote.toggle_power()
    radio_remote.channel_up()
    radio_remote.channel_up()
    print(f"  {radio}")
    
    print("\n✅ Bridge pattern demonstrated successfully!")

"""
============================================================
Example: File System (Files and Directories)
Pattern: Composite (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A file system consists of Files (Leaves) and Directories (Composites).
A Directory can contain Files AND other Directories.
If you ask for the size of a File, it returns its size in bytes.
If you ask for the size of a Directory, it recursively asks all its
children for their sizes and adds them up.

KEY INSIGHT:
------------
The client just calls `get_size()` or `render()`. It does not need
to check `if isinstance(child, Directory)`. The polymorphism handles
the recursion naturally.

============================================================
"""

from typing import Protocol


# ─── Component Interface ───────────────────────────────

class FileSystemNode(Protocol):
    """The Component interface that both Leaves and Composites implement."""
    
    @property
    def name(self) -> str: ...
    
    def get_size(self) -> int:
        """Returns size in bytes."""
        ...
        
    def render(self, depth: int = 0) -> str:
        """Renders the node as a string for tree visualization."""
        ...


# ─── Leaf ──────────────────────────────────────────────

class File:
    """Leaf node. Represents an actual file with a size. Has no children."""
    
    def __init__(self, name: str, size: int) -> None:
        self._name = name
        self._size = size
        
    @property
    def name(self) -> str:
        return self._name
        
    def get_size(self) -> int:
        return self._size
        
    def render(self, depth: int = 0) -> str:
        indent = "  " * depth
        return f"{indent}📄 {self.name} ({self.get_size()} bytes)"


# ─── Composite ─────────────────────────────────────────

class Directory:
    """
    Composite node. Contains children (which can be Files or other Directories).
    Routes calls to its children.
    """
    
    def __init__(self, name: str) -> None:
        self._name = name
        self._children: list[FileSystemNode] = []
        
    @property
    def name(self) -> str:
        return self._name
        
    def add(self, node: FileSystemNode) -> None:
        self._children.append(node)
        
    def remove(self, node: FileSystemNode) -> None:
        self._children.remove(node)
        
    def get_size(self) -> int:
        """
        Recursively calculates the size of the directory.
        Notice there is NO type checking (isinstance). It just calls get_size()!
        """
        return sum(child.get_size() for child in self._children)
        
    def render(self, depth: int = 0) -> str:
        """Recursively renders the directory tree."""
        indent = "  " * depth
        lines = [f"{indent}📁 {self.name}/ (Total: {self.get_size()} bytes)"]
        for child in self._children:
            lines.append(child.render(depth + 1))
        return "\n".join(lines)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("COMPOSITE PATTERN - File System")
    print("=" * 60)
    
    # 1. Create Leaves (Files)
    file1 = File("readme.md", 1024)
    file2 = File("logo.png", 2048)
    file3 = File("script.py", 512)
    file4 = File("secret_key.pem", 256)
    
    # 2. Create Composites (Directories) and build the tree
    root = Directory("root")
    
    docs = Directory("docs")
    docs.add(file1)
    docs.add(file2)
    
    src = Directory("src")
    src.add(file3)
    
    # We can put a directory inside a directory!
    hidden = Directory(".hidden")
    hidden.add(file4)
    src.add(hidden)
    
    # Add directories to root
    root.add(docs)
    root.add(src)
    
    # 3. Client interacts with the tree
    print("\n  [Rendering the entire File System Tree]")
    print(root.render())
    
    print("\n  [Client interacting with individual nodes vs the root]")
    print(f"  Size of {file3.name}: {file3.get_size()} bytes")
    print(f"  Size of {docs.name} directory: {docs.get_size()} bytes")
    print(f"  Size of entire {root.name} directory: {root.get_size()} bytes")
    
    print("\n✅ Composite pattern demonstrated successfully!")

"""
============================================================
Example: Coffee Shop (Object Decorator)
Pattern: Decorator (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You run a coffee shop. You have a base `Coffee` object. 
Customers can add various condiments: Milk, Whip, Vanilla, Caramel.
Instead of creating a subclass for every combination (`MilkCoffee`,
`MilkVanillaCoffee`, `DoubleWhipCaramelCoffee`), we use decorators.

Each decorator wraps the previous object, adding to its cost
and description.

KEY INSIGHT:
------------
Decorators have the SAME INTERFACE as the objects they decorate.
This allows them to be stacked infinitely.

============================================================
"""

from typing import Protocol


# ─── Component Interface ───────────────────────────────

class Beverage(Protocol):
    """The Component interface that both base beverages and decorators implement."""
    def get_description(self) -> str: ...
    def cost(self) -> float: ...


# ─── Concrete Components (The Base Objects) ────────────

class DarkRoast:
    def get_description(self) -> str:
        return "Dark Roast Coffee"
        
    def cost(self) -> float:
        return 2.50


class Espresso:
    def get_description(self) -> str:
        return "Espresso"
        
    def cost(self) -> float:
        return 1.99


# ─── Decorator Base Class (Optional but helpful) ───────

class CondimentDecorator:
    """
    Base Decorator. 
    It holds the wrapped component and implements the Beverage protocol.
    (In Python, this base class is optional due to duck typing, but it
    makes the pattern explicit).
    """
    def __init__(self, beverage: Beverage) -> None:
        self._beverage = beverage
        
    def get_description(self) -> str:
        return self._beverage.get_description()
        
    def cost(self) -> float:
        return self._beverage.cost()


# ─── Concrete Decorators ───────────────────────────────

class Milk(CondimentDecorator):
    def get_description(self) -> str:
        return f"{self._beverage.get_description()}, Milk"
        
    def cost(self) -> float:
        return self._beverage.cost() + 0.50


class Whip(CondimentDecorator):
    def get_description(self) -> str:
        return f"{self._beverage.get_description()}, Whip"
        
    def cost(self) -> float:
        return self._beverage.cost() + 0.70


class Vanilla(CondimentDecorator):
    def get_description(self) -> str:
        return f"{self._beverage.get_description()}, Vanilla Syrup"
        
    def cost(self) -> float:
        return self._beverage.cost() + 0.30


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("DECORATOR PATTERN - Coffee Shop")
    print("=" * 60)
    
    # 1. Plain Espresso
    beverage1 = Espresso()
    print("  [Order 1]")
    print(f"  Description: {beverage1.get_description()}")
    print(f"  Cost: ${beverage1.cost():.2f}")
    
    # 2. Dark Roast with Double Milk and Whip
    print("\n  [Order 2 - Stacking Decorators]")
    beverage2: Beverage = DarkRoast()
    beverage2 = Milk(beverage2)    # Wrap in Milk
    beverage2 = Milk(beverage2)    # Wrap in Milk again (Double Milk)
    beverage2 = Whip(beverage2)    # Wrap in Whip
    
    print(f"  Description: {beverage2.get_description()}")
    print(f"  Cost: ${beverage2.cost():.2f}")
    
    # 3. Espresso with Vanilla and Milk
    print("\n  [Order 3]")
    beverage3 = Milk(Vanilla(Espresso())) # You can nest them inline!
    
    print(f"  Description: {beverage3.get_description()}")
    print(f"  Cost: ${beverage3.cost():.2f}")
    
    print("\n✅ Decorator pattern demonstrated successfully!")

"""
============================================================
Example: Video Conversion Facade
Pattern: Facade (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You are building a video streaming app. You use a complex 3rd party
video conversion library (simulated here) with many classes: 
VideoFile, CodecFactory, BitrateReader, AudioMixer, etc.

To convert a video, you have to orchestrate 6 different classes in 
a specific order. If you put this logic in your UI code, your UI 
becomes tightly coupled to the video library.

Instead, you build a `VideoConverterFacade` that exposes a single
method: `convert(filename, format)`.

KEY INSIGHT:
------------
The client only talks to the Facade. The Facade orchestrates the
subsystem. If the 3rd party library changes its API, you only have
to update the Facade, not your entire application.

============================================================
"""

# ─── COMPLEX SUBSYSTEM (Simulated 3rd Party Library) ───

class VideoFile:
    def __init__(self, filename: str) -> None:
        self.filename = filename
        print(f"  [Subsystem] Loaded video file: {filename}")

class OggCompressionCodec:
    def get_type(self) -> str:
        return "ogg"

class MPEG4CompressionCodec:
    def get_type(self) -> str:
        return "mp4"

class CodecFactory:
    @staticmethod
    def extract(file: VideoFile) -> str:
        print(f"  [Subsystem] Extracting codec from {file.filename}...")
        return "mp4" if file.filename.endswith(".mp4") else "ogg"

class BitrateReader:
    @staticmethod
    def read(filename: str, source_codec: str) -> str:
        print(f"  [Subsystem] Reading file {filename} with codec {source_codec}...")
        return f"buffer_of_{filename}"

    @staticmethod
    def convert(buffer: str, destination_codec: object) -> str:
        print(f"  [Subsystem] Converting {buffer} to target codec...")
        return f"converted_{buffer}"

class AudioMixer:
    @staticmethod
    def fix_audio(result: str) -> str:
        print("  [Subsystem] Fixing audio sync issues...")
        return f"audio_synced_{result}"


# ─── FACADE ────────────────────────────────────────────

class VideoConverterFacade:
    """
    The Facade. It hides the complexity of the subsystem from the client.
    It provides a simple interface for the most common use case.
    """
    
    def convert(self, filename: str, format: str) -> str:
        print(f"\n🎬 Facade starting conversion of '{filename}' to '{format}'...")
        
        # The Facade handles all the ugly orchestration!
        file = VideoFile(filename)
        source_codec = CodecFactory.extract(file)
        
        if format == "mp4":
            destination_codec = MPEG4CompressionCodec()
        else:
            destination_codec = OggCompressionCodec()
            
        buffer = BitrateReader.read(filename, source_codec)
        result = BitrateReader.convert(buffer, destination_codec)
        final_result = AudioMixer.fix_audio(result)
        
        print("🎬 Facade finished conversion!")
        return final_result


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("FACADE PATTERN - Video Conversion")
    print("=" * 60)
    
    # Client Code
    # Look how simple the client code is! 
    # It knows nothing about CodecFactory, AudioMixer, or BitrateReader.
    
    converter = VideoConverterFacade()
    
    # Convert an OGG to MP4
    mp4_file = converter.convert("vacation_video.ogg", "mp4")
    print(f"\nClient received: {mp4_file}")
    
    print("\n✅ Facade pattern demonstrated successfully!")

"""
============================================================
Example: Forest Simulator (Tree Models vs Placements)
Pattern: Flyweight (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You are building a game that needs to render a forest with millions
of trees. If every tree contains its own 3D mesh and texture data,
you will run out of RAM instantly.

Solution:
1. Extract the shared data (name, color, texture) into a Flyweight (`TreeModel`).
2. Keep the unique data (x, y coordinates) in a Context class (`Tree`).
3. Use a Factory to ensure we only create one `TreeModel` per type.

KEY INSIGHT:
------------
Notice how `draw()` requires the extrinsic state (canvas, x, y) to
be passed in as arguments. The Flyweight itself has no idea WHERE it is.

============================================================
"""

from typing import Dict, List


# ─── 1. Flyweight (Intrinsic State) ─────────────────────────

class TreeModel:
    """
    The Flyweight. It contains state that is shared across many trees.
    This object should be IMMUTABLE.
    (Imagine `texture` is a massive 10MB byte array).
    """
    def __init__(self, name: str, color: str, texture: str) -> None:
        self.name = name
        self.color = color
        self.texture = texture
        
    def draw(self, canvas: str, x: int, y: int) -> None:
        """
        The operation. It takes the EXTRINSIC state (x, y) as arguments!
        """
        print(f"  🌳 Drawing [{self.name}] colored '{self.color}' at ({x}, {y})")


# ─── 2. Flyweight Factory ──────────────────────────────────

class TreeFactory:
    """
    Manages the Flyweights. Ensures we only ever create ONE instance
    of a specific TreeModel.
    """
    _tree_models: Dict[str, TreeModel] = {}

    @classmethod
    def get_tree_model(cls, name: str, color: str, texture: str) -> TreeModel:
        # Create a unique key for this combination of intrinsic state
        key = f"{name}_{color}_{texture}"
        
        if key not in cls._tree_models:
            print(f"  [Factory] Cache miss: Creating new TreeModel for '{key}'")
            cls._tree_models[key] = TreeModel(name, color, texture)
        else:
            print(f"  [Factory] Cache hit: Returning existing TreeModel for '{key}'")
            
        return cls._tree_models[key]


# ─── 3. Context (Extrinsic State) ──────────────────────────

class Tree:
    """
    The Context. It contains the extrinsic state (x, y) and a reference
    to the Flyweight (model). 
    This object is very lightweight (just a few bytes).
    """
    def __init__(self, x: int, y: int, model: TreeModel) -> None:
        self.x = x
        self.y = y
        self.model = model
        
    def draw(self, canvas: str) -> None:
        # Pass the extrinsic state to the Flyweight
        self.model.draw(canvas, self.x, self.y)


# ─── 4. Client Code ────────────────────────────────────────

class Forest:
    """The client that spawns the objects."""
    def __init__(self) -> None:
        self.trees: List[Tree] = []

    def plant_tree(self, x: int, y: int, name: str, color: str, texture: str) -> None:
        # Get the flyweight from the factory (reuses if it already exists)
        model = TreeFactory.get_tree_model(name, color, texture)
        
        # Create the lightweight context object
        tree = Tree(x, y, model)
        self.trees.append(tree)
        
    def draw(self, canvas: str) -> None:
        for tree in self.trees:
            tree.draw(canvas)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("FLYWEIGHT PATTERN - Forest Simulator")
    print("=" * 60)
    
    forest = Forest()
    
    print("\n  [Planting Oaks]")
    # Plant 3 Oaks. Notice the factory output: 1 cache miss, 2 cache hits.
    forest.plant_tree(10, 20, "Oak", "Green", "oak_texture.png")
    forest.plant_tree(15, 25, "Oak", "Green", "oak_texture.png")
    forest.plant_tree(50, 80, "Oak", "Green", "oak_texture.png")
    
    print("\n  [Planting Pines]")
    # Plant 2 Pines.
    forest.plant_tree(100, 200, "Pine", "Dark Green", "pine_texture.png")
    forest.plant_tree(105, 205, "Pine", "Dark Green", "pine_texture.png")
    
    print("\n  [Drawing the Forest]")
    forest.draw("MainCanvas")
    
    print("\n  [Memory Analysis]")
    num_trees = len(forest.trees)
    num_models = len(TreeFactory._tree_models)
    print(f"  Total Trees (Contexts) created: {num_trees}")
    print(f"  Total TreeModels (Flyweights) in memory: {num_models}")
    
    # We have 5 trees, but only 2 heavy model objects!
    assert num_trees == 5
    assert num_models == 2
    
    # Prove that the oaks share the exact same model instance
    oak1 = forest.trees[0]
    oak2 = forest.trees[1]
    assert oak1.model is oak2.model, "Flyweights are not being shared!"
    
    print("\n✅ Flyweight pattern demonstrated successfully!")

"""
============================================================
Example: Virtual & Protection Proxy
Pattern: Proxy (Structural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a highly sensitive, very resource-intensive `DatabaseDownloader`
object. 

1. It takes 3 seconds just to instantiate (establish connection).
2. It contains sensitive financial data.

We want to solve two problems:
- Don't establish the connection (instantiate) unless the user ACTUALLY
  requests data (Virtual Proxy / Lazy Loading).
- Don't allow the request if the user doesn't have the "admin" role
  (Protection Proxy).

KEY INSIGHT:
------------
The Proxy implements the exact same interface (`DownloaderProtocol`)
as the real object. The client has no idea it's talking to a proxy.

============================================================
"""

from typing import Protocol
import time

# ─── Subject (The Interface) ───────────────────────────

class DownloaderProtocol(Protocol):
    """The common interface for both the Real Subject and the Proxy."""
    def download_financial_report(self, user_role: str) -> str: ...


# ─── Real Subject (The Heavy, Sensitive Object) ────────

class RealDatabaseDownloader:
    """
    The RealSubject.
    It takes a long time to initialize and does the actual heavy lifting.
    """
    def __init__(self) -> None:
        print("  [RealSubject] ⏳ Initializing database connection (this is slow)...")
        time.sleep(1.5)  # Simulated heavy init
        print("  [RealSubject] ✅ Connection established!")
        
    def download_financial_report(self, user_role: str) -> str:
        # Note: The real subject doesn't check permissions.
        # It assumes whoever calls it is allowed. That's the Proxy's job!
        print("  [RealSubject] 💾 Downloading 500MB financial report...")
        return "FINANCIAL_REPORT_Q3_2026.pdf"


# ─── Proxy (The Gatekeeper) ────────────────────────────

class DatabaseProxy:
    """
    The Proxy.
    It acts as BOTH a Virtual Proxy (lazy loading) AND a Protection Proxy (security).
    """
    def __init__(self) -> None:
        # We DO NOT instantiate the real subject yet! (Virtual Proxy)
        self._real_downloader: RealDatabaseDownloader | None = None
        
    def check_access(self, role: str) -> bool:
        """Protection Proxy logic."""
        print(f"  [Proxy] Checking access for role '{role}'...")
        return role == "admin"
        
    def download_financial_report(self, user_role: str) -> str:
        # 1. Protection Proxy: Check permissions first
        if not self.check_access(user_role):
            print(f"  [Proxy] ❌ Access DENIED for role '{user_role}'.")
            return "ACCESS_DENIED"
            
        print(f"  [Proxy] 🔓 Access GRANTED for role '{user_role}'.")
        
        # 2. Virtual Proxy: Lazy-load the real subject
        if self._real_downloader is None:
            print("  [Proxy] First request! Creating the RealSubject now...")
            self._real_downloader = RealDatabaseDownloader()
        else:
            print("  [Proxy] RealSubject already exists. Using cached instance.")
            
        # 3. Delegation: Pass the request to the real subject
        return self._real_downloader.download_financial_report(user_role)


# ─── Client ────────────────────────────────────────────

def client_code(downloader: DownloaderProtocol, role: str) -> None:
    """
    The client operates against the interface.
    It doesn't know if 'downloader' is the RealSubject or the Proxy.
    """
    print(f"\n--- Client requesting report as '{role}' ---")
    result = downloader.download_financial_report(role)
    print(f"Client received: {result}")


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("PROXY PATTERN - Virtual & Protection Proxy")
    print("=" * 60)
    
    # Instantiate the proxy. Notice how FAST this is!
    # The expensive DB connection is NOT made yet.
    print("Instantiating proxy...")
    proxy = DatabaseProxy()
    print("Proxy instantiated (almost instantly).\n")
    
    # 1. Try as a guest (Protection Proxy blocks it)
    # The real subject is NEVER created! We saved 1.5 seconds.
    client_code(proxy, "guest")
    
    # 2. Try as an admin (Protection Proxy allows it)
    # The Virtual Proxy sees no real subject exists, so it creates it now.
    client_code(proxy, "admin")
    
    # 3. Try as an admin again
    # The Virtual Proxy reuses the existing real subject. Very fast!
    client_code(proxy, "admin")
    
    print("\n✅ Proxy pattern demonstrated successfully!")

"""
============================================================
Example: Customer Support Chain (Classic GoF)
Pattern: Chain of Responsibility (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A customer submits a support ticket with a certain severity.
- Severity 1 (Low): Handled by a Chatbot.
- Severity 2 (Medium): Handled by a Human Agent.
- Severity 3 (High): Handled by a Manager.

The client just sends the ticket to the first handler. If that
handler can't process it, it passes it down the chain. The FIRST
handler that can resolve the ticket does so, and the chain stops.

KEY INSIGHT:
------------
Notice the `BaseHandler` class. It implements the boilerplate for
managing the linked list (`set_next`). The concrete handlers only
need to implement the `handle()` logic.

============================================================
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class SupportTicket:
    id: int
    severity: int
    description: str


# ─── Handler Interface / Base Class ─────────────────────

class Handler(ABC):
    """
    The interface and base class for the Chain.
    It manages the `_next_handler` reference.
    """
    def __init__(self) -> None:
        self._next_handler: Optional["Handler"] = None
        
    def set_next(self, handler: "Handler") -> "Handler":
        """
        Sets the next handler in the chain.
        Returning the handler allows for a fluent interface:
        h1.set_next(h2).set_next(h3)
        """
        self._next_handler = handler
        return handler
        
    @abstractmethod
    def handle(self, ticket: SupportTicket) -> Optional[str]:
        """
        If this handler can't process the ticket, it delegates 
        to the next handler (if one exists).
        """
        if self._next_handler:
            return self._next_handler.handle(ticket)
        
        # End of the chain, no one handled it
        return None


# ─── Concrete Handlers ──────────────────────────────────

class ChatbotHandler(Handler):
    def handle(self, ticket: SupportTicket) -> Optional[str]:
        if ticket.severity == 1:
            print(f"  🤖 [Chatbot] Handling ticket {ticket.id}: {ticket.description}")
            return f"Chatbot resolved ticket {ticket.id} automatically."
        
        # Not severity 1, pass it down the chain!
        print(f"  🤖 [Chatbot] Cannot handle severity {ticket.severity}. Passing to Agent...")
        return super().handle(ticket)


class HumanAgentHandler(Handler):
    def handle(self, ticket: SupportTicket) -> Optional[str]:
        if ticket.severity == 2:
            print(f"  🧑‍💼 [Human Agent] Handling ticket {ticket.id}: {ticket.description}")
            return f"Agent resolved ticket {ticket.id}."
            
        print(f"  🧑‍💼 [Human Agent] Cannot handle severity {ticket.severity}. Passing to Manager...")
        return super().handle(ticket)


class ManagerHandler(Handler):
    def handle(self, ticket: SupportTicket) -> Optional[str]:
        if ticket.severity >= 3:
            print(f"  👔 [Manager] Handling urgent ticket {ticket.id}: {ticket.description}")
            return f"Manager resolved urgent ticket {ticket.id}."
            
        return super().handle(ticket)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("CHAIN OF RESPONSIBILITY - Classic (Support Tickets)")
    print("=" * 60)
    
    # 1. Instantiate the handlers
    chatbot = ChatbotHandler()
    agent = HumanAgentHandler()
    manager = ManagerHandler()
    
    # 2. Wire the chain together: Chatbot -> Agent -> Manager
    chatbot.set_next(agent).set_next(manager)
    
    # 3. Create some tickets
    tickets = [
        SupportTicket(101, 1, "How do I reset my password?"),
        SupportTicket(102, 2, "I was overcharged on my last bill."),
        SupportTicket(103, 3, "Production server is ON FIRE!"),
        SupportTicket(104, 0, "Wait, severity 0?"), # An unhandled case
    ]
    
    # 4. Client just sends all tickets to the FRONT of the chain (chatbot)
    for ticket in tickets:
        print(f"\n--- Submitting Ticket {ticket.id} (Severity {ticket.severity}) ---")
        result = chatbot.handle(ticket)
        
        if result:
            print(f"  ✅ Result: {result}")
        else:
            print(f"  ❌ UNHANDLED: No one in the chain could handle ticket {ticket.id}!")
            
    print("\n✅ Chain of Responsibility demonstrated successfully!")

"""
============================================================
Example: Web Middleware Chain (Modern)
Pattern: Chain of Responsibility (Behavioral)
Framework: Pure Python (FastAPI/Django style)
============================================================

REAL-WORLD SCENARIO:
--------------------
A modern web server receives an HTTP request. Before it reaches
the actual application logic (the view), it needs to pass through:
1. Logging Middleware
2. Authentication Middleware
3. Payload Validation Middleware

Unlike the classic GoF pattern (where the chain stops at the FIRST
handler that can process it), this "Middleware" chain passes the 
request through EVERY handler sequentially. Each handler can:
- Modify the request/response
- Stop the chain early (e.g., if Auth fails)
- Do work *after* the next handler returns (onion routing)

KEY INSIGHT:
------------
This is the architecture used by almost every modern web framework
(Django, Express, FastAPI, Starlette). It is a variation of the
Chain of Responsibility pattern.

============================================================
"""

from typing import Any, Callable, Dict

# The "Request" and "Response" objects
Request = Dict[str, Any]
Response = Dict[str, Any]

# A handler is a function that takes a Request and returns a Response
HandlerFunc = Callable[[Request], Response]


# ─── Middleware Base Class ─────────────────────────────

class Middleware:
    """
    The base class for our chain. 
    It holds a reference to the `next` middleware (or the final app).
    """
    def __init__(self) -> None:
        self._next_app: HandlerFunc | None = None
        
    def set_next(self, next_app: HandlerFunc) -> None:
        self._next_app = next_app
        
    def __call__(self, request: Request) -> Response:
        """
        By implementing __call__, our middleware acts like a function.
        Subclasses MUST implement this and call `self._next_app(request)`
        when they are ready to pass the request down the chain.
        """
        raise NotImplementedError()


# ─── Concrete Middleware (The Handlers) ────────────────

class LoggingMiddleware(Middleware):
    def __call__(self, request: Request) -> Response:
        print(f"  📝 [Logging] Received request to {request.get('path')}")
        
        # Pass to the next handler...
        if self._next_app:
            response = self._next_app(request)
        else:
            response = {"status": 500, "body": "No app attached"}
            
        # We can also do work ON THE WAY BACK UP! (Onion routing)
        print(f"  📝 [Logging] Sending response with status {response.get('status')}")
        return response


class AuthMiddleware(Middleware):
    def __call__(self, request: Request) -> Response:
        print("  🔒 [Auth] Checking headers...")
        token = request.get("headers", {}).get("Authorization")
        
        if token != "Bearer valid_token":
            print("  🔒 [Auth] ❌ Invalid token! Halting the chain.")
            # SHORT-CIRCUIT: We DO NOT call the next app!
            return {"status": 401, "body": "Unauthorized"}
            
        print("  🔒 [Auth] ✅ Token valid. Passing down chain.")
        if self._next_app:
            return self._next_app(request)
        return {"status": 500, "body": "No app attached"}


class ValidationMiddleware(Middleware):
    def __call__(self, request: Request) -> Response:
        print("  ✅ [Validation] Checking payload...")
        if "body" not in request:
            print("  ✅ [Validation] ❌ Missing body! Halting the chain.")
            return {"status": 400, "body": "Bad Request"}
            
        print("  ✅ [Validation] Payload valid. Passing down chain.")
        if self._next_app:
            return self._next_app(request)
        return {"status": 500, "body": "No app attached"}


# ─── The Final Application (End of the Chain) ──────────

def core_application(request: Request) -> Response:
    """
    The actual view function. It assumes all middleware checks passed.
    """
    print(f"  ⚙️  [App] Processing valid, authenticated request: {request['body']}")
    return {"status": 200, "body": "Success!"}


# ─── Chain Builder Utility ─────────────────────────────

def build_middleware_chain(middlewares: list[Middleware], app: HandlerFunc) -> HandlerFunc:
    """
    Helper function to wire the chain together backwards.
    M1 -> M2 -> M3 -> App
    """
    current_app = app
    for middleware in reversed(middlewares):
        middleware.set_next(current_app)
        current_app = middleware
    return current_app


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("CHAIN OF RESPONSIBILITY - Web Middleware")
    print("=" * 60)
    
    # 1. Build the chain
    chain = build_middleware_chain(
        middlewares=[
            LoggingMiddleware(),
            AuthMiddleware(),
            ValidationMiddleware()
        ],
        app=core_application
    )
    
    # 2. Test Case 1: Bad Auth (Should halt at AuthMiddleware)
    print("\n--- Test 1: Bad Token ---")
    bad_req = {
        "path": "/api/data",
        "headers": {"Authorization": "Bearer BAD_TOKEN"},
        "body": {"data": 123}
    }
    resp1 = chain(bad_req)
    print(f"Result: {resp1}")
    
    # 3. Test Case 2: Bad Payload (Should halt at ValidationMiddleware)
    print("\n--- Test 2: Bad Payload ---")
    bad_payload_req = {
        "path": "/api/data",
        "headers": {"Authorization": "Bearer valid_token"}
        # missing "body"
    }
    resp2 = chain(bad_payload_req)
    print(f"Result: {resp2}")
    
    # 4. Test Case 3: Perfect Request (Should reach the App)
    print("\n--- Test 3: Perfect Request ---")
    good_req = {
        "path": "/api/data",
        "headers": {"Authorization": "Bearer valid_token"},
        "body": {"data": 123}
    }
    resp3 = chain(good_req)
    print(f"Result: {resp3}")
    
    print("\n✅ Middleware Chain demonstrated successfully!")

"""
============================================================
Example: Text Editor Undo/Redo
Pattern: Command (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You are building a text editor. You need to support Ctrl+Z (Undo)
and Ctrl+Y (Redo).

To do this, every modification to the text cannot just be a simple
string mutation. Instead, every action (typing, deleting, pasting)
must be encapsulated in a `Command` object that knows how to:
1. `execute()`: Apply the change.
2. `undo()`: Reverse the change.

The editor keeps two stacks: a History stack (for undo) and a 
Redo stack.

KEY INSIGHT:
------------
This is the absolute best, textbook use-case for the Command pattern.
A simple Python callback/lambda cannot easily store the state required
to reverse an action. A Command class handles this perfectly.

============================================================
"""

from abc import ABC, abstractmethod


# ─── Receiver ──────────────────────────────────────────

class TextDocument:
    """The Receiver. The object being manipulated."""
    def __init__(self) -> None:
        self.text = ""
        
    def __str__(self) -> str:
        return f"Document: '{self.text}'"


# ─── Command Interface ─────────────────────────────────

class Command(ABC):
    """The Command interface."""
    def __init__(self, document: TextDocument) -> None:
        self.document = document
        
    @abstractmethod
    def execute(self) -> None:
        """Applies the command."""
        pass
        
    @abstractmethod
    def undo(self) -> None:
        """Reverses the command."""
        pass


# ─── Concrete Commands ─────────────────────────────────

class TypeTextCommand(Command):
    def __init__(self, document: TextDocument, text_to_add: str) -> None:
        super().__init__(document)
        self.text_to_add = text_to_add
        
    def execute(self) -> None:
        self.document.text += self.text_to_add
        print(f"  [Command] Typed: '{self.text_to_add}'")
        
    def undo(self) -> None:
        # To undo, we slice off the length of the text we added
        slice_length = len(self.text_to_add)
        self.document.text = self.document.text[:-slice_length]
        print(f"  [Command] Undid typing: removed '{self.text_to_add}'")


class DeleteTextCommand(Command):
    def __init__(self, document: TextDocument, length_to_delete: int) -> None:
        super().__init__(document)
        self.length_to_delete = length_to_delete
        self._deleted_text = ""  # State required for undo!
        
    def execute(self) -> None:
        # Save what we are about to delete so we can undo it later
        if len(self.document.text) >= self.length_to_delete:
            self._deleted_text = self.document.text[-self.length_to_delete:]
            self.document.text = self.document.text[:-self.length_to_delete]
        else:
            self._deleted_text = self.document.text
            self.document.text = ""
            
        print(f"  [Command] Deleted: '{self._deleted_text}'")
        
    def undo(self) -> None:
        # To undo a deletion, we just append the saved text back
        self.document.text += self._deleted_text
        print(f"  [Command] Undid deletion: restored '{self._deleted_text}'")


# ─── Invoker ───────────────────────────────────────────

class TextEditor:
    """The Invoker. Manages command execution and the history stacks."""
    def __init__(self, document: TextDocument) -> None:
        self.document = document
        self.history: list[Command] = []
        self.redo_stack: list[Command] = []
        
    def execute_command(self, command: Command) -> None:
        """Executes a command and pushes it to history."""
        command.execute()
        self.history.append(command)
        # Any new action clears the redo stack!
        self.redo_stack.clear()
        
    def undo(self) -> None:
        """Pops the last command, calls undo(), and pushes to redo stack."""
        if not self.history:
            print("  [Editor] Nothing to undo.")
            return
            
        command = self.history.pop()
        command.undo()
        self.redo_stack.append(command)
        
    def redo(self) -> None:
        """Pops the last undone command, calls execute(), and pushes to history."""
        if not self.redo_stack:
            print("  [Editor] Nothing to redo.")
            return
            
        command = self.redo_stack.pop()
        command.execute()
        self.history.append(command)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("COMMAND PATTERN - Undo/Redo History")
    print("=" * 60)
    
    doc = TextDocument()
    editor = TextEditor(doc)
    
    print("\n--- 1. Typing ---")
    editor.execute_command(TypeTextCommand(doc, "Hello "))
    editor.execute_command(TypeTextCommand(doc, "World!"))
    print(f"Current State: {doc}")
    
    print("\n--- 2. Deleting ---")
    editor.execute_command(DeleteTextCommand(doc, 6)) # Delete "World!"
    print(f"Current State: {doc}")
    
    print("\n--- 3. Undo ---")
    editor.undo() # Restores "World!"
    print(f"Current State: {doc}")
    
    editor.undo() # Removes "Hello "
    print(f"Current State: {doc}")
    
    print("\n--- 4. Redo ---")
    editor.redo() # Types "Hello " again
    print(f"Current State: {doc}")
    
    print("\n--- 5. New Action Clears Redo Stack ---")
    # We still have one thing we *could* redo (World!), but if we type 
    # something new, the redo stack is cleared (standard editor behavior).
    editor.execute_command(TypeTextCommand(doc, "Python!"))
    print(f"Current State: {doc}")
    
    editor.redo() # Should do nothing
    
    print("\n✅ Command pattern (Undo/Redo) demonstrated successfully!")

"""
============================================================
Example: Tree Traversals (DFS vs BFS)
Pattern: Iterator (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a complex data structure: A Tree representing a company's
management hierarchy.

You want to allow other developers to loop over this tree easily:
`for employee in company_tree:`

But a tree isn't a flat list. Do we go deep first (Depth-First Search)? 
Or level by level (Breadth-First Search)? 

The Iterator pattern allows us to provide multiple ways to traverse 
the exact same data structure, completely hiding the complex algorithms 
from the client.

KEY INSIGHT:
------------
We will implement one iterator the "Hard Way" (using a Class with 
__iter__ and __next__) and one the "Pythonic Way" (using a generator 
with `yield`). Both fulfill the Iterator pattern!

============================================================
"""

from collections import deque
from typing import Any, Generator, Iterator


# ─── Node ──────────────────────────────────────────────

class Node:
    """A node in our tree."""
    def __init__(self, value: str) -> None:
        self.value = value
        self.children: list['Node'] = []
        
    def add(self, child: 'Node') -> None:
        self.children.append(child)


# ─── Iterator 1: The "Class" Way (Breadth-First) ───────

class BreadthFirstIterator(Iterator[Node]):
    """
    A classic class-based iterator.
    Implements BFS (Level Order Traversal) using a queue.
    """
    def __init__(self, root: Node) -> None:
        self._queue = deque([root]) if root else deque()
        
    def __iter__(self) -> Iterator[Node]:
        """Iterators must return themselves."""
        return self
        
    def __next__(self) -> Node:
        """The core logic to get the next element."""
        if not self._queue:
            # This is how Python knows the loop is finished!
            raise StopIteration
            
        current = self._queue.popleft()
        
        # Add children to the queue for later processing
        for child in current.children:
            self._queue.append(child)
            
        return current


# ─── The Collection (Iterable) ─────────────────────────

class CompanyTree:
    """
    The Iterable Collection.
    It holds the data and provides methods to get Iterators.
    """
    def __init__(self, root: Node) -> None:
        self.root = root
        
    def __iter__(self) -> Iterator[Node]:
        """
        Default iteration method (used by `for x in tree:`).
        We'll default to Breadth-First Search using our custom class.
        """
        return BreadthFirstIterator(self.root)
        
    def depth_first(self) -> Generator[Node, None, None]:
        """
        Iterator 2: The "Pythonic" Way (Generators).
        Using `yield` automatically creates an Iterator class behind the scenes!
        """
        if not self.root:
            return
            
        # DFS uses a stack (LIFO)
        stack = [self.root]
        
        while stack:
            current = stack.pop()
            yield current # Pause execution and return the value!
            
            # Add children to stack in reverse order so left is processed first
            for child in reversed(current.children):
                stack.append(child)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("ITERATOR PATTERN - Tree Traversals")
    print("=" * 60)
    
    # 1. Build the Tree
    #       CEO
    #      /   \
    #    VP1   VP2
    #   /   \     \
    # Dev1 Dev2   HR1
    
    ceo = Node("CEO")
    vp1 = Node("VP Engineering")
    vp2 = Node("VP HR")
    dev1 = Node("Dev 1")
    dev2 = Node("Dev 2")
    hr1 = Node("HR 1")
    
    vp1.add(dev1)
    vp1.add(dev2)
    vp2.add(hr1)
    ceo.add(vp1)
    ceo.add(vp2)
    
    company = CompanyTree(ceo)
    
    # 2. Iterate using the Default Iterator (BFS / Level Order)
    print("\n--- Default Iteration (Breadth-First via Class) ---")
    print("Expected: CEO -> VP Eng -> VP HR -> Dev 1 -> Dev 2 -> HR 1")
    for employee in company:
        print(f"  🏢 {employee.value}")
        
    # 3. Iterate using the Alternative Iterator (DFS / Pre-order)
    print("\n--- Alternative Iteration (Depth-First via Generator) ---")
    print("Expected: CEO -> VP Eng -> Dev 1 -> Dev 2 -> VP HR -> HR 1")
    for employee in company.depth_first():
        print(f"  🏢 {employee.value}")
        
    print("\n✅ Iterator pattern demonstrated successfully!")

"""
============================================================
Example: Air Traffic Control
Pattern: Mediator (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
Airplanes (Components) need to coordinate landing on a single
Runway. If Airplane A talks directly to Airplane B, Airplane C,
and the Runway, the code becomes tightly coupled spaghetti.

Instead, every Airplane communicates ONLY with the Control Tower
(Mediator). The Control Tower contains the logic to decide who
can land and when.

KEY INSIGHT:
------------
The `Airplane` class does not know about the `Runway` or other
`Airplanes`. It only knows about the `ControlTowerProtocol`.

============================================================
"""

from typing import Protocol


# ─── Mediator Interface ────────────────────────────────

class ControlTowerProtocol(Protocol):
    """The interface that Components use to talk to the Mediator."""
    def notify(self, sender: 'Airplane', event: str) -> None: ...


# ─── Components ────────────────────────────────────────

class Airplane:
    """
    A Component. It only knows about the Mediator.
    It does NOT know about other airplanes or the runway.
    """
    def __init__(self, flight_number: str) -> None:
        self.flight_number = flight_number
        self.mediator: ControlTowerProtocol | None = None
        
    def set_mediator(self, mediator: ControlTowerProtocol) -> None:
        self.mediator = mediator
        
    def request_landing(self) -> None:
        print(f"  ✈️  [Flight {self.flight_number}] Requesting landing clearance...")
        if self.mediator:
            self.mediator.notify(self, "request_landing")
            
    def finish_landing(self) -> None:
        print(f"  ✈️  [Flight {self.flight_number}] Has landed and cleared the runway.")
        if self.mediator:
            self.mediator.notify(self, "landed")


class Runway:
    """Another Component."""
    def __init__(self) -> None:
        self.is_clear = True


# ─── Concrete Mediator ─────────────────────────────────

class JFKControlTower:
    """
    The Concrete Mediator.
    It knows about all the components (Runway, Airplanes) and
    contains the complex business logic of how they interact.
    """
    def __init__(self) -> None:
        self.runway = Runway()
        self.waiting_queue: list[Airplane] = []
        
    def notify(self, sender: Airplane, event: str) -> None:
        """The central hub for all communication."""
        
        if event == "request_landing":
            if self.runway.is_clear:
                print(f"  🗼 [Tower] Runway is clear. Flight {sender.flight_number}, you are cleared to land.")
                self.runway.is_clear = False
            else:
                print(f"  🗼 [Tower] Runway is busy! Flight {sender.flight_number}, please hold.")
                self.waiting_queue.append(sender)
                
        elif event == "landed":
            self.runway.is_clear = True
            
            # If someone is waiting, clear them to land now
            if self.waiting_queue:
                next_flight = self.waiting_queue.pop(0)
                print(f"  🗼 [Tower] Runway now clear. Flight {next_flight.flight_number}, you are cleared to land.")
                self.runway.is_clear = False


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("MEDIATOR PATTERN - Air Traffic Control")
    print("=" * 60)
    
    # 1. Create the Mediator
    tower = JFKControlTower()
    
    # 2. Create the Components
    flight1 = Airplane("AA101")
    flight2 = Airplane("DL404")
    flight3 = Airplane("UA909")
    
    # 3. Connect components to the Mediator
    flight1.set_mediator(tower)
    flight2.set_mediator(tower)
    flight3.set_mediator(tower)
    
    # 4. Action!
    # Flight 1 requests to land. Runway is clear.
    flight1.request_landing()
    
    # Flight 2 requests to land. Runway is busy, so it holds.
    flight2.request_landing()
    
    # Flight 3 requests to land. Runway is busy, so it holds.
    flight3.request_landing()
    
    # Flight 1 finishes landing. The tower automatically notifies Flight 2.
    flight1.finish_landing()
    
    # Flight 2 finishes landing. The tower automatically notifies Flight 3.
    flight2.finish_landing()
    
    flight3.finish_landing()
    
    print("\n✅ Mediator pattern demonstrated successfully!")

"""
============================================================
Example: Video Game Saves
Pattern: Memento (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You are playing an RPG game. Your character has health, mana,
coordinates, and a list of items.

You encounter a boss and hit "Quick Save" (F5).
You die. You hit "Quick Load" (F9) to restore your state.

KEY INSIGHT:
------------
The `GameCaretaker` manages the save files, but it HAS NO IDEA
what is inside them. Only the `RPGGame` (Originator) knows how
to create and read a `GameMemento`. This perfectly preserves
encapsulation!

============================================================
"""

from dataclasses import dataclass
import copy


# ─── Memento ───────────────────────────────────────────

@dataclass(frozen=True)
class GameMemento:
    """
    The Memento.
    It is completely immutable (frozen). It holds a snapshot of state.
    Notice we don't expose any methods to alter this data.
    """
    name: str  # e.g., "Save 1 - Boss Room"
    health: int
    mana: int
    level: int
    inventory: list[str]


# ─── Originator ────────────────────────────────────────

class RPGGame:
    """
    The Originator.
    This is the actual game. It has complex internal state.
    It is the ONLY class that creates and consumes GameMementos.
    """
    def __init__(self) -> None:
        # Complex internal state
        self._health = 100
        self._mana = 50
        self._level = 1
        self._inventory = ["Sword", "Potion"]
        
    def take_damage(self, amount: int) -> None:
        self._health -= amount
        print(f"  ⚔️  Took {amount} damage! Health is now {self._health}.")
        
    def level_up(self) -> None:
        self._level += 1
        self._health = 100
        self._mana = 50
        print(f"  ✨ Leveled up to {self._level}!")
        
    def loot(self, item: str) -> None:
        self._inventory.append(item)
        print(f"  💰 Looted: {item}")

    def __str__(self) -> str:
        return (f"Game State -> Level: {self._level} | "
                f"HP: {self._health} | MP: {self._mana} | "
                f"Inv: {self._inventory}")

    # --- Memento Logic ---

    def save_game(self, save_name: str) -> GameMemento:
        """Creates a snapshot of the current state."""
        print(f"  💾 Saving game: '{save_name}'...")
        # Note: We must DEEP COPY mutable objects like lists!
        return GameMemento(
            name=save_name,
            health=self._health,
            mana=self._mana,
            level=self._level,
            inventory=copy.deepcopy(self._inventory)
        )
        
    def load_game(self, memento: GameMemento) -> None:
        """Restores the state from a snapshot."""
        print(f"  🔄 Loading game: '{memento.name}'...")
        self._health = memento.health
        self._mana = memento.mana
        self._level = memento.level
        self._inventory = copy.deepcopy(memento.inventory)


# ─── Caretaker ─────────────────────────────────────────

class GameCaretaker:
    """
    The Caretaker.
    It manages the save files (mementos), but NEVER looks inside them.
    It just holds onto them and gives them back to the Game when asked.
    """
    def __init__(self, game: RPGGame) -> None:
        self._game = game
        self._saves: list[GameMemento] = []
        
    def quick_save(self) -> None:
        save_name = f"QuickSave_Slot_{len(self._saves) + 1}"
        memento = self._game.save_game(save_name)
        self._saves.append(memento)
        
    def quick_load(self) -> None:
        if not self._saves:
            print("  ❌ No save files found!")
            return
            
        memento = self._saves.pop()  # Load the most recent save
        self._game.load_game(memento)


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("MEMENTO PATTERN - Video Game Saves")
    print("=" * 60)
    
    game = RPGGame()
    caretaker = GameCaretaker(game)
    
    print("\n[Starting Game]")
    print(f"  {game}")
    
    print("\n[Progressing...]")
    game.level_up()
    game.loot("Dragon Shield")
    print(f"  {game}")
    
    print("\n[Before Boss Room - Quick Save!]")
    caretaker.quick_save()
    
    print("\n[Fighting Boss...]")
    game.take_damage(80)
    game.loot("Cursed Ring")
    print(f"  {game}")
    game.take_damage(50) # Dead!
    print(f"  {game} (DEAD!)")
    
    print("\n[Rage Quit & Quick Load!]")
    caretaker.quick_load()
    print(f"  {game}")
    
    print("\n✅ Memento pattern demonstrated successfully!")

"""
============================================================
Example: Pythonic Event Emitter
Pattern: Observer (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a `ShoppingCart` object. When a user completes checkout,
several things need to happen:
1. Send an email receipt.
2. Update inventory.
3. Log the transaction.

Instead of writing all that logic inside `ShoppingCart.checkout()`,
we make the Cart an "Event Emitter" (Subject). It just broadcasts
the "checkout_complete" event. Other systems subscribe to this event.

KEY INSIGHT:
------------
Instead of using full classes for Observers (like the GoF book),
we use Python's first-class functions (callbacks). This is the
standard way to write Observers in modern Python.

============================================================
"""

from typing import Any, Callable, Dict, List

# Type alias for our observer callbacks
ObserverCallback = Callable[[Dict[str, Any]], None]


# ─── Subject (Publisher / Event Emitter) ───────────────

class EventEmitter:
    """
    A generic Publisher that can handle multiple types of events.
    (Very similar to Node.js EventEmitter).
    """
    def __init__(self) -> None:
        # A dictionary mapping event names to lists of callbacks
        self._events: Dict[str, List[ObserverCallback]] = {}
        
    def on(self, event_name: str, callback: ObserverCallback) -> None:
        """Subscribe to an event (Attach)."""
        if event_name not in self._events:
            self._events[event_name] = []
        self._events[event_name].append(callback)
        print(f"  [System] Attached callback '{callback.__name__}' to event '{event_name}'")
        
    def off(self, event_name: str, callback: ObserverCallback) -> None:
        """Unsubscribe from an event (Detach)."""
        if event_name in self._events and callback in self._events[event_name]:
            self._events[event_name].remove(callback)
            print(f"  [System] Detached callback '{callback.__name__}' from event '{event_name}'")
            
    def emit(self, event_name: str, event_data: Dict[str, Any]) -> None:
        """Broadcast an event to all subscribers (Notify)."""
        if event_name in self._events:
            print(f"\n  📢 [EventEmitter] Broadcasting '{event_name}'...")
            for callback in self._events[event_name]:
                callback(event_data)


# ─── Concrete Subject (The Shopping Cart) ──────────────

class ShoppingCart(EventEmitter):
    """
    Our specific business logic class. It inherits the emit/on methods.
    """
    def __init__(self, user_id: str) -> None:
        super().__init__()
        self.user_id = user_id
        self.items: List[str] = []
        
    def add_item(self, item: str) -> None:
        self.items.append(item)
        
    def checkout(self) -> None:
        print(f"\n  🛒 [Cart] {self.user_id} is checking out with {self.items}...")
        
        # We do NOT send emails or update inventory here!
        # We just EMIT the event and let the observers handle the rest.
        
        event_data = {
            "user_id": self.user_id,
            "items": self.items,
            "total_items": len(self.items)
        }
        self.emit("checkout_complete", event_data)
        
        self.items.clear()


# ─── Observers (Just plain functions!) ─────────────────

def send_email_receipt(data: Dict[str, Any]) -> None:
    print(f"  ✉️  [EmailService] Sending receipt to {data['user_id']} for {data['total_items']} items.")

def update_inventory(data: Dict[str, Any]) -> None:
    print(f"  📦 [InventoryService] Deducting stock for: {data['items']}")

def log_transaction(data: Dict[str, Any]) -> None:
    print(f"  📝 [Logger] Transaction logged: User {data['user_id']} bought {data['total_items']} items.")


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("OBSERVER PATTERN - Pythonic Event Emitter")
    print("=" * 60)
    
    # 1. Setup the Subject
    cart = ShoppingCart("Alice")
    
    # 2. Attach Observers (Wire up the app)
    cart.on("checkout_complete", send_email_receipt)
    cart.on("checkout_complete", update_inventory)
    cart.on("checkout_complete", log_transaction)
    
    # 3. Use the app!
    cart.add_item("Laptop")
    cart.add_item("Mouse")
    
    # When checkout runs, it will trigger all 3 observers automatically.
    cart.checkout()
    
    # 4. Detach an observer (Alice opts out of emails)
    print("\n[Detaching Email Service]")
    cart.off("checkout_complete", send_email_receipt)
    
    cart.add_item("Keyboard")
    cart.checkout() # Only Inventory and Logger will run this time!
    
    print("\n✅ Observer pattern demonstrated successfully!")

"""
============================================================
Example: Vending Machine FSM
Pattern: State (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
A Vending Machine has 3 states:
1. NoCoinState
2. HasCoinState
3. DispensingState

If you press "Dispense" while in NoCoinState, it errors.
If you insert a coin while in HasCoinState, it refunds the extra coin.
Instead of having massive `if/else` blocks in the VendingMachine,
we put the logic inside the State classes themselves.

KEY INSIGHT:
------------
The State objects have a reference back to the Context (VendingMachine).
This allows them to call `self.machine.set_state(...)` to trigger
transitions.

============================================================
"""

from abc import ABC, abstractmethod


# ─── Context ───────────────────────────────────────────

class VendingMachine:
    """
    The Context. It maintains a reference to the current state.
    It delegates all work to the state object.
    """
    def __init__(self, inventory_count: int) -> None:
        self.inventory_count = inventory_count
        # Start in the NoCoinState
        self._state: State = NoCoinState(self)
        
    def set_state(self, state: 'State') -> None:
        """Called by the States to trigger transitions."""
        print(f"  🔄 [Transition] Changing state to: {type(state).__name__}")
        self._state = state
        
    # Expose the API to the user, but delegate to the state!
    def insert_coin(self) -> None:
        self._state.insert_coin()
        
    def eject_coin(self) -> None:
        self._state.eject_coin()
        
    def press_button(self) -> None:
        self._state.press_button()
        
    def dispense(self) -> None:
        self._state.dispense()


# ─── State Interface ───────────────────────────────────

class State(ABC):
    """
    Base State class. Every state must know about the Context
    so it can trigger transitions.
    """
    def __init__(self, machine: VendingMachine) -> None:
        self.machine = machine
        
    @abstractmethod
    def insert_coin(self) -> None: pass
    @abstractmethod
    def eject_coin(self) -> None: pass
    @abstractmethod
    def press_button(self) -> None: pass
    @abstractmethod
    def dispense(self) -> None: pass


# ─── Concrete States ───────────────────────────────────

class NoCoinState(State):
    def insert_coin(self) -> None:
        print("  🪙 Coin inserted.")
        # TRANSITION!
        self.machine.set_state(HasCoinState(self.machine))
        
    def eject_coin(self) -> None:
        print("  ❌ Cannot eject. You haven't inserted a coin.")
        
    def press_button(self) -> None:
        print("  ❌ Cannot dispense. Insert a coin first.")
        
    def dispense(self) -> None:
        print("  ❌ Pay first!")


class HasCoinState(State):
    def insert_coin(self) -> None:
        print("  ❌ You already inserted a coin. Returning extra coin.")
        
    def eject_coin(self) -> None:
        print("  🪙 Coin returned.")
        # TRANSITION!
        self.machine.set_state(NoCoinState(self.machine))
        
    def press_button(self) -> None:
        print("  🟩 Button pressed...")
        if self.machine.inventory_count > 0:
            # TRANSITION!
            self.machine.set_state(DispensingState(self.machine))
            # Trigger the internal dispense action immediately
            self.machine.dispense()
        else:
            print("  ❌ Out of stock! Returning coin.")
            self.machine.set_state(NoCoinState(self.machine))
            
    def dispense(self) -> None:
        print("  ❌ Press the button first.")


class DispensingState(State):
    def insert_coin(self) -> None:
        print("  ❌ Please wait, already dispensing.")
        
    def eject_coin(self) -> None:
        print("  ❌ Sorry, you already pressed the button.")
        
    def press_button(self) -> None:
        print("  ❌ Already dispensing!")
        
    def dispense(self) -> None:
        print("  🍬 Dispensing candy!")
        self.machine.inventory_count -= 1
        print(f"  [Inventory: {self.machine.inventory_count} left]")
        # TRANSITION! (Back to start)
        self.machine.set_state(NoCoinState(self.machine))


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("STATE PATTERN - Vending Machine")
    print("=" * 60)
    
    machine = VendingMachine(inventory_count=2)
    
    print("\n--- Scenario 1: Successful Purchase ---")
    machine.insert_coin()
    machine.press_button()
    
    print("\n--- Scenario 2: Try to break it ---")
    machine.press_button() # No coin!
    machine.insert_coin()
    machine.insert_coin() # Double coin!
    machine.eject_coin()  # Changed mind
    
    print("\n--- Scenario 3: Buy last item & Out of stock ---")
    machine.insert_coin()
    machine.press_button() # Buys the 2nd (last) item
    
    machine.insert_coin()
    machine.press_button() # Fails gracefully!
    
    print("\n✅ State pattern demonstrated successfully!")

"""
============================================================
Example: Payment Gateways & Pythonic Strategies
Pattern: Strategy (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have an E-Commerce checkout system. Customers can pay via
Credit Card, PayPal, or Crypto.

Instead of putting all that API logic inside the `ShoppingCart`
class, we inject a Payment Strategy into the cart.

We will show TWO ways to do this in Python:
1. The classic OOP way (Classes)
2. The modern Pythonic way (Functions)

KEY INSIGHT:
------------
The `ShoppingCart` (Context) NEVER changes, no matter how many
new payment methods we invent. It perfectly obeys the Open/Closed Principle.

============================================================
"""

from typing import Callable, Protocol


# ─── Method 1: Classic OOP Strategies ──────────────────

class PaymentStrategy(Protocol):
    """The interface for class-based strategies."""
    def pay(self, amount: float) -> None: ...


class StripeStrategy:
    def __init__(self, api_key: str) -> None:
        self.api_key = api_key
        
    def pay(self, amount: float) -> None:
        print(f"  💳 [Stripe] Processing ${amount:.2f} using API key ending in '...{self.api_key[-4:]}'")


class PayPalStrategy:
    def __init__(self, email: str) -> None:
        self.email = email
        
    def pay(self, amount: float) -> None:
        print(f"  🅿️  [PayPal] Processing ${amount:.2f} for account '{self.email}'")


# ─── Method 2: Pythonic Functional Strategies ──────────

# A strategy can just be a function signature!
FunctionalPaymentStrategy = Callable[[float], None]

def crypto_strategy(amount: float) -> None:
    btc_amount = amount / 60000.0
    print(f"  🪙 [Crypto] Processing {btc_amount:.6f} BTC to wallet '0x1A2B...'")


# ─── The Context ───────────────────────────────────────

class ShoppingCart:
    """
    The Context.
    It takes a strategy (either a class instance or a function)
    and executes it.
    """
    def __init__(self) -> None:
        self.items: list[dict] = []
        self._strategy: PaymentStrategy | FunctionalPaymentStrategy | None = None
        
    def add_item(self, name: str, price: float) -> None:
        self.items.append({"name": name, "price": price})
        
    def set_strategy(self, strategy: PaymentStrategy | FunctionalPaymentStrategy) -> None:
        """Swap the strategy at runtime!"""
        self._strategy = strategy
        
    def checkout(self) -> None:
        if not self._strategy:
            print("  ❌ Cannot checkout: No payment strategy selected!")
            return
            
        total = sum(item["price"] for item in self.items)
        print(f"\n🛒 Checking out {len(self.items)} items. Total: ${total:.2f}")
        
        # Execute the strategy! (Handles both classes and functions)
        if callable(getattr(self._strategy, 'pay', None)):
            self._strategy.pay(total)  # OOP Class
        else:
            self._strategy(total)      # Function


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("STRATEGY PATTERN - Payment Gateways")
    print("=" * 60)
    
    cart = ShoppingCart()
    cart.add_item("Mechanical Keyboard", 150.00)
    cart.add_item("Coffee Mug", 20.00)
    
    # 1. Use Stripe
    print("\n--- Paying with Stripe ---")
    stripe = StripeStrategy("sk_live_123456789")
    cart.set_strategy(stripe)
    cart.checkout()
    
    # 2. Swap to PayPal AT RUNTIME
    print("\n--- Swapping to PayPal ---")
    paypal = PayPalStrategy("alice@example.com")
    cart.set_strategy(paypal)
    cart.checkout()
    
    # 3. Use the Pythonic Functional Strategy
    print("\n--- Swapping to Crypto (Function) ---")
    cart.set_strategy(crypto_strategy)
    cart.checkout()
    
    print("\n✅ Strategy pattern demonstrated successfully!")

"""
============================================================
Example: Data Miner / ETL Pipeline
Pattern: Template Method (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You are building an ETL (Extract, Transform, Load) pipeline that 
reads data from different sources (CSV files, APIs), processes it,
and saves it to a database.

The sequence of steps is ALWAYS the same:
1. Extract data.
2. Clean data.
3. [Optional hook: Send notification].
4. Load into database.

By putting this sequence in a Base Class (`mine_data`), we guarantee
every data miner follows the exact same protocol.

KEY INSIGHT:
------------
Notice the Hollywood Principle: "Don't call us, we'll call you."
The `DataMiner` base class is in charge. It calls the subclass 
methods when it needs them. The subclass never calls the base class.

============================================================
"""

from abc import ABC, abstractmethod


# ─── Abstract Class (The Skeleton) ─────────────────────

class DataMiner(ABC):
    """
    The Base Class. It defines the Template Method and the primitive
    steps that subclasses must/can implement.
    """
    
    def mine_data(self, source: str) -> None:
        """
        THE TEMPLATE METHOD.
        This defines the skeleton of the algorithm. It is usually
        NOT overridden by subclasses (in languages with 'final', this
        method would be marked final).
        """
        print(f"\n--- Starting Data Mining for: {source} ---")
        
        # Step 1: Extract (Required)
        raw_data = self.extract(source)
        
        # Step 2: Clean (Required)
        clean_data = self.clean(raw_data)
        
        # Step 3: Hook (Optional)
        self.before_load_hook(clean_data)
        
        # Step 4: Load (Standard implementation in base class)
        self._load_to_database(clean_data)
        
        print("--- Mining Complete ---")
        
    
    # --- Primitive Operations ---
    
    @abstractmethod
    def extract(self, source: str) -> str:
        """Subclasses MUST implement how they extract data."""
        pass
        
    @abstractmethod
    def clean(self, raw_data: str) -> str:
        """Subclasses MUST implement how they clean data."""
        pass
        
    def before_load_hook(self, clean_data: str) -> None:
        """
        A HOOK.
        It has an empty default implementation. Subclasses CAN override 
        it if they want to inject behavior before saving to the DB.
        """
        pass
        
    def _load_to_database(self, data: str) -> None:
        """
        A base operation.
        It is fully implemented in the base class. Subclasses generally
        use this as-is and do not override it.
        """
        print(f"  💾 [Base] Saving '{data}' to central database...")


# ─── Concrete Classes (The Details) ────────────────────

class CSVMiner(DataMiner):
    """Mines data from CSV files."""
    
    def extract(self, source: str) -> str:
        print(f"  📄 [CSV] Opening CSV file {source} and reading rows...")
        return "row1,row2,row3"
        
    def clean(self, raw_data: str) -> str:
        print("  🧹 [CSV] Removing commas and bad rows...")
        return "clean_csv_data"


class APIMiner(DataMiner):
    """Mines data from a JSON API."""
    
    def extract(self, source: str) -> str:
        print(f"  🌐 [API] Making HTTP GET request to {source}...")
        return '{"data": "json_blob"}'
        
    def clean(self, raw_data: str) -> str:
        print("  🧹 [API] Parsing JSON and validating schema...")
        return "clean_json_data"
        
    def before_load_hook(self, clean_data: str) -> None:
        """
        Overriding the hook! We only want to notify slack for API data.
        """
        print("  🪝  [API Hook] Sending Slack notification about new API data!")


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("TEMPLATE METHOD PATTERN - ETL Pipeline")
    print("=" * 60)
    
    # We instantiate the subclasses, but we call the Template Method
    # inherited from the Base class!
    
    csv_miner = CSVMiner()
    csv_miner.mine_data("users_export.csv")
    
    api_miner = APIMiner()
    api_miner.mine_data("https://api.example.com/v1/users")
    
    print("\n✅ Template Method pattern demonstrated successfully!")

"""
============================================================
Example: Shape Exporter (Classic GoF vs SingleDispatch)
Pattern: Visitor (Behavioral)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a drawing app with `Dot`, `Circle`, and `Rectangle` objects.
You need to add a feature to export these shapes to XML. Later, you
need to export them to JSON.

Instead of adding `export_xml()` and `export_json()` to every shape
(which bloats the shape classes), we create a `Visitor` that extracts
the data from the shapes.

KEY INSIGHT:
------------
We will show TWO methods:
1. The Classic GoF approach (Double Dispatch via `accept()`).
2. The modern Pythonic approach (using `@singledispatch`).

============================================================
"""

from typing import Protocol
from functools import singledispatch


# ==========================================================
# METHOD 1: Classic GoF (Double Dispatch)
# ==========================================================

print("=" * 60)
print("VISITOR PATTERN - Classic GoF")
print("=" * 60)

# ─── Elements ──────────────────────────────────────────

class Shape(Protocol):
    def accept(self, visitor: 'Visitor') -> str: ...

class Dot:
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y
        
    def accept(self, visitor: 'Visitor') -> str:
        # Double Dispatch Step 2: The Element calls the specific 
        # visitor method associated with its class.
        return visitor.visit_dot(self)

class Circle:
    def __init__(self, radius: int) -> None:
        self.radius = radius
        
    def accept(self, visitor: 'Visitor') -> str:
        return visitor.visit_circle(self)


# ─── Visitor Interface & Implementations ───────────────

class Visitor(Protocol):
    def visit_dot(self, dot: Dot) -> str: ...
    def visit_circle(self, circle: Circle) -> str: ...

class XMLExporterVisitor:
    """Extracts state from shapes and returns XML."""
    
    def visit_dot(self, dot: Dot) -> str:
        return f"<dot><x>{dot.x}</x><y>{dot.y}</y></dot>"
        
    def visit_circle(self, circle: Circle) -> str:
        return f"<circle><radius>{circle.radius}</radius></circle>"


# ─── Classic Demo ───────────────

shapes: list[Shape] = [Dot(10, 20), Circle(15)]
xml_visitor = XMLExporterVisitor()

for shape in shapes:
    # Double Dispatch Step 1: The Client calls accept() on the Element
    result = shape.accept(xml_visitor)
    print(f"  Exported: {result}")


# ==========================================================
# METHOD 2: Modern Python (SingleDispatch)
# ==========================================================

print("\n" + "=" * 60)
print("VISITOR PATTERN - Modern Python (@singledispatch)")
print("=" * 60)

# ─── Elements (Notice there is NO accept() method!) ────

class PythonicDot:
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y

class PythonicCircle:
    def __init__(self, radius: int) -> None:
        self.radius = radius


# ─── Visitor using SingleDispatch ──────────────────────
# @singledispatch gives us method overloading by type!

@singledispatch
def export_json(shape) -> str:
    raise NotImplementedError("Unsupported shape type")

@export_json.register(PythonicDot)
def _(dot: PythonicDot) -> str:
    return f'{{"type": "dot", "x": {dot.x}, "y": {dot.y}}}'

@export_json.register(PythonicCircle)
def _(circle: PythonicCircle) -> str:
    return f'{{"type": "circle", "radius": {circle.radius}}}'


# ─── Modern Demo ───────────────

modern_shapes = [PythonicDot(30, 40), PythonicCircle(50)]

for shape in modern_shapes:
    # Look how clean this is! No accept() boilerplate.
    # Python automatically routes it to the correct registered function.
    result = export_json(shape)
    print(f"  Exported: {result}")

print("\n✅ Visitor pattern demonstrated successfully!")

"""
============================================================
Example: Testable User Service with Repository
Pattern: Repository (Architectural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a service that upgrades a user to a "Premium" account.
To do this, it needs to check their balance, deduct funds, and
update their status.

If you hardcode database queries (SQL/ORM) into this service, 
you cannot unit test it without a real database. 

Instead, we use a `UserRepository` interface. For production, we
use a `SqlUserRepository`. For testing, we use a `FakeUserRepository`.

KEY INSIGHT:
------------
The `UserService` (Business Logic) knows absolutely NOTHING about SQL,
sessions, connections, or database tables. It only knows about the
pure `User` entity and the `UserRepository` protocol.

============================================================
"""

from typing import Protocol, Optional
from dataclasses import dataclass


# ─── 1. Domain Entity (Pure Python, No DB logic) ────────

@dataclass
class User:
    """A pure domain entity. Contains business logic and data."""
    id: int
    name: str
    balance: float
    is_premium: bool = False
    
    def can_afford(self, amount: float) -> bool:
        return self.balance >= amount
        
    def upgrade_to_premium(self) -> None:
        if self.is_premium:
            raise ValueError("User is already premium!")
        self.is_premium = True
        self.balance -= 100.0


# ─── 2. Repository Interface ───────────────────────────

class UserRepository(Protocol):
    """The contract for data access. Completely independent of the DB."""
    
    def get(self, user_id: int) -> Optional[User]: ...
    def save(self, user: User) -> None: ...


# ─── 3. Business Service (The Use Case) ────────────────

class UserService:
    """
    Business Logic Layer. 
    Notice how it takes the repository via Dependency Injection.
    """
    def __init__(self, repo: UserRepository) -> None:
        self.repo = repo
        
    def upgrade_user(self, user_id: int) -> None:
        print(f"  [Service] Attempting to upgrade user {user_id}...")
        
        user = self.repo.get(user_id)
        if not user:
            print("  ❌ Upgrade failed: User not found.")
            return
            
        if not user.can_afford(100.0):
            print(f"  ❌ Upgrade failed: {user.name} has insufficient funds (${user.balance:.2f}).")
            return
            
        # Execute business logic on the pure entity
        user.upgrade_to_premium()
        
        # Persist the changes
        self.repo.save(user)
        print(f"  ✅ Upgrade successful! {user.name} is now Premium. Balance: ${user.balance:.2f}")


# ─── 4. Concrete Repositories ──────────────────────────

class SqlUserRepository:
    """
    Production Repository.
    Pretend this connects to Postgres using SQLAlchemy.
    """
    def __init__(self, db_connection_string: str) -> None:
        print(f"  [DB] Connecting to Production Database at {db_connection_string}...")
        
    def get(self, user_id: int) -> Optional[User]:
        print(f"  [DB] Executing: SELECT * FROM users WHERE id = {user_id}")
        # Simulated DB fetch...
        return User(id=user_id, name="Production Proderson", balance=500.0)
        
    def save(self, user: User) -> None:
        print(f"  [DB] Executing: UPDATE users SET balance={user.balance}, is_premium={user.is_premium} WHERE id={user.id}")


class FakeUserRepository:
    """
    Testing Repository.
    Stores data in memory (a dictionary). Lightning fast. No DB required.
    """
    def __init__(self, initial_data: list[User]) -> None:
        self._store = {user.id: user for user in initial_data}
        
    def get(self, user_id: int) -> Optional[User]:
        print(f"  [TestRepo] Fetching user {user_id} from memory...")
        return self._store.get(user_id)
        
    def save(self, user: User) -> None:
        print(f"  [TestRepo] Saving user {user.id} to memory...")
        self._store[user.id] = user


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("REPOSITORY PATTERN")
    print("=" * 60)
    
    print("\n--- 1. Running in Production Mode ---")
    prod_repo = SqlUserRepository("postgresql://user:pass@localhost/db")
    prod_service = UserService(prod_repo)
    prod_service.upgrade_user(99)
    
    print("\n--- 2. Running in Unit Test Mode ---")
    # We can easily setup edge cases without touching a database!
    test_repo = FakeUserRepository([
        User(id=1, name="Alice (Rich)", balance=500.0),
        User(id=2, name="Bob (Poor)", balance=20.0)
    ])
    test_service = UserService(test_repo)
    
    print("\n  [Testing Bob (Should Fail)]")
    test_service.upgrade_user(2)
    
    print("\n  [Testing Alice (Should Succeed)]")
    test_service.upgrade_user(1)
    
    print("\n✅ Repository pattern demonstrated successfully!")

"""
============================================================
Example: Bank Transfer with Unit of Work
Pattern: Unit of Work (Architectural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You need to transfer $500 from Alice's account to Bob's account.
1. Deduct $500 from Alice.
2. Add $500 to Bob.

If step 1 succeeds but step 2 crashes (e.g. database disconnects), 
the money is destroyed! It vanished into the void.

To fix this, we use a Unit of Work (UoW). The UoW ensures that BOTH
operations happen together (Atomicity). If anything fails, it rolls
back all changes.

KEY INSIGHT:
------------
We use Python Context Managers (`__enter__` and `__exit__`).
If an exception occurs inside the `with` block, `__exit__` catches
it and calls `rollback()`.

============================================================
"""

from abc import ABC, abstractmethod
from types import TracebackType


# ─── Simulated Database ────────────────────────────────

class FakeDatabaseSession:
    """Simulates an ORM session (like SQLAlchemy's Session)."""
    def __init__(self) -> None:
        self.accounts = {"Alice": 1000, "Bob": 100}
        self.uncommitted_changes: dict[str, int] = {}
        self.is_active = False
        
    def begin(self) -> None:
        self.is_active = True
        self.uncommitted_changes.clear()
        print("  [DB] BEGIN TRANSACTION")
        
    def commit(self) -> None:
        if not self.is_active: return
        self.accounts.update(self.uncommitted_changes)
        self.is_active = False
        self.uncommitted_changes.clear()
        print("  [DB] COMMIT")
        
    def rollback(self) -> None:
        if not self.is_active: return
        self.is_active = False
        self.uncommitted_changes.clear()
        print("  [DB] ROLLBACK (Discarding pending changes)")
        
    def update_balance(self, user: str, new_balance: int) -> None:
        self.uncommitted_changes[user] = new_balance


# ─── Repositories ──────────────────────────────────────

class AccountRepository:
    """Takes a session and uses it to execute queries."""
    def __init__(self, session: FakeDatabaseSession) -> None:
        self.session = session
        
    def get_balance(self, user: str) -> int:
        # Check uncommitted changes first, then committed state
        return self.session.uncommitted_changes.get(user, self.session.accounts[user])
        
    def set_balance(self, user: str, balance: int) -> None:
        print(f"  [Repo] Setting {user}'s balance to ${balance}")
        self.session.update_balance(user, balance)


# ─── Unit Of Work ──────────────────────────────────────

class AbstractUnitOfWork(ABC):
    accounts: AccountRepository
    
    def __enter__(self) -> 'AbstractUnitOfWork':
        return self
        
    def __exit__(
        self, 
        exc_type: type[BaseException] | None, 
        exc_val: BaseException | None, 
        exc_tb: TracebackType | None
    ) -> None:
        """Called automatically when the 'with' block ends."""
        if exc_type:
            self.rollback() # An error happened! Rollback!
        
    @abstractmethod
    def commit(self) -> None: ...
    @abstractmethod
    def rollback(self) -> None: ...


class DatabaseUnitOfWork(AbstractUnitOfWork):
    def __init__(self, session: FakeDatabaseSession) -> None:
        self.session = session
        
    def __enter__(self) -> 'DatabaseUnitOfWork':
        # 1. Start the transaction
        self.session.begin()
        
        # 2. Instantiate repositories injecting the active session
        self.accounts = AccountRepository(self.session)
        return super().__enter__()
        
    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        super().__exit__(exc_type, exc_val, exc_tb)
        # We always rollback at the end. If commit() was called successfully
        # inside the block, this rollback does nothing.
        self.rollback()
        
    def commit(self) -> None:
        self.session.commit()
        
    def rollback(self) -> None:
        self.session.rollback()


# ─── Business Logic (The Service) ──────────────────────

def transfer_money(uow: AbstractUnitOfWork, sender: str, receiver: str, amount: int, crash: bool = False) -> None:
    print(f"\n--- Initiating Transfer: ${amount} from {sender} to {receiver} ---")
    
    try:
        # THE MAGIC HAPPENS HERE
        with uow:
            # 1. Read balances
            sender_bal = uow.accounts.get_balance(sender)
            receiver_bal = uow.accounts.get_balance(receiver)
            
            # 2. Modify balances
            uow.accounts.set_balance(sender, sender_bal - amount)
            
            # Simulate a system crash right in the middle!
            if crash:
                print("  💥 SYSTEM CRASH (Power out, Exception thrown)!")
                raise Exception("System crash!")
                
            uow.accounts.set_balance(receiver, receiver_bal + amount)
            
            # 3. Commit only if we reach the end
            uow.commit()
            print("  ✅ Transfer successful.")
            
    except Exception as e:
        print(f"  ❌ Transfer failed: {e}")


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("UNIT OF WORK PATTERN - Bank Transfer")
    print("=" * 60)
    
    # Setup global database connection
    db_session = FakeDatabaseSession()
    
    print("\nInitial State:")
    print(f"  Alice: ${db_session.accounts['Alice']}")
    print(f"  Bob: ${db_session.accounts['Bob']}")
    
    # Scenario 1: Successful Transfer
    transfer_money(DatabaseUnitOfWork(db_session), "Alice", "Bob", 200)
    print("\nState after Scenario 1:")
    print(f"  Alice: ${db_session.accounts['Alice']} (Expected: 800)")
    print(f"  Bob: ${db_session.accounts['Bob']} (Expected: 300)")
    
    # Scenario 2: Crashed Transfer (Money should NOT be lost!)
    transfer_money(DatabaseUnitOfWork(db_session), "Alice", "Bob", 500, crash=True)
    print("\nState after Scenario 2 (Crash):")
    print(f"  Alice: ${db_session.accounts['Alice']} (Expected: 800 - No change!)")
    print(f"  Bob: ${db_session.accounts['Bob']} (Expected: 300 - No change!)")
    
    print("\n✅ Unit of Work pattern demonstrated successfully!")

"""
============================================================
Example: Manual DI & Mini DI Container
Pattern: Dependency Injection (Architectural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
You have a `NotificationService` that needs to fetch users from a
database and send them an SMS message.

Instead of hardcoding `PostgresDatabase()` and `TwilioSMSClient()`
inside the service, we use Dependency Injection.

We will show TWO ways to wire this up:
1. Manual wiring (doing it yourself).
2. Using a basic Dependency Injection Container (IoC).

KEY INSIGHT:
------------
The `NotificationService` ONLY relies on Protocols (Interfaces).
It has zero knowledge of Postgres or Twilio.

============================================================
"""

from typing import Protocol, Type, Any, Callable, Dict


# ─── 1. The Abstractions (Protocols) ───────────────────

class DatabaseProtocol(Protocol):
    def get_phone_number(self, user_id: int) -> str: ...

class SMSClientProtocol(Protocol):
    def send_sms(self, phone: str, message: str) -> None: ...


# ─── 2. The Low-Level Modules (Details) ────────────────

class PostgresDatabase:
    """A concrete implementation of DatabaseProtocol."""
    def get_phone_number(self, user_id: int) -> str:
        print("  [DB] Connecting to Postgres...")
        return f"+1-555-010{user_id}"

class TwilioSMSClient:
    """A concrete implementation of SMSClientProtocol."""
    def __init__(self, api_key: str) -> None:
        self.api_key = api_key
        
    def send_sms(self, phone: str, message: str) -> None:
        print(f"  [Twilio] Sending '{message}' to {phone} using key {self.api_key[:4]}...")


# ─── 3. The High-Level Module (Business Logic) ─────────

class NotificationService:
    """
    Notice the CONSTRUCTOR INJECTION.
    We ask for the Protocols, not the concrete classes!
    """
    def __init__(self, db: DatabaseProtocol, sms: SMSClientProtocol) -> None:
        self.db = db
        self.sms = sms
        
    def notify_user(self, user_id: int, message: str) -> None:
        print(f"\n--- Notifying User {user_id} ---")
        phone = self.db.get_phone_number(user_id)
        self.sms.send_sms(phone, message)


# ==========================================================
# METHOD 1: Manual Wiring
# ==========================================================

print("=" * 60)
print("DEPENDENCY INJECTION - Manual Wiring")
print("=" * 60)

# We act as the "Mechanic". We build the parts, then assemble the car.
db_instance = PostgresDatabase()
sms_instance = TwilioSMSClient("sk_live_987654321")

# We pass the dependencies IN.
service = NotificationService(db=db_instance, sms=sms_instance)
service.notify_user(1, "Your pizza is ready!")


# ==========================================================
# METHOD 2: Mini DI Container (Inversion of Control)
# ==========================================================
# In complex apps, building 50 objects manually is tedious.
# A DI Container automates the wiring.

class DIContainer:
    """A very basic DI Container."""
    def __init__(self) -> None:
        # Maps a Protocol to a factory function that builds the concrete class
        self._providers: Dict[Type, Callable[[], Any]] = {}
        
    def register(self, protocol: Type, factory: Callable[[], Any]) -> None:
        """Register how to build a certain type."""
        self._providers[protocol] = factory
        
    def resolve(self, protocol: Type) -> Any:
        """Ask the container for an object, and it builds it for you."""
        if protocol not in self._providers:
            raise ValueError(f"No provider registered for {protocol}")
        return self._providers[protocol]()


print("\n" + "=" * 60)
print("DEPENDENCY INJECTION - IoC Container")
print("=" * 60)

container = DIContainer()

# 1. Configuration Phase: Tell the container how to build things
container.register(DatabaseProtocol, lambda: PostgresDatabase())
container.register(SMSClientProtocol, lambda: TwilioSMSClient("sk_live_987654321"))

# 2. Wire up the Service
# We ask the container to resolve the dependencies for us!
container.register(
    NotificationService, 
    lambda: NotificationService(
        db=container.resolve(DatabaseProtocol), 
        sms=container.resolve(SMSClientProtocol)
    )
)

# 3. Execution Phase: Just ask for the finished service!
# (Notice we don't manually build the DB or SMS client here!)
app_service: NotificationService = container.resolve(NotificationService)
app_service.notify_user(2, "Your driver is arriving.")

print("\n✅ Dependency Injection demonstrated successfully!")

"""
============================================================
Example: Event Sourced Bank Account
Pattern: Event Sourcing & CQRS (Architectural)
Framework: Pure Python
============================================================

REAL-WORLD SCENARIO:
--------------------
We are building a Bank. We cannot use standard CRUD (UPDATE/DELETE).
We must use Event Sourcing to maintain a perfect audit log.

We will build:
1. An Event Store (Append-only log of facts).
2. A Write Side (Processes Commands and creates Events).
3. A Read Side / Projection (Listens to Events and updates the balance).

KEY INSIGHT:
------------
Notice that we NEVER do `balance = new_amount`. We only ever append 
events to a list. The current balance is derived by replaying history.

============================================================
"""

from dataclasses import dataclass
from datetime import datetime
from typing import List, Dict, Protocol


# ─── 1. Events (Immutable Facts) ───────────────────────
# Events are named in the PAST TENSE. They have already happened.

@dataclass(frozen=True)
class Event:
    account_id: str
    timestamp: datetime = datetime.now()

@dataclass(frozen=True)
class AccountOpenedEvent(Event):
    initial_deposit: int = 0

@dataclass(frozen=True)
class MoneyDepositedEvent(Event):
    amount: int = 0

@dataclass(frozen=True)
class MoneyWithdrawnEvent(Event):
    amount: int = 0


class Projection(Protocol):
    """Protocol for Read Models / Projections that consume domain events."""
    def handle_event(self, event: Event) -> None:
        ...


# ─── 2. Event Store (The Single Source of Truth) ───────

class EventStore:
    """An append-only database (like Kafka or EventStoreDB)."""
    def __init__(self) -> None:
        # Dictionary mapping account_id -> List of Events
        self.streams: Dict[str, List[Event]] = {}
        # Simple PubSub for the Read Models
        self.subscribers: List['Projection'] = []
        
    def append(self, event: Event) -> None:
        if event.account_id not in self.streams:
            self.streams[event.account_id] = []
            
        self.streams[event.account_id].append(event)
        print(f"  💾 [EventStore] Appended: {type(event).__name__}")
        
        # Notify the Read Side (CQRS)
        for sub in self.subscribers:
            sub.handle_event(event)
            
    def get_stream(self, account_id: str) -> List[Event]:
        """Fetch all history for an account."""
        return self.streams.get(account_id, [])


# ─── 3. Write Side / Command API ───────────────────────
# Handles business logic, validates rules, and generates events.

class BankAccountService:
    def __init__(self, event_store: EventStore) -> None:
        self.event_store = event_store
        
    def open_account(self, account_id: str, deposit: int) -> None:
        # Validate Command
        if deposit < 0: raise ValueError("Cannot open with negative balance")
        
        # Generate and Save Event
        event = AccountOpenedEvent(account_id=account_id, initial_deposit=deposit)
        self.event_store.append(event)
        
    def deposit(self, account_id: str, amount: int) -> None:
        if amount <= 0: raise ValueError("Deposit must be positive")
        event = MoneyDepositedEvent(account_id=account_id, amount=amount)
        self.event_store.append(event)
        
    def withdraw(self, account_id: str, amount: int) -> None:
        # WARNING: In a real Event Sourced system, we have to rebuild the 
        # state here to ensure they have enough funds before withdrawing!
        # For this simple example, we skip the balance check.
        if amount <= 0: raise ValueError("Withdrawal must be positive")
        event = MoneyWithdrawnEvent(account_id=account_id, amount=amount)
        self.event_store.append(event)


# ─── 4. Read Side / Projection (CQRS) ──────────────────
# A background worker that listens to events and updates a fast DB for queries.

class BalanceProjection:
    """The Read Model. Highly optimized for fast queries."""
    def __init__(self) -> None:
        # This acts like a Redis cache or a highly indexed SQL table
        self.read_database: Dict[str, int] = {}
        
    def handle_event(self, event: Event) -> None:
        """Called automatically when the EventStore receives a new event."""
        account_id = event.account_id
        
        # Initialize if not exists
        if account_id not in self.read_database:
            self.read_database[account_id] = 0
            
        # Apply the changes to the Read DB
        if isinstance(event, AccountOpenedEvent):
            self.read_database[account_id] += event.initial_deposit
        elif isinstance(event, MoneyDepositedEvent):
            self.read_database[account_id] += event.amount
        elif isinstance(event, MoneyWithdrawnEvent):
            self.read_database[account_id] -= event.amount
            
        print(f"  📊 [Projection] Updated Read DB. {account_id} Balance is now ${self.read_database[account_id]}")

    def query_balance(self, account_id: str) -> int:
        """Lightning fast query. No calculations needed!"""
        return self.read_database.get(account_id, 0)


# ─── 5. Time Travel (Replaying History) ────────────────
# If the Read DB crashes, we can rebuild it from scratch!

def rebuild_state_from_events(events: List[Event]) -> int:
    balance = 0
    for event in events:
        if isinstance(event, AccountOpenedEvent): balance += event.initial_deposit
        elif isinstance(event, MoneyDepositedEvent): balance += event.amount
        elif isinstance(event, MoneyWithdrawnEvent): balance -= event.amount
    return balance


# ─── Demo ──────────────────────────────────────────────
if __name__ == "__main__":
    print("=" * 60)
    print("EVENT SOURCING & CQRS - Bank Account")
    print("=" * 60)
    
    # Setup Infrastructure
    store = EventStore()
    projection = BalanceProjection()
    store.subscribers.append(projection) # Connect the Read Side to the EventStore
    
    # Setup Write API
    service = BankAccountService(store)
    
    print("\n--- Processing Commands (Write Side) ---")
    service.open_account("ACC_123", 500)
    service.deposit("ACC_123", 200)
    service.withdraw("ACC_123", 100)
    service.deposit("ACC_123", 50)
    
    print("\n--- Processing Queries (Read Side) ---")
    # Client asks for balance. It queries the lightning fast Read DB.
    final_balance = projection.query_balance("ACC_123")
    print(f"  🔎 Fast Query Result: ${final_balance}")
    
    print("\n--- Auditing / Time Travel ---")
    # The bank auditors want to know HOW we got that number.
    history = store.get_stream("ACC_123")
    print("  📜 Audit Log:")
    for i, e in enumerate(history):
        print(f"     Step {i+1}: {type(e).__name__} {e}")
        
    print("\n  [Disaster Recovery] Read DB crashed! Rebuilding from Event Store...")
    rebuilt_balance = rebuild_state_from_events(history)
    print(f"  🛠️  Rebuilt Balance: ${rebuilt_balance}")
    
    print("\n✅ Event Sourcing & CQRS demonstrated successfully!")