Modern Python package template

A Copier template for modern Python projects.

Canonical example repo generated from this template: mgaitan/yet-another-demo

Documentation: https://mgaitan.github.io/python-package-copier-template/

Features

• 🐍 Modern Python package supporting Python 3.12-3.15
• 📦 Build and dependency management with uv, split by groups (dev/qa/docs)
• 🧊 Dependency cooldowns enabled by default in uv ([tool.uv].exclude-newer = "1 week"), with targeted overrides when needed (for example ty) to reduce supply-chain risk without blocking QA tools
• 🛡️ uv malware checks enabled in Make targets and GitHub Actions to reject locked dependencies with known malicious-package advisories
• 🧹 Linting and formatting via Ruff with a broad set of rules enabled
• ✅ Type checking via ty
• 🪝 Optional pre-commit style QA orchestration via prek as an external tool (uv tool install prek; hooks include check-ast, check-yaml, check-toml, Ruff, Ty)
• 🧪 Tests with pytest, coverage.py and extensions
• 📚 Docs with Sphinx, MyST and a few extensions, deployed to GitHub Pages
• 👀 Automatic docs preview deployment for PRs that modify documentation (/_preview/pr-<PR_NUMBER>/ on GitHub Pages)
• 🧭 Generated docs follow Diataxis and document rationale in about_the_docs
• 🏗️ Use of GitHub CLI for autotic project creation
• ⚙️ CI workflow on GitHub Actions
• 🚀 Automated releases to PyPI via Trusted Publishing
• 🧠 Sensible defaults via introspection to minimize answers during the initial setup
• 🛠️ Makefile with shortcuts for common tasks
• 📄 Generation of generic docs such as CODE_OF_CONDUCT, plus an optional LICENSE
• 🤖 Heavily curated AGENTS.md
• 🌀 Initial setup of the development environment and git repo
• 🔁 Scheduled template refresh workflow that opens a PR every 20 days when updates are available
• ♻️ Projects updatable with copier update

Please read my blog post to learn about the details of the decisions I made and the alternatives I considered.

Quick setup and usage

Quick shortcut (auto-detects copy vs update):

uvx python-package-copier-template [PATH_TO_PROJECT]

This runs copier copy --defaults --unsafe to PATH_TO_PROJECT (or . if omitted) when no .copier-answers.yml is present, or copier update --defaults --unsafe when it is. Check the installed version with uvx python-package-copier-template --version. When installed from PyPI, the wrapper copies from the matching template release instead of always using main.

If you want the latest development version straight from this repository instead of the latest published release, use:

uvx git+https://github.com/mgaitan/python-package-copier-template [PATH_TO_PROJECT]

You can check that wrapper version with uvx git+https://github.com/mgaitan/python-package-copier-template -- --version.

Start a new project explicitly with Copier if you want to bypass the wrapper:

uvx --with=copier-template-extensions copier copy --trust "gh:mgaitan/python-package-copier-template" /path/to/your/new/project

To upgrade an existing project created from this template to the latest version, run:

uvx --with=copier-template-extensions copier update . --trust 

This fetches the latest template version and guides you through updating your project. Existing README.md and docs/** files are left untouched so project-specific documentation is not replaced. New documentation files are still added when the template introduces them; adopt later changes to existing pages manually from the template diff when they are relevant to your project.

The generated project also ships a Template Update GitHub Actions workflow that runs every 20 days (or on manual dispatch) to execute uvx copier update --trust --defaults . and open a pull request with the changes and template version bump.

To test a local development version of the template, clone the repository and run:

uv sync
uv run copier copy --trust  --vcs-ref=HEAD . /path/to/your/test/project

If you create the GitHub repository via the gh CLI prompt, the template will attempt to enable immutable releases and GitHub Pages (using the Actions build type). Immutability protects assets and tags for future releases. If Pages is unavailable (for example, with some private repositories or account policies), the docs workflow will keep failing until Pages is allowed.

To publish a release of your project to PyPI, you need to register the project with trusted publishing. Read more about how this workflow works here.

This repository's own release workflow also refreshes the demo repository after a successful publish. That step requires the DEMO_REPO_TOKEN GitHub Actions secret, documented in Configuration.

Then

$ make bump    # optional
$ make release

Acknowledgement

This project template started as a fork of pawamoy/copier-uv. Then I simplified and changed it to fit my needs.