fix(python): address final review (CI matrix, lazy-load docs, guards)

- Drop windows-latest from the new CI jobs (binding has no win32 support
  yet: no _build.py linker branch, run() uses POSIX signal.pause()).
- Remove unused cibuildwheel from the wheel-build install step.
- Restore the explicit LUOS_ENGINE_LIB_DIR-miss error instead of silently
  falling back to a .pio walk-up build.
- Lock get_phy_handle's _PHY_HANDLES read-check-write.
- Fix the stale load_phy docstring (phys load lazily, not at import).
- Clean up the .tmp file if the atomic cache rename fails.
- Refuse phy download on a +dev build with a clear message.
- Tests for the LIB_DIR-miss error and the dev-build download guard.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nicolas-rabault

.github/workflows/pio_release.yml

@@ -190,7 +190,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
+        # Windows is not yet supported by the binding (no win32 linker
+        # branch in _build.py; luos.run() uses POSIX signal.pause()).
+        os: [ubuntu-22.04, macos-latest]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -200,7 +202,7 @@ jobs:
       - name: Install build tooling
         run: |
           python -m pip install --upgrade pip
-          pip install platformio cibuildwheel==2.* build
+          pip install platformio build
       - name: Build native engine + phy dylibs
         run: pio run -e native_lib
       - name: Stage core engine into the package and pin version
@@ -223,7 +225,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
+        # Windows is not yet supported by the binding (no win32 linker
+        # branch in _build.py; luos.run() uses POSIX signal.pause()).
+        os: [ubuntu-22.04, macos-latest]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -252,7 +256,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
+        # Windows is not yet supported by the binding (no win32 linker
+        # branch in _build.py; luos.run() uses POSIX signal.pause()).
+        os: [ubuntu-22.04, macos-latest]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

bindings/python/luos_engine/_engine.py

@@ -84,8 +84,8 @@ def is_detected() -> bool:
 def load_phy(descriptor, **kwargs) -> None:
     """Load and initialise a network phy. Must be called before start().
 
-    The phy dylib is pre-loaded at package import time (see
-    _ffi.load_dylib). This function validates kwargs via
+    The phy dylib is resolved and loaded lazily on first use via
+    get_phy_handle. This function validates kwargs via
     descriptor.configure, then calls the phy's init symbol (once per
     process — subsequent calls skip init but still register the phy
     for the loop thread to tick).

bindings/python/luos_engine/_ffi.py

@@ -42,6 +42,17 @@ def resolve_lib_path() -> Path:
             )
         return p
 
+    # An explicitly-set LUOS_ENGINE_LIB_DIR must contain the engine; fail
+    # loudly rather than silently falling back to a .pio walk-up build.
+    env_dir = os.environ.get("LUOS_ENGINE_LIB_DIR")
+    if env_dir:
+        found = _find_in_dir(Path(env_dir))
+        if found:
+            return found
+        raise LuosEngineNotFoundError(
+            f"No libluos_engine.* in LUOS_ENGINE_LIB_DIR={env_dir}"
+        )
+
     for d in local_lib_dirs():
         found = _find_in_dir(d)
         if found:
@@ -56,6 +67,7 @@ def resolve_lib_path() -> Path:
 
 _LIB_HANDLE = None
 _LIB_LOCK = threading.Lock()
+_PHY_LOCK = threading.Lock()
 _PHY_HANDLES: dict[str, ctypes.CDLL] = {}
 
 
@@ -76,8 +88,11 @@ def get_phy_handle(basename: str) -> ctypes.CDLL:
     and loading (and downloading if necessary) on first use."""
     handle = _PHY_HANDLES.get(basename)
     if handle is None:
-        from ._phy_loader import ensure_phy_dylib
-        path = ensure_phy_dylib(basename)
-        handle = ctypes.CDLL(str(path), mode=ctypes.RTLD_GLOBAL)
-        _PHY_HANDLES[basename] = handle
+        with _PHY_LOCK:
+            handle = _PHY_HANDLES.get(basename)
+            if handle is None:
+                from ._phy_loader import ensure_phy_dylib
+                path = ensure_phy_dylib(basename)
+                handle = ctypes.CDLL(str(path), mode=ctypes.RTLD_GLOBAL)
+                _PHY_HANDLES[basename] = handle
     return handle

bindings/python/luos_engine/_phy_loader.py

@@ -59,7 +59,11 @@ def _download(asset_name: str, dest: Path) -> Path:
     dest.parent.mkdir(parents=True, exist_ok=True)
     tmp = dest.with_name(dest.name + ".tmp")
     tmp.write_bytes(data)
-    os.replace(tmp, dest)  # atomic
+    try:
+        os.replace(tmp, dest)  # atomic
+    except OSError:
+        tmp.unlink(missing_ok=True)
+        raise
     return dest
 
 
@@ -86,5 +90,12 @@ def ensure_phy_dylib(basename: str) -> Path:
             f"variable to download from the {ENGINE_VERSION} release."
         )
 
+    if ENGINE_VERSION.endswith("+dev"):
+        raise PhyDownloadError(
+            f"{filename} not found locally and this is a dev build "
+            f"(ENGINE_VERSION={ENGINE_VERSION!r}, no matching release). "
+            f"Build it with `~/.platformio/penv/bin/pio run -e native_lib`."
+        )
+
     asset_name = f"{basename}-{platform_key()}{ext}"
     return _download(asset_name, cached)

bindings/python/tests/test_ffi_discovery.py

@@ -25,3 +25,14 @@ def test_missing_raises(monkeypatch, tmp_path):
     from luos_engine._ffi import resolve_lib_path, LuosEngineNotFoundError
     with pytest.raises(LuosEngineNotFoundError):
         resolve_lib_path()
+
+
+def test_explicit_lib_dir_miss_raises_specific(monkeypatch, tmp_path):
+    """An explicitly-set LUOS_ENGINE_LIB_DIR that lacks the engine must
+    fail loudly, not silently fall back to a .pio walk-up build."""
+    monkeypatch.delenv("LUOS_ENGINE_LIB", raising=False)
+    monkeypatch.setenv("LUOS_ENGINE_LIB_DIR", str(tmp_path))
+    from luos_engine._ffi import resolve_lib_path, LuosEngineNotFoundError
+    with pytest.raises(LuosEngineNotFoundError) as exc:
+        resolve_lib_path()
+    assert "LUOS_ENGINE_LIB_DIR" in str(exc.value)

bindings/python/tests/test_phy_loader.py

@@ -8,10 +8,13 @@
 @pytest.fixture(autouse=True)
 def _isolate_cache(tmp_path, monkeypatch):
     """Force the cache into tmp and disable any local-build discovery so
-    tests exercise the cache/download paths deterministically."""
+    tests exercise the cache/download paths deterministically. Pin a
+    non-dev engine version so the +dev download guard doesn't fire (the
+    dev-build guard is covered by its own test)."""
     monkeypatch.setenv("LUOS_ENGINE_CACHE_DIR", str(tmp_path / "cache"))
     monkeypatch.delenv("LUOS_ENGINE_LIB_DIR", raising=False)
     monkeypatch.delenv("LUOS_ENGINE_NO_DOWNLOAD", raising=False)
+    monkeypatch.setattr(_phy_loader, "ENGINE_VERSION", "9.9.9")
     # No local build dirs.
     monkeypatch.setattr(_phy_loader, "local_lib_dirs", lambda: iter(()))
 
@@ -77,3 +80,17 @@ def test_no_download_env_raises_when_missing(monkeypatch):
     monkeypatch.setenv("LUOS_ENGINE_NO_DOWNLOAD", "1")
     with pytest.raises(LuosEngineNotFoundError):
         _phy_loader.ensure_phy_dylib("libws_network")
+
+
+def test_dev_build_refuses_download(monkeypatch):
+    """A +dev build has no matching release; fail with a clear message
+    instead of 404-ing on a non-existent release asset."""
+    monkeypatch.setattr(_phy_loader, "ENGINE_VERSION", "0.0.0+dev")
+
+    def _boom(*a, **k):
+        raise AssertionError("must not attempt a download for a dev build")
+
+    monkeypatch.setattr(_phy_loader, "_fetch_json", _boom)
+    with pytest.raises(_phy_loader.PhyDownloadError) as exc:
+        _phy_loader.ensure_phy_dylib("libws_network")
+    assert "dev build" in str(exc.value)