Browse 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 adds packaging, typed source layout, documentation, testing, benchmarking, and PyPI publishing on top of the shared repository and release foundations.

Important

This template depends on gh:liblaf/copier-shared and gh:liblaf/copier-release. Apply the stack in that order: shared → release → python.

If you want the real source of truth for generated files, start in template/. This repository README documents the template itself; the generated project README comes from template/README.md.jinja.

✨ What You Get

• 📦 A modern Python package layout under src/, including py.typed, version stubs, and lazy-loader-friendly package exports.
• ⚙️ A pyproject.toml wired for PEP 621 metadata, uv dependency groups, Hatchling builds, and Hatch VCS versioning.
• 🧪 A noxfile.py with multi-version test sessions, dependency resolution variants, and optional benchmark sessions.
• 📚 Docs scaffolding with Zensical, MkDocs Material, mkdocstrings, GitHub-friendly Markdown, and Read the Docs configuration.
• 🚀 Release automation that fits the rest of the liblaf Copier stack, including changelog generation, draft releases, and PyPI publishing through OIDC.
• 🔁 Copier-friendly update paths so the generated repository can be refreshed later without redoing the whole setup by hand.

🚀 Apply The Template

After applying the shared and release templates, add the Python layer with:

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

🔄 Update The Template

To refresh the Python layer in an existing repository:

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

The generated repository usually keeps separate Copier answers files for each layer, so scheduled update workflows can refresh the whole stack over time.

🧱 Template Stack

• 🧰 gh:liblaf/copier-shared: repository hygiene, common automation, editor settings, and shared project metadata.
• 🏷️ gh:liblaf/copier-release: release PRs, changelog generation, Git 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 looks like this:

1. Push commits using Conventional Commits.
2. release-pr.yaml creates a release PR with the changelog and updated version.
3. Merge the release PR yourself, or approve it and let mergery[bot] merge it once the button is green.
4. release-draft.yaml creates a draft release.
5. python-release.yaml builds the package, publishes it to PyPI with GitHub OIDC, and uploads release assets to the draft release.
6. release-publish.yaml publishes the draft release after 6 hours so the release jobs have enough time to finish.

🛠️ Post Setup

📚 Read the Docs

1. Visit https://app.readthedocs.org/dashboard/import/.
2. Follow the prompts to import the generated repository.
3. Configure these settings:

Location	Value
Setup > Settings > Default version	stable
Setup > Settings	Enable Build pull requests for this project
Setup > Addons > Analytics	Enable
Setup > Addons > Link previews	Enable
Building > Pull request builds	Enable Build pull requests for this project
Building > Pull request builds	Enable Show build overview in a comment

4. Add this automation rule:

Field	Value
Description	Semantic Versioning
Match	SemVer versions
Version type	Tag
Action	Activate version

📦 PyPI Trusted Publishing

1. Visit https://pypi.org/manage/account/publishing/.
2. Create a trusted publisher for the generated repository.
3. Point it at the GitHub Actions release workflow created by this template stack.

This template publishes with GitHub OIDC, so you do not need a long-lived PyPI API token.

🤝 Contributing

To improve the template, edit the files under template/ and the small helper files around it, then keep commit messages in Conventional Commits format so the release automation can do its job cleanly.

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