Preamble
List[int] and Optional[str] are table stakes. The pieces I actually lean on in packaged code are Protocol for structural typing, Union / | for explicit alternatives, and TypedDict for JSON-shaped dictionaries. They line up with Architecture for Evolvable Services After Polyglot Expansion’s boundary framing: types document ports without forcing inheritance-heavy Java patterns.
Protocol: duck typing with guardrails
A Protocol describes the methods a collaborator must provide. Third-party classes can satisfy it without subclassing—ideal for test doubles and adapter boundaries.
TypedDict: keys are part of the contract
External APIs return dicts with known keys; TypedDict lets mypy catch typos and missing optional keys before KeyError at 2 a.m. Pair with NotRequired (3.11+) for partial payloads.
Debugging before runtime
Mypy errors often read like design reviews: wrong branch of a Union, forgotten None check, incompatible return shapes. The cost is CI time; the benefit is fewer production exceptions in large payloads.
Conclusion
Types are lightweight architecture documentation—especially at module boundaries. SpotBugs and Error Prone for Java Static Analysis adds SpotBugs and Error Prone as the Java-side analogue.