mypy

mypy is a static type checker for Python that adds optional, gradual typing on top of the language’s existing type hint syntax (PEP 484 and friends). Rather than requiring a fully-typed codebase up front, mypy lets you annotate incrementally and will infer types where it can, flagging mismatches — calling a function with the wrong argument type, accessing an attribute that doesn’t exist, returning the wrong type — as static errors instead of runtime crashes.

Under the hood mypy is itself written largely in Python and compiled with mypyc (its own sibling project) for speed, and ships as both a CLI (mypy path/to/code) and an importable API for editor/IDE integrations. It’s the reference implementation the Python typing ecosystem is built around, maintained under the official python GitHub organization with backing from Dropbox, Google, Microsoft, and the broader community, and it powers type-checking in most major Python IDEs and CI pipelines.

What You Get

• A CLI (mypy) that type-checks a file, package, or entire project and reports errors with file/line precision
• Gradual typing: mix typed and untyped code, and control strictness per-module via --strict, --disallow-untyped-defs, and similar flags
• Type inference for unannotated local variables and expressions, reducing how much you need to annotate manually
• Support for the full modern typing feature set: generics, Protocols, TypedDict, overloads, Literal types, and typeshed-provided stubs for the standard library and popular packages
• A daemon mode (dmypy) and incremental caching for fast repeated type checks in editors and CI
• Compiled itself with mypyc for significantly faster execution than a pure-Python interpreter run

Common Use Cases

• Adding a CI gate that fails a build when new code introduces type errors or removes existing type-safety guarantees
• Incrementally typing a large legacy Python codebase module-by-module without a disruptive big-bang rewrite
• Powering real-time type-checking and autocomplete in editors (VS Code, PyCharm) via the mypy language server integration
• Enforcing strict typing on library public APIs so consumers get accurate type information and IDE support
• Catching None-safety and Optional-handling bugs (e.g. calling a method on a value that might be None) before they hit production

Under The Hood

Architecture - mypy’s core lives in mypy/checker.py (~10,000 lines), which walks a parsed AST performing type inference and constraint checking against the declared/inferred types, coordinating with mypy/semanal.py for semantic analysis and name binding and mypy/build.py for the overall multi-module build graph, dependency ordering, and incremental caching. Type stub resolution (typeshed bundling, third-party stub packages) and plugin hooks (for frameworks like Django/attrs that generate types dynamically) are layered on top of this core pipeline. Tech Stack - Implemented in Python 3, with the performance-critical parts compiled ahead-of-time via mypyc (mypy’s own compiler project, itself a directory in this repo) into C extensions for a substantial speed-up over interpreted execution; packaging uses setuptools with a build-time dependency on typing_extensions, pathspec, and tomli. Code Quality - The mypy/test directory contains an extensive test suite including self-checking (mypy type-checks its own codebase via mypy_self_check.ini), snapshot-style .test data files under test-data/, and a stubtest.py tool for verifying stub accuracy against runtime behavior — reflecting a mature, heavily-tested project after over a decade of development. API Design - The CLI surface is a single mypy entry point with a large but well-documented flag set (--strict, --ignore-missing-imports, per-module overrides via config file), and the library exposes a stable-ish internal API used by editor plugins (dmypy daemon protocol) and IDE integrations, though the internal AST/type APIs are explicitly not a public stability contract.