Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/catalog/.python-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
3.13
16 changes: 16 additions & 0 deletions modules/catalog/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,22 @@ Holds the tools a neighbour is willing to lend in their neighbourhood.

## Known traps

- **`--locked` says nothing about `uv run --with`.** A package given with `--with` is
resolved in a layer of its own, outside `uv.lock`, and what it pulls in floats from one run
to the next with no refusal. A package a verb needs goes in a dependency group of
`pyproject.toml`, then `uv lock`, and the verb runs `--group <name>`. A pin changed without
`uv lock` is refused by every verb that runs `uv run`, and `uv` names the fix — not by
`check`, which runs ruff through `uvx` and never reads the lock.

- **`test`, `e2e` and `bootstrap` run `--exact`.** Without it `uv run` installs what is missing
and never removes an extraneous package, so in CI, where the verbs share one environment, a
verb would pass on a package only another group brings, and fail on a workstation that runs
it first.

- **`.python-version` holds the charter's Python, 3.13 (C2).** `requires-python` only sets a
floor: without the pin, a runner whose own Python is below it gets the newest one `uv` can
download — CI ran 3.14.7 while workstations ran 3.13.

- **`src/` is not on `sys.path` under `uv run`.** This `pyproject.toml` declares no
`[build-system]`, so uv treats the project as non-packaged and never installs it:
`python -m contract_double` fails with *No module named contract_double*, while `pytest`
Expand Down
8 changes: 4 additions & 4 deletions modules/catalog/MANIFEST.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,18 +57,18 @@ dependencies: []
# whatever a workstation leaves in it.
commands:
check: "uvx --from ruff==0.16.8 ruff format --check src tests e2e && uvx --from ruff==0.16.8 ruff check src tests e2e"
test: "uv run --with pytest==9.1.1 pytest"
test: "uv run --locked --exact --group test pytest"
# D1's scenarios read the contract and call the double built from it; D2's drive this
# module - the page in a browser at a phone's width, and the contract answered by the
# module itself. Playwright is the charter's e2e driver (C2); the browser arrives with D2,
# and bootstrap downloads it.
e2e: "uv run --group e2e pytest e2e"
e2e: "uv run --locked --exact --group e2e pytest e2e"
# Playwright's browser, installed as a package and never as an action (charter, C2). CI
# runs this before check, test and e2e; a workstation runs it once per clone.
bootstrap: "uv run --group e2e playwright install chromium"
bootstrap: "uv run --locked --exact --group e2e playwright install chromium"
# The page, on its own SQLite file. PYTHONPATH because this project declares no
# [build-system], so uv never puts src/ on sys.path - see AGENTS.md, known traps.
run: "PYTHONPATH=src uv run python -m catalog.app"
run: "PYTHONPATH=src uv run --locked python -m catalog.app"

# Review budget. Inherited from the project when absent (docs/os/05-workflow.md §4).
review_budget:
Expand Down
4 changes: 2 additions & 2 deletions modules/catalog/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ address**, which is a no-go of the charter and an invariant of this module.

```bash
cd modules/catalog
PYTHONPATH=src uv run python -m catalog.app [database] [port]
PYTHONPATH=src uv run --locked python -m catalog.app [database] [port]
```

This is the command the `run` verb and the scenarios both use, so it is checked on every run
Expand All @@ -56,7 +56,7 @@ publishing is something a neighbour does, not something another module does.

```bash
cd modules/catalog
uv run --group e2e python src/contract_double.py ../../contracts/catalog-api/v1/openapi.yaml 8000
uv run --locked --group e2e python src/contract_double.py ../../contracts/catalog-api/v1/openapi.yaml 8000
```

This is the command the `e2e` scenarios use to start it, so it is checked on every run
Expand Down
9 changes: 7 additions & 2 deletions modules/catalog/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,14 @@ dependencies = [
"python-multipart==0.0.32", # what Starlette reads a submitted form with
]

# What the e2e verb needs, and nothing else needs. Pinned: a scenario that answers
# differently from one run to the next is evidence of nothing.
# What the test and e2e verbs need, and the page does not. Pinned, and resolved in uv.lock
# with everything else: `uv run --with` would resolve outside the lock, where what the pins
# pull in floats. A scenario that answers differently from one run to the next is evidence
# of nothing.
[dependency-groups]
test = [
"pytest==9.1.1",
]
e2e = [
"pytest==9.1.1", # 9 is what schemathesis 4 requires
"playwright==1.63.0", # the charter's e2e driver (C2); its browser arrives with D2
Expand Down
2 changes: 1 addition & 1 deletion modules/catalog/src/catalog/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

Start it from the module folder, exactly as `README.md` says — and as the scenarios do:

PYTHONPATH=src uv run python -m catalog.app [database] [port]
PYTHONPATH=src uv run --locked python -m catalog.app [database] [port]
"""

from __future__ import annotations
Expand Down
2 changes: 1 addition & 1 deletion modules/catalog/src/contract_double.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@

Start it from the module folder, exactly as `README.md` says — and as the scenarios do:

uv run --group e2e python src/contract_double.py <openapi document> [port]
uv run --locked --group e2e python src/contract_double.py <openapi document> [port]
"""

from __future__ import annotations
Expand Down
Loading
Loading