Skip to content

Latest commit

 

History

History
112 lines (85 loc) · 3.43 KB

README.md

File metadata and controls

112 lines (85 loc) · 3.43 KB

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