Advanced Examples

"""Example 58: Refactor Inheritance to Composition.
 
co-33 (refactor to pattern): a 4-level inheritance hierarchy, each level bolting on
one orthogonal capability (logging, retry, throttling), is refactored to a single
depth-1 class composed with small behavior objects -- co-09 (grasp-low-coupling):
the composed version needs zero new subclasses to add a capability, only a new
wrapper object. test_example.py locks both versions' observable behavior so the
refactor is verifiably safe.
"""
 
from __future__ import annotations
 
from dataclasses import dataclass, field
 
# ============================================================
# BEFORE: a 4-level inheritance hierarchy, one capability per level
# ============================================================
 
 
class Notifier:  # => level 1 (base): just sends -- no capabilities yet
    def send(self, message: str) -> str:  # => returns what was "sent", stubbed as a string for this example
        return f"SEND:{message}"  # => the delivery itself
 
 
class LoggingNotifier(Notifier):  # => level 2: bolts on logging via override
    def __init__(self) -> None:  # => LoggingNotifier's constructor takes no new parameters beyond self
        self.log: list[str] = []  # => records every message this notifier has sent
 
    def send(self, message: str) -> str:  # => override adds ONE capability: logging
        self.log.append(message)  # => side effect before delegating up
        return super().send(message)  # => delegates to level 1's real send
 
 
# => level 3 repeats level 2's override-and-delegate shape one layer deeper, adding retry state
class RetryingLoggingNotifier(LoggingNotifier):  # => level 3: bolts on retry, on top of logging
    def __init__(self, attempts: int) -> None:  # => adds one new constructor parameter for this level's capability
        super().__init__()  # => must still wire up level 2's state
        self.attempts = attempts  # => how many times to retry
 
    def send(self, message: str) -> str:  # => override adds a SECOND capability: retry
        last_result = ""  # => tracks the most recent attempt's result
        for _ in range(self.attempts):  # => retry loop wraps the logging+base chain
            last_result = super().send(message)  # => delegates up two levels each iteration
        return last_result  # => the final attempt's result
 
 
# => level 4 keeps stacking: every new capability means one more override plus one more __init__ chain link
class ThrottledRetryingLoggingNotifier(RetryingLoggingNotifier):  # => level 4: bolts on throttling
    def __init__(self, attempts: int, max_calls: int) -> None:  # => now carries state for capabilities from two different levels
        super().__init__(attempts)  # => must wire up levels 3 AND 2's __init__ chain
        self.max_calls = max_calls  # => a THIRD, independent capability: a call budget
        self.calls_made = 0  # => how many sends have happened so far
 
    def send(self, message: str) -> str:  # => override adds a THIRD capability: throttling
        if self.calls_made >= self.max_calls:  # => guard: budget exhausted
            return "THROTTLED"  # => refuse to send once the budget is spent
        self.calls_made += 1  # => consume one unit of budget
        return super().send(message)  # => delegates up the whole three-level chain
        # => one send() call now cascades through 4 stacked overrides: throttle -> retry -> logging -> base
 
 
# ============================================================
# AFTER: one depth-1 class, capabilities composed as small standalone objects
# ============================================================
 
 
@dataclass  # => auto-generates __init__ from the single field below
class LoggingBehavior:  # => composed equivalent of LoggingNotifier -- one small standalone class
    log: list[str] = field(default_factory=list)  # => same responsibility, now owned independently
 
 
# => this single class replaces all 4 inheritance levels above, using composed collaborators instead of subclassing
class ComposedNotifier:  # => depth 1: no subclass at all -- capabilities are composed, not inherited
    def __init__(self, logging: LoggingBehavior | None = None) -> None:  # => takes an OPTIONAL composed capability instead of a hardcoded subclass chain
        self.logging = logging  # => an OPTIONAL logging capability, composed in per instance
 
    def raw_send(self, message: str) -> str:  # => the equivalent of Notifier.send() in the old hierarchy
        if self.logging is not None:  # => only log if a LoggingBehavior was composed in
            self.logging.log.append(message)  # => same log side effect, now opt-in rather than baked into a subclass
        return f"SEND:{message}"  # => identical delivery stub to the inheritance version
 
 
@dataclass  # => auto-generates __init__ for the retry capability's single field
class RetryBehavior:  # => composed equivalent of the retry capability -- reusable on its own
    attempts: int  # => how many times to retry
 
 
@dataclass  # => auto-generates __init__ for the throttle capability's two fields
class ThrottleBehavior:  # => composed equivalent of the throttle capability -- reusable on its own
    max_calls: int  # => the call budget
    calls_made: int = 0  # => mutable counter, local to this one small class
 
 
# => a free function stands in for a 4th subclass level, since retry/throttle here are simple per-call parameters
def send_with_capabilities(  # => a free function stands in for what would have been a 4th subclass level
    notifier: ComposedNotifier,  # => the base object, already composed with logging
    message: str,  # => the message to send
    retry: RetryBehavior,  # => the retry capability, composed in as a parameter
    throttle: ThrottleBehavior,  # => the throttle capability, composed in as a parameter
) -> str:  # => closes the multi-line signature; the function still returns a plain string like the old send()
    if throttle.calls_made >= throttle.max_calls:  # => throttle checked first, matching the old outermost override
        return "THROTTLED"  # => matches ThrottledRetryingLoggingNotifier's early return
    throttle.calls_made += 1  # => consumes budget exactly once per call, matching the old behavior
    last_result = ""  # => tracks the final attempt across retries
    for _ in range(retry.attempts):  # => same retry loop as before, now composed rather than inherited
        last_result = notifier.raw_send(message)  # => delegates to the composed base (which itself logs)
    return last_result  # => the final attempt's result
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    old_notifier = ThrottledRetryingLoggingNotifier(attempts=2, max_calls=5)  # => 4-level inheritance version
    print(old_notifier.send("hello"))  # => exercises the full inherited chain
    # => Output: SEND:hello
    logging_behavior = LoggingBehavior()  # => the composed logging unit
    new_notifier = ComposedNotifier(logging=logging_behavior)  # => depth-1 composed version
    result = send_with_capabilities(new_notifier, "hello", RetryBehavior(attempts=2), ThrottleBehavior(max_calls=5))  # => exercises the composed equivalent
    print(result)  # => identical output to the inheritance version
    # => Output: SEND:hello
    print(len(ThrottledRetryingLoggingNotifier.__mro__))  # => old hierarchy: 4 custom classes + object
    # => Output: 5
    print(ComposedNotifier.__mro__ == (ComposedNotifier, object))  # => new version: depth 1, no intermediate bases
    # => Output: True

SEND:hello
SEND:hello
5
True

"""Example 58: pytest verification that behavior is unchanged after the composition refactor."""
 
from example import (
    ComposedNotifier,
    LoggingBehavior,
    RetryBehavior,
    ThrottledRetryingLoggingNotifier,
    ThrottleBehavior,
    send_with_capabilities,
)
 
 
def test_inheritance_and_composition_versions_agree_on_successful_sends() -> None:
    old = ThrottledRetryingLoggingNotifier(attempts=2, max_calls=5)  # => 4-level inheritance version
    old_result = old.send("hello")  # => exercises the full inherited chain
    logging = LoggingBehavior()  # => the composed logging unit
    new = ComposedNotifier(logging=logging)  # => depth-1 composed version
    new_result = send_with_capabilities(new, "hello", RetryBehavior(attempts=2), ThrottleBehavior(max_calls=5))
    assert old_result == new_result == "SEND:hello"  # => both versions produce identical output
    assert old.log == logging.log == ["hello", "hello"]  # => both log every retry attempt identically
 
 
def test_throttling_behavior_is_identical_once_budget_is_exhausted() -> None:
    old = ThrottledRetryingLoggingNotifier(attempts=1, max_calls=1)  # => budget of exactly one call
    old.send("first")  # => consumes the single-call budget
    old_second = old.send("second")  # => budget exhausted -- should be throttled
    logging = LoggingBehavior()
    new = ComposedNotifier(logging=logging)
    retry = RetryBehavior(attempts=1)
    throttle = ThrottleBehavior(max_calls=1)
    send_with_capabilities(new, "first", retry, throttle)  # => consumes the composed version's budget too
    new_second = send_with_capabilities(new, "second", retry, throttle)  # => should also be throttled
    assert old_second == new_second == "THROTTLED"  # => both versions refuse identically once budget is spent
 
 
def test_composed_version_has_inheritance_depth_of_exactly_one() -> None:
    assert ComposedNotifier.__mro__ == (ComposedNotifier, object)  # => depth 1: no intermediate base classes
    assert len(ThrottledRetryingLoggingNotifier.__mro__) == 5  # => old version: 4 custom levels + object
 
 
# => Run: pytest -q -- Output: 3 passed

3 passed

"""Example 59: Refactor to Strategy.
 
co-33 (refactor to pattern): an embedded if-chain computing shipping cost by method
name is refactored to a strategy family under a locking test suite that stays green
through every step -- co-25 (strategy): each shipping method becomes its own small
callable, and the dispatcher looks the method up instead of branching on it.
"""
 
from __future__ import annotations
 
from typing import Callable
 
# ============================================================
# BEFORE: an if-chain that must be edited for every new shipping method
# ============================================================
 
 
def shipping_cost_if_chain(method: str, weight_kg: float) -> float:  # => the original, unrefactored dispatcher
    if method == "standard":  # => branch 1: flat rate per kg
        return 2.0 * weight_kg  # => $2/kg
    elif method == "express":  # => branch 2: higher flat rate
        return 5.0 * weight_kg  # => $5/kg
    elif method == "overnight":  # => branch 3: highest flat rate plus a surcharge
        return 10.0 * weight_kg + 15.0  # => $10/kg plus a $15 fixed surcharge
    raise ValueError(f"unknown shipping method: {method}")  # => every new method needs a new elif here (OCP violation)
 
 
# ============================================================
# AFTER: a strategy family -- new methods are added, not edited into a switch
# ============================================================
 
ShippingStrategy = Callable[[float], float]  # => a strategy is just "weight_kg -> cost", nothing more
 
 
def standard_shipping(weight_kg: float) -> float:  # => strategy 1, extracted verbatim from the if-chain
    return 2.0 * weight_kg  # => identical formula to the "standard" branch above
 
 
def express_shipping(weight_kg: float) -> float:  # => strategy 2, extracted verbatim
    return 5.0 * weight_kg  # => identical formula to the "express" branch above
 
 
def overnight_shipping(weight_kg: float) -> float:  # => strategy 3, extracted verbatim
    return 10.0 * weight_kg + 15.0  # => identical formula to the "overnight" branch above
 
 
# => three strategies extracted so far, each a pure one-line function with the exact old formula
SHIPPING_STRATEGIES: dict[str, ShippingStrategy] = {  # => the dispatch table replaces the if-chain entirely
    "standard": standard_shipping,  # => maps the method name to its strategy function
    "express": express_shipping,  # => maps a second method name to its strategy function
    "overnight": overnight_shipping,  # => maps a third method name to its strategy function
}  # => closes the dispatch table literal
 
 
def shipping_cost_via_strategy(method: str, weight_kg: float) -> float:  # => the refactored dispatcher
    strategy = SHIPPING_STRATEGIES.get(method)  # => look up the strategy by name, no branching required
    if strategy is None:  # => guard: unknown method still raises, matching the old behavior
        raise ValueError(f"unknown shipping method: {method}")  # => identical error message to the if-chain version
    return strategy(weight_kg)  # => delegate to whichever strategy was found
 
 
# => this is the OCP payoff: shipping_cost_via_strategy above needs zero edits to support this new method
def bulk_shipping(weight_kg: float) -> float:  # => a FOURTH method, added with zero edits to the dispatcher above
    return 1.0 * weight_kg - 3.0  # => cheapest rate, bulk discount baked in
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    print(shipping_cost_if_chain("express", 4.0))  # => old dispatcher, exercised for comparison
    # => Output: 20.0
    print(shipping_cost_via_strategy("express", 4.0))  # => new dispatcher, identical result
    # => Output: 20.0
    SHIPPING_STRATEGIES["bulk"] = bulk_shipping  # => adding "bulk" required zero edits to shipping_cost_via_strategy
    print(shipping_cost_via_strategy("bulk", 10.0))  # => the newly registered strategy works immediately
    # => Output: 7.0

20.0
20.0
7.0

"""Example 59: pytest verification that the strategy refactor stays green throughout."""
 
import pytest
 
from example import (
    SHIPPING_STRATEGIES,
    bulk_shipping,
    shipping_cost_if_chain,
    shipping_cost_via_strategy,
)
 
 
@pytest.mark.parametrize(
    "method,weight,expected",
    [("standard", 3.0, 6.0), ("express", 4.0, 20.0), ("overnight", 2.0, 35.0)],
)  # => same three cases run through both dispatchers, proving the refactor changed nothing observable
def test_old_and_new_dispatchers_agree_on_every_known_method(method: str, weight: float, expected: float) -> None:
    assert shipping_cost_if_chain(method, weight) == expected  # => old if-chain dispatcher
    assert shipping_cost_via_strategy(method, weight) == expected  # => new strategy-table dispatcher
 
 
def test_both_dispatchers_reject_an_unknown_method_identically() -> None:
    with pytest.raises(ValueError, match="unknown shipping method"):  # => old dispatcher's error
        shipping_cost_if_chain("teleport", 1.0)
    with pytest.raises(ValueError, match="unknown shipping method"):  # => new dispatcher's error, same message
        shipping_cost_via_strategy("teleport", 1.0)
 
 
def test_adding_a_new_strategy_requires_zero_edits_to_the_dispatcher() -> None:
    SHIPPING_STRATEGIES["bulk"] = bulk_shipping  # => registers a fourth strategy at test time
    assert shipping_cost_via_strategy("bulk", 10.0) == 7.0  # => works immediately, no dispatcher code changed
    del SHIPPING_STRATEGIES["bulk"]  # => cleans up so this test does not leak state into other tests
 
 
# => Run: pytest -q -- Output: 5 passed

5 passed

"""Example 60: Refactor to State.
 
co-33 (refactor to pattern): a boolean-flag implementation of order lifecycle
(is_paid, is_shipped, is_cancelled -- independently settable) is refactored to the
State pattern -- co-29 (state): each lifecycle stage becomes its own class, and the
current-state object is the only thing that decides which transitions are legal,
making invalid flag combinations unrepresentable.
"""
 
from __future__ import annotations
 
from abc import ABC, abstractmethod
 
# ============================================================
# BEFORE: boolean-flag soup -- nothing prevents illegal combinations
# ============================================================
 
 
class FlagOrder:  # => the original, unrefactored order
    def __init__(self) -> None:  # => sets up all three independent boolean flags below
        self.is_paid = False  # => three independent booleans...
        self.is_shipped = False  # => ...that can be set in ANY combination...
        self.is_cancelled = False  # => ...including ones that make no business sense
 
    def mark_shipped(self) -> None:  # => nothing here checks is_paid first
        self.is_shipped = True  # => BUG: this can fire even when is_paid is still False
        # => nothing in FlagOrder's design stops mark_shipped() from running before is_paid is ever set
 
 
# ============================================================
# AFTER: the State pattern -- illegal transitions are structurally impossible
# ============================================================
 
 
class OrderState(ABC):  # => the shared interface every concrete state implements
    @abstractmethod  # => forces every concrete state to define its own pay() behavior
    def pay(self, order: "StateOrder") -> None:  # => only states where paying is legal override this meaningfully
        raise NotImplementedError  # => abstract method body, never actually executed
 
    @abstractmethod  # => forces every concrete state to define its own ship() behavior
    def ship(self, order: "StateOrder") -> None:  # => only the Paid state allows shipping
        raise NotImplementedError  # => abstract method body, never actually executed
 
    def name(self) -> str:  # => a readable label for the current state, used in tests and printing
        return type(self).__name__  # => e.g. "Created", "Paid", "Shipped"
 
 
class Created(OrderState):  # => the starting state: nothing has happened yet
    def pay(self, order: "StateOrder") -> None:  # => the ONLY legal transition out of Created
        order.state = Paid()  # => moves the order into the Paid state
 
    def ship(self, order: "StateOrder") -> None:  # => shipping from Created is illegal
        raise ValueError("cannot ship an order that has not been paid")  # => structurally rejected, not just unwise
 
 
# => Paid is reachable only via Created.pay() above -- there is no way to construct an order that skips it
class Paid(OrderState):  # => after payment, before shipping
    def pay(self, order: "StateOrder") -> None:  # => paying twice is illegal
        raise ValueError("order is already paid")  # => Paid has no legal pay() transition
 
    def ship(self, order: "StateOrder") -> None:  # => the ONLY legal transition out of Paid
        order.state = Shipped()  # => moves the order into the Shipped state
 
 
# => Shipped is the terminal state: both its methods only ever raise, matching a real "closed" order
class Shipped(OrderState):  # => the terminal happy-path state
    def pay(self, order: "StateOrder") -> None:  # => paying a shipped order is illegal
        raise ValueError("order is already shipped")  # => Shipped has no legal pay() transition
 
    def ship(self, order: "StateOrder") -> None:  # => shipping twice is illegal
        raise ValueError("order is already shipped")  # => Shipped has no legal ship() transition
 
 
# => StateOrder itself contains ZERO business rules -- every legality check lives inside the state classes above
class StateOrder:  # => the refactored order -- delegates every transition to its current state object
    def __init__(self) -> None:  # => starts every new order in a single, well-defined state
        self.state: OrderState = Created()  # => starts in the Created state, same as FlagOrder's initial flags
 
    def pay(self) -> None:  # => delegates to whichever state object is current
        self.state.pay(self)  # => the STATE decides whether this is legal, not an if-chain here
 
    def ship(self) -> None:  # => delegates to whichever state object is current
        self.state.ship(self)  # => "shipped without paid" cannot happen: Created.ship() always raises
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    flag_order = FlagOrder()  # => the old version
    flag_order.mark_shipped()  # => BUG reproduced: shipped is True even though paid is still False
    print(flag_order.is_shipped, flag_order.is_paid)  # => demonstrates the illegal combination the flags allow
    # => Output: True False
 
    state_order = StateOrder()  # => the refactored version
    try:  # => wraps the illegal transition attempt so its ValueError can be shown
        state_order.ship()  # => attempting the same illegal move
    except ValueError as exc:  # => catches the rejection raised by Created.ship()
        print(exc)  # => the State pattern rejects it outright
    # => Output: cannot ship an order that has not been paid
 
    state_order.pay()  # => legal: Created -> Paid
    state_order.ship()  # => legal: Paid -> Shipped
    print(state_order.state.name())  # => confirms the final state
    # => Output: Shipped

True False
cannot ship an order that has not been paid
Shipped

"""Example 60: pytest verification that state-object refactor makes illegal combos impossible."""
 
import pytest
 
from example import Created, FlagOrder, StateOrder
 
 
def test_flag_order_allows_the_illegal_shipped_without_paid_combination() -> None:
    order = FlagOrder()  # => reproduces the bug the refactor fixes
    order.mark_shipped()  # => nothing stops this even though is_paid is still False
    assert order.is_shipped is True and order.is_paid is False  # => the illegal combination exists
 
 
def test_state_order_rejects_shipping_before_payment() -> None:
    order = StateOrder()  # => starts in Created
    with pytest.raises(ValueError, match="not been paid"):  # => the illegal move is structurally rejected
        order.ship()
    assert isinstance(order.state, Created)  # => the order never left Created
 
 
def test_state_order_allows_the_legal_created_to_paid_to_shipped_path() -> None:
    order = StateOrder()
    order.pay()  # => Created -> Paid
    order.ship()  # => Paid -> Shipped
    assert order.state.name() == "Shipped"  # => reached the terminal state via only legal transitions
 
 
def test_state_order_rejects_paying_twice() -> None:
    order = StateOrder()
    order.pay()  # => first pay is legal
    with pytest.raises(ValueError, match="already paid"):  # => second pay is illegal
        order.pay()
 
 
# => Run: pytest -q -- Output: 4 passed

4 passed

"""Example 61: Refactor God Object.
 
co-33 (refactor to pattern): a god object mixing user validation, order pricing, and
receipt formatting is decomposed by applying co-01 (SRP) and co-06 (grasp-information-
expert) -- each responsibility moves to the class that already holds the data it
needs, and a locking test suite proves the decomposition preserves behavior.
"""
 
from __future__ import annotations
 
from dataclasses import dataclass, field
 
# ============================================================
# BEFORE: one class doing validation, pricing, AND formatting
# ============================================================
 
 
class GodShop:  # => three unrelated responsibilities crammed into one class
    def __init__(self) -> None:  # => sets up the shared price dictionary used by all three responsibilities
        self.items: dict[str, float] = {}  # => item name -> unit price, used by pricing
 
    def add_item(self, name: str, price: float) -> None:  # => pricing-related setup
        self.items[name] = price  # => stores the price for later total() calls
 
    def is_valid_email(self, email: str) -> bool:  # => VALIDATION concern, unrelated to pricing/formatting
        return "@" in email and "." in email.split("@")[-1]  # => a minimal, deliberately simple check
 
    def total(self, item_names: list[str]) -> float:  # => PRICING concern
        return sum(self.items[name] for name in item_names)  # => sums the requested items' prices
 
    def format_receipt(self, item_names: list[str]) -> str:  # => FORMATTING concern
        lines = [f"{name}: ${self.items[name]:.2f}" for name in item_names]  # => one line per item
        lines.append(f"TOTAL: ${self.total(item_names):.2f}")  # => reuses total(), coupling formatting to pricing
        return "\n".join(lines)  # => the full receipt as one string
 
 
# ============================================================
# AFTER: three cohesive classes, one responsibility each
# ============================================================
 
 
class EmailValidator:  # => SRP: validation, and only validation
    def is_valid(self, email: str) -> bool:  # => identical logic to GodShop.is_valid_email, now isolated
        return "@" in email and "." in email.split("@")[-1]  # => same check, moved to its own home
 
 
@dataclass  # => auto-generates __init__ from the prices field below
class Catalog:  # => grasp-information-expert: Catalog owns the prices, so it computes totals
    prices: dict[str, float] = field(default_factory=dict)  # => item name -> unit price
 
    def add_item(self, name: str, price: float) -> None:  # => pricing-related setup, unchanged behavior
        self.prices[name] = price  # => same assignment as GodShop.add_item, now scoped to pricing only
 
    def total(self, item_names: list[str]) -> float:  # => information-expert: Catalog holds prices, so it sums them
        return sum(self.prices[name] for name in item_names)  # => identical formula to GodShop.total
 
 
class ReceiptFormatter:  # => SRP: formatting, and only formatting -- depends on Catalog, not the other way around
    def __init__(self, catalog: Catalog) -> None:  # => depends on Catalog rather than owning prices itself
        self.catalog = catalog  # => the one collaborator this class needs
 
    def format(self, item_names: list[str]) -> str:  # => identical output to GodShop.format_receipt
        lines = [f"{name}: ${self.catalog.prices[name]:.2f}" for name in item_names]  # => same per-line format
        lines.append(f"TOTAL: ${self.catalog.total(item_names):.2f}")  # => delegates pricing to Catalog, not itself
        return "\n".join(lines)  # => identical join to the god-object version
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    god = GodShop()  # => the original god object
    god.add_item("Book", 12.5)  # => registers a price on the god object
    god.add_item("Pen", 1.5)  # => registers a second price on the god object
    print(god.format_receipt(["Book", "Pen"]))  # => exercises all three responsibilities through one class
    # => Output: Book: $12.50
    # => Pen: $1.50
    # => TOTAL: $14.00
 
    catalog = Catalog()  # => the decomposed version
    catalog.add_item("Book", 12.5)  # => registers the same price on the decomposed Catalog
    catalog.add_item("Pen", 1.5)  # => registers the same second price on the decomposed Catalog
    formatter = ReceiptFormatter(catalog)  # => formatter depends on catalog, not the reverse
    print(formatter.format(["Book", "Pen"]))  # => identical output, now via three cohesive classes
    # => Output: Book: $12.50
    # => Pen: $1.50
    # => TOTAL: $14.00

Book: $12.50
Pen: $1.50
TOTAL: $14.00
Book: $12.50
Pen: $1.50
TOTAL: $14.00

"""Example 61: pytest verification that the god-object decomposition preserves behavior."""
 
from example import Catalog, EmailValidator, GodShop, ReceiptFormatter
 
 
def test_god_object_and_decomposed_version_produce_identical_receipts() -> None:
    god = GodShop()
    god.add_item("Book", 12.5)
    god.add_item("Pen", 1.5)
    catalog = Catalog()
    catalog.add_item("Book", 12.5)
    catalog.add_item("Pen", 1.5)
    formatter = ReceiptFormatter(catalog)
    assert god.format_receipt(["Book", "Pen"]) == formatter.format(["Book", "Pen"])  # => byte-identical output
 
 
def test_email_validation_is_identical_after_extraction() -> None:
    god = GodShop()
    validator = EmailValidator()  # => the extracted, standalone responsibility
    for email in ["a@b.com", "not-an-email", "x@y"]:  # => same three cases through both implementations
        assert god.is_valid_email(email) == validator.is_valid(email)  # => behavior is unchanged after extraction
 
 
def test_each_decomposed_class_has_exactly_one_responsibility() -> None:
    validator = EmailValidator()
    assert not hasattr(validator, "total")  # => EmailValidator knows nothing about pricing
    catalog = Catalog()
    assert not hasattr(catalog, "format")  # => Catalog knows nothing about formatting
    assert not hasattr(catalog, "is_valid")  # => Catalog knows nothing about validation
 
 
# => Run: pytest -q -- Output: 3 passed

3 passed

"""Example 62: Anti-Pattern -- God Object.
 
co-34 (anti-pattern recognition): a god object is diagnosed by a simple, objective
metric -- the number of DISTINCT responsibilities (unrelated method groups) a single
class carries -- and a fix is sketched (not fully executed here; Example 61 executes
the equivalent fix for a smaller case) as "split by reason-to-change."
"""
 
from __future__ import annotations
 
 
# => this class deliberately mixes concerns to demonstrate the smell -- Example 61 shows the same smell fixed
class ApplicationManager:  # => a god object: user auth, email sending, AND report generation, all in one class
    def __init__(self) -> None:  # => sets up state for TWO of the three responsibilities this god object carries
        self.users: dict[str, str] = {}  # => username -> password, for AUTH
        self.sent_emails: list[str] = []  # => log of sent emails, for EMAIL
 
    # => below: two methods share the SAME state (self.users) -- a genuine, cohesive AUTH pair
    def register_user(self, username: str, password: str) -> None:  # => AUTH responsibility
        self.users[username] = password  # => mutates the AUTH state dict directly
 
    def authenticate(self, username: str, password: str) -> bool:  # => AUTH responsibility
        return self.users.get(username) == password  # => reads the same AUTH state dict to check credentials
 
    # => this method touches a DIFFERENT piece of state (self.sent_emails) than the two AUTH methods above
    def send_email(self, to: str, subject: str) -> None:  # => EMAIL responsibility, unrelated to auth
        self.sent_emails.append(f"{to}:{subject}")  # => mutates the EMAIL state list, a completely different concern
 
    # => this method touches NEITHER self.users NOR self.sent_emails -- it is a pure function bolted onto the class
    def generate_report(self, title: str, rows: list[str]) -> str:  # => REPORTING responsibility, unrelated to both
        return f"# {title}\n" + "\n".join(rows)
 
 
# => this function is the "objective metric" the docstring promises: it counts concerns, not lines of code
def count_distinct_responsibilities(cls: type) -> int:  # => a simple, mechanical god-object detector
    method_prefixes = {  # => groups methods by a naming-convention proxy for "responsibility"
        "register_user": "auth",  # => maps each method name to the concern it actually serves
        "authenticate": "auth",  # => a second AUTH-concern method
        "send_email": "email",  # => the EMAIL-concern method
        "generate_report": "reporting",  # => the REPORTING-concern method
    }  # => closes the method-to-concern mapping dict
    methods_on_class = [name for name in method_prefixes if hasattr(cls, name)]  # => which of these methods exist
    concerns = {method_prefixes[name] for name in methods_on_class}  # => the DISTINCT concerns those methods serve
    return len(concerns)  # => 1 concern = cohesive class; 2+ = candidate god object
 
 
# => intentionally a sketch, not a real refactor: Example 61 shows the equivalent split fully executed and tested
def sketch_fix() -> list[str]:  # => the fix is SKETCHED here (named responsibilities), not fully executed
    return [  # => opens the list of sketched, human-readable split targets
        "AuthService: register_user(), authenticate() -- owns self.users",  # => split 1
        "EmailService: send_email() -- owns self.sent_emails",  # => split 2
        "ReportService: generate_report() -- owns nothing, pure function of its arguments",  # => split 3
    ]  # => closes the sketched-fix list
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    count = count_distinct_responsibilities(ApplicationManager)  # => the diagnostic metric
    print(count)  # => 3 distinct concerns in ONE class -- the god-object smell, named
    # => Output: 3
    # => count_distinct_responsibilities is deliberately crude (a naming-convention lookup), but names the smell
    for line in sketch_fix():  # => print the sketched split, one responsibility per line
        print(line)  # => prints one sketched responsibility split per line
    # => Output: AuthService: register_user(), authenticate() -- owns self.users
    # => Output: EmailService: send_email() -- owns self.sent_emails
    # => Output: ReportService: generate_report() -- owns nothing, pure function of its arguments

3
AuthService: register_user(), authenticate() -- owns self.users
EmailService: send_email() -- owns self.sent_emails
ReportService: generate_report() -- owns nothing, pure function of its arguments

"""Example 62: pytest verification that the god-object smell is named and a fix sketched."""
 
from example import ApplicationManager, count_distinct_responsibilities, sketch_fix
 
 
def test_god_object_is_named_by_counting_distinct_responsibilities() -> None:
    assert count_distinct_responsibilities(ApplicationManager) == 3  # => auth + email + reporting, three concerns
 
 
def test_fix_is_sketched_with_one_line_per_extracted_responsibility() -> None:
    fix = sketch_fix()
    assert len(fix) == 3  # => one sketched service per responsibility identified above
    assert any("AuthService" in line for line in fix)  # => the auth split is named
    assert any("EmailService" in line for line in fix)  # => the email split is named
    assert any("ReportService" in line for line in fix)  # => the reporting split is named
 
 
# => Run: pytest -q -- Output: 2 passed

2 passed

"""Example 63: Anti-Pattern -- Anemic Domain Model.
 
co-34 (anti-pattern recognition): an anemic model is a data class with all behavior
pulled into a separate service, so the "object" in object-oriented is data-only --
co-06 (grasp-information-expert) names the fix: move behavior onto the entity that
already holds the data the behavior needs.
"""
 
from __future__ import annotations
 
from dataclasses import dataclass
 
# ============================================================
# BEFORE: an anemic Account (data only) plus a service that does everything
# ============================================================
 
 
@dataclass  # => auto-generates __init__ from the balance field below
class AnemicAccount:  # => pure data -- no behavior at all, just fields
    balance: float  # => the only thing this "object" holds
 
 
# => contrast: nothing here stops other code from mutating account.balance directly, bypassing withdraw()
class AccountService:  # => ALL the behavior lives here instead, disconnected from the data it operates on
    def withdraw(self, account: AnemicAccount, amount: float) -> None:  # => reaches INTO the account to mutate it
        if amount > account.balance:  # => the invariant ("cannot overdraw") lives in the service, not the entity
            raise ValueError("insufficient funds")  # => nothing stops OTHER code from bypassing this check
        account.balance -= amount  # => direct field mutation, invariant enforced only if you remembered to call this
        # => this mutation is only safe if every caller remembers to call withdraw() instead of touching balance
 
 
# ============================================================
# AFTER: the entity owns its own behavior -- information-expert applied
# ============================================================
 
 
# => RichAccount fixes the anemia: balance and the rule that guards it now live in the same place
class RichAccount:  # => the entity now owns the data AND the behavior that guards it
    def __init__(self, balance: float) -> None:  # => takes the initial balance directly, same shape as AnemicAccount
        self._balance = balance  # => the same data, but now private -- no direct external mutation
 
    @property  # => exposes balance for reading without exposing a way to write it directly
    def balance(self) -> float:  # => read-only view of the balance
        return self._balance  # => the only way to read balance from outside the class
 
    def withdraw(self, amount: float) -> None:  # => information-expert: RichAccount holds balance, so IT withdraws
        if amount > self._balance:  # => the SAME invariant, but now impossible to bypass via direct field access
            raise ValueError("insufficient funds")  # => identical error to the anemic version
        self._balance -= amount  # => the only way balance can change is through this guarded method
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    anemic = AnemicAccount(balance=100.0)  # => the old version
    service = AccountService()  # => the disconnected service the old design requires
    service.withdraw(anemic, 30.0)  # => behavior lives OUTSIDE the object it operates on
    print(anemic.balance)  # => still correct here, but nothing prevents anemic.balance = 999 elsewhere
    # => Output: 70.0
 
    # => same starting balance as the anemic example above, for a fair side-by-side comparison
    rich = RichAccount(balance=100.0)  # => the refactored version
    rich.withdraw(30.0)  # => behavior lives ON the object, next to the data it guards
    print(rich.balance)  # => identical result to the anemic version
    # => Output: 70.0

70.0
70.0

"""Example 63: pytest verification that behavior moved onto the entity."""
 
import pytest
 
from example import AccountService, AnemicAccount, RichAccount
 
 
def test_anemic_version_lets_the_invariant_be_bypassed_via_direct_field_access() -> None:
    account = AnemicAccount(balance=100.0)
    account.balance = -50.0  # => NOTHING stops this: the invariant only lives in AccountService.withdraw
    assert account.balance == -50.0  # => the anemic model allows an invalid balance to exist
 
 
def test_rich_account_enforces_the_same_invariant_and_cannot_be_bypassed() -> None:
    account = RichAccount(balance=100.0)
    with pytest.raises(AttributeError):  # => balance has no setter -- direct mutation is impossible
        account.balance = -50.0  # type: ignore[misc]  # => deliberately demonstrates the blocked mutation path
    account.withdraw(30.0)  # => the only sanctioned way to change balance
    assert account.balance == 70.0
 
 
def test_both_versions_agree_on_a_legal_withdrawal() -> None:
    anemic = AnemicAccount(balance=100.0)
    AccountService().withdraw(anemic, 40.0)
    rich = RichAccount(balance=100.0)
    rich.withdraw(40.0)
    assert anemic.balance == rich.balance == 60.0  # => same math, different ownership of the behavior
 
 
# => Run: pytest -q -- Output: 3 passed

3 passed

"""Example 64: Anti-Pattern -- Yo-Yo Inheritance.
 
co-34 (anti-pattern recognition): yo-yo inheritance is diagnosed when understanding
one method call requires jumping up and down a deep hierarchy, following super()
calls back and forth across many classes. The fix is flattening: collapse the chain
to the minimum depth that still expresses a genuine is-a relationship.
"""
 
from __future__ import annotations
 
# ============================================================
# BEFORE: understanding discount() requires jumping through 4 classes
# ============================================================
 
 
class BasePricer:  # => level 1
    def discount(self, price: float) -> float:  # => defines the base case
        return price  # => no discount at this level
 
 
class RegionalPricer(BasePricer):  # => level 2 -- must jump UP to BasePricer to see the base case
    def discount(self, price: float) -> float:  # => override signature, unchanged from BasePricer's
        base = super().discount(price)  # => jump UP to level 1
        return base * 0.95  # => 5% regional discount, only visible by reading THIS override
 
 
class SeasonalPricer(RegionalPricer):  # => level 3 -- must jump UP through level 2 AND level 1
    def discount(self, price: float) -> float:  # => override signature, unchanged from the level below
        base = super().discount(price)  # => jump UP to level 2, which itself jumps UP to level 1
        return base * 0.90  # => additional 10% seasonal discount
 
 
class LoyaltyPricer(SeasonalPricer):  # => level 4 -- understanding this needs all THREE super() calls above it
    def discount(self, price: float) -> float:  # => override signature, unchanged from all three levels below
        base = super().discount(price)  # => jump UP to level 3, which jumps to level 2, which jumps to level 1
        return base * 0.98  # => additional 2% loyalty discount -- the "yo-yo": up, up, up just to see the total
 
 
# => this function literalizes "yo-yo" as a number: how many classes must be opened to read one method fully
def count_hops_to_understand(cls: type, method_name: str) -> int:  # => a mechanical yo-yo detector
    hops = 0  # => counts how many classes in the MRO define this method
    for klass in cls.__mro__:  # => walk the method resolution order top to bottom
        if method_name in klass.__dict__:  # => this class DEFINES (not just inherits) the method
            hops += 1  # => reading the full behavior requires visiting this class too
    return hops  # => 4+ hops for one method is the yo-yo smell
 
 
# ============================================================
# AFTER: flattened to depth 1 -- discount is one function, fully readable in place
# ============================================================
 
 
def flattened_discount(price: float) -> float:  # => the SAME final formula, with zero jumps required to read it
    return price * 0.95 * 0.90 * 0.98  # => regional * seasonal * loyalty, all visible on one line
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    print(count_hops_to_understand(LoyaltyPricer, "discount"))  # => 4 classes must be read to understand ONE method
    # => Output: 4
    loyalty = LoyaltyPricer()  # => instantiating the deepest, most yo-yo-prone class
    print(round(loyalty.discount(100.0), 4))  # => the yo-yo version's result
    # => Output: 83.79
    print(round(flattened_discount(100.0), 4))  # => the flattened version's result -- identical, zero jumps
    # => Output: 83.79

4
83.79
83.79

"""Example 64: pytest verification that yo-yo inheritance is diagnosed and flattened."""
 
from example import LoyaltyPricer, count_hops_to_understand, flattened_discount
 
 
def test_yo_yo_hierarchy_requires_four_hops_to_understand_one_method() -> None:
    assert count_hops_to_understand(LoyaltyPricer, "discount") == 4  # => the smell, named as a number
 
 
def test_flattened_version_produces_the_identical_result() -> None:
    loyalty = LoyaltyPricer()
    original = round(loyalty.discount(100.0), 6)  # => the yo-yo version's result
    flattened = round(flattened_discount(100.0), 6)  # => the flattened version's result
    assert original == flattened  # => flattening changed nothing observable
 
 
def test_flattened_version_is_a_single_plain_function_with_no_hierarchy_at_all() -> None:
    assert flattened_discount.__module__ == "example"  # => defined once, at module level -- no MRO to walk at all
    assert not hasattr(flattened_discount, "__mro__")  # => a plain function has no inheritance chain to jump through
 
 
# => Run: pytest -q -- Output: 3 passed

3 passed

"""Example 65: Anti-Pattern -- Singleton Abuse.
 
co-34 (anti-pattern recognition) + co-19 (singleton and its costs): a singleton used
as a shared mutable counter is hidden global coupling -- any test that runs before
another can silently leak state into it, because nothing in either test's signature
reveals the dependency exists.
"""
 
from __future__ import annotations  # => defers type-hint evaluation, letting RequestCounter reference itself
 
 
# => the singleton pattern itself: __new__ ensures only ONE instance is ever created, globally
class RequestCounter:  # => a classic singleton: one shared instance, reachable globally
    # => the Optional sentinel pattern: None means "not constructed yet", the class itself means "constructed"
    _instance: "RequestCounter | None" = None  # => the one shared instance, or None before first use
 
    def __new__(cls) -> "RequestCounter":  # => __new__ is overridden so every RequestCounter() returns the SAME object
        if cls._instance is None:  # => first call: create the one instance
            cls._instance = super().__new__(cls)  # => allocate it exactly once
            # => count is set dynamically here, never declared in the class body -- static checkers cannot see it
            cls._instance.count = 0  # type: ignore[attr-defined]  # => initialize state on the shared instance
        return cls._instance  # => every subsequent call returns this SAME object, not a new one
 
    # => every call to increment(), from ANYWHERE in the program, mutates this one shared counter
    def increment(self) -> int:  # => mutates the ONE shared instance's state
        # => the `# type: ignore[attr-defined]` markers exist because count is never declared as a class field
        self.count += 1  # type: ignore[attr-defined]  # => hidden global mutation -- no caller passed this in
        return self.count  # type: ignore[attr-defined]
 
 
# => neither handle_request_a nor handle_request_b takes a counter parameter -- the coupling is invisible
def handle_request_a() -> int:  # => neither function's SIGNATURE reveals it depends on RequestCounter
    counter = RequestCounter()  # => silently reaches for the global singleton
    return counter.increment()  # => mutates shared state as a side effect
 
 
# => this function looks completely independent of handle_request_a, yet secretly shares its state
def handle_request_b() -> int:  # => a completely unrelated-looking function...
    counter = RequestCounter()  # => ...that happens to share state with handle_request_a via the singleton
    return counter.increment()  # => whichever function runs first determines the other's starting count
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    # NOTE: resetting _instance here is itself evidence of the cost -- production code has no clean reset hook
    # => contrast with dependency injection: a passed-in counter would need no such manual reset ritual
    RequestCounter._instance = None  # => manual reset required before every isolated demonstration
    # => without the manual reset on the line above, this count would carry over from any earlier run
    print(handle_request_a())  # => first call anywhere: count becomes 1
    # => Output: 1
    print(handle_request_b())  # => a DIFFERENT function, yet it sees count=2 -- hidden coupling via the singleton
    # => Output: 2
    # => the defining trait of a singleton: two separate construction calls, one identity
    print(RequestCounter() is RequestCounter())  # => confirms both calls returned the exact same object
    # => Output: True

1
2
True

"""Example 65: pytest verification that singleton state leaks silently between tests."""
 
from example import RequestCounter, handle_request_a, handle_request_b
 
 
def test_state_leaks_across_two_unrelated_looking_functions() -> None:
    RequestCounter._instance = None  # => manual reset required BECAUSE the singleton has no other reset mechanism
    a_result = handle_request_a()  # => no parameter reveals this depends on shared state
    b_result = handle_request_b()  # => a DIFFERENT function, yet its result depends on what ran before it
    assert a_result == 1  # => first increment anywhere
    assert b_result == 2  # => the "hidden coupling" pain: b's result depends on a having run first
 
 
def test_forgetting_the_manual_reset_leaks_state_into_the_next_test() -> None:
    # => this test intentionally does NOT reset _instance first, demonstrating the isolation cost directly
    leaked_start = RequestCounter().count  # type: ignore[attr-defined]  # => count is whatever the PREVIOUS test left
    assert leaked_start > 0  # => proof: state from test_state_leaks_across_two_unrelated_looking_functions survived
 
 
# => Run: pytest -q -- Output: 2 passed

2 passed

"""Example 66: Anti-Pattern -- Premature Abstraction.
 
co-34 (anti-pattern recognition) + co-02 (OCP, its counterpart): a Strategy family
built for a SINGLE implementation ("just in case" a second one shows up) is
speculative generality -- extra indirection paid for before any real variation
exists. The fix is removing the abstraction and calling the one implementation
directly; OCP earns its indirection only once a second variant is real (Example 3).
"""
 
from __future__ import annotations  # => defers type-hint evaluation, not required here but kept for consistency
 
from abc import ABC, abstractmethod  # => the tools used to build the abstraction this example argues against
 
# ============================================================
# BEFORE: a strategy interface for exactly ONE implementation
# ============================================================
 
 
class TaxStrategy(ABC):  # => an interface built for "future" tax strategies that do not exist yet
    @abstractmethod  # => forces every future strategy to implement calculate() -- but only one ever will
    def calculate(self, amount: float) -> float:  # => the one abstract method every strategy would implement
        # => this body is dead code: @abstractmethod already forbids instantiating TaxStrategy directly
        raise NotImplementedError  # => abstract method body, never actually executed
 
 
# => this is the ONLY class that will ever subclass TaxStrategy in this codebase's actual history
class FlatRateTaxStrategy(TaxStrategy):  # => the ONLY implementation that has ever existed
    def calculate(self, amount: float) -> float:  # => the ONLY override that has ever existed or is planned
        return amount * 0.08  # => flat 8% tax -- there is no second rule to switch between
 
 
# => the strategy parameter exists to support variation that has never materialized
def total_with_tax_premature(amount: float, strategy: TaxStrategy) -> float:  # => a parameter for a choice nobody makes
    return amount + strategy.calculate(amount)  # => every caller passes the SAME FlatRateTaxStrategy() instance
 
 
# ============================================================
# AFTER: the abstraction is removed -- one function, one formula
# ============================================================
 
 
# => AFTER: same behavior, but the interface, the concrete class, and the parameter are all simply gone
def total_with_tax_simple(amount: float) -> float:  # => no interface, no strategy parameter, no indirection
    return amount + amount * 0.08  # => the SAME formula, with zero ceremony around it
 
 
# => a crude proxy metric, but it makes the added ceremony countable rather than just a feeling
def count_lines_of_indirection(strategy_based: bool) -> int:  # => a simple proxy for "how much ceremony"
    if strategy_based:  # => the premature-abstraction version needs: ABC + abstractmethod + concrete class + param
        return 4  # => TaxStrategy class, calculate() signature, FlatRateTaxStrategy class, strategy parameter
    return 0  # => the simplified version needs none of that
    # => the count itself never varies at runtime -- it exists only to make "more ceremony" a checkable fact
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    # => both branches below compute the exact same tax on the exact same amount -- only the ceremony differs
    premature = total_with_tax_premature(100.0, FlatRateTaxStrategy())  # => must construct a strategy just to call this
    print(premature)  # => the abstraction adds ceremony without adding any actual flexibility used anywhere
    # => Output: 108.0
    simple = total_with_tax_simple(100.0)  # => identical result, zero ceremony
    print(simple)  # => same number, arrived at directly
    # => Output: 108.0
    print(count_lines_of_indirection(strategy_based=True) > count_lines_of_indirection(strategy_based=False))  # => confirms the abstraction costs strictly more ceremony
    # => Output: True

108.0
108.0
True

"""Example 66: pytest verification that removing a premature abstraction simplifies the code."""
 
from example import (
    FlatRateTaxStrategy,
    count_lines_of_indirection,
    total_with_tax_premature,
    total_with_tax_simple,
)
 
 
def test_both_versions_produce_the_identical_result() -> None:
    premature = total_with_tax_premature(100.0, FlatRateTaxStrategy())  # => needs a strategy instance
    simple = total_with_tax_simple(100.0)  # => needs nothing extra
    assert premature == simple == 108.0  # => removing the abstraction changed nothing observable
 
 
def test_the_simplified_version_has_strictly_less_indirection() -> None:
    assert count_lines_of_indirection(strategy_based=True) > count_lines_of_indirection(strategy_based=False)  # => the win
 
 
# => Run: pytest -q -- Output: 2 passed

2 passed

"""Example 67: GoF Gallery -- Creational Patterns.
 
co-32 (gof-pattern-gallery): a single-file tour of the four essential creational
patterns -- factory method (co-16), abstract factory (co-17), builder (co-18), and
singleton (co-19) -- each constructs correctly, verified independently.
"""
 
from __future__ import annotations  # => defers type-hint evaluation for the forward references used below
 
from dataclasses import dataclass, field  # => field() supplies mutable defaults safely, used by HttpRequest
 
# ============================================================
# 1. Factory Method -- defer instantiation to a creation method
# ============================================================
 
 
class Shape:  # => the shared abstract product every factory-method output implements
    def area(self) -> float:  # => no body -- every concrete Shape must override this
        raise NotImplementedError  # => a plain-class stand-in for @abstractmethod, still enforces the contract
 
 
class Circle(Shape):  # => one concrete product
    def __init__(self, radius: float) -> None:  # => the constructor
        self.radius = radius  # => stores radius on this instance
 
    def area(self) -> float:  # => satisfies Shape's contract
        return 3.14159 * self.radius**2  # => pi * r^2
 
 
def shape_factory(kind: str, size: float) -> Shape:  # => the FACTORY METHOD -- caller never names Circle directly
    if kind == "circle":  # => the ONLY place that knows which concrete class to build
        return Circle(size)  # => constructs the concrete product internally, hidden from the caller
    raise ValueError(f"unknown shape kind: {kind}")  # => an honest failure for any kind this factory cannot build
 
 
# ============================================================
# 2. Abstract Factory -- a family of factory methods producing a matched set
# ============================================================
 
 
@dataclass  # => generates __init__ from the field below
class Button:  # => one member of the "widget family"
    theme: str  # => the family tag, part of the generated __init__
 
 
@dataclass  # => generates __init__ from the field below
class Checkbox:  # => the other member of the "widget family" -- must match Button's theme
    theme: str  # => the family tag, part of the generated __init__
 
 
class WidgetFactory:  # => the abstract factory interface
    def create_button(self) -> Button:  # => no body -- every concrete factory must override this
        raise NotImplementedError  # => a plain-class stand-in for @abstractmethod
 
    def create_checkbox(self) -> Checkbox:  # => no body -- every concrete factory must override this
        raise NotImplementedError  # => a plain-class stand-in for @abstractmethod
 
 
class DarkWidgetFactory(WidgetFactory):  # => one concrete factory -- produces a MATCHED dark-themed family
    def create_button(self) -> Button:  # => overrides the abstract factory method
        return Button(theme="dark")  # => always builds the dark-family Button, never mixed with other themes
 
    def create_checkbox(self) -> Checkbox:  # => overrides the abstract factory method
        return Checkbox(theme="dark")  # => always builds the dark-family Checkbox, matching create_button()
 
 
# ============================================================
# 3. Builder -- assemble a complex object step by step
# ============================================================
 
 
@dataclass  # => generates __init__ from the fields below
class HttpRequest:  # => the complex object being assembled
    url: str  # => the one required field
    headers: dict[str, str] = field(default_factory=dict)  # => field() avoids a shared mutable default dict
    body: str | None = None  # => optional, defaults to no body
 
 
class RequestBuilder:  # => the fluent builder -- no telescoping constructor needed
    def __init__(self, url: str) -> None:  # => the constructor takes only the one required part
        self._url = url  # => the one required part
        self._headers: dict[str, str] = {}  # => optional parts, added incrementally
        self._body: str | None = None  # => optional, starts unset until with_body() is called
 
    def with_header(self, key: str, value: str) -> "RequestBuilder":  # => returns self -- enables chaining
        self._headers[key] = value  # => accumulates one header per call, in-place
        return self  # => returning self is what makes .with_header(...).with_body(...) chainable
 
    def with_body(self, body: str) -> "RequestBuilder":  # => also returns self
        self._body = body  # => sets the optional body, overwriting any previous value
        return self  # => same chaining trick as with_header()
 
    def build(self) -> HttpRequest:  # => assembles the final immutable-in-spirit object
        return HttpRequest(url=self._url, headers=self._headers, body=self._body)  # => one call, fully assembled
 
 
# ============================================================
# 4. Singleton -- exactly one shared instance
# ============================================================
 
 
class AppConfig:  # => a minimal singleton, deliberately small for this gallery tour (see Example 30 for the cost)
    _instance: "AppConfig | None" = None  # => the one shared instance, or None before first use
 
    def __new__(cls) -> "AppConfig":  # => overridden so every AppConfig() returns the SAME object
        if cls._instance is None:  # => first call: create the one instance
            cls._instance = super().__new__(cls)  # => allocate it exactly once
        return cls._instance  # => every subsequent call returns the SAME object
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    circle = shape_factory("circle", 2.0)  # => 1. factory method
    print(round(circle.area(), 2))  # => constructs a Circle without the caller importing Circle
    # => Output: 12.57
 
    dark_factory: WidgetFactory = DarkWidgetFactory()  # => 2. abstract factory
    print(dark_factory.create_button().theme, dark_factory.create_checkbox().theme)  # => both match the same theme
    # => Output: dark dark
 
    # => 3. builder -- four chained calls assemble one HttpRequest, no telescoping constructor needed
    request = RequestBuilder("https://api.example.com").with_header("Accept", "json").with_body("{}").build()
    print(request.url, request.headers, request.body)  # => 3. builder, assembled without a telescoping constructor
    # => Output: https://api.example.com {'Accept': 'json'} {}
 
    print(AppConfig() is AppConfig())  # => 4. singleton -- exactly one shared instance
    # => Output: True

12.57
dark dark
https://api.example.com {'Accept': 'json'} {}
True

"""Example 67: pytest verification that each creational pattern constructs correctly."""
 
import pytest
 
from example import AppConfig, Circle, DarkWidgetFactory, RequestBuilder, shape_factory
 
 
def test_factory_method_constructs_the_correct_concrete_type() -> None:
    shape = shape_factory("circle", 2.0)  # => caller never named Circle directly
    assert isinstance(shape, Circle)  # => yet the correct concrete type was constructed
    with pytest.raises(ValueError):
        shape_factory("hexagon", 1.0)  # => an unknown kind is rejected cleanly
 
 
def test_abstract_factory_produces_a_matched_family() -> None:
    factory = DarkWidgetFactory()
    button = factory.create_button()
    checkbox = factory.create_checkbox()
    assert button.theme == checkbox.theme == "dark"  # => both members of the family share one theme
 
 
def test_builder_assembles_a_request_without_a_telescoping_constructor() -> None:
    request = RequestBuilder("https://api.example.com").with_header("Accept", "json").with_body("{}").build()
    assert request.url == "https://api.example.com"  # => the required part
    assert request.headers == {"Accept": "json"}  # => an optional part, included
    assert request.body == "{}"  # => another optional part, included
 
 
def test_singleton_returns_the_same_instance_every_time() -> None:
    assert AppConfig() is AppConfig()  # => two calls, one object
 
 
# => Run: pytest -q -- Output: 4 passed

4 passed

"""Example 68: GoF Gallery -- Structural Patterns.
 
co-32 (gof-pattern-gallery): a single-file tour of the five essential structural
patterns -- adapter (co-20), decorator (co-21), facade (co-22), composite (co-23),
and proxy (co-24) -- each wraps correctly, verified independently.
"""
 
from __future__ import annotations  # => defers type-hint evaluation for the forward references used below
 
from typing import Callable  # => Callable types the logging_decorator's wrapped function argument
 
# ============================================================
# 1. Adapter -- convert one interface into another a client expects
# ============================================================
 
 
class FahrenheitSensor:  # => the class being adapted -- exposes Fahrenheit only
    def read_fahrenheit(self) -> float:  # => the ONLY interface this class exposes
        return 98.6  # => a fixed sample reading, in Fahrenheit
 
 
class CelsiusAdapter:  # => converts FahrenheitSensor's interface into the one the client expects
    def __init__(self, sensor: FahrenheitSensor) -> None:  # => the constructor
        self._sensor = sensor  # => wraps the adapted object, held as a collaborator
 
    def read_celsius(self) -> float:  # => the interface the client actually wants
        return (self._sensor.read_fahrenheit() - 32) * 5 / 9  # => the conversion, hidden from the client
 
 
# ============================================================
# 2. Decorator -- wrap an object to add behavior without subclass explosion
# ============================================================
 
 
def logging_decorator(func: Callable[[str], str]) -> Callable[[str], str]:  # => wraps ANY str->str function
    def wrapped(message: str) -> str:  # => the replacement function returned in place of func
        result = func(message)  # => delegates to the wrapped function
        return f"[logged] {result}"  # => adds behavior around it, without editing func itself
 
    return wrapped  # => the decorator returns a NEW function, never mutates func in place
 
 
@logging_decorator  # => applies the wrapper at definition time -- greet IS wrapped from here on
def greet(name: str) -> str:  # => the wrapped function never knows it is being decorated
    return f"hello, {name}"  # => the original, undecorated behavior
 
 
# ============================================================
# 3. Facade -- one simplified entry point over a complex subsystem
# ============================================================
 
 
class Inventory:  # => one subsystem member
    def reserve(self, item: str) -> bool:  # => the reservation step, hidden inside the facade
        return True  # => stubbed: assume reservation always succeeds
 
 
class Payment:  # => another subsystem member
    def charge(self, amount: float) -> bool:  # => the charge step, hidden inside the facade
        return True  # => stubbed: assume payment always succeeds
 
 
class CheckoutFacade:  # => hides the sequencing of Inventory + Payment behind ONE call
    def __init__(self) -> None:  # => the constructor
        self._inventory = Inventory()  # => wires subsystem one internally
        self._payment = Payment()  # => wires subsystem two internally
 
    def checkout(self, item: str, amount: float) -> bool:  # => the caller makes ONE call
        return self._inventory.reserve(item) and self._payment.charge(amount)  # => sequencing hidden inside
 
 
# ============================================================
# 4. Composite -- treat individual objects and compositions uniformly
# ============================================================
 
 
class FileNode:  # => a leaf
    def __init__(self, size: int) -> None:  # => the constructor
        self.size = size  # => a leaf's own, fixed size
 
    def total_size(self) -> int:  # => the SHARED interface with DirectoryNode
        return self.size  # => a leaf's total IS its own size -- no recursion needed
 
 
class DirectoryNode:  # => a composite -- contains other FileNode or DirectoryNode children
    def __init__(self, children: list["FileNode | DirectoryNode"]) -> None:  # => the constructor
        self.children = children  # => a mix of leaves and/or nested composites, held uniformly
 
    def total_size(self) -> int:  # => the SAME interface as FileNode -- callers don't special-case leaf vs. group
        return sum(child.total_size() for child in self.children)  # => recurses uniformly
 
 
# ============================================================
# 5. Proxy -- a stand-in controlling access to a real subject
# ============================================================
 
 
class ExpensiveImage:  # => the "real subject", expensive to construct
    def __init__(self, path: str) -> None:  # => simulates a costly construction step
        self.path = path  # => stores the path on this instance
        self.loaded = True  # => simulates the expensive load happening at construction time
 
 
class LazyImageProxy:  # => the proxy -- defers construction until first access
    def __init__(self, path: str) -> None:  # => cheap: no ExpensiveImage built yet
        self._path = path  # => remembered so the real subject can be built later, on demand
        self._real: ExpensiveImage | None = None  # => not loaded yet
 
    def display(self) -> str:  # => the client-facing interface, identical shape to using ExpensiveImage directly
        if self._real is None:  # => only construct the real subject on FIRST access
            self._real = ExpensiveImage(self._path)  # => the expensive construction, deferred until now
        return f"displaying {self._real.path}"  # => every later call reuses the already-built real subject
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    adapter = CelsiusAdapter(FahrenheitSensor())  # => 1. adapter
    print(round(adapter.read_celsius(), 1))  # => the client reads Celsius, never touches Fahrenheit directly
    # => Output: 37.0
 
    print(greet("Ada"))  # => 2. decorator -- logging added without editing greet()
    # => Output: [logged] hello, Ada
 
    facade = CheckoutFacade()  # => 3. facade
    print(facade.checkout("Book", 12.5))  # => one call hides inventory + payment sequencing
    # => Output: True
 
    tree = DirectoryNode([FileNode(10), DirectoryNode([FileNode(5), FileNode(3)])])  # => 4. composite
    print(tree.total_size())  # => recursive total through ONE shared interface
    # => Output: 18
 
    proxy = LazyImageProxy("photo.png")  # => 5. proxy
    print(proxy._real is None)  # => not loaded yet -- proves laziness
    # => Output: True
    print(proxy.display())  # => triggers the load, on first access only
    # => Output: displaying photo.png

37.0
[logged] hello, Ada
True
18
True
displaying photo.png

"""Example 68: pytest verification that each structural pattern wraps correctly."""
 
from example import (
    CelsiusAdapter,
    CheckoutFacade,
    DirectoryNode,
    FahrenheitSensor,
    FileNode,
    LazyImageProxy,
    greet,
)
 
 
def test_adapter_converts_fahrenheit_to_celsius() -> None:
    adapter = CelsiusAdapter(FahrenheitSensor())
    assert round(adapter.read_celsius(), 1) == 37.0  # => the client reads Celsius only
 
 
def test_decorator_wraps_the_function_without_editing_it() -> None:
    assert greet("Ada") == "[logged] hello, Ada"  # => logging added purely by wrapping
 
 
def test_facade_hides_subsystem_sequencing_behind_one_call() -> None:
    facade = CheckoutFacade()
    assert facade.checkout("Book", 12.5) is True  # => one call, inventory + payment both succeeded
 
 
def test_composite_computes_a_recursive_total_via_one_interface() -> None:
    tree = DirectoryNode([FileNode(10), DirectoryNode([FileNode(5), FileNode(3)])])
    assert tree.total_size() == 18  # => leaf and composite share total_size()
 
 
def test_proxy_defers_loading_until_first_access() -> None:
    proxy = LazyImageProxy("photo.png")
    assert proxy._real is None  # => not loaded yet
    proxy.display()  # => triggers the load
    assert proxy._real is not None  # => loaded exactly once, on first access
 
 
# => Run: pytest -q -- Output: 5 passed

5 passed

"""Example 69: GoF Gallery -- Behavioral Patterns.
 
co-32 (gof-pattern-gallery): a single-file tour of seven essential behavioral
patterns -- strategy (co-25), observer (co-26), command (co-27), template method
(co-28), state (co-29), iterator (co-30), and chain of responsibility (co-31) --
each dispatches correctly, verified independently.
"""
 
from __future__ import annotations  # => defers type-hint evaluation for the forward references used below
 
from abc import ABC, abstractmethod  # => builds the template-method, state, and chain-of-responsibility bases
from typing import Callable, Iterator  # => Callable types strategies/observers, Iterator types the custom collection
 
# ============================================================
# 1. Strategy -- interchangeable algorithms behind one interface
# ============================================================
 
 
def by_length(word: str) -> int:  # => one strategy
    return len(word)  # => a plain function IS a strategy -- no class hierarchy required
 
 
def sort_words(words: list[str], key: Callable[[str], int]) -> list[str]:  # => the dispatcher, takes a strategy
    return sorted(words, key=key)  # => the strategy decides HOW to compare
 
 
# ============================================================
# 2. Observer -- subjects notify subscribers without knowing them concretely
# ============================================================
 
 
class Publisher:  # => the subject
    def __init__(self) -> None:  # => the constructor
        self._subscribers: list[Callable[[str], None]] = []  # => knows only that subscribers are callables
 
    def subscribe(self, handler: Callable[[str], None]) -> None:  # => adding a subscriber needs no publisher edit
        self._subscribers.append(handler)  # => grows the list, nothing else
 
    def publish(self, message: str) -> None:  # => notifies every subscriber, without knowing what they do
        for handler in self._subscribers:  # => visits every registered subscriber, in order
            handler(message)  # => the subject never knows what a handler does with the message
 
 
# ============================================================
# 3. Command -- reify a request as an object with execute/undo
# ============================================================
 
 
class AddTextCommand:  # => a request, turned into an object
    def __init__(self, document: list[str], text: str) -> None:  # => the constructor
        self.document = document  # => the receiver this command acts on
        self.text = text  # => remembers WHAT it appended, needed later to undo
 
    def execute(self) -> None:  # => performs the request
        self.document.append(self.text)  # => the forward action
 
    def undo(self) -> None:  # => reverses the request
        self.document.remove(self.text)  # => the reverse action, mirroring execute() exactly
 
 
# ============================================================
# 4. Template Method -- a base defines the skeleton, subclasses fill steps
# ============================================================
 
 
class ReportBase(ABC):  # => defines the FIXED skeleton
    def run(self) -> str:  # => the shared flow, defined exactly once
        return f"[{self.header()}] {self.body()} [{self.footer()}]"  # => calls the varying steps in a fixed order
 
    @abstractmethod  # => forces every subclass to fill this ONE varying step
    def body(self) -> str:  # => the ONLY step subclasses must fill
        raise NotImplementedError  # => abstract method body, never actually executed
 
    def header(self) -> str:  # => a step with a sensible default, overridable
        return "REPORT"  # => the shared default, used unless a subclass overrides it
 
    def footer(self) -> str:  # => another step with a sensible default
        return "END"  # => the shared default, used unless a subclass overrides it
 
 
class SalesReport(ReportBase):  # => fills only the varying step
    def body(self) -> str:  # => overrides the ONE required step -- header() and footer() stay default
        return "sales: 42 units"  # => the only thing SalesReport ever needs to supply
 
 
# ============================================================
# 5. State -- represent states as objects so transitions are explicit
# ============================================================
 
 
class TrafficLightState(ABC):  # => the shared state interface every concrete light color implements
    @abstractmethod  # => forces every concrete state to define its own legal next transition
    def next(self) -> "TrafficLightState":  # => returns the NEXT legal state
        raise NotImplementedError  # => abstract method body, never actually executed
 
 
class Red(TrafficLightState):  # => one concrete state object, not a boolean flag
    def next(self) -> TrafficLightState:  # => encodes red's ONE legal transition
        return Green()  # => red -> green is the only legal move
 
 
class Green(TrafficLightState):  # => a second concrete state object
    def next(self) -> TrafficLightState:  # => encodes green's ONE legal transition
        return Yellow()  # => green -> yellow
 
 
class Yellow(TrafficLightState):  # => a third concrete state object, completing the cycle
    def next(self) -> TrafficLightState:  # => encodes yellow's ONE legal transition
        return Red()  # => yellow -> red, completing the cycle
 
 
# ============================================================
# 6. Iterator -- expose sequential access without revealing representation
# ============================================================
 
 
class EvenNumbers:  # => a custom collection with hidden internal representation
    def __init__(self, upper_bound: int) -> None:  # => the constructor
        self._upper_bound = upper_bound  # => the only internal state -- callers never see this directly
 
    def __iter__(self) -> Iterator[int]:  # => the iterator protocol -- callers just use a for loop
        current = 0  # => the iteration cursor, private to this generator
        while current < self._upper_bound:  # => stops once the bound is reached
            yield current  # => lazily yields the next even number
            current += 2  # => advances the cursor by 2, staying on even numbers
 
 
# ============================================================
# 7. Chain of Responsibility -- pass a request along handlers until one handles it
# ============================================================
 
 
class Handler(ABC):  # => the shared link interface every tier in the chain implements
    def __init__(self) -> None:  # => the constructor
        self._next: "Handler | None" = None  # => no successor linked yet -- set_next() wires it later
 
    def set_next(self, handler: "Handler") -> "Handler":  # => links this handler to the next one in the chain
        self._next = handler  # => stores the successor link
        return handler  # => returned so calls can chain: a.set_next(b).set_next(c)
 
    def handle(self, level: int) -> str:  # => tries to handle, or passes along
        if self.can_handle(level):  # => asks the CONCRETE subclass whether it can resolve this level
            return self.resolve(level)  # => yes -- resolve it here, the chain stops
        if self._next is not None:  # => not handled here -- pass to the next link
            return self._next.handle(level)  # => delegates, recursively, to the next handler in the chain
        return "UNHANDLED"  # => fell off the end of the chain
 
    @abstractmethod  # => forces every concrete handler to define its own eligibility check
    def can_handle(self, level: int) -> bool:
        raise NotImplementedError  # => abstract method body, never actually executed
 
    @abstractmethod  # => forces every concrete handler to define its own resolution
    def resolve(self, level: int) -> str:
        raise NotImplementedError  # => abstract method body, never actually executed
 
 
class TierOneSupport(Handler):  # => the FIRST link in the chain
    def can_handle(self, level: int) -> bool:  # => tier 1's own eligibility rule
        return level <= 1  # => only handles the lowest severity levels
 
    def resolve(self, level: int) -> str:  # => tier 1's own resolution
        return "resolved by tier 1"
 
 
class TierTwoSupport(Handler):  # => the SECOND link in the chain
    def can_handle(self, level: int) -> bool:  # => tier 2's own eligibility rule
        return level <= 2  # => handles what tier 1 could not
 
    def resolve(self, level: int) -> str:  # => tier 2's own resolution
        return "resolved by tier 2"
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    print(sort_words(["banana", "kiwi", "fig"], key=by_length))  # => 1. strategy
    # => Output: ['fig', 'kiwi', 'banana']
 
    events: list[str] = []  # => the list the observer's handler will append into
    publisher = Publisher()  # => 2. observer
    publisher.subscribe(lambda msg: events.append(msg.upper()))  # => registers a handler, no Publisher edit needed
    publisher.publish("news")  # => notifies every subscriber, this one included
    print(events)
    # => Output: ['NEWS']
 
    doc: list[str] = []  # => the receiver AddTextCommand will mutate
    cmd = AddTextCommand(doc, "hello")  # => 3. command
    cmd.execute()  # => performs the request: appends "hello" to doc
    cmd.undo()  # => reverses the SAME request: removes "hello" from doc
    print(doc)
    # => Output: []
 
    print(SalesReport().run())  # => 4. template method
    # => Output: [REPORT] sales: 42 units [END]
 
    light: TrafficLightState = Red()  # => 5. state
    light = light.next()  # => transitions via a method call, never an if/elif on a string or int flag
    print(type(light).__name__)
    # => Output: Green
 
    print(list(EvenNumbers(10)))  # => 6. iterator
    # => Output: [0, 2, 4, 6, 8]
 
    tier_one: Handler = TierOneSupport()  # => 7. chain of responsibility
    tier_two = TierTwoSupport()  # => the second link, not yet wired into the chain
    tier_one.set_next(tier_two)  # => wires tier_one -> tier_two
    print(tier_one.handle(2))  # => tier 1 can't handle level 2, passes to tier 2
    # => Output: resolved by tier 2

['fig', 'kiwi', 'banana']
['NEWS']
[]
[REPORT] sales: 42 units [END]
Green
[0, 2, 4, 6, 8]
resolved by tier 2

"""Example 69: pytest verification that each behavioral pattern dispatches correctly."""
 
from example import (
    AddTextCommand,
    EvenNumbers,
    Green,
    Publisher,
    Red,
    SalesReport,
    TierOneSupport,
    TierTwoSupport,
    by_length,
    sort_words,
)
 
 
def test_strategy_sorts_by_the_supplied_key() -> None:
    assert sort_words(["banana", "kiwi", "fig"], key=by_length) == ["fig", "kiwi", "banana"]  # => shortest first
 
 
def test_observer_notifies_a_subscriber_without_publisher_edits() -> None:
    events: list[str] = []
    publisher = Publisher()
    publisher.subscribe(lambda msg: events.append(msg.upper()))  # => registered without editing Publisher
    publisher.publish("news")
    assert events == ["NEWS"]
 
 
def test_command_undo_reverses_the_last_command() -> None:
    doc: list[str] = []
    cmd = AddTextCommand(doc, "hello")
    cmd.execute()
    assert doc == ["hello"]
    cmd.undo()
    assert doc == []  # => undo reversed exactly what execute() did
 
 
def test_template_method_shares_the_flow_and_fills_only_body() -> None:
    assert SalesReport().run() == "[REPORT] sales: 42 units [END]"  # => header/footer defaults, body overridden
 
 
def test_state_moves_red_to_green_via_next() -> None:
    light = Red()
    light = light.next()
    assert isinstance(light, Green)  # => the state pattern's transition, verified by type
 
 
def test_iterator_yields_even_numbers_lazily() -> None:
    assert list(EvenNumbers(10)) == [0, 2, 4, 6, 8]  # => a for-loop-compatible custom iterator
 
 
def test_chain_of_responsibility_falls_through_to_the_next_handler() -> None:
    tier_one = TierOneSupport()
    tier_two = TierTwoSupport()
    tier_one.set_next(tier_two)
    assert tier_one.handle(2) == "resolved by tier 2"  # => tier 1 couldn't handle it, tier 2 did
 
 
# => Run: pytest -q -- Output: 7 passed

7 passed

"""Example 70: SOLID -- Full Order Engine.
 
co-01..co-05: all five SOLID principles applied together to one small order engine,
each at its own seam -- SRP splits pricing/persistence/receipts into three classes;
OCP adds a new discount without editing the dispatcher; LSP lets any DiscountStrategy
substitute for another without breaking OrderCalculator; ISP gives OrderService only
the narrow Repository protocol it needs, not a fat one; DIP has OrderService depend
on that protocol, not a concrete database class.
"""
 
from __future__ import annotations  # => defers type-hint evaluation for the forward references used below
 
from dataclasses import dataclass, field  # => field() supplies a safe mutable default for Order.items
from typing import Protocol  # => Protocol declares the DiscountStrategy and Repository abstractions
 
# ============================================================
# SRP -- three classes, three reasons to change
# ============================================================
 
 
@dataclass  # => generates __init__ from the field below
class Order:  # => plain data: an order's line items
    items: dict[str, float] = field(default_factory=dict)  # => item name -> unit price
 
 
class DiscountStrategy(Protocol):  # => OCP: new discounts are added as new classes, not new elif branches
    def apply(self, subtotal: float) -> float: ...  # => every strategy takes a subtotal, returns the discounted total
 
 
class NoDiscount:  # => LSP: substitutable for any other DiscountStrategy -- never breaks a caller's expectations
    def apply(self, subtotal: float) -> float:  # => satisfies DiscountStrategy structurally
        return subtotal  # => no discount applied
 
 
class TenPercentOff:  # => LSP: also substitutable -- honors the SAME contract (never returns MORE than subtotal)
    def apply(self, subtotal: float) -> float:  # => satisfies DiscountStrategy structurally
        return subtotal * 0.90  # => a flat 10% off, still honors the "never exceeds subtotal" contract
 
 
# => OrderCalculator never imports InMemoryRepository or ReceiptFormatter -- it only knows discount strategies
class OrderCalculator:  # => SRP: pricing, and only pricing -- depends on the DiscountStrategy ABSTRACTION (DIP)
    def total(self, order: Order, discount: DiscountStrategy) -> float:  # => OCP: adding a discount needs no edit here
        subtotal = sum(order.items.values())  # => information-expert: Order holds items, this sums them
        return discount.apply(subtotal)  # => delegates the VARYING part to whichever strategy was passed in
 
 
class Repository(Protocol):  # => ISP: OrderService depends on ONLY this narrow protocol, not a fat DB interface
    def save(self, order_id: str, total: float) -> None: ...  # => the ONE method OrderService actually calls
 
 
# => a real implementation might be Postgres or Redis -- OrderService would not need to change at all
class InMemoryRepository:  # => a concrete, swappable implementation of the Repository protocol
    def __init__(self) -> None:  # => the constructor
        self.saved: dict[str, float] = {}  # => order_id -> total, standing in for a real database
 
    def save(self, order_id: str, total: float) -> None:  # => satisfies Repository structurally
        self.saved[order_id] = total  # => the ONE narrow responsibility this class has
 
 
class ReceiptFormatter:  # => SRP: formatting, and only formatting -- its own reason to change, separate from pricing
    def format(self, order_id: str, total: float) -> str:  # => defines the format() method
        return f"Order {order_id}: ${total:.2f}"  # => a pure string-building step, no pricing or persistence here
 
 
# => this is the class DIP is really about: it depends on Repository (abstract), never on InMemoryRepository (concrete)
class OrderService:  # => DIP: depends on the Repository ABSTRACTION, never on InMemoryRepository directly
    def __init__(self, calculator: OrderCalculator, repository: Repository) -> None:  # => both injected, not constructed
        self._calculator = calculator  # => the high-level policy owns these abstractions
        self._repository = repository  # => held as a collaborator, never constructed internally
 
    def checkout(self, order_id: str, order: Order, discount: DiscountStrategy) -> float:  # => the ONE orchestrating method
        total = self._calculator.total(order, discount)  # => delegates pricing
        self._repository.save(order_id, total)  # => delegates persistence, via the ABSTRACT protocol only
        return total  # => hands the computed total back to the caller
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    order = Order(items={"Book": 20.0, "Pen": 5.0})  # => subtotal = 25.0
    calculator = OrderCalculator()  # => constructs the pricing collaborator
    repository = InMemoryRepository()  # => constructs the persistence collaborator
    service = OrderService(calculator, repository)  # => DIP: injected, not hard-coded
 
    total_no_discount = service.checkout("ord-1", order, NoDiscount())  # => LSP: NoDiscount substitutes cleanly
    print(total_no_discount)  # => the undiscounted subtotal
    # => Output: 25.0
 
    total_with_discount = service.checkout("ord-2", order, TenPercentOff())  # => OCP: swapped WITHOUT editing service
    print(total_with_discount)  # => the SAME checkout() method, a different discount object
    # => Output: 22.5
 
    formatter = ReceiptFormatter()  # => SRP: a third, independent responsibility
    print(formatter.format("ord-2", total_with_discount))  # => confirms formatting stays separate from pricing
    # => Output: Order ord-2: $22.50
 
    print(repository.saved)  # => confirms persistence happened via the Repository protocol only
    # => Output: {'ord-1': 25.0, 'ord-2': 22.5}
    # => all five SOLID seams cooperated in this one run: SRP, OCP, LSP, ISP, and DIP each did real work above

25.0
22.5
Order ord-2: $22.50
{'ord-1': 25.0, 'ord-2': 22.5}

"""Example 70: pytest verification of each SOLID seam in the order engine."""
 
from example import (
    InMemoryRepository,
    NoDiscount,
    Order,
    OrderCalculator,
    OrderService,
    ReceiptFormatter,
    TenPercentOff,
)
 
 
def test_srp_each_class_has_exactly_one_reason_to_change() -> None:
    assert not hasattr(OrderCalculator(), "save")  # => pricing never touches persistence
    assert not hasattr(InMemoryRepository(), "total")  # => persistence never touches pricing
    assert not hasattr(ReceiptFormatter(), "apply")  # => formatting never touches discounting
 
 
def test_ocp_a_new_discount_is_added_without_editing_order_calculator() -> None:
    order = Order(items={"Book": 20.0, "Pen": 5.0})
    calculator = OrderCalculator()
    assert calculator.total(order, NoDiscount()) == 25.0
    assert calculator.total(order, TenPercentOff()) == 22.5  # => new strategy, zero edits to OrderCalculator.total
 
 
def test_lsp_any_discount_strategy_substitutes_for_another_without_breaking_the_caller() -> None:
    order = Order(items={"Book": 20.0})
    calculator = OrderCalculator()
    for discount in (NoDiscount(), TenPercentOff()):  # => both honor "never return more than subtotal"
        assert calculator.total(order, discount) <= 20.0  # => the contract every substitutable strategy must satisfy
 
 
def test_isp_order_service_depends_on_only_the_narrow_save_method() -> None:
    repository = InMemoryRepository()
    assert not hasattr(repository, "delete") and not hasattr(repository, "update")  # => no fat interface exists here
    assert hasattr(repository, "save")  # => exactly the one method OrderService's Repository protocol needs
 
 
def test_dip_order_service_never_constructs_a_concrete_repository_itself() -> None:
    order = Order(items={"Book": 20.0})
    repository = InMemoryRepository()  # => constructed OUTSIDE OrderService and injected in
    service = OrderService(OrderCalculator(), repository)
    total = service.checkout("ord-1", order, NoDiscount())
    assert total == 20.0
    assert repository.saved == {"ord-1": 20.0}  # => persistence happened through the injected abstraction
 
 
# => Run: pytest -q -- Output: 5 passed

5 passed

"""Example 71: GRASP -- Full Assignment.
 
co-06..co-14: all nine GRASP patterns assigned across one small library-checkout
domain -- information expert, creator, controller, low coupling, high cohesion,
polymorphism, pure fabrication, indirection, and protected variations -- each
pattern placed at the point in the domain that motivated it.
"""
 
from __future__ import annotations  # => defers type-hint evaluation for the forward references used below
 
from dataclasses import dataclass  # => Loan uses only plain fields, so only dataclass itself is needed here
from datetime import date, timedelta  # => date drives due_date/overdue math, timedelta computes the loan period
from typing import Callable, Protocol  # => Protocol declares FeePolicy and OverdueNotifier, both stable seams
 
# ============================================================
# 9. Protected Variations -- an unstable fee RULE wrapped behind a stable interface
# ============================================================
 
 
class FeePolicy(Protocol):  # => the stable interface -- a fee-rule change never touches Loan
    def daily_rate(self) -> float: ...  # => the ONE method every fee rule must provide
 
 
class StandardFeePolicy:  # => one concrete, swappable rule
    def daily_rate(self) -> float:  # => satisfies FeePolicy structurally
        return 0.25  # => the standard-member daily rate
 
 
# ============================================================
# 6. Polymorphism -- dispatch on fee policy type, no if/elif type-switch anywhere
# ============================================================
 
 
class PremiumFeePolicy:  # => a SECOND concrete rule -- Loan never branches on which one it got
    def daily_rate(self) -> float:  # => satisfies FeePolicy structurally, same shape as StandardFeePolicy
        return 0.10  # => premium members pay a lower daily rate
 
 
# ============================================================
# 5. High Cohesion + 1. Information Expert -- Loan's methods all use ITS OWN fields
# ============================================================
 
 
@dataclass  # => generates __init__ from the fields below
class Loan:  # => holds due_date, so Loan is the natural INFORMATION EXPERT for lateness/fee math
    book_title: str  # => plain field, part of the generated __init__
    borrower: str  # => plain field, part of the generated __init__
    due_date: date  # => plain field, part of the generated __init__
    fee_policy: FeePolicy  # => co-14: depends on the STABLE interface, not a concrete policy class
 
    def days_overdue(self, today: date) -> int:  # => every method here reads ONLY this instance's own fields
        return max(0, (today - self.due_date).days)  # => high cohesion: no unrelated state touched
 
    def fee(self, today: date) -> float:  # => information-expert: Loan owns due_date, so Loan computes the fee
        return self.days_overdue(today) * self.fee_policy.daily_rate()  # => co-6: dispatches polymorphically
 
 
# ============================================================
# 8. Pure Fabrication -- LoanRepository is not a domain concept, invented for persistence
# ============================================================
 
 
class LoanRepository:  # => co-12: a non-domain class that exists purely to keep Library IO-free
    def __init__(self) -> None:  # => the constructor
        self._loans: list[Loan] = []  # => stands in for a real database table
 
    def add(self, loan: Loan) -> None:  # => the ONE write path
        self._loans.append(loan)  # => appended, never mutated after this
 
    def all(self) -> list[Loan]:  # => the ONE read path
        return list(self._loans)  # => returns a COPY, so callers cannot mutate internal state
 
 
# ============================================================
# 2. Creator -- Library aggregates Loans, so Library is the natural creator of one
# ============================================================
 
 
class OverdueNotifier(Protocol):  # => co-13: the mediator's narrow interface
    def __call__(self, loan: Loan, /) -> None: ...  # => positional-only so a bare Callable[[Loan], None] matches structurally
 
 
class Library:  # => co-9: LOW COUPLING -- Library never imports a concrete notification class
    def __init__(self, repository: LoanRepository, on_overdue: OverdueNotifier | None = None) -> None:  # => both injected
        self._repository = repository  # => co-12: depends on the pure fabrication, not raw persistence code
        self._on_overdue: list[OverdueNotifier] = []  # => co-13: INDIRECTION -- a list of callbacks, not direct refs
        if on_overdue is not None:  # => the optional notifier is registered only if the caller supplied one
            self._on_overdue.append(on_overdue)  # => co-9: coupling is through a callable, not a concrete class
 
    def checkout(self, book_title: str, borrower: str, fee_policy: FeePolicy) -> Loan:  # => co-7: CREATOR
        due_date = date.today() + timedelta(days=14)  # => Library aggregates Loans, so it creates them (co-7)
        loan = Loan(book_title, borrower, due_date, fee_policy)  # => the natural creation point
        self._repository.add(loan)  # => delegated to the pure fabrication
        return loan  # => hands the newly created Loan back to the caller
 
    def check_for_overdue(self, today: date) -> list[Loan]:  # => scans every stored loan for lateness
        overdue = [loan for loan in self._repository.all() if loan.days_overdue(today) > 0]  # => filters via Loan itself
        for loan in overdue:  # => visits each overdue loan
            for notify in self._on_overdue:  # => co-13: Library talks only to the MEDIATOR list, never to a concrete notifier
                notify(loan)  # => co-9: no import of any concrete notification class anywhere in Library
        return overdue  # => hands the overdue subset back to the caller
 
 
# ============================================================
# 4. Controller -- routes the "checkout" event; the UI never touches Library directly
# ============================================================
 
 
class LibraryController:  # => co-8: a dedicated coordinating object between UI events and the domain
    def __init__(self, library: Library) -> None:  # => the constructor
        self._library = library  # => the ONE domain collaborator the controller coordinates with
 
    def handle_checkout_request(self, book_title: str, borrower: str, is_premium: bool) -> Loan:  # => the ENTRY POINT
        policy: FeePolicy = PremiumFeePolicy() if is_premium else StandardFeePolicy()  # => co-6: chosen, not switched on later
        return self._library.checkout(book_title, borrower, policy)  # => the UI calls THIS, never Library directly
 
 
# ============================================================
# Wiring: an event log stands in for a real NotificationService, decoupled via co-13
# ============================================================
 
 
def make_logging_notifier(log: list[str]) -> Callable[[Loan], None]:  # => co-9: Library only knows this is callable
    def notify(loan: Loan) -> None:  # => the actual callback, closing over `log`
        log.append(f"{loan.borrower} is overdue on {loan.book_title}")  # => the ONE side effect this notifier has
 
    return notify  # => a plain function IS a valid OverdueNotifier -- no class required
 
 
if __name__ == "__main__":  # => demonstration entry point, executed only when this file is run directly
    notifications: list[str] = []  # => the log the notifier closure above appends into
    repository = LoanRepository()  # => 8. pure fabrication
    library = Library(repository, on_overdue=make_logging_notifier(notifications))  # => 9. low coupling + 13 indirection
    controller = LibraryController(library)  # => 4. controller
 
    controller.handle_checkout_request("Clean Code", "Ada", is_premium=False)  # => 2. creator, via Library.checkout
    controller.handle_checkout_request("Refactoring", "Grace", is_premium=True)  # => 6. polymorphism: different policy
 
    past_due = date.today() + timedelta(days=20)  # => simulate 6 days overdue
    overdue_loans = library.check_for_overdue(past_due)  # => triggers both the query and the mediated notification
    print(len(overdue_loans))  # => both loans are overdue by this date
    # => Output: 2
    print(round(overdue_loans[0].fee(past_due), 2))  # => 1. information expert: Loan computes its own fee
    # => Output: 1.5
    print(round(overdue_loans[1].fee(past_due), 2))  # => 6. polymorphism: premium's LOWER daily rate applied
    # => Output: 0.6
    print(len(notifications))  # => 13. indirection worked: notifier fired without Library knowing its concrete type
    # => Output: 2