Pythonic Design: Protocols, ABCs & SOLID¶

from typing import Protocol, runtime_checkable

# Define the interface structurally — no inheritance needed from users
@runtime_checkable   # enables isinstance() checks at runtime
class Serializer(Protocol):
    def dumps(self, data: dict) -> str: ...
    def loads(self, text: str) -> dict: ...

class JSONSerializer:              # does NOT inherit from Serializer
    def dumps(self, data: dict) -> str:
        import json; return json.dumps(data)
    def loads(self, text: str) -> dict:
        import json; return json.loads(text)

class TOMLSerializer:              # also satisfies the protocol structurally
    def dumps(self, data: dict) -> str:
        import tomllib
        ...
    def loads(self, text: str) -> dict:
        ...

# Any class with dumps() and loads() satisfies Serializer
def save_config(config: dict, serializer: Serializer) -> str:
    return serializer.dumps(config)

save_config({"debug": True}, JSONSerializer())    # works
save_config({"debug": True}, TOMLSerializer())    # works

# Runtime check (because of @runtime_checkable)
isinstance(JSONSerializer(), Serializer)    # True
isinstance("not a serializer", Serializer)  # False

# ── Iterable Protocol — the built-in example ─────────────────────────────────
class Countdown:
    """Any class implementing __iter__ and __next__ is Iterable."""
    def __init__(self, n: int):
        self.n = n

    def __iter__(self):
        return self

    def __next__(self):
        if self.n <= 0:
            raise StopIteration
        self.n -= 1
        return self.n + 1

for n in Countdown(5):
    print(n, end=" ")   # 5 4 3 2 1
# No inheritance from any Iterable class — pure structural protocol

from abc import ABC, abstractmethod
from typing import Iterator

class Storage(ABC):
    """Abstract interface for a key-value store.
    Any concrete implementation must provide get, put, delete, and keys.
    """
    @abstractmethod
    def get(self, key: str) -> bytes:
        """Retrieve value by key. Raises KeyError if not found."""
        ...

    @abstractmethod
    def put(self, key: str, value: bytes) -> None:
        """Store value under key, overwriting if exists."""
        ...

    @abstractmethod
    def delete(self, key: str) -> None:
        """Remove key. Raises KeyError if not found."""
        ...

    @abstractmethod
    def keys(self) -> Iterator[str]:
        """Iterate all stored keys."""
        ...

    # Non-abstract method: shared behavior implemented on top of the abstracts
    def exists(self, key: str) -> bool:
        try:
            self.get(key)
            return True
        except KeyError:
            return False

class MemoryStore(Storage):
    """In-memory store — fast, non-persistent. Good for tests."""
    def __init__(self):
        self._data: dict[str, bytes] = {}

    def get(self, key):
        if key not in self._data:
            raise KeyError(key)
        return self._data[key]

    def put(self, key, value):
        self._data[key] = value

    def delete(self, key):
        if key not in self._data:
            raise KeyError(key)
        del self._data[key]

    def keys(self):
        return iter(self._data.keys())

# class IncompleteStore(Storage):
#     def get(self, key): ...
#     # forgot put, delete, keys
# IncompleteStore()  # TypeError: Can't instantiate abstract class — caught at instantiation!

# Usage — code that works with ANY Storage implementation
def copy_store(source: Storage, dest: Storage) -> int:
    count = 0
    for key in source.keys():
        dest.put(key, source.get(key))
        count += 1
    return count

from abc import ABC, abstractmethod
from typing import Protocol

# ── S: Single Responsibility ──────────────────────────────────────────────────
# BEFORE: one class does too much
class OrderProcessorBad:
    def process(self, order): ...
    def send_email(self, order): ...      # email is not "processing"
    def save_to_db(self, order): ...      # DB is not "processing"
    def generate_pdf(self, order): ...    # PDF is not "processing"

# AFTER: each class has one reason to change
class OrderProcessor:
    def __init__(self, repo, notifier):
        self._repo      = repo
        self._notifier  = notifier
    def process(self, order):
        self._repo.save(order)
        self._notifier.notify(order.customer_email, "Order confirmed")

# ── D: Dependency Inversion — the most impactful SOLID principle ──────────────
# BEFORE: business logic directly depends on a concrete database
class OrderRepository:
    def save(self, order):
        import psycopg2
        conn = psycopg2.connect("postgresql://...")  # HARD dependency!
        # ...

# AFTER: business logic depends on an abstraction; infra injects the concrete
class OrderRepo(Protocol):
    def save(self, order) -> None: ...
    def get(self, order_id: int): ...

class PostgresOrderRepo:              # one concrete implementation
    def save(self, order): ...
    def get(self, order_id): ...

class InMemoryOrderRepo:              # test/dev implementation
    def __init__(self): self._db = {}
    def save(self, order): self._db[order.id] = order
    def get(self, order_id): return self._db[order_id]

class OrderService:
    def __init__(self, repo: OrderRepo):    # depends on abstraction
        self._repo = repo

    def place(self, order):
        self._repo.save(order)

# Production
service = OrderService(PostgresOrderRepo())
# Tests — no real DB needed
service = OrderService(InMemoryOrderRepo())