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 ➜ mise run 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. Supports PAT or GitHub App authentication via the renovate_auth_method variable. See the Renovate setup guide for detailed instructions.

  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
• pre-commit (if not installed check pre-commit installation guide)
• 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, 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:

audit                      Check dependencies for known vulnerabilities.
build                      Build source and wheel distributions.
check-all                  Run all quality checks.
check-quality              Run linters and format checks.
check-security             Run security analysis with Bandit.
check-types                Run static type checks.
clean-all                  Delete build artifacts.
clean-cache                Remove cache files.
coverage                   Generate coverage reports (text, HTML, XML).
dc                         Run docker compose with Doppler-mounted .env.
docker-build               Build Docker images.
docker-shell               Open a shell in a service container.
docker-start               Start Docker Compose services.
docker-stop                Stop and remove Docker Compose services.
docs-check                 Check if the documentation builds correctly.
docs-deploy                Publish docs to GitHub Pages.
docs-serve                 Serve the documentation (localhost:8080).
doppler-create-config      Create a new Doppler branch config.
doppler-create-token       Create a Doppler service token for this directory.
doppler-delete-config      Delete a Doppler branch config.
doppler-set-token          Configure a preexisting Doppler service token.
doppler-upload-secrets     Upload a local .env file to Doppler.
format                     Auto-format code (Ruff).
mise-setup-completions     Install mise shell completions for the current shell.
pre-commit                 Run all pre-commit hooks on all files.
publish                    Upload distributions to PyPI.
release                    Automate version bump, changelog, and publish.
setup-cli                  Install the project's CLI globally via uv.
setup-dev                  Bootstrap dev environment & install pre-commit hooks.
setup-prod                 Set up the project environment.
test                       Run tests with pytest.
tox                        Run tests across multiple Python versions.
upgrade                    Upgrade all dependencies to latest compatible 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
renovate_auth_method	Renovate auth method (pat or github_app)	pat
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.