Make the Python client test suite runnable and document how to run it

[dmccoystephenson]

Summary

• pytest.ini's pythonpath is pointed at the repository root. The previous value listed the package directories themselves, which supports preponderous.viron... imports, whereas the client source and all eight test modules import through src.main.python.preponderous.viron... — so every test module failed collection with ModuleNotFoundError: No module named 'src'. Of the two ways out described in pytest fails to collect the Python client tests: pytest.ini's pythonpath does not match the tests' import style #201, the root was chosen deliberately: the alternative (rewriting the imports to preponderous.viron...) would have to change the client's own internal imports too, and that is the path external consumers import by, so it is an API decision rather than a test-configuration one. testpaths is also pinned so a bare pytest run picks up only the client suite.
• environmentService.get_all_environments is annotated with typing.List instead of the builtin generic list[Environment], matching all three sibling services. Builtin generics in annotations are evaluated when the class body runs and are not subscriptable before Python 3.9, so EnvironmentService could not be imported at all on 3.8 and test_environmentService.py could not be collected.
• The README's Testing section now documents the client suite, its Python and dependency requirements, why the root is on the path, and that CI covers the Java build only. The project-structure listing gains src/test/python/.

Test plan

• mvn -B test — 424 tests, 0 failures, 0 errors, BUILD SUCCESS
• pytest (pytest 9.0.3) — 107 passed
• python3 -m pytest (Python 3.8.10, pytest 7.1.3) — 107 passed, confirming the annotation fix on the lowest interpreter available here
• Regression evidence for pytest fails to collect the Python client tests: pytest.ini's pythonpath does not match the tests' import style #201: with pytest.ini stashed, pytest reports Interrupted: 8 errors during collection; restored, 107 pass
• Regression evidence for environmentService's get_all_environments uses a builtin generic annotation the rest of the client avoids, breaking Python 3.8 #204: with environmentService.py stashed, python3 -m pytest reports TypeError: 'type' object is not subscriptable collecting test_environmentService.py; restored, 107 pass. Note this failure is only observable on Python 3.8 — on 3.9+ the reverted annotation is valid, so the suite alone does not guard it.

Notes on the rest of the backlog

Deferred this cycle, with reasons recorded here per the loop's auditability rule:

• moveEntityToLocation's collision check is a read-then-write race the database cannot settle #203 (moveEntityToLocation's read-then-write race) — the issue's own acceptance criteria are gated on a design decision that is not the loop's to make: whether one-entity-per-location is meant to be a real invariant of the data or a rule of that one endpoint. addEntityToLocation currently ignores occupancy entirely, so either answer implies changes beyond the reported endpoint. A conditional-write fix (option 3) is implementable without settling that question and is the recommended next step once the question is answered.
• Wire OpenAPI-first codegen / spec-drift guard (rebuild-plan hygiene gap) #130 (OpenAPI-first codegen / spec-drift guard) — build and CI infrastructure touching pom.xml and .github/workflows/, both on the do-not-auto-merge list, and larger than a polish-sized PR.

CI runs ./mvnw compile and ./mvnw test only, so a green run does not exercise any file changed here except by proving the Java build is unaffected; the Python verification above was performed locally.

Closes #201
Closes #204

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric, scored against the diff at 29853d6 and the command output named in each line. Items are scored FAIL unless direct evidence of PASS was produced.

• CI (external anchor): PASS — gh pr checks 205 --watch reports build pass on the current head. Scope caveat: the CI workflow runs ./mvnw compile -B and ./mvnw test -B only, so it exercises none of the three files changed here; what it proves is that the Java build is unaffected. The Python verification below was run locally and is the real anchor for this PR. That structural gap is now filed as CI does not run the Python client test suite, so client regressions are caught only by hand #207.
• Scope: FAIL, then fixed — the first push also added testpaths = src/test/python to pytest.ini, which was not needed for either issue. pytest -q -o "testpaths=" collects the same 107 tests without it, so the line changed nothing measurable and was removed in b3b8fe3. Re-scored PASS: the remaining diff is one path setting, one annotation plus its import, and the README.
• Tests-new: PASS by inapplicability — no public method or function is added. get_all_environments, whose annotation changed, is already exercised by test_environmentService.py:20, :181, and :199.
• Tests-fix (empirical): PASS — git stash push -- pytest.ini makes pytest report Interrupted: 8 errors during collection, and restoring it returns 107 passed. git stash push -- src/main/python/.../environmentService.py makes python3 -m pytest (Python 3.8.10, pytest 7.1.3) report TypeError: 'type' object is not subscriptable while collecting test_environmentService.py, and restoring it returns 107 passed. Stated plainly: the second failure is observable only below Python 3.9 — on 3.9+ the reverted annotation is legal, so the suite by itself does not guard environmentService's get_all_environments uses a builtin generic annotation the rest of the client avoids, breaking Python 3.8 #204 unless CI runs a 3.8 interpreter.
• Sibling structure: PASS by inapplicability — no new file is created.
• Sibling renames: PASS — grep -rn "list\[" src/main/python/ now returns nothing, so all four services annotate list returns with typing.List consistently.
• Docs: PASS — the Phase 7 sweep was run over every source of truth. docs/openapi/viron-api.json, docs/MVP.md, docs/PLANNING.md, docs/REBUILD_PLAN.md, tickets.md, and postman/ contain no reference to Python, pytest, or the client's import path (grep -rn -i python across docs/, tickets.md, and .github/ matches nothing), and no endpoint, DTO, or schema is touched by this diff. README.md is the only affected doc and is updated.
• Issue resolution: PASS with one deliberate exclusion — pytest fails to collect the Python client tests: pytest.ini's pythonpath does not match the tests' import style #201's core claim (the pythonpath/import-style mismatch) is fixed, and environmentService's get_all_environments uses a builtin generic annotation the rest of the client avoids, breaking Python 3.8 #204's named annotation is changed. pytest fails to collect the Python client tests: pytest.ini's pythonpath does not match the tests' import style #201 additionally muses that this is "worth resolving alongside a decision about whether CI should run the Python suite at all"; that aside is not resolved here and is filed as CI does not run the Python client test suite, so client regressions are caught only by hand #207 rather than left implied, so closing pytest fails to collect the Python client tests: pytest.ini's pythonpath does not match the tests' import style #201 does not quietly absorb it.
• DTO boundary / Spec alignment / Java-Python parallelism / Override correctness: PASS by inapplicability — no Java file, controller, endpoint, or DTO is touched. The annotation change has no Java counterpart, since the Java side already returns List<EnvironmentDto>.

Findings folded in from outside the rubric

• requirements.txt pins pytest==6.2.4, which predates the pythonpath ini setting (introduced in pytest 7.0). A developer installing from that file therefore still hits the original collection failure, because the key is silently ignored. This was not verified by execution — a virtualenv could not be created in this environment (ensurepip is not available), so the claim rests on pytest's changelog rather than an observed run, and it is asserted in the README on that basis. The pin itself is left alone because requirements.txt is a dependency surface this repository's automation holds back from autonomous change; it is filed as requirements.txt pins a pytest older than the pythonpath setting the test suite depends on #206 and the README carries an explicit warning in the meantime.
• The two verified interpreter/pytest combinations differ, which is worth stating so later readers are not misled: pytest on this machine is 9.0.3 running on 3.9+, while python3 -m pytest is 7.1.3 on 3.8.10. Both pass all 107 tests with this branch applied.

One intrinsic-critique pass; no further self-scoring will follow absent a reviewer comment or a CI failure.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson