Renamed local_binary_path to _local_stagehand_binary_path, making it internal and clarifying the name

Author: monadoid

src/stagehand/_client.py

@@ -62,7 +62,7 @@ def __init__(
         browserbase_project_id: str | None = None,
         model_api_key: str | None = None,
         server: Literal["remote", "local"] = "remote",
-        local_binary_path: str | os.PathLike[str] | None = None,
+        _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
         local_host: str = "127.0.0.1",
         local_port: int = 0,
         local_headless: bool = True,
@@ -96,7 +96,7 @@ def __init__(
         - `model_api_key` from `MODEL_API_KEY`
         """
         self._server_mode: Literal["remote", "local"] = server
-        self._local_binary_path = local_binary_path
+        self._local_stagehand_binary_path = _local_stagehand_binary_path
         self._local_host = local_host
         self._local_port = local_port
         self._local_headless = local_headless
@@ -136,7 +136,7 @@ def __init__(
                     openai_api_key=openai_api_key,
                     shutdown_on_close=local_shutdown_on_close,
                 ),
-                local_binary_path=local_binary_path,
+                _local_stagehand_binary_path=_local_stagehand_binary_path,
             )
         else:
             if base_url is None:
@@ -229,7 +229,7 @@ def copy(
         browserbase_project_id: str | None = None,
         model_api_key: str | None = None,
         server: Literal["remote", "local"] | None = None,
-        local_binary_path: str | os.PathLike[str] | None = None,
+        _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
         local_host: str | None = None,
         local_port: int | None = None,
         local_headless: bool | None = None,
@@ -273,7 +273,7 @@ def copy(
             browserbase_project_id=browserbase_project_id or self.browserbase_project_id,
             model_api_key=model_api_key or self.model_api_key,
             server=server or self._server_mode,
-            local_binary_path=local_binary_path if local_binary_path is not None else self._local_binary_path,
+            _local_stagehand_binary_path=_local_stagehand_binary_path if _local_stagehand_binary_path is not None else self._local_stagehand_binary_path,
             local_host=local_host or self._local_host,
             local_port=local_port if local_port is not None else self._local_port,
             local_headless=local_headless if local_headless is not None else self._local_headless,
@@ -346,7 +346,7 @@ def __init__(
         browserbase_project_id: str | None = None,
         model_api_key: str | None = None,
         server: Literal["remote", "local"] = "remote",
-        local_binary_path: str | os.PathLike[str] | None = None,
+        _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
         local_host: str = "127.0.0.1",
         local_port: int = 0,
         local_headless: bool = True,
@@ -380,7 +380,7 @@ def __init__(
         - `model_api_key` from `MODEL_API_KEY`
         """
         self._server_mode: Literal["remote", "local"] = server
-        self._local_binary_path = local_binary_path
+        self._local_stagehand_binary_path = _local_stagehand_binary_path
         self._local_host = local_host
         self._local_port = local_port
         self._local_headless = local_headless
@@ -419,7 +419,7 @@ def __init__(
                     openai_api_key=openai_api_key,
                     shutdown_on_close=local_shutdown_on_close,
                 ),
-                local_binary_path=local_binary_path,
+                _local_stagehand_binary_path=_local_stagehand_binary_path,
             )
         else:
             if base_url is None:
@@ -512,7 +512,7 @@ def copy(
         browserbase_project_id: str | None = None,
         model_api_key: str | None = None,
         server: Literal["remote", "local"] | None = None,
-        local_binary_path: str | os.PathLike[str] | None = None,
+        _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
         local_host: str | None = None,
         local_port: int | None = None,
         local_headless: bool | None = None,
@@ -556,7 +556,7 @@ def copy(
             browserbase_project_id=browserbase_project_id or self.browserbase_project_id,
             model_api_key=model_api_key or self.model_api_key,
             server=server or self._server_mode,
-            local_binary_path=local_binary_path if local_binary_path is not None else self._local_binary_path,
+            _local_stagehand_binary_path=_local_stagehand_binary_path if _local_stagehand_binary_path is not None else self._local_stagehand_binary_path,
             local_host=local_host or self._local_host,
             local_port=local_port if local_port is not None else self._local_port,
             local_headless=local_headless if local_headless is not None else self._local_headless,

src/stagehand/lib/sea_binary.py

@@ -78,11 +78,11 @@ def _copy_to_cache(*, src: Path, filename: str, version: str) -> Path:
 
 def resolve_binary_path(
     *,
-    local_binary_path: str | os.PathLike[str] | None = None,
+    _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
     version: str | None = None,
 ) -> Path:
-    if local_binary_path is not None:
-        path = Path(local_binary_path)
+    if _local_stagehand_binary_path is not None:
+        path = Path(_local_stagehand_binary_path)
         _ensure_executable(path)
         return path
 

src/stagehand/lib/sea_server.py

@@ -101,10 +101,10 @@ def __init__(
         self,
         *,
         config: SeaServerConfig,
-        local_binary_path: str | os.PathLike[str] | None = None,
+        _local_stagehand_binary_path: str | os.PathLike[str] | None = None,
     ) -> None:
         self._config = config
-        self._binary_path: Path = resolve_binary_path(local_binary_path=local_binary_path, version=__version__)
+        self._binary_path: Path = resolve_binary_path(_local_stagehand_binary_path=_local_stagehand_binary_path, version=__version__)
 
         self._lock = Lock()
         self._async_lock = asyncio.Lock()
@@ -163,7 +163,7 @@ def _start_sync(self) -> tuple[str, subprocess.Popen[bytes]]:
         if not self._binary_path.exists():
             raise FileNotFoundError(
                 f"Stagehand SEA binary not found at {self._binary_path}. "
-                "Pass local_binary_path=... or set STAGEHAND_SEA_BINARY."
+                "Pass _local_stagehand_binary_path=... or set STAGEHAND_SEA_BINARY."
             )
 
         port = _pick_free_port(self._config.host) if self._config.port == 0 else self._config.port
@@ -212,7 +212,7 @@ async def _start_async(self) -> tuple[str, subprocess.Popen[bytes]]:
         if not self._binary_path.exists():
             raise FileNotFoundError(
                 f"Stagehand SEA binary not found at {self._binary_path}. "
-                "Pass local_binary_path=... or set STAGEHAND_SEA_BINARY."
+                "Pass _local_stagehand_binary_path=... or set STAGEHAND_SEA_BINARY."
             )
 
         port = _pick_free_port(self._config.host) if self._config.port == 0 else self._config.port

tests/test_local_server.py

@@ -55,7 +55,7 @@ def test_sync_local_mode_starts_before_first_request(respx_mock: MockRouter, mon
         )
     )
 
-    client = Stagehand(server="local", local_binary_path="/does/not/matter/in/test")
+    client = Stagehand(server="local", _local_stagehand_binary_path="/does/not/matter/in/test")
     # Swap in a dummy server so we don't spawn a real binary in unit tests.
     client._sea_server = dummy  # type: ignore[attr-defined]
 
@@ -90,7 +90,7 @@ async def test_async_local_mode_starts_before_first_request(
         )
     )
 
-    async with AsyncStagehand(server="local", local_binary_path="/does/not/matter/in/test") as client:
+    async with AsyncStagehand(server="local", _local_stagehand_binary_path="/does/not/matter/in/test") as client:
         client._sea_server = dummy  # type: ignore[attr-defined]
         resp = await client.sessions.start(model_name="openai/gpt-5-nano")
         assert resp.success is True