Reproducible Python project contract
First classify the repository:
| Project |
Build system |
Installation expectation |
| Application/non-package |
Usually none; optionally tool.uv.package = false |
Sync dependencies, do not invent a distributable package. |
| Library/package |
Explicit [build-system] and package layout |
Build and inspect wheel plus sdist. |
| Workspace |
Root membership plus member metadata |
One shared lock; run member-specific commands deliberately. |
Workflow
- Inspect existing
pyproject.toml, uv.lock, Python constraint, source
layout, build backend, dependency groups/extras, tool configuration, CI, and
current commands before changing anything.
- Preserve the declared project type. Do not add a build system merely to make
an application look like a package.
- Put runtime dependencies in
[project.dependencies], optional consumer
features in [project.optional-dependencies], and development tools in
[dependency-groups]. Keep environment markers explicit.
- Use
uv add/remove or an intentional metadata edit followed by uv lock.
Commit uv.lock for reproducible projects; never edit it manually.
- Use
uv sync for an exact project environment and uv run for commands.
In CI or verification, use --locked so stale metadata fails rather than
silently updating the lock.
- Configure one canonical quality pipeline: Ruff check and format, Pyright,
pytest, and build inspection when the project is distributable.
- For a package, run
uv build, inspect sdist/wheel contents and metadata,
install the wheel into a clean environment, then import and exercise its
public entry point.
Invariants
pyproject.toml declares intent; uv.lock records resolution; .venv is
generated state and is not committed.
- A passing editable install is not proof that the built wheel contains the
package or data files.
- Extras are consumer-selectable features; dependency groups are development
or task environments. Do not use one as the other.
- Never invoke publishing or handle registry tokens without explicit authority.
- Preview uv features and tool schemas are version-sensitive; inspect installed
help and current official docs before encoding them.
uv lock --check
uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pyright
uv run --locked pytest
uv build
Use project and dependency layout, quality and build
verification, and migration safeguards.
1---2name: python-project-tooling3description: >-4 Use for creating, reviewing, debugging, or modernizing Python project5 structure and deterministic tooling with pyproject.toml, uv, dependency6 groups, lockfiles, Ruff, Pyright, pytest, build backends, wheels, sdists, or7 workspaces. Do not use for application architecture, publishing credentials,8 arbitrary pip command help, or code changes unrelated to project tooling.9argument-hint: "[project type, Python support, dependencies, checks, and packaging goal]"10metadata:11 source: https://skillmd.com/skills/schattenspiegel/python-project-tooling12---1314# Reproducible Python project contract1516First classify the repository:1718| Project | Build system | Installation expectation |19|---|---|---|20| Application/non-package | Usually none; optionally `tool.uv.package = false` | Sync dependencies, do not invent a distributable package. |21| Library/package | Explicit `[build-system]` and package layout | Build and inspect wheel plus sdist. |22| Workspace | Root membership plus member metadata | One shared lock; run member-specific commands deliberately. |2324## Workflow25261. Inspect existing `pyproject.toml`, `uv.lock`, Python constraint, source27 layout, build backend, dependency groups/extras, tool configuration, CI, and28 current commands before changing anything.292. Preserve the declared project type. Do not add a build system merely to make30 an application look like a package.313. Put runtime dependencies in `[project.dependencies]`, optional consumer32 features in `[project.optional-dependencies]`, and development tools in33 `[dependency-groups]`. Keep environment markers explicit.344. Use `uv add`/`remove` or an intentional metadata edit followed by `uv lock`.35 Commit `uv.lock` for reproducible projects; never edit it manually.365. Use `uv sync` for an exact project environment and `uv run` for commands.37 In CI or verification, use `--locked` so stale metadata fails rather than38 silently updating the lock.396. Configure one canonical quality pipeline: Ruff check and format, Pyright,40 pytest, and build inspection when the project is distributable.417. For a package, run `uv build`, inspect sdist/wheel contents and metadata,42 install the wheel into a clean environment, then import and exercise its43 public entry point.4445## Invariants4647- `pyproject.toml` declares intent; `uv.lock` records resolution; `.venv` is48 generated state and is not committed.49- A passing editable install is not proof that the built wheel contains the50 package or data files.51- Extras are consumer-selectable features; dependency groups are development52 or task environments. Do not use one as the other.53- Never invoke publishing or handle registry tokens without explicit authority.54- Preview uv features and tool schemas are version-sensitive; inspect installed55 help and current official docs before encoding them.5657```text58uv lock --check59uv sync --locked60uv run --locked ruff check .61uv run --locked ruff format --check .62uv run --locked pyright63uv run --locked pytest64uv build65```6667Use [project and dependency layout](references/projects.md), [quality and build68verification](references/verification.md), and [migration safeguards](references/migration.md).