Textbook of Python

Gradual typing is an approach where type annotations can be added to a codebase incrementally — some functions have full type hints while others have none, and the type checker handles both. Python's type system is designed around this principle: type hints are optional, the interpreter ignores them, and type checkers like mypy treat un-annotated code as implicitly typed with Any (compatible with everything).

This design was a deliberate choice. Requiring types everywhere would have broken Python's dynamic character and alienated much of the community. Instead, you can add types to the critical parts of your codebase (public APIs, complex logic, data models) and leave informal scripts, notebooks, and exploratory code un-annotated. As your project matures, you can gradually increase type coverage.

mypy's --strict mode makes un-annotated functions an error, effectively opting into full static typing. In between, options like --check-untyped-defs and --disallow-untyped-defs provide intermediate strictness levels. The gradual typing philosophy acknowledges that type checking is a spectrum, not a binary choice — and that even partial type coverage catches real bugs.