T-HHYG-python-runtime-doc-uv-test-recipe

Status: closed/superseded · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

The plugin/lib/ convention established by T-75LX-establish-plugin-lib-convention sets up pytest.ini pythonpath so that from lease import ... resolves in tests — but it doesn’t pin the actual shell command for running those tests. On a fresh contributor’s shell, pytest plugin/lib/lease/tests/ fails because pytest isn’t on PATH, and python3 -m pytest reports “no module named pytest” because the mise-managed interpreter lacks it. The working invocation is uv run --with pytest --with pydantic pytest ... but the convention doc doesn’t say so. Cite T-S0PK-add-lease-protocol-library-and-schemas for the wall. Adding the canonical recipe to python-runtime.md saves the next contributor the same 10 minutes of trial-and-error.

Today

Location	Role today
plugin/conventions/python-runtime.md	Documents the plugin/lib/ layout and the pytest.ini pythonpath bootstrap. Does NOT document the shell command for running library tests.
pytest.ini	Sets pythonpath = plugin/lib. Doesn’t address interpreter / dependency provisioning.

Proposed

plugin/conventions/python-runtime.md gains a “Running library tests” section with the canonical uv run --with pytest --with <runtime-deps> pytest <library>/tests/ recipe, a one-line rationale (mise-managed interpreters won’t have pytest pre-installed; uv handles ephemeral deps), and a worked example for the lease library.

Approach

1. Read the current python-runtime.md to find the right insertion point (after the pytest.ini section).
2. Add a “Running library tests” subsection with the canonical command and the rationale.
3. Add a worked example: uv run --with pytest --with pydantic pytest plugin/lib/lease/tests/.

Files to touch

Location	Kind	Change
plugin/conventions/python-runtime.md	modify	Add the “Running library tests” section with the canonical uv-flavored command.

Acceptance criteria

• AC-1: plugin/conventions/python-runtime.md contains a “Running library tests” section with the canonical uv run --with pytest --with <deps> pytest recipe and a one-line rationale.
• AC-2: The section includes at least one worked example referencing a real library under plugin/lib/ (e.g. the lease library).

Out of scope

• Introducing a justfile recipe (e.g. just test-lib lease). Worth considering separately; not blocking this doc fix.
• Pinning specific dependency versions in the recipe. uv run --with resolves to current pins; that’s intentional for a doc example.

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-S0PK-add-lease-protocol-library-and-schemas on 2026-05-23.

Dedup search (spawn-from-post-mortem)

Bullet: Pytest invocation surface. pytest plugin/lib/lease/tests/ fails on fresh shell because pytest isn’t on PATH and python3 -m pytest reports no module named pytest. Working invocation is uv run —with pytest —with pydantic pytest. Add canonical uv-flavored test command for libraries to plugin/conventions/python-runtime.md. Keywords searched: python-runtime, uv-flavored, conventions, invocation, canonical, libraries, pydantic, surface Excluded: 2026-05-23-add-lease-protocol-library-and-schemas Top candidates (score / status / headline):

• 34 / closed/done / 2026-05-23-establish-plugin-lib-convention — Establish plugin/lib/ convention for Python libraries
• 19 / planning/draft / 2026-05-23-add-sdlc-lease-cli-commands — Add sdlc lease CLI commands
• 15 / closed/done / 2026-05-20-sdlc-yaml-json-schema-and-validator — Add JSON Schema + validator for sdlc.yaml
• 14 / closed/done / 2026-05-19-schema-bump-tasks-handle-missing-version — Schema-bump task template enumerates the missing-schema_version case explicitly
• 14 / closed/done / 2026-05-20-orchestrator-categorized-in-flight-limits — Replace orchestrator parallelism cap with categorized in-flight limits configurable in sdlc.yaml Decision: SPAWNED

---

← Back to Tasks