exclude docs from wheel; harden bundle item handling; single-source version

build/common/verify/__init__.py

@@ -3,6 +3,7 @@
 from common.verify.gui import GUI_PRODUCTS, verify_gui_dist
 from common.verify.wheel import (
     verify_built_wheel,
+    verify_wheel,
     verify_wheel_assets,
     verify_wheel_runtime,
 )
@@ -14,6 +15,7 @@ __all__ = [
     "inspect_wheel",
     "verify_built_wheel",
     "verify_gui_dist",
+    "verify_wheel",
     "verify_wheel_assets",
     "verify_wheel_runtime",
 ]

build/common/verify/cli.py

@@ -16,6 +16,7 @@ from common.verify import (  # noqa: E402
     inspect_wheel,
     verify_built_wheel,
     verify_gui_dist,
+    verify_wheel,
     verify_wheel_assets,
     verify_wheel_runtime,
 )
@@ -79,7 +80,28 @@ def main(argv: list[str] | None = None) -> int:
         if not result.ok:
             exit_code = 1
 
-    if args.assets or args.runtime:
+    if args.assets and args.runtime:
+        video = args.video or default_verification_video(REPO_ROOT)
+        if video is None:
+            print("[FAIL] runtime: no clip found; pass --video or set ORISYS_VERIFY_VIDEO")
+            return 1
+        try:
+            record = verify_wheel(
+                args.wheel,
+                video=video,
+                config_name=args.config,
+                frames=args.frames,
+                offline=args.offline,
+            )
+            print(f"[ok  ] {record['imports']}")
+            print(f"[ok  ] {record['assets']}")
+            print(f"[ok  ] runtime: frames={record['frames']} flow={record['flow_shape']}")
+        except Exception as exc:
+            print(f"[FAIL] isolated verification: {type(exc).__name__}: {exc}")
+            exit_code = 1
+        return exit_code
+
+    if args.assets:
         try:
             print(verify_wheel_assets(args.wheel))
         except Exception as exc:

build/common/verify/wheel.py

@@ -20,6 +20,7 @@ import subprocess
 import sys
 import tempfile
 import venv
+from contextlib import contextmanager
 from pathlib import Path
 
 # Public SDK surface that must import from a released wheel.
@@ -302,60 +303,75 @@ class WheelVerificationError(RuntimeError):
     """
 
 
-def _run_in_fresh_venv(
+def _run_script(
+    python: Path, script: str, args: list[str] | None = None, *, env: dict
+) -> str:
+    """Run a verification script in an already-prepared venv."""
+    completed = subprocess.run(
+        [str(python), "-c", script, *(args or [])],
+        capture_output=True,
+        text=True,
+        env=env,
+        check=False,
+    )
+    if completed.returncode != 0:
+        command = " ".join(str(part) for part in (args or []))
+        raise WheelVerificationError(
+            f"verification script failed in the venv (exit {completed.returncode}"
+            + (f", args: {command}" if command else "")
+            + ").\n--- stdout ---\n"
+            + (completed.stdout.strip() or "<empty>")
+            + "\n--- stderr ---\n"
+            + (completed.stderr.strip() or "<empty>")
+        )
+    return completed.stdout.strip()
+
+
+@contextmanager
+def _installed_venv(
     wheel_path: Path,
-    script: str,
-    args: list[str] | None = None,
     *,
     python_executable: Path | None = None,
     offline: bool = False,
     prefix: str = "orisys-wheel-verify-",
-) -> str:
+):
+    """Create a venv with the wheel installed, for one or more checks.
+
+    Creating a venv and installing the runtime dependencies is by far the most
+    expensive part of verification (tens of seconds plus a large download when
+    not using ``--offline``), so callers that run several checks must share one
+    venv instead of building one per check.
+    """
     wheel_path = wheel_path.resolve()
     env = _hermetic_env()
     with tempfile.TemporaryDirectory(prefix=prefix) as tmp:
         venv_dir = Path(tmp) / "venv"
+        interpreter = python_executable or Path(sys.executable)
+        print(
+            f"  [{wheel_path.name}] creating venv from {interpreter.name}"
+            + ("" if offline else " and installing dependencies (first run downloads packages)")
+            + " ...",
+            flush=True,
+        )
         python = _create_venv(
             venv_dir,
             python_executable=python_executable,
             system_site_packages=offline,
         )
         _install_wheel(python, wheel_path, offline=offline, env=env)
-        completed = subprocess.run(
-            [str(python), "-c", script, *(args or [])],
-            capture_output=True,
-            text=True,
-            env=env,
-            check=False,
-        )
-        if completed.returncode != 0:
-            command = " ".join(str(part) for part in (args or []))
-            raise WheelVerificationError(
-                f"verification script failed in the venv (exit {completed.returncode}"
-                + (f", args: {command}" if command else "")
-                + ").\n--- stdout ---\n"
-                + (completed.stdout.strip() or "<empty>")
-                + "\n--- stderr ---\n"
-                + (completed.stderr.strip() or "<empty>")
-            )
-        return completed.stdout.strip()
+        yield python, env
 
 
 def verify_built_wheel(wheel_path: Path, *, python_executable: Path | None = None) -> None:
     """Install the wheel in a temporary venv and smoke-test public imports."""
-    _run_in_fresh_venv(
-        wheel_path, _SMOKE_IMPORT_SCRIPT, python_executable=python_executable
-    )
+    with _installed_venv(wheel_path, python_executable=python_executable) as (python, env):
+        _run_script(python, _SMOKE_IMPORT_SCRIPT, env=env)
 
 
 def verify_wheel_assets(wheel_path: Path, *, python_executable: Path | None = None) -> str:
     """Assert the wheel carries loadable bundled configs and sensor assets."""
-    return _run_in_fresh_venv(
-        wheel_path,
-        _ASSET_SCRIPT,
-        python_executable=python_executable,
-        prefix="orisys-wheel-assets-",
-    )
+    with _installed_venv(wheel_path, python_executable=python_executable) as (python, env):
+        return _run_script(python, _ASSET_SCRIPT, env=env)
 
 
 def verify_wheel_runtime(
@@ -372,20 +388,59 @@ def verify_wheel_runtime(
     This is the only check that proves the compiled extension plus the bundled
     sensor assets actually produce finite flow/force output end to end.
     """
+    with _installed_venv(
+        wheel_path, python_executable=python_executable, offline=offline
+    ) as (python, env):
+        return _runtime_check(python, env, video=video, config_name=config_name, frames=frames)
+
+
+def _runtime_check(
+    python: Path, env: dict, *, video: Path, config_name: str, frames: int
+) -> dict:
     video = Path(video).resolve()
     if not video.is_file():
         raise FileNotFoundError(f"verification video not found: {video}")
     if frames < 1:
         raise ValueError("frames must be >= 1")
 
-    output = _run_in_fresh_venv(
-        wheel_path,
-        _RUNTIME_SCRIPT,
-        [str(video), config_name, str(frames)],
-        python_executable=python_executable,
-        offline=offline,
-        prefix="orisys-wheel-runtime-",
+    print(f"  processing {frames} frame(s) with config {config_name!r} ...", flush=True)
+    output = _run_script(
+        python, _RUNTIME_SCRIPT, [str(video), config_name, str(frames)], env=env
     )
     import json
 
     return json.loads(output.splitlines()[-1])
+
+
+def verify_wheel(
+    wheel_path: Path,
+    *,
+    video: Path | None = None,
+    config_name: str = DEFAULT_RUNTIME_CONFIG,
+    frames: int = 40,
+    python_executable: Path | None = None,
+    offline: bool = False,
+    check_assets: bool = True,
+) -> dict:
+    """Run every isolated-check level for one wheel inside a single venv.
+
+    Use this instead of calling the individual ``verify_wheel_*`` helpers: it
+    pays the venv/dependency cost once and returns the runtime record plus the
+    asset and import summaries.
+    """
+    with _installed_venv(
+        wheel_path, python_executable=python_executable, offline=offline
+    ) as (python, env):
+        imports = _run_script(python, _SMOKE_IMPORT_SCRIPT, env=env)
+        record: dict = {"wheel": Path(wheel_path).name, "imports": imports}
+        if check_assets:
+            record["assets"] = _run_script(python, _ASSET_SCRIPT, env=env)
+        else:
+            record["assets"] = "asset check skipped (--no-assets)"
+        if video is not None:
+            record.update(
+                _runtime_check(
+                    python, env, video=video, config_name=config_name, frames=frames
+                )
+            )
+        return record