How joosthart/pre-commit-hook-mypy works
Project type and purpose
• Type: A command-line tool / Git pre-commit hook written in Python.
• Purpose: When a user runs git commit, the hook invokes mypy on all files to resolve imports but only reports errors for the files being committed.
File structure
• Top-level directories:
• src/pre_commit_hook_mypy/ contains the implementation.
• tests/ holds unit tests.
• docs/ illustrates usage examples.
• Config and packaging files: pyproject.toml, setup.py, requirements-dev.txt, GitHub workflow, pre-commit templates.
• Key modules under src/pre_commit_hook_mypy/:
• cli.py – entry point for the hook.
• mypy_committed.py – logic to detect committed files, invoke mypy, filter output.
• Deployment: packaged to PyPI, installed via pip install -e ., referenced in .pre-commit-config.yaml.
Extract insights from the README
• The hook steps:
1. Committed Python files.
2. Run mypy on entire codebase (for proper import resolution).
3. Filter mypy’s output to errors in the committed files only.
4. Fail the commit if errors remain.
• Configuration options mirror the standard mypy pre-commit hook.
Main components
a. External Systems
• Git (user triggers git commit)
• Pre-commit framework (invokes the hook)
• mypy tool (external type checker)
b. Internal Components
• CLI module (cli.py) – invoked by pre-commit
• File detection submodule (in mypy_committed.py) – queries Git for a list of staged .py files
• Mypy invocation submodule – spawns a subprocess running mypy on the codebase
• Output filter submodule – parses mypy stdout/stderr, filters messages to only those whose file path matches the staged files list
• Exit handler – returns success (0) or failure (non-zero) to pre-commit
c. Configuration Layer
• .pre-commit-config.yaml (defines hook ID, args, additional dependencies)
• pyproject.toml / setup.py (packaging metadata)
Relationships and data flow
1. User runs git commit.
2. Pre-commit framework intercepts the commit and invokes the pre_commit_hook_mypy CLI.
3. CLI module calls the file detection logic to get the list of staged Python files from Git.
4. CLI then calls the mypy invocation logic with the full codebase path (ensuring correct module resolution).
5. mypy runs and emits errors/warnings for all checked files.
6. Output filter processes mypy’s output, keeping only errors related to the staged files.
7. Exit handler determines if filtered errors exist:
– If yes, it exits with a nonzero status → commit aborted.
– If no, it exits with zero → commit proceeds.
Architectural patterns and design principles
• Single-Responsibility: each submodule does one thing (detect files, call mypy, filter output).
• Modularity: CLI vs. core logic (mypy_committed.py) separated for testability.
• External dependency isolation: invoking mypy as a subprocess rather than embedding it.
• Extensibility: CLI accepts arbitrary mypy args and additional dependencies via pre-commit config.
Technologies and frameworks
• Python 3.x
• click or argparse (depending on implementation in cli.py)
• subprocess or similar for external calls
• pytest for tests (tests/ directory)
• pre-commit framework for hook orchestration