python-template

A batteries-included Python project template powered by Copier. Pick the features you need, skip the ones you don't.

Quickstart

Requires: uv and just

uvx copier copy --trust gh:namitdeb739/python-template my-project
cd my-project

Copier prompts for your project name, author details, and feature choices. Answer the questions (or hit Enter for defaults) and you're done.

To auto-fill author info from your git/GitHub config:

uvx copier copy --trust gh:namitdeb739/python-template my-project \
  --data author_name="$(git config user.name)" \
  --data author_email="$(git config user.email)" \
  --data github_user="$(gh api user --jq .login)"

Features

All features are opt-in or opt-out at generation time:

Option	Default	What it adds
ci_github	true	GitHub Actions workflows: lint, type-check, test (3.11–3.13), audit
security	basic	none · basic (pre-commit, ruff) · full (+ CodeQL, pip-audit, Dependabot)
testing	standard	minimal (pytest) · standard (+ coverage + fixtures) · full (+ 80% threshold)
use_typecheck	true	mypy strict type checking
use_docs	true	MkDocs Material site with GitHub Pages auto-deploy
use_docker	cpu	none · cpu (Dockerfile + Compose) · gpu (+ GPU variant)
use_devcontainer	false	VS Code / Codespaces dev container
use_ml	false	Notebooks dir, data dir, optional ML deps, DVC, .env template
use_iot	false	IoT/embedded setup: serial, GPIO, MQTT drivers, device config, mock fixtures
use_cli	false	Typer CLI scaffold: commands, --help, rich output
use_api	false	FastAPI REST API scaffold: routes, health endpoint, uvicorn serve
use_db	false	SQLAlchemy 2 + Alembic: database session, migrations

To skip all prompts and get the standard setup:

uvx copier copy --trust --defaults gh:namitdeb739/python-template my-project \
  --data author_name="$(git config user.name)" \
  --data author_email="$(git config user.email)" \
  --data github_user="$(gh api user --jq .login)"

What's included

Tooling: uv · ruff · mypy · pytest · pre-commit · just

CI/CD: lint, type-check, test matrix, dependency audit, Conventional Commits enforced on commits and PR titles, trusted-publisher PyPI release

Optional: CodeQL · Dependabot · MkDocs Material · Docker (CPU + GPU) · DVC

After scaffolding

just check                      # verify lint + type-check + tests all pass
just init-remote                # create GitHub repo, push, configure branch protection + Pages
just init-remote visibility=private  # or keep the repo private

init-remote uses the project name and GitHub username you entered during setup — no manual substitution needed. Requires gh CLI to be authenticated (gh auth login).

Keeping up to date

Pull in improvements from this template at any time:

uvx copier update --trust

License

MIT