python-template-uv

A modern, batteries‑included Copier template for bootstrapping Python packages and applications managed with uv

🚀 Features

• Copier-powered scaffolding: Effortlessly generate or update projects with one command.

• Task runner integration: Project tasks are defined in a mise.toml file. The Makefile is a simple wrapper that proxies commands to mise run for convenience. Run tasks with make <task> (e.g. make check-all, make docs-serve) or directly with mise run <task>.

• Quality & standards

  • Formatting and Linting: Ruff ➜ make format & make check-quality
  • Type checking: Mypy ➜ make check-types
  • Pre-commit hooks: pre-commit

• Testing & coverage

  • pytest ➜ make test
  • Coverage (text, HTML, XML) ➜ make coverage
  • Compatibility testing for multiple versions of Python with Tox and its plugin tox-uv ➜ make tox

• Documentation

  • MkDocs with mkdocs-material theme
  • Live server: make docs-serve (serves on localhost:8080)
  • Deploy to GitHub Pages: make docs-deploy

• Release & changelog

  • Conventional Commits + Commitizen + gitmoji
  • Automated CHANGELOG.md updates
  • Release new versions ➜ make release

• Docker & Docker Compose

  • Generate Dockerfile + compose.yaml for deployment and compose.override.yaml for development overrides (hot-reload, exposed ports, GPU support)
  • Docker targets: make docker-build, make docker-start, make docker-stop

• Optional features

  • Typer CLI scaffold
  • Strict typing (py.typed marker for type checking)
  • Run tests with parallel execution via pytest-xdist
  • Settings & configuration with Pydantic Settings + Doppler integration for secure secret management

• CI/CD Workflows

  This template includes GitHub Actions workflows for continuous integration, testing, and release automation:

  • PR Commenting (pr-thank-you.yaml): Posts a fun GIPHY comment on new pull requests using docker-action-pr-giphy-comment. Requires a GIPHY_API_KEY repository secret. To obtain one, sign up at GIPHY Developers, create an app, and copy the API key. Then add it to your repository:

    • CLI: gh secret set GIPHY_API_KEY and paste the key when prompted
    • Web UI: Go to repo Settings → Secrets and variables → Actions → New repository secret, name it GIPHY_API_KEY, and paste the key

  • CI/CD Pipeline (main.yaml.jinja):

    • Checks: Linting (Ruff), type checking (Mypy), documentation build.
    • Tests: Runs pytest across supported Python versions using a matrix strategy.
    • Releases: Automatically publishes releases when a Git tag is pushed.
    • Docs Deployment: Deploys MkDocs documentation to GitHub Pages.
    • Package Publishing (optional): Publishes the package to PyPI if publish_to_pypi is enabled and PYPI_TOKEN is set.

  • Dependency Updates (optional): Choose between Dependabot or self-hosted Renovate via the dependency_updater template variable.

    • Dependabot (dependabot.yml): Opens weekly PRs to keep GitHub Actions dependencies up to date.

    • Renovate (renovate.yaml + renovate.json5): Self-hosted via GitHub Actions. Updates all dependencies (Python packages, pre-commit hooks, GitHub Actions, lock files) with smart grouping and automerge. Requires a RENOVATE_TOKEN repository secret containing a fine-grained PAT. To create one:

      1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
      2. Set a token name, expiration, and under Repository access select the target repo
      3. Under Permissions, grant: Contents: Read and write, Pull requests: Read and write, Workflows: Read and write, and Issues: Read-only
      4. Click Generate token and copy it

      Then add it to your repository:

      • CLI: gh secret set RENOVATE_TOKEN and paste the token when prompted
      • Web UI: Go to repo Settings → Secrets and variables → Actions → New repository secret, name it RENOVATE_TOKEN, and paste the token

  These workflows are generated into .github/workflows/ in the scaffolded project. You can customize them further as needed.

🛠 Prerequisites

• Python ≥ 3.10
• Copier ≥ 9.14.0
• copier-templates-extensions ≥ 0.3.2
• uv (if not installed check uv installation guide)
• mise (if not installed check mise installation guide)

🎉 Quickstart

# 1. Scaffold a new project

# Option 1: Use uvx to run Copier with extensions
uvx --with copier-templates-extensions copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project

# Option 2: Install Copier globally
uv tool install copier --with copier-templates-extensions

# Then run
copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project

# Notes:
# • copier.yaml automatically runs `git init`, so `--trust` is required
# • Add `--prereleases` to include pre-release versions
# • Add `--vcs-ref=HEAD` to use the latest commit

# 2. Enter your project
cd /path/to/my-project

# 3. Set up development environment and hooks
make setup-dev

# 4. (Optional) Install your CLI globally via uv
make setup-cli

# 5. Run quality & tests
make check-all   # runs all checks: lint, types, docs build, API, etc.

Stay up to date

cd /path/to/my-project

uvx copier update --trust --exclude src/ --exclude tests/ .

Warning

To be able to update your project, do not delete or manually modify the generated .copier-answers.yml file.

📋 Available Tasks

All tasks are defined in mise.toml and exposed through make. Common tasks include:

build                      Build source and wheel distributions.
check                      Check it all!
docs-check                 Check if the documentation builds correctly.
check-quality              Run linters and format checks.
check-types                Run static type checks.
clean-all                  Delete build artifacts.
clean-cache                Remove cache files.
coverage                   Generate coverage reports (text, HTML, XML).
docker-build               Build Docker images.
docker-start               Start Docker Compose services.
docker-stop                Stop and remove Docker Compose services.
docs-serve                 Serve the documentation (localhost:8080).
docs-deploy                Publish docs to GitHub Pages.
format                     Auto-format code (Ruff).
publish                    Upload distributions to PyPI.
release                    Automate version bump, changelog, and publish.
setup                      Bootstrap prod environment.
setup-cli                  Install the project's CLI globally via uv.
setup-dev                  Bootstrap dev environment & install pre-commit hooks.
test                       Run tests with pytest.
tox                        Run tests across multiple Python versions.

For the full list and details, see mise.toml.

🔧 Template Variables

When running copier, you’ll be prompted for:

Variable	Description	Default
project_name	Your project’s name (lowercase, letters/digits/dashes)	—
project_description	A short summary of what your project does	—
author_fullname	Your full name	from git
author_email	Your email address	from git
repository_provider	Where you host your repo (github or other)	github
homepage	Project homepage URL	https://<user>.github.io/<proj>
python_version	Default Python interpreter for development	3.12
min_python_version	Minimum supported Python version	3.10
with_typer_cli	Include a Typer CLI scaffold?	false
with_strict_typing	Enable strict typing (py.typed marker)?	false
with_settings	Include Pydantic Settings for configuration?	true
with_doppler	Add Doppler integration for secrets management?	false
tox	Include Tox configuration?	true
coverage_threshold	Minimum test coverage %	100
with_conventional_commits	Enforce Conventional Commits?	true
cz_gitmoji	Include emojis in commit messages?	true
dockerfile	Generate Dockerfile and Compose file?	true
dependency_updater	Dependency update tool (none, dependabot, or renovate)	renovate
gpus	Enable GPU support in Docker builds?	false

See the full list in copier.yaml.

📄 License

This project is released under the MIT License. See LICENSE for details.