A quick reference to every tool used in this project — what it does, where
it's configured, and where to learn more.
Why this file exists: Template users may not be familiar with all the
tools bundled in this repo. This page gives a one-line explanation of each
tool and a link to its docs so you can learn at your own pace.
Build & Environments
| Tool |
What it does |
Config |
Docs |
| Hatchling |
Builds Python packages (sdist + wheel) from source. This is the build backend — it runs when you pip install . or hatch build. |
pyproject.toml → [build-system] |
Hatchling docs |
| Hatch |
Manages virtual environments, runs scripts, and orchestrates builds. This is the project manager — it creates envs, installs deps, and runs commands like hatch run test. |
pyproject.toml → [tool.hatch.*] |
Hatch docs |
| hatch-vcs |
Derives the package version from git tags at build time. No manual version bumping needed. |
pyproject.toml → [tool.hatch.version] |
hatch-vcs docs |
| Task |
A task runner that wraps hatch run commands into shorter aliases like task test. Optional convenience layer. |
Taskfile.yml |
Taskfile docs |
How these layers relate: See command-workflows.md
for a visual breakdown of task test → hatch run test → pytest.
Code Quality
| Tool |
What it does |
Config |
Docs |
| Ruff |
Lints and formats Python code. A single Rust binary that replaces flake8, isort, black, pyupgrade, and more. |
pyproject.toml → [tool.ruff] |
Ruff docs |
| mypy |
Static type checker. Catches type errors without running your code. Runs in strict mode in this project. |
pyproject.toml → [tool.mypy] |
mypy docs |
| typos |
Finds spelling mistakes in source code, docs, and filenames. Rust-based, very fast. |
_typos.toml |
typos docs |
| codespell |
Another spellchecker that runs in CI as a safety net alongside typos. |
CLI args in spellcheck.yml |
codespell docs |
| deptry |
Checks for unused, missing, and transitive dependencies by comparing pyproject.toml against actual imports. |
pyproject.toml → [tool.deptry] |
deptry docs |
Testing
| Tool |
What it does |
Config |
Docs |
| pytest |
Test framework. Discovers and runs tests in tests/. Supports fixtures, parametrize, markers, and a huge plugin ecosystem. |
pyproject.toml → [tool.pytest.ini_options] |
pytest docs |
| pytest-cov |
Coverage plugin for pytest. Measures which lines are executed during tests and generates reports. |
pyproject.toml → [tool.coverage] |
pytest-cov docs |
Security
| Tool |
What it does |
Config |
Docs |
| Bandit |
Static security linter for Python. Finds common security issues like hardcoded passwords, shell=True, unsafe YAML loading. |
pyproject.toml → [tool.bandit] |
Bandit docs |
| pip-audit |
Checks installed packages against vulnerability databases (OSV, PyPI). The PyPA-maintained successor to safety. |
— (scans the environment) |
pip-audit docs |
| gitleaks |
Scans git history and staged changes for secrets (API keys, tokens, passwords). Runs as a pre-push hook. |
.gitleaks.toml (if present) |
gitleaks docs |
| CodeQL |
GitHub's semantic code analysis engine. Finds security vulnerabilities via deep static analysis. Runs in CI. |
security-codeql.yml |
CodeQL docs |
| OpenSSF Scorecard |
Evaluates repository security practices (branch protection, dependency pinning, etc.). Runs in CI. |
scorecard.yml |
Scorecard docs |
Git Hooks
Documentation
| Tool |
What it does |
Config |
Docs |
| MkDocs |
Static site generator for project documentation. Writes docs in Markdown, builds an HTML site. |
mkdocs.yml |
MkDocs docs |
| Material for MkDocs |
Theme for MkDocs with search, dark mode, admonitions, tabs, and more. |
mkdocs.yml → theme: |
Material docs |
| mkdocstrings |
Generates API reference docs from Python docstrings. Auto-renders function signatures and descriptions. |
mkdocs.yml → plugins: |
mkdocstrings docs |
CI/CD & Release
| Tool |
What it does |
Config |
Docs |
| GitHub Actions |
CI/CD platform. Runs workflows on push, PR, schedule, or manual trigger. This project has 36 workflows. |
.github/workflows/*.yml |
Actions docs |
| release-please |
Automates versioning and changelog generation from Conventional Commits. Creates a Release PR that you review and merge. |
release-please-config.json |
release-please docs |
| Dependabot |
Automatically opens PRs to update outdated or vulnerable dependencies. |
.github/dependabot.yml |
Dependabot docs |
Container
| Tool |
What it does |
Config |
Docs |
| Podman / Docker |
Builds and runs OCI container images. The project uses a Containerfile (same syntax as Dockerfile). |
Containerfile, docker-compose.yml |
Podman docs |
| Trivy |
Scans container images for vulnerabilities. Runs in CI. |
.github/workflows/container-scan.yml |
Trivy docs |
| Grype |
Scans container images for vulnerabilities using a different DB than Trivy. Provides complementary coverage. |
.github/workflows/container-scan.yml |
Grype docs |
Link Checking
| Tool |
What it does |
Config |
Docs |
| lychee |
Checks Markdown and HTML for broken links. Rust-based, async. Runs in CI via link-checker.yml. |
.github/workflows/link-checker.yml |
lychee docs |
Config Validation
| Tool |
What it does |
Config |
Docs |
| Prettier |
Formats Markdown, YAML, and JSON files. Runs as a manual pre-commit hook and VS Code default formatter. |
.pre-commit-config.yaml |
Prettier docs |
| markdownlint-cli2 |
Lints Markdown files for style and structure issues. Runs as a manual pre-commit hook. |
.markdownlint-cli2.jsonc |
markdownlint-cli2 docs |
| hadolint |
Lints Dockerfiles/Containerfiles for best practices. Runs as a manual pre-commit hook. |
.pre-commit-config.yaml |
hadolint docs |
See Also