Gradual typing in Python with type hints

Goal

Introduce static type checking into an existing Python project without a big-bang rewrite, so that mismatched call sites and impossible states are caught before tests run.

Prerequisites

Python 3 with a checker such as mypy installed in the development environment and run in the pipeline.

Steps

1. Run the checker with lenient settings on the whole project and fix only real errors; annotations stay optional at this stage.
2. Annotate module boundaries first: public functions, data classes, return types of I/O wrappers. These carry the most information per annotation.
3. Enable stricter options per module or package as they become fully annotated (disallow_untyped_defs and similar in mypy), so strictness grows with coverage.
4. Model states with types: Literal for enumerations, TypedDict or dataclasses for records, Optional only where None is a real value.
5. Keep Any and # type: ignore visible and rare; each is a place where the checker cannot help.

Expected result

The checker fails the build on calls with wrong argument types or missing return handling; annotations serve as documentation that cannot drift from the code.

Limits and test basis

Hints are not enforced at runtime; validation at system boundaries (parsing input) is still required. Highly dynamic code may resist typing; isolate it behind typed interfaces. The mechanics follow PEP 484 and the cited tool documentation.