GitHub - liblaf/copier-python: 🐍 Copier template for Python packages with uv, nox, MkDocs, typed src layout, and PyPI release automation

🐍 What Is `copier-python`?

copier-python is the Python layer in the liblaf Copier stack. It turns the shared repository and release foundations into a typed Python package with source layout, docs, tests, benchmarks, generated reference pages, and PyPI publishing through GitHub OIDC.

The generated files live under template/. The README that generated projects receive is template/README.md.jinja.

✨ What You Get

📦 PEP 621 package metadata, Hatchling builds, Hatch VCS versioning, and a src/ layout with py.typed.
🧰 uv dependency groups for build, docs, lint, nox, and tests.
🧪 A noxfile.py that discovers supported Python versions and runs highest plus lowest-direct dependency resolutions.
📚 Zensical, MkDocs Material, mkdocstrings, Read the Docs, and generated API reference pages.
📈 GitHub Actions for tests, coverage, benchmark sessions, docs deployment, and Python release publishing.
🔁 Copier answer files and update workflows that let generated repositories keep the stack refreshed.

🚀 Apply The Template

After applying the shared and release layers, add the Python layer:

copier copy --trust gh:liblaf/copier-python .

To refresh an existing generated repository:

copier recopy --trust --answers-file '.config/copier/.copier-answers.python.yaml'

🧱 Template Stack

🧰 gh:liblaf/copier-shared: repository hygiene, shared automation, editor settings, and project metadata.
🏷️ gh:liblaf/copier-release: release PRs, changelog generation, tags, GitHub Releases, and publish orchestration.
🐍 gh:liblaf/copier-python: Python packaging, docs, tests, benchmarks, and PyPI workflow wiring.

🚢 Release Workflow

In a generated project, the default release flow is:

Push commits using Conventional Commits.
release-pr.yaml opens a release PR with the changelog and next version.
Merge the release PR, or approve it and let mergery[bot] merge it when checks pass.
release-publish.yaml creates the tag and publishes the GitHub Release from the merged release PR.
The published GitHub Release triggers python-release.yaml, which builds the package, publishes to PyPI with OIDC, and uploads distributions as release assets.

This flow assumes immutable GitHub Releases are disabled for generated repositories, so release assets can be attached after the release is published.

🛠️ Post Setup

📚 Read the Docs

Import the generated repository at https://app.readthedocs.org/dashboard/import/ and keep stable as the default version. The generated template/.readthedocs.yaml installs with uv, builds with zensical build, and publishes the generated site/ directory.

📦 PyPI Trusted Publishing

Create a trusted publisher at https://pypi.org/manage/account/publishing/ for the generated repository and point it at .github/workflows/python-release.yaml. The workflow uses GitHub OIDC, so it does not need a long-lived PyPI API token.

🤝 Contributing

Edit files under template/ for generated output, and edit mise-tasks/ for helper behavior used by generated projects. Keep commit messages in Conventional Commit format so the release stack can produce clean changelogs.

🔗 More Copier Templates

Shared - ✨ Automated code quality, repository hygiene, and project-wide defaults for the rest of the template stack.
Release - 🚀 Release PRs, changelog generation, tags, GitHub Releases, and publishing automation.
Python - 🐍 Python packaging, docs, tests, benchmarks, and PyPI workflow wiring.
Rust - 🦀 Rust project template with modern tooling and CI/CD.
TypeScript - 🚀 TypeScript project template with modern runtime, tooling, and release automation.