Mypy

Mypy - Professional Static Type Checking

Mypy is a static type checker for Python that finds bugs without running code. This skill provides comprehensive guidance for professional mypy integration and usage.

Quick Start

Installation and Basic Usage

# Install mypy
python3 -m pip install mypy

# Check a file
mypy program.py

# Check with strict mode
mypy --strict program.py

Basic Type Annotations

def greeting(name: str) -> str:
    return 'Hello ' + name

# Type checking catches errors
greeting(3)  # Error: Argument has incompatible type "int"; expected "str"

Configuration

Mypy supports multiple configuration formats (discovery order):

1. mypy.ini
2. .mypy.ini
3. pyproject.toml (with [tool.mypy] section)
4. setup.cfg (with [mypy] section)

Essential Configuration Options

# mypy.ini
[mypy]
python_version = 3.11
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

# Per-module configuration
[mypy-module_name.*]
ignore_missing_imports = True

See references/config_file.md for complete configuration reference.

Core Workflows

Adding Types to Existing Code

1. Start with --check-untyped-defs for gradual typing
2. Use # type: ignore comments sparingly for temporary exceptions
3. Add type annotations incrementally, module by module
4. Enable stricter checks progressively

See references/existing_code.md for migration strategies.

Resolving Type Errors

When mypy reports errors:

1. Check the error code (e.g., [attr-defined])
2. Consult error code documentation:
   • references/error_code_list.md - Default errors
   • references/error_code_list2.md - Optional checks
3. Use type narrowing techniques when needed
4. Consider reveal_type() for debugging type inference

See references/common_issues.md for troubleshooting.

Working with Advanced Types

Generics: references/generics.md

• TypeVar, Generic classes, bounded type variables
• Variance (covariant, contravariant, invariant)

Protocols: references/protocols.md

• Structural subtyping, runtime checkable protocols
• Protocol composition

TypedDict: references/typed_dict.md

• Required vs optional keys, inheritance
• Total vs non-total TypedDicts

Literal Types: references/literal_types.md

• String/int/bool/Enum literals
• Exhaustiveness checking

See references/kinds_of_types.md for type system overview.

Command Line Reference

# Strict mode (recommended for new projects)
mypy --strict module.py

# Check specific paths
mypy src/ tests/

# Generate HTML coverage report
mypy --html-report ./mypy-report src/

# Use mypy daemon for faster checking
dmypy run -- src/

# Generate stubs from existing code
stubgen -p mypackage -o stubs/

See references/command_line.md for all CLI options.

CI/CD Integration

GitHub Actions Example

- name: Type check with mypy
  run: |
    pip install mypy
    mypy --install-types --non-interactive
    mypy src/

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.19.1
    hooks:
      - id: mypy
        additional_dependencies: [types-all]

Reference Documentation

The references/ directory contains complete mypy 1.19.1 documentation:

Getting Started

• getting_started.md - Installation, basic concepts
• cheat_sheet_py3.md - Quick reference guide

Type System

• builtin_types.md - Python built-in types
• type_inference_and_annotations.md - Annotations guide
• kinds_of_types.md - Type system overview
• class_basics.md - Class typing fundamentals
• protocols.md - Structural subtyping
• generics.md - Generic types and TypeVars
• typed_dict.md - TypedDict patterns
• literal_types.md - Literal types and Enums
• final_attrs.md - Final declarations
• more_types.md - Additional type patterns
• type_narrowing.md - Type narrowing techniques
• duck_type_compatibility.md - Duck typing rules

Configuration & Running

• config_file.md - Complete configuration reference
• command_line.md - CLI options and flags
• running_mypy.md - Running mypy guide
• inline_config.md - Inline type comments
• mypy_daemon.md - Daemon mode for speed
• installed_packages.md - Package type stubs

Advanced Topics

• stubs.md - Stub files guide
• stubgen.md - Automatic stub generation
• stubtest.md - Stub testing tool
• extending_mypy.md - Plugins and extensions
• metaclasses.md - Metaclass typing
• runtime_troubles.md - Runtime annotation issues
• dynamic_typing.md - Dynamic typing patterns

Troubleshooting

• error_codes.md - Error code system
• error_code_list.md - Default error codes
• error_code_list2.md - Optional error codes
• common_issues.md - Solutions to common issues
• faq.md - Frequently asked questions

Project Info

• additional_features.md - Advanced features
• supported_python_features.md - Python version support
• existing_code.md - Migration strategies
• changelog.md - Version history

Updating Documentation

The scripts/ directory contains tools to refresh documentation from mypy.readthedocs.io:

# Discover all documentation pages
python scripts/discover_pages.py > mypy_pages.txt

# Bulk scrape and clean documentation
python scripts/scrape_docs.py

# Clean individual markdown files
python scripts/clean_markdown.py input.md output.md

These scripts use cloudscraper for Cloudflare bypass and automatically clean navigation/footer content.

Best Practices

1. Start gradually - Use --check-untyped-defs initially
2. Configure per-module - Different strictness for different parts of codebase
3. Use error codes - Specific # type: ignore[code] instead of blanket ignores
4. Leverage inference - Let mypy infer types when obvious
5. Run in CI - Catch type errors before merge
6. Update regularly - Stay current with mypy releases for better type checking

Common Patterns

Optional Values

from typing import Optional

def find_user(id: int) -> Optional[User]:
    # May return None
    return user_db.get(id)

Union Types

from typing import Union

def process(value: Union[int, str]) -> str:
    if isinstance(value, int):
        return str(value)
    return value

Generic Functions

from typing import TypeVar, Sequence

T = TypeVar('T')

def first(seq: Sequence[T]) -> T:
    return seq[0]

Protocol (Structural Typing)

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: Drawable) -> None:
    obj.draw()  # Any object with draw() works

Version Information

This skill is based on mypy 1.19.1 (stable) documentation. Use the scraping scripts to update to newer versions as they are released.