python-copier-template

TL;DR

Prerequisites: uv (its uvx shim runs copier) and git. Both commands below expand this fork's newest release tag, so no revision flag is needed:

python-copier-template new my-project --preset library   # the shipped CLI, from a clone of this repo: picks the release, renders, records the answers
uvx copier copy --trust https://github.com/kasi-x/python-copier-template.git my-project   # or drive copier directly

An opinionated copier template for Python projects: create a new project from it, update existing projects in line with it, and keep them in sync as it changes. One questionnaire covers libraries, web APIs, CLIs, data-science pipelines, competitive programming, ROS 2 packages and MicroPython firmware — and its logic is machine-verified (Z3 satisfiability over every question path) rather than only documented.

What you get

Each area of the questionnaire first asks "use the recommended settings?" (default: yes), so the recommended path is usually a single keystroke:

• Eight project types — library, web_api, cli, data_science, online_judge, script, ros2, micropython, each with its own layout, CI and docs.
• A toolchain of your choice — uv, pixi or poetry; just, Task, poethepoet, Make, pyinvoke, duty or pixi's native tasks; zensical, Sphinx or great-docs.
• Quality gates — ruff (ALL rules), basedpyright + pyrefly, typos, vulture, deptry, pip-audit, pytest + coverage + hypothesis, hardened CI with pinned actions, SECURITY.md and OpenSSF Scorecard.
• Opt-in layers — the data-science layout, a FastAPI service, MCP servers, chat bots (Discord / Slack / LINE / Gmail), polite web scraping, CTF tooling, cloud providers and Sentry.
• Field rules, not vibes — every generated project ships an AGENTS.md agent guide plus an ethics/regional appendix matched to the project kind: dependency-license drift, post-quantum crypto standards, AI-and-copyright, PKI trust chains, personal data, EU CRA duties, medical-device software, face recognition, ML fairness and LLM/MCP security. Sections are registered, dated and enforcement-graded (_shared/ethics/), held to the renders by invariants, and machine-readable through the template's MCP server (check_ethics, template://ethics).

The feature catalogue walks through all of it, the questionnaire reference lists every question, and the support tiers reference says which combinations CI executes end to end. For the comparison with the upstream template and the alternatives, see Vision & Positioning; the template in action is the example project.

Create a new project

The shipped CLI is the recommended path. It runs from a clone of this repository, picks the release to expand, decides between creating a project and adopting an existing one, and reports the files the target already has:

git clone https://github.com/kasi-x/python-copier-template.git
uv run --project python-copier-template python-copier-template new my-project --preset library

--preset library answers the one question that defines the project family (cli, web-api, data-science, ros2, micropython and online-judge-atcoder also exist); drop it and copier asks the whole questionnaire instead, which needs a terminal.

Without a preset you can also drive copier directly, which is all the CLI wraps. --trust is required: the template runs post-generation tasks (the adoption report, the next-steps hint and the REUSE LICENSES/ copy), and without it copier generates nothing and exits with status 4:

git init --initial-branch=main /path/to/my-project
uvx copier copy --trust https://github.com/kasi-x/python-copier-template.git /path/to/my-project

Both paths expand this fork's newest release tag; Create a new project covers the flags, the presets, adoption and pinning an exact release, and generating a project non-interactively covers --defaults with an answers file for CI. For the inverse question — you know the features you want, not the answers that produce them — task answers-for -- --require <name>=<value> searches the verified answer space (the same page's Tell the template what you want).

Everyday commands

The generated project drives lint, type-check, test and docs through the task runner you chose (just by default; task, poe, invoke, duty, make or pixi's native tasks are the alternatives — one shared task definition, invoked by CI too). Swap task for your runner; the task names are the same:

task lint        # ruff format --check + ruff check (check-only)
task fix         # ruff --fix + format (typos stays report-only in type-check)
task type-check  # basedpyright + pyrefly, vulture, deptry, typos
task test        # pytest, with coverage at the recommended strictness
task docs        # build the documentation site
task check       # lint + type-check + test

task audit and task license-check need the network and so stay out of check.

Where to go next

• Documentation site — the full docs, in tutorials, how-to guides, explanations and reference, starting from the docs index.
• New here — the installation tutorial and create a new project.
• Already have a repo — adopt this template into it, or update an existing project that already uses it.
• Template internals — authoring template sources, the structure, how a change is verified and how the template catches rot with no code changes.

License, contributing and releases

Licensed under Apache-2.0. This repository is the template's own source (not a generated project): source · docs site · releases, whose notes are generated by git-cliff from the tag's conventional commits (CHANGELOG.md). Contributions are welcome — see CONTRIBUTING.md, the contributing how-to and GOVERNANCE.md; report vulnerabilities as described in SECURITY.md.