A Copier template for Python projects. Projects created from it can pull in later
template changes with copier update.
uvfor dependencies andjustas the command runner- ruff, ty, codespell, actionlint, and markdownlint for linting
- pytest with coverage, Zensical docs with an API reference generated from docstrings
- pip-audit, betterleaks, and zizmor for security checks
- prek git hooks, GitHub Actions CI, Dependabot, Release Drafter, and a release workflow
- A VS Code dev container
See template/README.md.jinja for the commands and workflows a generated project gets.
Requires uv. Copier asks for the project name, package name, description, and GitHub
owner/repo.
uvx copier copy --trust gh:ahcodedev/python-project-template my-project--trust lets Copier run the template's post-create task (uv lock). New projects use the latest template release.
From the project folder, with a clean git working tree:
uvx copier update --trustCopier compares the template release the project was created from (_commit in .copier-answers.yml) with the
latest release and applies only the template's changes, keeping your edits. Conflicts are marked for you to resolve,
like a git merge. Don't edit .copier-answers.yml by hand after it's created.
Projects created before the template used Copier have no .copier-answers.yml. To connect one:
-
Add
.copier-answers.ymlto the project root with the project's real values._commitmust bev1.0.0(or a later release), the first release with Copier support:# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY _commit: v1.0.0 _src_path: gh:ahcodedev/python-project-template description: My project github_repo: someone/my-project package_name: my_project project_name: my-project
package_namemust match the project'ssrc/<package>/folder. -
Optional catch-up: Copier now assumes the project matches
v1.0.0. To pick up template changes the project missed before that, runuvx copier recopy --trust --vcs-ref v1.0.0on a clean working tree, reviewgit diff, and keep what you want. -
Commit. From then on,
uvx copier update --trustworks as usual.
copier.yml- template questions and settingstemplate/- the files copied into new projects. Only files ending in.jinjaare rendered (the suffix is removed), so GitHub Actions${{ }}expressions in other files are left alone. Folder names can use placeholders too (template/src/{{ package_name }}/).github/- CI, security, and release workflows for this template repositoryprek.toml- git hooks for this repository (prek installto enable)
Commands (requires uv and just; install just with brew install just, then run just setup):
just setup- install Homebrew tools from theBrewfilejust render- render a demo project into_rendered/demo-projectfrom the current template, including uncommitted changesjust check- render the demo project and run its lint, tests, docs build, pip-audit, and zizmor (used in CI)just actionlint- lint the root and template GitHub workflowsjust zizmor- audit the root and template GitHub workflows for security issuesjust betterleaks- scan staged changes for secrets with betterleaksjust prek- run the git hooks on staged files
Template releases use the same label-based Release Drafter flow as generated projects (see the Releases section of
template/README.md.jinja). The Release workflow publishes the draft and tags it vX.Y.Z.
Copier uses these tags as template versions, so changes merged to main reach projects only after a release.