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] warning:Malware checks are experimental and may change without warning. Pass  `--preview-features malware-check` to disable this warning. Copying from template version 0.6.0.post1.dev0+89c1af1     create  .copier-answers.yml     create  .github     create  .github/workflows     create  .github/workflows/cd.yml     create  .github/workflows/ci.yml     create  .github/workflows/template-update.yml     create  .github/FUNDING.yml     create  tests     create  tests/test_cli.py     create  tests/conftest.py     create  .python-version     create  CONTRIBUTING.md     create  CODE_OF_CONDUCT.md     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  AGENTS.md     create  .gitignore     create  docs     create  docs/configuration.md     create  docs/getting_started.md     create  docs/CONTRIBUTING.md     create  docs/CODE_OF_CONDUCT.md     create  docs/_static     create  docs/_static/.gitkeep     create  docs/development_workflow.md     create  docs/conf.py     create  docs/index.md     create  docs/about_the_docs.md     create  Makefile     create  README.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.

The canonical 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.