python-architectlisted

# Python Architecture Standards Targets **Python 3.14**. See [STACK.md](STACK.md) for pinned dependency versions. ## 1. Typing & Domain Safety - **Modern syntax:** Built-in generics (`list[str]`, `dict[K, V]`, `X | None`). Never the legacy `typing.List` / `typing.Optional`. - **Deferred annotations (PEP 649, 3.14):** Annotations are no longer eagerly evaluated — forward references no longer need quotes (`def f(arg: NotYetDefined)` works). Inspect via `annotationlib.get_annotations()`, not `__annotations__` directly. - **Domain types:** `typing.NewType` to separate distinct concepts (`UserId` vs `OrderId`). - **Constraints:** `Literal` for string flags; `Enum` (with `__str__`) for states. - **Structured payloads:** `TypedDict` over `dict[str, Any]` for known-shape mappings. - **Subclassing safety:** `typing.override` decorator (3.12+) on every overriding method — mypy flags broken overrides. ## 2. Data Structures & Memory - **Immutability:** Default to `@dataclass(slots=True, frozen=True)` for DTOs and value objects. - **Pydantic vs dataclass boundary:** Pydantic only at application boundaries (API request/response, DB row parsing, config). Standard dataclasses for core domain logic — keeps the domain free of validation-framework coupling. - **Memory:** `__slots__` (explicit or via `dataclass(slots=True)`) on high-volume instances. ## 3. Interfaces & DI - **Protocols:** `typing.Protocol` (structural typing) over deep `abc.ABC` inheritance. Define protocols where consume