Skip to content

Official Codebase of 3DCodeVerse

Python

doctor + docs: an all-green doctor on a broken install, and a "pure-python" pytest line that re-enabled the live tests

gaoypeng79cbc5a202c5
diff --git a/harness/codeverse/cli/doctor.py b/harness/codeverse/cli/doctor.py
index 167f3e99..4bae2fd0 100644
--- a/harness/codeverse/cli/doctor.py
+++ b/harness/codeverse/cli/doctor.py
@@ -19,7 +19,15 @@ doctor_app = typer.Typer(invoke_without_command=True)
Row = tuple[str, str, str]
_PY_DEPS = ("pydantic", "pydantic_settings", "typer", "rich", "jinja2", "yaml", "numpy", "trimesh", "fcl", "PIL", "pyarrow",
"scipy", "shapely", "networkx", "manifold3d", "playwright", "google.genai", "anthropic", "openai",
- "yourdfpy", "mcp")
+ "yourdfpy", "mcp", "moderngl", "cadquery")
+#: modules that come from an OPTIONAL extra: missing means one track is unavailable, not a
+#: broken install, so they are a WARN naming the extra to install. `moderngl` and `cadquery`
+#: were absent from the list entirely until 2026-08-24, so an environment installed without
+#: [graphics] passed doctor "21/21 importable" and then failed in the graphics track with
+#: "no usable OpenGL context: No module named 'moderngl'" — a missing pip package reported
+#: as a GPU/driver problem (docs/INSTALL.md §4 promises every extra is listed here).
+_OPTIONAL_DEPS = {"manifold3d": "mesh", "shapely": "mesh", "yourdfpy": "urdf", "mcp": "mcp",
+ "moderngl": "graphics", "cadquery": "cad"}
_CLI_TIMEOUT = 25
@@ -48,8 +56,12 @@ def check_python_deps() -> list[Row]:
import sys
rows: list[Row] = [("python", "OK", sys.version.split()[0] + f" ({sys.executable})")]
- status = "OK" if not missing else ("WARN" if set(missing) <= {"manifold3d", "yourdfpy", "mcp", "shapely"} else "FAIL")
- rows.append(("python deps", status, f"{len(present)}/{len(_PY_DEPS)} importable" + (f"; missing: {', '.join(missing)}" if missing else "")))
+ status = "OK" if not missing else ("WARN" if set(missing) <= set(_OPTIONAL_DEPS) else "FAIL")
+ detail = f"{len(present)}/{len(_PY_DEPS)} importable" + (f"; missing: {', '.join(missing)}" if missing else "")
+ extras = sorted({_OPTIONAL_DEPS[m] for m in missing if m in _OPTIONAL_DEPS})
+ if extras: # name the fix, not just the symptom
+ detail += f"; fix: pip install -e 'harness[{','.join(extras)}]'"
+ rows.append(("python deps", status, detail))
return rows
diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.md
index 64f43711..32bc74dc 100644
--- a/harness/docs/INSTALL.md
+++ b/harness/docs/INSTALL.md
@@ -142,20 +142,23 @@ openai, playwright.
`graphics`, `mesh`, `mcp` and `flywheel` are lazily imported: without them the
harness installs and starts fine and only the named feature raises `ImportError`
at the moment you use it. `3dcodeverse doctor` lists every one of these modules
-under `python deps` and only tolerates `manifold3d`, `yourdfpy`, `mcp`, `shapely`
-as WARN — everything else missing is a FAIL.
+under `python deps` and only tolerates the optional-extra modules — `manifold3d`,
+`shapely` (mesh), `yourdfpy` (urdf), `mcp`, `moderngl` (graphics), `cadquery` (cad) —
+as WARN, naming the extra to install; everything else missing is a FAIL.
Run the offline test suite to confirm the install:
```bash
cd harness
python -m pytest tests -q # needs node + Blender for the full set
-python -m pytest tests -q -m "not blender and not node" # pure-python subset
+python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset
python -m pytest tests -q -m live # OPT-IN: real API calls, needs keys
```
Live tests are deselected by default (`addopts = ["-m", "not live"]` in `pyproject.toml`),
-so a bare `pytest` never spends money and never hangs waiting on a provider outage.
+so a bare `pytest` never spends money and never hangs waiting on a provider outage. A
+command-line `-m` **replaces** that default rather than adding to it, so any subset you
+select must spell `not live` itself — as the line above does.
---
@@ -442,7 +445,7 @@ Real output on this box (exit code 0; any FAIL row makes it exit 1):
┃ check ┃ status ┃ detail ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ python │ OK │ 3.13.9 (/home/yipeng/miniconda3/bin/python3.13) │
-│ python deps │ OK │ 21/21 importable │
+│ python deps │ OK │ 23/23 importable │
│ blender │ OK │ Blender 5.0.1 @ /home/yipeng/.local/bin/blender-5.0 │
│ node │ OK │ v24.14.0 │
│ three │ OK │ 0.182.0 (…/harness/runtime_js/node_modules) │
@@ -475,7 +478,7 @@ that the keys work end to end):
|---|---|---|---|
| `python` | — | interpreter running the CLI | if it is not the interpreter you installed into, your shell is picking up another `3dcodeverse` — `which -a 3dcodeverse`, reinstall with `python -m pip install -e harness` |
| `python deps` | FAIL | a core import is missing/broken | `pip install -e 'harness[all]'`; a broken native lib (`fcl`, `manifold3d`) shows up here too — reinstall that wheel (`pip install --force-reinstall python-fcl`) |
-| `python deps` | WARN | only `manifold3d` / `yourdfpy` / `mcp` / `shapely` missing | install the matching extra: `pip install -e 'harness[mesh,urdf,mcp]'` (§4) |
+| `python deps` | WARN | only optional-extra modules missing (`manifold3d` / `shapely` / `yourdfpy` / `mcp` / `moderngl` / `cadquery`) | install the extra the row names, e.g. `pip install -e 'harness[mesh,urdf,mcp,graphics,cad]'` (§4) |
| `blender` | FAIL | no binary found, or `--version` failed | §6 — install Blender, or `export CV3D_BINARIES__BLENDER=/path/to/blender`. If it is found but fails, run it by hand: a `libSM.so.6`/`libICE.so.6` error means you need the `LD_LIBRARY_PATH` wrapper |
| `node` | FAIL | node missing or older than 20.6.0 (§2.1) | install a newer node (`nvm install --lts`) or point `binaries.node` / `CV3D_BINARIES__NODE` at one. The same check fires from every node workload (`codeverse.spatial.node.run_node`), so a too-old node cannot fail obscurely mid-render |
| `three` | FAIL | `runtime_js/node_modules/three` missing | `cd harness/runtime_js && npm ci` (§5) |
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index 296f00cb..ca9a3d0c 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -13,7 +13,7 @@ cd /home/yipeng/3dcodeverse/harness/runtime_js && npm install # [email protected], p
3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, ffmpeg, mcp
3dcv doctor --live # + one tiny Gemini call ("pong", ~$0.00001)
python -m pytest tests -q # offline suite; live tests are opt-in (blender/node/GL run when the binaries exist)
-python -m pytest tests -q -m "not blender and not node" # pure-python subset
+python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset
python -m pytest tests -q -m live # OPT-IN: real API calls
```
diff --git a/harness/tests/install/test_docs.py b/harness/tests/install/test_docs.py
index 83df34fa..1a1259cb 100644
--- a/harness/tests/install/test_docs.py
+++ b/harness/tests/install/test_docs.py
@@ -180,6 +180,60 @@ def test_every_pyproject_extra_is_documented() -> None:
assert not undocumented, f"extras missing from docs/INSTALL.md: {undocumented}"
+#: `pytest ... -m "<expr>"` as published in the docs
+_PYTEST_MARKER_EXPR = re.compile(r'pytest[^\n]*?-m\s+"([^"]+)"')
+#: every file that publishes a pytest command a reader will paste
+DOCS_WITH_TEST_COMMANDS = [INSTALL, HARNESS / "docs" / "RUNBOOK.md", HARNESS / "CLAUDE.md",
+ HARNESS / "README.md", REPO / "README.md"]
+
+
[email protected]("doc", DOCS_WITH_TEST_COMMANDS, ids=lambda p: p.name)
+def test_documented_pytest_subsets_never_re_enable_the_live_tests(doc: Path) -> None:
+ """PORT-1: a command-line ``-m`` REPLACES ``addopts = ["-m", "not live"]``, it does not
+ add to it. The published "pure-python subset" line was ``-m "not blender and not
+ node"``, which selects 23 live tests (2058 collected vs 2035) — run verbatim it opened
+ real Gemini connections and hung against the intermittent provider, three lines above a
+ sentence promising the opposite. Every documented selection must spell ``not live``
+ itself; the only exception is the deliberate ``-m live`` opt-in."""
+ if not doc.is_file(): # the harness can be checked out without the repo README
+ pytest.skip(f"{doc} not present")
+ for expr in _PYTEST_MARKER_EXPR.findall(doc.read_text()):
+ assert "not live" in expr or expr.strip() == "live", (
+ f"{doc.name} publishes pytest -m \"{expr}\", which re-enables the live tests")
+
+
+def test_doctor_checks_every_module_of_every_optional_extra(monkeypatch) -> None:
+ """PORT-3: docs/INSTALL.md §4 says `3dcv doctor` lists every one of these modules under
+ `python deps`, and docs/RUNBOOK.md:12 names moderngl explicitly — but neither moderngl
+ nor cadquery was in ``_PY_DEPS``, so a venv installed with every extra EXCEPT
+ [graphics] printed "21/21 importable" and exited 0, and the graphics track then died
+ with "no usable OpenGL context: ModuleNotFoundError: No module named 'moderngl'" — a
+ missing pip package reported as a GPU/driver problem."""
+ import importlib
+
+ from codeverse.cli.doctor import _OPTIONAL_DEPS, _PY_DEPS, check_python_deps
+
+ with (HARNESS / "pyproject.toml").open("rb") as fh:
+ extras = tomllib.load(fh)["project"]["optional-dependencies"]
+ wanted = {re.split(r"[<>=!\[ ]", req)[0].replace("-", "_")
+ for name, reqs in extras.items() if name not in ("all", "dev") for req in reqs}
+ assert not wanted - set(_PY_DEPS), f"extras doctor never checks: {sorted(wanted - set(_PY_DEPS))}"
+ # the two lazily-imported tracks are a WARN naming their extra, not a FAIL: without them
+ # the harness installs and starts fine and only that track raises (docs/INSTALL.md §4)
+ assert _OPTIONAL_DEPS["moderngl"] == "graphics" and _OPTIONAL_DEPS["cadquery"] == "cad"
+
+ real = importlib.import_module
+
+ def no_graphics(name: str, *a, **kw):
+ if name == "moderngl":
+ raise ModuleNotFoundError("No module named 'moderngl'")
+ return real(name, *a, **kw)
+
+ monkeypatch.setattr(importlib, "import_module", no_graphics)
+ _, deps = check_python_deps()
+ assert deps[1] == "WARN" and "moderngl" in deps[2] and "harness[graphics]" in deps[2]
+
+
def test_doctor_rows_have_troubleshooting_entries() -> None:
"""Every check `3dcv doctor` can print must appear in the INSTALL troubleshooting table."""
from codeverse.cli import doctor as doctor_mod