python-package-copier-template

python-package-copier-template#

python-package-copier-template is a template for creating and maintaining modern Python packages with a batteries-included baseline: current packaging practices, updated tooling, CI/CD automation, documentation scaffolding, and conventions that work well for both humans and code agents.

It is implemented as a Copier template and also published as a small Python CLI wrapper, so the most common entrypoint is:

$ uvx python-package-copier-template [PATH_TO_PROJECT] Copying from template version 0.4.3.post5.dev0+3d0ee32     create  AGENTS.md     create  .copier-answers.yml     create  CONTRIBUTING.md     create  .github     create  .github/FUNDING.yml     create  .github/workflows     create  .github/workflows/cd.yml     create  .github/workflows/ci.yml     create  .github/workflows/template-update.yml     create  README.md     create  LICENSE     create  .gitignore     create  CODE_OF_CONDUCT.md     create  tests     create  tests/conftest.py     create  tests/test_cli.py     create  Makefile     create  pyproject.toml     create  src     create  src/demo_project     create  src/demo_project/__main__.py     create  src/demo_project/py.typed     create  src/demo_project/__init__.py     create  docs     create  docs/CONTRIBUTING.md     create  docs/conf.py     create  docs/_static     create  docs/_static/.gitkeep     create  docs/CODE_OF_CONDUCT.md     create  docs/index.md     create  docs/about_the_docs.md     create  docs/configuration.md     create  docs/getting_started.md     create  docs/development_workflow.md

The docs build runs that example non-interactively with defaults in a temporary directory. The command shown is the general entrypoint, and the capture is one concrete example of it. The wrapper decides whether to run copier copy or copier update by inspecting the destination directory for a Copier answers file. If you want the details of how the wrapper resolves template versions and source locations, see CLI Reference. If you prefer the raw Copier commands, or want the latest development version from GitHub, the details are in Getting Started.

A public example generated from the template lives at mgaitan/yet-another-demo. It is useful both as a smoke target and as a concrete reference for what the scaffold looks like in practice.

What this template includes#

  • A modern Python package baseline targeting Python 3.12+.

  • Dependency and environment management with uv.

  • Linting and formatting with Ruff.

  • Type checking with ty.

  • Testing with pytest, coverage, and related extensions.

  • Optional QA orchestration and git hook setup with prek.

  • Sphinx documentation written in Markdown with MyST.

  • GitHub Actions workflows for CI, docs publishing, template refreshes, and PyPI releases.

  • An AGENTS.md starter so code agents have project-specific guidance from day one.

  • Optional GitHub repository bootstrapping with GitHub CLI.

  • Generated projects that remain updatable with copier update.

The broader rationale for these choices is described in the original blog post: My opinionated scaffolding for modern Python projects.

Contents