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.pyindex 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 sysrows: 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 rowsdiff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.mdindex 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 theharness 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:```bashcd harnesspython -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 subsetpython -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.mdindex 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], p3dcv doctor # python deps (incl. python-fcl, moderngl), blender, node/three/puppeteer, chrome WebGL, keys, CLIs, git, ffmpeg, mcp3dcv 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 subsetpython -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.pyindex 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