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`). - **Enums:** Default to `Enum` (with `__str__` overridden) for closed sets of domain states — members are distinct identities, not interchangeable with raw primitives, which catches accidental comparisons against arbitrary strings/ints. Reach for `StrEnum` (3.11+) when members must interoperate directly with strings — JSON payloads, query params, f-strings — without a `.value` call at every site. Reach for `IntEnum` when members must support arithmetic or ordering against plain integers (HTTP status codes, priority levels, wire values from an external system). Both trade `Enum`'s identity-safety for primitive compatibility — reach for them only when that interop is a real requirement, not by default. - **Constraints:** `Literal` for a narrow, function-local set of string flags that doesn't warrant a full `Enum`. - **Structured payloads:** `TypedDict` over `dict[str, Any]