Skip to content

Introduction

A copier-based template for Python packages.

Features

  • 📦 Package management:
    • Develop with your preferred tools (extras, uv or Hatch).
    • Automatic changelog generation from emoji-typed commit messages.
    • Build your package with Hatch.
  • 🧹 Pre-commit: Format and lint your code with Ruff.
  • 🧪 Tests: Write tests with pytest, with optional coverage reporting (basic summary or Codecov integration).
  • 📚 Documentation: Write docs in MyST or MkDocs.
  • ⚙️ GitHub Actions:
    • Deploy documentation to GitHub Pages or Read the Docs.
    • Run pre-commit checks, commit-message linting, and tests on every pull request.
    • Publish to PyPI on vX.Y.Z tags via Trusted Publishing — no API tokens.
    • Optional automatic template updates via a bot.

Usage

Follow the copier installation instructions. Then simply run

copier copy https://github.com/mbercx/python-copier <package_name>

And answer the questions to generate a new Python package.

Next steps

After copying the template, you might still have to do some additional configuration.

Publish to PyPI

The generated package ships with a cd.yaml workflow that publishes to PyPI on vX.Y.Z tag pushes via Trusted Publishing. See Publishing to PyPI for the one-time setup steps.

You don't have to publish right away, but if you care about the project name, push an early 0.0.1 release to claim it on PyPI before someone else does.

Deploy documentation

Read the Docs

  1. Push your code to GitHub.
  2. Go to Read the Docs (RTD) and import your project. The build will use the included .readthedocs.yaml automatically.
  3. Set the RTD settings to build from GitHub pull requests.

Coverage with Codecov

If you selected coverage=codecov when generating, the CI workflow uploads coverage data to Codecov after every test run. To get this working:

  1. Sign up at codecov.io and connect your GitHub account.
  2. Add your repository on the Codecov dashboard — it will start receiving uploads automatically.

No repository secret is needed for public repos. For private repos, add a CODECOV_TOKEN secret to your repository and pass it in the workflow's codecov-action step.

Repository URL

Several files in the generated package reference the source repository URL: the docs site (GitHub icon + link), [project.urls] in pyproject.toml, the README badges, and commit links in the generated changelog. The URL is controlled by the hidden repo_url question, which is empty by default so the template works without a remote.

Once you have created the remote repository, set it via:

copier update -A -d repo_url=https://github.com/<user>/<repo>

The -A flag (--skip-answered) skips questions you already answered, so only repo_url is applied. To change the URL later, run the same command with the new value.

Automatic template updates

The template can optionally add a copier-update.yaml workflow that checks for upstream template changes every week, runs copier update, and opens a PR with the proposed changes. This feature is controlled by the hidden auto_update question (set via --data auto_update=<value> when copying or updating):

  • none (default) — no workflow is added.
  • github-token — uses the default GITHUB_TOKEN. Zero setup, but PRs created this way won't trigger other CI workflows.
  • pat — uses a Personal Access Token stored as a COPIER_UPDATE_TOKEN repository secret. PRs will trigger CI normally.

To enable it on an existing project, run:

copier update --data auto_update=github-token