GO — Healthy across the board

• Last commit 2d ago
• 23+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

Mypy is a static type checker for Python that enforces type hints (PEP 484) at development time, catching type errors before runtime. It analyzes Python code annotated with type hints and reports mismatches in variable usage, function calls, and assignments—enabling developers to write safer, more maintainable Python without sacrificing the language's flexibility. Monolithic but well-modularized: core type checker logic lives in mypy/ (the main package); documentation and configuration templates in docs/source/ and .github/; testing infrastructure centered on conftest.py and GitHub Actions workflows; build requirements managed in build-requirements.txt for reproducibility. No clear monorepo structure, but strong separation between compiler core and tooling (stubgen, dmypy, etc).

Python developers building production codebases who want early detection of type-related bugs; library maintainers publishing typed packages to typeshed; teams adopting gradual typing in legacy Python projects. Contributors are typically type system enthusiasts and Python compiler engineers.

Highly mature and production-ready. The project has substantial infrastructure (7M+ lines of Python, multi-platform CI/CD in .github/workflows/, ReadTheDocs integration, mypy_primer regression testing), active development signaled by recent workflow additions (test_stubgenc.yml, mypy_primer workflows), and comprehensive documentation in docs/source/. This is the de facto standard Python type checker recommended by the Python community.

Low risk for stable use, but moderate risk for cutting-edge contributions: the C/C++ dependencies (818KB C, 102KB C++, likely from performance-critical type inference) add complexity; the massive test surface area means changes require extensive validation (see .github/workflows/test.yml and conftest.py). Single-organization control (python/mypy) means breaking changes reflect Python's own typing evolution decisions. Open issue backlog is substantial but actively triaged.

Active development on test infrastructure and CI/CD efficiency: recent additions include test_stubgenc.yml for stub generation testing, mypy_primer.yml and mypy_primer_comment.yml for regression detection across real-world codebases, and sync_typeshed.yml for keeping type stubs synchronized. Ongoing incremental typing support and refinement of error reporting (see docs/source/error_code_list.rst and error_codes.rst).

git clone https://github.com/python/mypy.git
cd mypy
pip install -r build-requirements.txt
python -m pytest tests/
mypy mypy  # Self-host: type-check mypy with itself

Daily commands:

# Type-check a file
mypy your_file.py

# Type-check with config (mypy.ini or setup.cfg)
mypy --config-file mypy.ini .

# Development: run test suite
python -m pytest tests/ -k test_name

# Self-host: type-check mypy itself
mypy mypy

• mypy/main.py — Primary entry point for the mypy type checker; all CLI invocations flow through here.
• mypy/nodes.py — Core AST node definitions representing Python syntax tree; fundamental to all type checking operations.
• mypy/types.py — Type representation system and type operations; essential for understanding how mypy models types internally.
• mypy/checker.py — Main type checking logic that traverses AST and enforces type constraints; heart of type checking.
• mypy/build.py — Build manager for managing module dependencies, caching, and incremental checking.
• mypy/api.py — Public API for embedding mypy; interface for programmatic type checking invocation.
• CONTRIBUTING.md — Contribution guidelines covering architecture, testing, and development workflow for the project.

• Parser (mypy/parser.py) (Recursive descent parser, tokenization) — Converts Python source text into AST nodes.
  • Failure mode: Syntax errors abort module processing; crashes on malformed Python.
• Semantic Analyzer (mypy/semanal.py) (Multi-pass symbol table construction, scope management) — Resolves names, processes type annotations, establishes symbol tables.
  • Failure mode: Undefined name or circular import errors; incomplete type information if references are unresolvable.
• Type Checker (mypy/checker.py + mypy/checkexpr.py) (Type inference, subtype checking, constraint solving) — Enforces type constraints by traversing AST and comparing against type rules.
  • Failure mode: Type mismatches reported as errors; may miss some dynamic patterns due to static analysis limitations.
• Build Manager (mypy/build.py) (Module graph, state caching with pickle, incremental tracking) — Orchestrates module loading, dependency resolution, and incremental state.
  • Failure mode: Cache corruption results in stale results; circular imports cause build failures.
• Error Reporter (mypy/messages.py + mypy/errors.py) (Message formatting, error collection, output rendering) — Generates human-readable error messages with source location and context.
  • Failure mode: Malformed error output or missing context; incorrect line numbers if AST nodes lack position info.

• User CLI → mypy/main.py — Source file paths and configuration options passed as arguments.
• mypy/main.py → mypy/build.py — Files and options forwarded to build manager for graph construction.
• mypy/build.py → mypy/parser.py — Source code text forwarded for parsing into AST.
• mypy/parser.py → mypy/semanal.py — AST nodes passed for semantic analysis and symbol resolution.
• mypy/semanal.py → mypy/checker.py — Analyzed AST with resolved symbols passed to type checker.
• mypy/checker.py → mypy/messages.py — Type violations forwarded for human-readable error message generation.

Add a New Type Checking Rule

1. Define the type violation rule in mypy/messages.py as a new error message method (mypy/messages.py)
2. Implement the checking logic in mypy/checker.py or mypy/checkexpr.py to detect violations (mypy/checker.py)
3. Add test cases to test-data/ with expected error annotations to validate the new rule (test-data/)

Add a New Command-Line Option

1. Define the new option in mypy/options.py as a field in the Options class (mypy/options.py)
2. Add argument parser configuration in mypy/main.py to parse the option from CLI (mypy/main.py)
3. Implement the option logic in relevant checker or build modules (mypy/checker.py)
4. Document the option in docs/source/command_line.rst (docs/source/command_line.rst)

Add Support for a New Python Language Feature

1. Extend mypy/nodes.py with new AST node classes if needed for the syntax (mypy/nodes.py)
2. Update mypy/parser.py to parse the new syntax into AST nodes (mypy/parser.py)
3. Implement semantic analysis in mypy/semanal.py for name resolution (mypy/semanal.py)
4. Add type checking logic in mypy/checker.py or mypy/checkexpr.py (mypy/checker.py)
5. Add comprehensive test cases in test-data/ (test-data/)

• Python — Self-hosted implementation allows mypy to type-check itself and be embedded in other Python tools.
• AST-based type checking — Provides deep semantic analysis over raw source code instead of runtime reflection.
• Incremental caching with pickle — Enables fast re-checking of large codebases by reusing type information from unchanged modules.
• Multi-pass semantic analysis — Multiple passes allow forward references and complex dependency resolution before type checking.

• Static analysis only (no runtime type information)

  • Why: Enables checking unrunnable code and provides deterministic results independent of environment.
  • Consequence: Cannot resolve some dynamic patterns; requires manual type annotations for complex runtime behavior.

• Gradual typing with optional annotations

  • Why: Allows incremental adoption on legacy codebases without requiring full type coverage.
  • Consequence: Any function can have Any type, reducing type safety guarantees in mixed-typed code.

• Plugin system for extensibility

  • Why: Allows third-party tools to extend mypy without forking the codebase.
  • Consequence: Plugin API surface is more limited than internal APIs; some advanced checking patterns require core changes.

• Runtime type enforcement or validation
• Integration with Python runtime type hints evaluation
• Support for untyped legacy Python codebases without any annotations
• Real-time IDE-quality responsiveness (optimized for batch checking)
• Complete Python 2 support (focused on Python 3.6+)

• Avg cyclomatic complexity: ~7.2 — Heavy use of recursive tree walking, multi-pass analysis, and constraint solving; complex type relationships and generic handling.
• Largest file: mypy/checker.py (7,500 lines)
• Estimated quality issues: ~34 — Large monolithic files, some sections with deep nesting, inconsistent error handling patterns, and areas lacking comprehensive test coverage for edge cases.

• Broad exception catching in main loop (Medium) — mypy/main.py: Catching all exceptions can mask bugs and make debugging difficult; should catch specific exception types.
• Deep nesting in type checking logic (Medium) — mypy/checker.py: Complex conditional logic with many nested branches reduces maintainability; should extract helper methods.
• Mutable default arguments in node constructors (Low) — mypy/nodes.py: Using mutable defaults (lists, dicts) can cause unexpected shared state between instances.
• String-based type references in forward references (Medium) — mypy/types.py: Relying on string parsing for forward refs is fragile; should use dedicated ForwardRef nodes.

• mypy/build.py - build_graph() (Algorithmic complexity) — Module dependency resolution and state reconstruction is expensive for large projects; scales quadratically with module count.
• mypy/checker.py - check all pass (Traversal overhead) — Full AST traversal for type checking can be slow for large files; no granular caching within file.
• mypy/constraints.py - constraint solving (Algorithmic complexity) — Generic type parameter solving can be exponential in worst case; may time out on deeply nested generics.
• Cache serialization in mypy/state.py (I/O overhead) — Pickle serialization of large type graphs is slow for incremental builds; no incremental cache updates.

mypypath and PYTHONPATH: The MYPYPATH environment variable controls stub/library resolution and must be set correctly for local module discovery. Incremental mode cache: .mypy_cache/ directory can become stale; use mypy --no-incremental to force full recheck if you suspect cache corruption. Plugin ordering: Plugin initialization order in mypy.ini [mypy] plugins= matters—some plugins must run before others (not always documented). Stub generation: stubgen (in mypy/stubgen/) has separate test suite (test_stubgenc.yml) and different behavior from the main checker. Vendored code: Check for C/C++ extensions in build system; type-checking mypy itself requires build-requirements.txt, not just pip install mypy.

• Gradual Typing — Mypy's core philosophy—allowing Python code to mix untyped and typed regions, enabling incremental adoption of type hints in large codebases without requiring full rewrites
• Structural Subtyping (Duck Typing with Types) — Mypy's --no-strict-optional mode and protocol typing (typing.Protocol) rely on structural compatibility checking rather than nominal types, reflecting Python's dynamic nature
• Hindley-Milner Type Inference — Mypy uses constraint-based type inference similar to ML languages; understanding this explains why some type annotations are inferred automatically and others must be explicit
• Incremental Compilation with Dependency Graphs — Mypy builds and caches a fine-grained dependency graph (in mypy/build.py) to re-check only affected modules on subsequent runs, critical for fast iteration on large projects
• PEP 484 Type Hints — The formal specification that mypy implements; understanding PEP 484 (and related PEPs like 544 for Protocols) is essential to predict mypy's behavior
• Variance in Generics (Covariance, Contravariance, Invariance) — Mypy enforces variance rules in mypy/subtypes.py to prevent type errors in generic classes and functions; a common source of confusing error messages
• Stub Files (.pyi) and PEP 561 — Mypy reads .pyi stub files for type information about compiled extensions and third-party libraries; understanding stub generation (via stubgen) and resolution is key to supporting new packages

• python/typeshed — The canonical type stub repository (PEP 561) that mypy consults for third-party library types; mypy_primer tests against it and sync_typeshed.yml keeps them in sync
• pyright/pyright — Alternative static type checker for Python (Microsoft's, used by Pylance); solves the same problem with different implementation philosophy and performance characteristics
• python/cpython — Home of Python's official typing module and PEPs (484, 585, 586, etc) that define the type hint syntax mypy enforces
• python/typing — Historical repository and discussions hub for Python typing evolution; mypy contributors monitor PRs and discussions here to stay aligned with typing standards
• pydantic/pydantic — Popular runtime validation library that mypy has deep integration with via plugins (mypy/plugin.py has pydantic support); common use case for mypy users

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for mypy_primer GitHub workflow

The repo has .github/workflows/mypy_primer.yml and mypy_primer_comment.yml workflows but likely lacks detailed tests for the primer infrastructure itself. The mypy_primer is a critical tool for regression testing against real-world codebases. Adding unit tests for the primer's core logic (result parsing, comparison, commenting) would improve reliability and make contributions easier.

• [ ] Create tests/test_mypy_primer.py with unit tests for primer result parsing and comparison logic
• [ ] Add tests for the GitHub API integration used in mypy_primer_comment.yml workflow
• [ ] Document expected primer output formats in tests to prevent regressions
• [ ] Add integration test that runs primer against a small fixture codebase

Expand error_code_list documentation with practical examples for each error code

The repo has docs/source/error_code_list.rst and error_code_list2.rst split across two files, but based on the file structure, these likely lack concrete code examples for each error category. Users frequently struggle to understand error codes without seeing the problematic code patterns. Adding before/after examples would significantly improve developer experience.

• [ ] Audit docs/source/error_code_list.rst and error_code_list2.rst for missing code examples
• [ ] Add Python code snippets showing incorrect code that triggers each major error code
• [ ] Add corrected code examples showing the proper type annotation pattern
• [ ] Create a test file test_docs_error_examples.py that validates all code examples in error docs actually produce the claimed errors

Add integration tests for stubgen with popular third-party packages

The repo has .github/workflows/test_stubgenc.yml and docs/source/stubgen.rst, but there's likely limited integration testing of stubgen against real-world packages with complex type patterns (decorators, metaclasses, async code). This would catch regressions in stub generation quality that unit tests miss.

• [ ] Create tests/test_stubgen_integration.py with fixtures for packages like dataclasses, asyncio, and functools
• [ ] Test stubgen output against packages using decorators, metaclasses, and type variable edge cases
• [ ] Add validation that generated stubs pass stubtest (referenced in docs/source/stubtest.rst)
• [ ] Update .github/workflows/test_stubgenc.yml to run these integration tests against a snapshot of popular PyPI packages

• Add type stubs or improved error messages for a specific standard library module. Many stdlib functions have incomplete or generic type hints in typeshed; you could improve docs/source/error_code_list.rst examples or add test cases in test-cases/ for edge cases that currently produce cryptic errors.: Low risk, high impact—improves user experience without touching core inference logic.
• Expand the mypy_primer regression test suite by adding a new popular open-source project. Edit .github/workflows/mypy_primer.yml or the underlying primer configuration to include a high-quality typed project (e.g., FastAPI, Pydantic); this catches breaking changes early.: Valuable for quality assurance, requires only configuration knowledge, not deep type system understanding.
• Improve documentation for a specific advanced feature. Many docs/source/ files (e.g., final_attrs.rst, generics.rst) lack concrete examples or explain edge cases poorly. Add runnable code snippets and test them against the current mypy binary to ensure accuracy.: Helps the whole community, self-contained, minimal risk of breaking anything.

The mypy repository demonstrates a generally good security posture as a mature, well-maintained Python static analysis tool. However, without visibility into the actual dependency manifests, specific security gaps cannot be fully assessed. The project follows standard open-source practices with GitHub workflows and documentation. Recommendations include establishing a formal security disclosure policy, providing dependency information for scanning, and ensuring utility scripts validate external input properly.

• Low · Missing Dependency Manifest — Root directory. No package dependency file (requirements.txt, setup.py, pyproject.toml, or Pipfile) was provided for analysis. This makes it impossible to identify vulnerable third-party dependencies that mypy relies upon. Fix: Provide dependency manifests (setup.py, pyproject.toml, setup.cfg) for security scanning. Regularly audit dependencies using tools like 'safety', 'pip-audit', or 'dependabot'.
• Low · No Security Policy Documented — Root directory. No SECURITY.md or security policy file is visible in the repository. This makes it unclear how to report security vulnerabilities responsibly. Fix: Create a SECURITY.md file following GitHub's security advisory guidelines to establish a responsible disclosure policy.
• Low · Docker Configuration Lacks Security Scanning — misc/docker/Dockerfile, .github/workflows/. The Docker configuration files in misc/docker/ are present but no visible security scanning tools (Trivy, Hadolint) are configured in the CI/CD pipeline. Fix: Add Docker image scanning to the CI/CD pipeline and ensure base images are regularly updated and scanned for vulnerabilities.
• Low · Potential Script Injection in Misc Tools — misc/*.py scripts. Multiple Python scripts in misc/ directory (misc/dump-ast.py, misc/find_type.py, etc.) that perform analysis or code generation could potentially be vectors for injection if they accept untrusted input without proper validation. Fix: Ensure all user input is validated and sanitized. Add input validation checks to utility scripts, especially those that parse or generate code.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/python/mypy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live python/mypy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/python/mypy.

What it runs against: a local clone of python/mypy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in python/mypy | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of python/mypy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/python/mypy.git
#   cd mypy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of python/mypy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "python/mypy(\\.git)?\\b" \\
  && ok "origin remote is python/mypy" \\
  || miss "origin remote is not python/mypy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "mypy/main.py" \\
  && ok "mypy/main.py" \\
  || miss "missing critical file: mypy/main.py"
test -f "mypy/nodes.py" \\
  && ok "mypy/nodes.py" \\
  || miss "missing critical file: mypy/nodes.py"
test -f "mypy/types.py" \\
  && ok "mypy/types.py" \\
  || miss "missing critical file: mypy/types.py"
test -f "mypy/checker.py" \\
  && ok "mypy/checker.py" \\
  || miss "missing critical file: mypy/checker.py"
test -f "mypy/build.py" \\
  && ok "mypy/build.py" \\
  || miss "missing critical file: mypy/build.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/python/mypy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.