| name | python-lint-format |
| description | Lint and format a Python project with the prek hook runner. Use when checking or cleaning the working tree, resolving lint/format/type/complexity/spelling failures, or understanding what each linter config enforces. |
Python Lint & Format (prek)
This project runs its linters and formatters through
prek, a pre-commit-compatible hook runner. The hooks
cover Python style/typing as well as Markdown, YAML, and spelling.
Installing the git hooks
A clone does not install prek's hooks — each developer installs them, and forgetting on
a fresh clone silently skips the checks:
prek install --install-hooks --overwrite
This is idempotent: re-run it if commits complete without the checks running. It needs a
prek.toml or .pre-commit-config.yaml present (the --install-hooks step also prepares
each hook's environment).
To verify the hooks are installed — cross-platform, via uv/Python rather than
shell-specific grep/Select-String (the shim's header reads # File generated by prek):
uv run python -c "import pathlib, subprocess; p = pathlib.Path(subprocess.run(['git', 'rev-parse', '--git-path', 'hooks'], capture_output=True, text=True).stdout.strip(), 'pre-commit'); print('installed' if p.is_file() and 'generated by prek' in p.read_text() else 'not installed')"
Running prek
prek run --all-files
- It auto-fixes many issues; if a run reports changed files, run it again (some first-run
failures are already fixed).
- Fix issues by hand only when a run reports no file changes but still fails.
- It only scans git-tracked files —
git add new files first.
What the toolchain enforces
Each hook is driven by a config file at the repo root:
| Config file | Tool | Enforces |
|---|
ruff.toml | Ruff | Code style and linting |
mypy.ini | mypy | Static type checking |
.complexipy.toml | complexipy | Code complexity limits |
.rumdl.toml | rumdl | Markdown linting |
.ryl.toml | ryl | YAML linting |
typos.toml | typos | Spelling |
