mypy - Static type checker for Python with gradual typing, strict mode, Protocol support, and framework integration

mypy Static Type Checking for Python Overview mypy is the standard static type checker for Python, enabling gradual typing with type hints (PEP 484) and comprehensive type safety. It catches type errors before runtime, improves code documentation, and enhances IDE support while maintaining Python's dynamic nature through incremental adoption. Key Features : Gradual typing: Add types incrementally to existing code Strict mode: Maximum type safety with strict flag Type inference: Automatically infer types from context Protocol support: Structural typing (duck typing with types) Generic types: TypeVar, Generic, and advanced type patterns Framework integration: FastAPI, Django, Pydantic compatibility Plugin system: Extend type checking for libraries Incremental checking: Fast type checking on large codebases Installation : Type Annotation Basics 1. Variable Type Hints 2. Function Type Hints 3. Collection Type Hints 4. Class Type Hints Advanced Type Hints 1. Literal Types 2. Type Aliases 3. Generics and TypeVar 4. Protocol (Structural Typing) 5. Callable Types mypy Configuration 1. mypy.ini Configuration 2. pyproject.toml Configuration 3. Strict Mode Incremental Adoption Strategies 1. Start with Entry Points 2. Per Module Strict Mode 3. Use type: ignore Strategically 4. Reveal Types During Development FastAPI Integration 1. FastAPI with Type Hints 2. Async FastAPI Type Checking 3. FastAPI Dependency Injection Types Django Integration 1. Django with django stubs 2. Django Models with Type Hints 3. Django Views with Type Hints Type Stubs and Third Party Libraries 1. Installing Type Stubs 2. Creating Custom Stubs 3. Ignoring Missing Imports CI/CD Integration 1. GitHub Actions 2. Pre commit Hook 3. Make Target Common Patterns and Idioms 1. Overload for Multiple Signatures 2. TypedDict for Structured Dicts 3. Final and Constant Values 4. Self Type for Method Chaining mypy vs pyright Comparison Feature Comparison Feature mypy pyright Type Checker Official Python type checker Microsoft's type checker Speed Slower on large codebases Faster, incremental Strictness Configurable strict mode Very strict by default IDE Integration Good (LSP support) Excellent (Pylance in VS Code) Plugin System Yes (mypy plugins) Limited Error Messages Clear, detailed Very detailed, helpful Community Large, official Growing, Microsoft backed Type Inference Good Excellent Configuration mypy.ini, pyproject.toml pyrightconfig.json, pyproject.toml When to Use mypy When to Use pyright Using Both Local mypy Profiles (Your Repos) Common patterns from your Python projects: Strict default (edgar, kuzu memory, mcp browser): disallow untyped defs = true , check untyped defs = true , no implicit optional = true , warn return any = true , strict equality = true . Relaxed profile (mcp ticketer): strict flags disabled temporarily with a disable error code list for patch releases. Incremental adoption (mcp vector search): ignore errors = true while stabilizing types. Missing imports : ignore missing imports = true used in mcp memory and mcp ticketer. Reference: see pyproject.toml in edgar , kuzu memory , mcp vector search , and mcp ticketer . Best Practices 1. Start with Key Modules 2. Use Type Aliases for Readability 3. Prefer Explicit Over Implicit 4. Use reveal type for Debugging 5. Document Type Ignores Common Pitfalls ❌ Anti Pattern 1: Using Any Everywhere Correct: ❌ Anti Pattern 2: Ignoring Type Errors Globally Correct: ❌ Anti Pattern 3: Not Using Optional Correct: Quick Reference Common Commands Error Code Reference Resources Official Documentation : https://mypy.readthedocs.io/ Type Hints PEP : https://peps.python.org/pep 0484/ typing Module : https://docs.python.org/3/library/typing.html mypy GitHub : https://github.com/python/mypy Type Stubs : https://github.com/python/typeshed django stubs : https://github.com/typeddjango/django stubs FastAPI + mypy : https://fastapi.tiangolo.com/tutorial/type hints/ Related Skills When using mypy, consider these complementary skills (available in the skill library): pytest : Type safe testing with mypy integrates type checking into your test suite for comprehensive type coverage fastapi local dev : FastAPI with full type safety combines FastAPI's runtime validation with mypy's static checking pydantic : Runtime type validation with mypy support validates data at runtime while mypy validates at compile time mypy Version Compatibility: This skill covers mypy 1.8+ and reflects current best practices for Python type checking in 2025.