Skip to content

simple-python-boilerplate

A minimal Python boilerplate using the src/ layout, configured with Hatch as the build system. Fork it, run python scripts/customize.py, and start building.

Features

  • src/ layout — clean separation between source code and project root (ADR 001).
  • Hatch — modern build backend and environment manager (ADR 016).
  • pytest — testing framework with coverage support, multi-version matrix (ADR 006).
  • Ruff — fast linting and formatting (ADR 005).
  • mypy — strict static type checking (ADR 007).
  • MkDocs + Material — documentation with auto-generated API reference.
  • 45 pre-commit hooks — across 4 stages: pre-commit, commit-msg, pre-push, manual (ADR 008).
  • 36 GitHub Actions workflows — all SHA-pinned, with repository guard pattern (ADR 004, ADR 011).
  • Security scanning — Bandit, pip-audit, CodeQL, Trivy, Gitleaks, Dependency Review, OpenSSF Scorecard (ADR 012).
Resource Description
Getting Started Installation and local development
Using This Template Customizing the boilerplate for your project
Development Guide Developer tools and workflows
Command Reference All task / hatch / script commands in one place
API Reference Auto-generated from source docstrings
Architecture System overview and module responsibilities
ADRs Architecture Decision Records
Workflows GitHub Actions inventory
Tooling All repo tools at a glance
Troubleshooting Common issues and fixes
Security Policy Vulnerability reporting and tooling
Learning Notes Concepts and tool comparisons from building
Resources (Links) Curated external links and further reading
Resources (Written) Self-written references and cheat sheets

Project layout

src/
  simple_python_boilerplate/
    __init__.py       # Package root, version export
    api.py            # HTTP/REST interface (placeholder)
    cli.py            # CLI argument parsing (argparse)
    engine.py         # Core business logic (TypedDicts)
    main.py           # Entry points (console scripts)
    dev_tools/        # Development utilities (clean, etc.)
tests/                # Test suite (unit + integration)
docs/                 # Documentation source (this site)
scripts/              # Utility scripts (bootstrap, clean, doctor, git_doctor, etc.)
db/                   # Database schema, migrations, seeds, queries
experiments/          # Scratch files for exploration (not packaged)
.github/
  workflows/          # 36 GitHub Actions workflows (SHA-pinned)
  ISSUE_TEMPLATE/     # Issue form templates
pyproject.toml        # Project configuration (single source of truth)
Taskfile.yml          # Task runner shortcuts
Containerfile         # Multi-stage container build
mkdocs.yml            # Documentation site config

See Repo Layout for the full annotated directory tree.