README.md

Python Template

---

A consistent, feature-rich template for Python projects. Use this as a starting point for new packages to get batteries-included tooling out of the box.

What's Included

Feature	Tool
Build & environments	Hatch with hatch-pip-compile
Linting & formatting	Ruff
Testing	pytest + coverage
Type checking	mypy
Documentation	MkDocs Material + mkdocstrings
Containerization	Multi-stage Dockerfile (dev / hatch / prod)
CI/CD	GitHub Actions with Dependabot
Dev environment	Dev Container for VS Code / Codespaces
Git hygiene	pre-commit hooks

Quick Start

Installation

pip install python-template

CLI

The template ships with an example CLI entry point:

python-template --version
python-template example "hello world"

As a Library

from python_template import example

result = example("hello")

Development Setup

Prerequisites: Python 3.9+ and Hatch.

git clone https://github.com/LavLabInfrastructure/python-template.git
cd python-template
pip install hatch

Optionally install pre-commit hooks:

pip install pre-commit
pre-commit install

Common Commands

Run these directly or use the provided Makefile shortcuts (e.g. make test, make lint).

Task	Command
Run tests	hatch run test:test
Tests + coverage	hatch run test:cov
Lint	hatch run lint:check
Format	hatch run lint:format
Auto-fix lint	hatch run lint:fix
Format + fix + lint	hatch run lint:all
Type check	hatch run types:check
Build docs	hatch run docs:build-docs
Serve docs	hatch run docs:serve-docs
Build wheel	hatch build
Clean artifacts	make clean

Docker

# Run tests via Docker
docker build --target hatch -t myapp:hatch .
docker run --rm -e HATCH_ENV=test myapp:hatch cov

# Production image (just the installed wheel)
docker build --target prod -t myapp:prod .

Project Structure

python-template/
├── src/
│   └── python_template/        # Package source
│       ├── __init__.py          # Public API & version export
│       ├── __about__.py         # Version string
│       ├── cli.py               # CLI entry point (thin wrapper)
│       ├── example.py           # Example library module
│       └── py.typed             # PEP 561 marker
├── tests/
│   ├── conftest.py              # Shared pytest fixtures
│   └── test_example.py          # Example tests
├── docs/                        # MkDocs source files
├── requirements/                # Locked deps (auto-generated by hatch-pip-compile)
├── .devcontainer/               # Dev container config
├── .github/
│   ├── workflows/               # CI workflows (build, test, lint)
│   └── dependabot.yml           # Auto-update deps + actions + Docker
├── pyproject.toml               # All project & tool configuration
├── Dockerfile                   # Multi-stage build
├── Makefile                     # Dev shortcuts
├── mkdocs.yml                   # Docs config
├── .pre-commit-config.yaml      # Pre-commit hooks
├── .editorconfig                # Editor consistency
└── .gitignore

Design Philosophy

This template follows a library-first approach:

1. All logic lives in importable modules under src/python_template/.
2. The CLI (cli.py) is a thin argparse wrapper that delegates to library functions.
3. Tests call library functions directly — never through the CLI.

This keeps your code reusable whether it's called from the command line, another package, a notebook, or an API.

Using This Template

1. Click Use this template on GitHub (or clone and reinitialize).
2. Rename src/python_template/ to your package name.
3. Find-and-replace python-template → your project name and python_template → your package name.
4. Update pyproject.toml with your metadata (author, description, dependencies).
5. Update LICENSE.txt if needed.
6. Delete example.py and test_example.py once you have real code.

Contributing

See CONTRIBUTING.md for development guidelines.

License

python-template is distributed under the terms of the MIT license.