Static Type Checking with mypy

Use mypy to add optional static typing to Python programs and catch programming errors through static analysis before runtime. Mypy acts as a powerful Python linter that analyzes type annotations to detect bugs early.

What This Skill Does

This skill guides you through using mypy to add type safety to Python projects. Mypy analyzes type annotations in your code without executing it, catching type errors, attribute errors, and other common bugs before runtime. It supports advanced type system features including type inference, gradual typing, generics, and union types.

Instructions

When a user requests type checking, static analysis, or adding type safety to Python code:

1. **Install mypy** in the project environment using the appropriate package manager (pip, uv, poetry, or pipenv)

2. **Analyze existing code** to understand current typing status:

- Check if type annotations already exist

- Identify untyped functions, variables, and return values

- Note any existing type hints or stubs

3. **Run mypy** on the target files or directories:

- Start with `mypy <file_or_directory>` to identify type errors

- Use `mypy --strict` for maximum type safety enforcement

- Use `mypy --install-types` to automatically install missing type stubs

4. **Add type annotations** to resolve errors:

- Add function parameter types and return types

- Annotate variables where type inference is insufficient

- Use appropriate types from `typing` module (List, Dict, Optional, Union, etc.)

- Apply generics where applicable (e.g., `List[str]`, `Dict[str, int]`)

5. **Handle gradual typing** if working with existing untyped code:

- Use `# type: ignore` comments sparingly for legacy code sections

- Consider using `Any` type temporarily for complex refactoring

- Prioritize critical code paths for initial type annotation

6. **Configure mypy** if needed:

- Create `mypy.ini` or add `[tool.mypy]` section to `pyproject.toml`

- Set appropriate strictness levels for the project

- Configure per-module overrides if mixing typed and untyped code

7. **Verify fixes** by re-running mypy until no errors remain

Example Usage

**User**: "Check this Python file for type errors"

**AI**:

1. Runs `mypy script.py` to identify type issues

2. Shows detected errors (missing return types, incompatible types, etc.)

3. Adds appropriate type annotations to fix errors

4. Re-runs mypy to verify all issues resolved

**User**: "Add strict type checking to my Flask app"

**AI**:

1. Installs mypy and type stubs for Flask

2. Configures `mypy.ini` with strict settings

3. Systematically adds type annotations to routes, models, and utilities

4. Uses `typing` module types (Optional, Union, etc.) where needed

5. Runs `mypy --strict` and resolves all errors

Constraints

When to Use This Skill