fix: #2938 make sandboxes importable on Windows (#2948)

Author: seratch

src/agents/sandbox/sandboxes/__init__.py

@@ -5,12 +5,27 @@
 execution environments (e.g. Docker, local Unix).
 """
 
-from .unix_local import (
-    UnixLocalSandboxClient,
-    UnixLocalSandboxClientOptions,
-    UnixLocalSandboxSession,
-    UnixLocalSandboxSessionState,
-)
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+_HAS_UNIX_LOCAL = sys.platform != "win32"
+
+if _HAS_UNIX_LOCAL:
+    from .unix_local import (
+        UnixLocalSandboxClient,
+        UnixLocalSandboxClientOptions,
+        UnixLocalSandboxSession,
+        UnixLocalSandboxSessionState,
+    )
+elif TYPE_CHECKING:
+    from .unix_local import (  # noqa: F401
+        UnixLocalSandboxClient,
+        UnixLocalSandboxClientOptions,
+        UnixLocalSandboxSession,
+        UnixLocalSandboxSessionState,
+    )
 
 try:
     from .docker import (  # noqa: F401
@@ -25,12 +40,17 @@
     # Docker is an optional extra; keep base imports working without it.
     _HAS_DOCKER = False
 
-__all__ = [
-    "UnixLocalSandboxClient",
-    "UnixLocalSandboxClientOptions",
-    "UnixLocalSandboxSession",
-    "UnixLocalSandboxSessionState",
-]
+__all__: list[str] = []
+
+if _HAS_UNIX_LOCAL:
+    __all__.extend(
+        [
+            "UnixLocalSandboxClient",
+            "UnixLocalSandboxClientOptions",
+            "UnixLocalSandboxSession",
+            "UnixLocalSandboxSessionState",
+        ]
+    )
 
 if _HAS_DOCKER:
     __all__.extend(

src/agents/sandbox/sandboxes/unix_local.py

@@ -1,3 +1,11 @@
+import sys
+
+if sys.platform == "win32":  # pragma: no cover
+    raise ImportError(
+        "UnixLocalSandbox is not supported on Windows. "
+        "Use DockerSandboxClient or another sandbox backend."
+    )
+
 import asyncio
 import errno
 import fcntl
@@ -7,7 +15,6 @@
 import shlex
 import shutil
 import signal
-import sys
 import tarfile
 import tempfile
 import termios

tests/sandbox/test_sandboxes_import.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from types import ModuleType
+from typing import Any
+
+import pytest
+
+
+def _restore_module(name: str, original: ModuleType | None) -> None:
+    sys.modules.pop(name, None)
+    if original is not None:
+        sys.modules[name] = original
+
+
+def _restore_attr(obj: Any, name: str, original: object, existed: bool) -> None:
+    if existed:
+        setattr(obj, name, original)
+    else:
+        try:
+            delattr(obj, name)
+        except AttributeError:
+            pass
+
+
+def test_sandboxes_package_import_skips_unix_local_on_windows(monkeypatch) -> None:
+    sandbox_package = importlib.import_module("agents.sandbox")
+    original_sandboxes_module = sys.modules.pop("agents.sandbox.sandboxes", None)
+    original_unix_local_module = sys.modules.pop("agents.sandbox.sandboxes.unix_local", None)
+    original_sandboxes_attr = getattr(sandbox_package, "sandboxes", None)
+    had_sandboxes_attr = hasattr(sandbox_package, "sandboxes")
+
+    if had_sandboxes_attr:
+        delattr(sandbox_package, "sandboxes")
+    monkeypatch.setattr(sys, "platform", "win32")
+
+    try:
+        sandboxes = importlib.import_module("agents.sandbox.sandboxes")
+
+        assert sandboxes.__name__ == "agents.sandbox.sandboxes"
+        assert "UnixLocalSandboxClient" not in sandboxes.__all__
+        assert "UnixLocalSandboxClient" not in sandboxes.__dict__
+        assert "agents.sandbox.sandboxes.unix_local" not in sys.modules
+    finally:
+        _restore_module("agents.sandbox.sandboxes", original_sandboxes_module)
+        _restore_module("agents.sandbox.sandboxes.unix_local", original_unix_local_module)
+        _restore_attr(
+            sandbox_package,
+            "sandboxes",
+            original_sandboxes_attr,
+            had_sandboxes_attr,
+        )
+
+
+def test_unix_local_backend_import_raises_clear_error_on_windows(monkeypatch) -> None:
+    parent = importlib.import_module("agents.sandbox.sandboxes")
+    original_unix_local_module = sys.modules.pop("agents.sandbox.sandboxes.unix_local", None)
+    original_unix_local_attr = getattr(parent, "unix_local", None)
+    had_unix_local_attr = hasattr(parent, "unix_local")
+
+    if had_unix_local_attr:
+        delattr(parent, "unix_local")
+    monkeypatch.setattr(sys, "platform", "win32")
+
+    try:
+        with pytest.raises(ImportError, match="not supported on Windows"):
+            importlib.import_module("agents.sandbox.sandboxes.unix_local")
+    finally:
+        _restore_module("agents.sandbox.sandboxes.unix_local", original_unix_local_module)
+        _restore_attr(
+            parent,
+            "unix_local",
+            original_unix_local_attr,
+            had_unix_local_attr,
+        )
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="Unix local sandbox is unavailable on Windows")
+def test_sandboxes_package_exports_unix_local_on_supported_platforms() -> None:
+    sandboxes = importlib.import_module("agents.sandbox.sandboxes")
+
+    assert "UnixLocalSandboxClient" in sandboxes.__all__
+    assert sandboxes.UnixLocalSandboxClient.__name__ == "UnixLocalSandboxClient"