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

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.

• 📦 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.

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'

• 🧰 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.

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.

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.

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.

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.

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

Copyright © 2024 liblaf.
This project is MIT licensed.