python-project

Scaffold a Python project

Creates a Python repository with the src/ layout, uv-managed dependencies, pinned developer tooling, and a Makefile gate. Apply the python-style, python-typing, and python-testing skills while filling in real code, and wire releases with the python-release skill.

1. Initialize with uv

uv is the only tool for interpreters, virtual environments, dependencies, locking, building, and publishing — do not reach for pip, pipenv, poetry, conda, pyenv, or pipx alongside it.

uv init --package myapp   # packaged app with a CLI entry point and [build-system]
uv init --lib myapp       # importable library (same src/ layout, no console script)

Both flavors produce the src/ layout and a [build-system]; the bare uv init (flat, no build system) is only for throwaway scripts. uv writes pyproject.toml and src/myapp/, and the first uv sync/uv run writes the uv.lock you commit.

2. Lay out the tree

pyproject.toml
uv.lock              # committed — the reproducible, cross-platform resolution
.python-version      # pins the interpreter uv provisions for `uv run`
README.md            # referenced by `readme` in pyproject.toml
src/myapp/__init__.py
src/myapp/__main__.py
tests/
Makefile

• src/ layout, never flat. Tests run against the installed package, so a missing __init__.py or a packaging mistake fails locally instead of being masked by an import-from-cwd. Copy templates/python-version to .python-version.
• One module per concern, named for what it provides (store, client, config) — never utils, common, or helpers.

3. Configure pyproject.toml on the uv_build backend

Copy templates/pyproject.toml. The choices that matter:

• [build-system] uses uv's native backend — requires = ["uv_build>=0.11.21,<0.12"], build-backend = "uv_build". It is fast and needs no configuration for the src/ layout; the upper bound keeps builds reproducible as the backend evolves.
• requires-python is the floor (>=3.13); .python-version pins the interpreter used during development. Runtime dependencies use lower bounds (>=), never == — uv.lock does the exact pinning.
• The [tool.ruff], [tool.ty.environment] (or [tool.pyright]), and [tool.pytest.ini_options] blocks ship in the same file; their rationale lives in the python-style, python-typing, and python-testing skills.