python-template

Copier template for Python projects with uv, ruff, ty, pytest, just, and GitHub Actions CI.

What's included

Tool	Purpose
uv	Package management, virtualenv, Python installs
just	Task runner (just check runs everything)
ruff	Linting and formatting
ty	Type checking
pytest	Testing with coverage
GitHub Actions	CI on push/PR to main
pre-commit	Git hooks for ruff + ty on commit
Codecov	Coverage reporting

Usage

With copier (recommended)

Auto-populates project name, author, package name, etc:

uv tool install copier
copier copy --trust gh:aligfellow/python-template my-new-project
cd my-new-project
just setup && just check

The --trust flag is required because the template runs git init and creates an initial commit automatically.

Then create a GitHub repo and push:

gh repo create my-new-project --public --source=. --push

Or if you prefer to create the repo on GitHub first:

git remote add origin git@github.com:your-user/my-new-project.git
git push -u origin main

As a GitHub template

Plain file copy — you rename things manually:

1. Click "Use this template" on this repo page, or:

   gh repo create my-new-project --template aligfellow/python-template --public --clone
   

2. Rename src/{{ package_name }}/ to your actual package name
3. Update name, description, authors, and homepage in pyproject.toml
4. Update source in [tool.coverage.run] to match your package name
5. Update LICENSE with your name and year

What you get

my-new-project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── cli.py          # if include_cli=true
├── tests/
│   ├── __init__.py
│   └── test_import.py
├── .github/workflows/
│   └── ci.yml
├── pyproject.toml           # ruff, ty, pytest, coverage config
├── justfile                 # check/lint/type/test/fix/build/setup
├── .pre-commit-config.yaml  # ruff on commit
├── CITATION.cff             # if include_citation=true
├── .gitignore
├── LICENSE
└── README.md

Copier questions

Question	Default
project_name	—
package_name	derived from project name
description	—
author	Alister S. Goodfellow
github_user	aligfellow
year	2026
python_version	3.12
ci_python_version	3.14
include_cli	false
include_citation	false

Updating existing projects

If a project was created with copier copy, pull in template improvements with:

copier update --trust

--trust is required because the template defines tasks (used for git init on first copy). The tasks don't run during update, but copier requires trust for any template that declares them.

Codecov setup

For repo, go to codecov.io. Navigate to the desired repository and activate it under Configuration > General. Copy the CODECOV_TOKEN and add as a repository secret on github under Settings > Secrets and variables > Actions, naming the secret CODECOV_TOKEN.

License

MIT