Explore the template files »

Changelog · Template Files · Report Bug · Request Feature

🐍 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.

Important

Apply gh:liblaf/copier-shared, then gh:liblaf/copier-release, then this template. The Python layer reads shared answers from .config/copier/.copier-answers.shared.yaml.

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:

1. Push commits using Conventional Commits.
2. release-pr.yaml opens a release PR with the changelog and next version.
3. Merge the release PR, or approve it and let mergery[bot] merge it when checks pass.
4. release-publish.yaml creates the tag and publishes the GitHub Release from the merged release PR.
5. 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.

---

📝 License

Copyright © 2024 liblaf.
This project is MIT licensed.