T-8Q23-python-runtime-doc-additions
Status: closed/obsoleted · Impact: low · Complexity: small
Two drafted tasks each propose a single-paragraph addition to
plugin/conventions/python-runtime.md: (1) the canonical uv test invocation that authors should
use for libraries under plugin/lib/, and (2) a warning + _cli resolution rule for scripts under
plugin/scripts/<name>/ that share a name with a package under plugin/lib/<name>/. Both edits
land in the same file in adjacent sections; shipping as 2 PRs means duplicated review of the
surrounding doc. This task merges them. The 2 originating drafts are superseded by this task.
| Location | Role today |
|---|---|
plugin/conventions/python-runtime.md | Documents the canonical Python runtime conventions for the plugin (uv self-bootstrapping PEP-723 shebangs, _cli suffix convention, lib/scripts separation). Missing: the canonical test-invocation recipe for plugin/lib/<name>/tests/, and an explicit warning about script/lib name collisions and the _cli resolution. |
plugin/lib/lease/, plugin/lib/fpid/ | Existing libraries with co-located tests. Each has informal uv run pytest … recipes in its own README or test-runner; none of these is the canonical project-wide pattern. |
plugin/scripts/sdlc_lease.py | Concrete instance of the _cli suffix in active use — the script is named sdlc_lease.py so it doesn’t collide with the plugin/lib/lease/ package. Worked example for the warning. |
Proposed
Section titled “Proposed”plugin/conventions/python-runtime.md gains two short subsections:
1. Library test recipe. A canonical uv run pytest plugin/lib/<name>/tests/ (or whatever the
project actually uses — verify against the existing test invocations) form, plus a note on how to
run a single test file or filter. Single paragraph.
2. Script/library name-collision warning. A short subsection naming the rule (“a script under
plugin/scripts/<name>.py and a library at plugin/lib/<name>/ will collide at import time”), the
failure mode (mysterious ImportError or wrong-module-imported), and the _cli suffix as the
conventional resolution (plugin/scripts/<name>_cli.py next to plugin/lib/<name>/). One worked
example.
The 2 originating drafts close as closed/superseded once this PR lands.
Approach
Section titled “Approach”- Read the current
plugin/conventions/python-runtime.mdto understand its existing structure and tone. - Survey the actual test-invocation patterns used by existing
plugin/lib/<name>/tests/(run a couple, see what works; pick the simplest canonical form). - Identify the natural sub-section anchor for each addition. The test recipe likely lives near the
existing PEP-723 / uv discussion; the name-collision warning lives near the existing
_clisuffix discussion. - Write both additions as concise prose. Each is one paragraph plus one code block plus (for the warning) one worked-example reference.
- Close the 2 originating drafts with
completion_notepointing here.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/conventions/python-runtime.md | modify | Add two short subsections: canonical library test recipe; script/lib name-collision warning with _cli resolution. |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1:
plugin/conventions/python-runtime.mdcontains a subsection that names the canonicaluv-based test invocation for libraries underplugin/lib/<name>/tests/, with at least one runnable example. - AC-2:
plugin/conventions/python-runtime.mdcontains a subsection that names the script/library name-collision rule, the failure mode, and the_clisuffix as the conventional resolution. - AC-3: The subsection includes at least one worked example demonstrating the collision rule and
its
_cli-suffixed resolution. - AC-4: A grep for
plugin/scripts/<name>directories that duplicate aplugin/lib/<name>name returns zero matches (asserted by a short check script underplugin/scripts/, or noted as a future addition if no enforcement is in scope). - AC-5: The 2 superseded originating drafts (T-HHYG-python-runtime-doc-uv-test-recipe,
T-1JAO-python-runtime-doc-warns-script-lib-name-collision) have
completion_notepointing to this task; their status isclosed/superseded.
Out of scope
Section titled “Out of scope”- Enforcing the conventions automatically (lint check that no
plugin/scripts/<name>collides withplugin/lib/<name>). AC-4 names it as a future addition; that’s a separate task if/when it grows past “grep returns zero matches today.” - Refactoring existing tests to the canonical recipe. The doc names the pattern; existing tests stay where they are unless they’re already broken.
- Adding a
pyproject.toml/uv.lockergonomics section. Out of scope; the existing PEP-723 discussion is sufficient for the convention.
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”Spawned 2026-05-28 from a consolidation audit. Two drafts (T-HHYG-python-runtime-doc-uv-test-recipe, T-1JAO-python-runtime-doc-warns-script-lib-name-collision) each propose a single-paragraph addition to the same file in adjacent sections. Merging into one PR cuts review overhead without changing the substance.
The superseded drafts: