python-project-template

A reusable, uv-managed starting point for Python projects. Clone it, rename the app package, and you have dependency management, linting, formatting, type checking, tests, and CI wired up from the first commit.

What's inside

Path	Purpose
pyproject.toml	Project metadata, dependencies, and tool config (ruff, mypy, pytest). Single source of truth.
uv.lock	Fully resolved, committed lockfile for reproducible installs.
.python-version	Pins the interpreter uv provisions (3.11).
src/app/	The package, using a src/ layout so tests run against the installed code.
tests/	pytest suite.
Makefile	Self-documenting task runner — run make help.
.github/workflows/ci.yml	Lint, format, type check, and test on every push/PR.

Requirements

Only uv — it manages the Python interpreter and the virtual environment for you. No global pip, venv, or requirements.txt.

Quick start

make setup     # create the .venv and install everything from uv.lock
make check     # lint + format check + type check + tests
make run       # run the app entry point

Run make help to see every target (core tasks in cyan, utilities in yellow).

Common tasks

make add PKG=httpx            # add a runtime dependency
make add PKG="--dev pytest-cov"  # add a dev dependency
make lock                     # refresh uv.lock after editing pyproject.toml
make lint-fix                 # auto-fix lint issues
make format                   # format the code
make clean                    # remove caches and build artifacts

Making it yours

1. Rename src/app/ and update the [project] name and [project.scripts] entry in pyproject.toml.
2. Run make lock to regenerate the lockfile.
3. Replace this README and the sample greet/main code.

License

MIT