mywebscrcpy-sdk 1.20.1__tar.gz

mywebscrcpy_sdk-1.20.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include examples *.py

mywebscrcpy_sdk-1.20.1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: mywebscrcpy-sdk
+Version: 1.20.1
+Summary: Python client for MyWebScrcpy device automation
+Project-URL: Homepage, https://github.com/liuzhuogood/MyWebScrcpy
+Project-URL: Documentation, https://github.com/liuzhuogood/MyWebScrcpy/blob/main/packages/python-sdk/README.md
+Project-URL: Repository, https://github.com/liuzhuogood/MyWebScrcpy
+Project-URL: Issues, https://github.com/liuzhuogood/MyWebScrcpy/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.28
+
+# MyWebScrcpy Python SDK
+
+SDK 使用 HTTPX，支持 `Client`、绑定设备的 `Device.adb()`、`Device.page_info()` 和类型化结果。按键、点击、滑动及 ASCII 输入可通过明确的 ADB 参数执行。当前尚不提供视频解码、模板管理和匹配 API，也无需安装 OpenCV/PyAV。
+
+使用 Python 3.10+，从 PyPI 安装：
+
+```bash
+python -m pip install mywebscrcpy-sdk
+```
+
+也可从仓库根目录安装源码并运行示例：
+
+```bash
+python -m pip install ./packages/python-sdk
+python packages/python-sdk/examples/device_query.py DEVICE_SERIAL --base-url http://HOST:PORT
+```
+
+也可构建并安装 wheel：
+
+```bash
+python -m pip install build
+python -m build packages/python-sdk
+python -m pip install --find-links packages/python-sdk/dist mywebscrcpy-sdk
+```
+
+```python
+from mywebscrcpy import Client
+
+with Client("http://HOST:PORT") as client:
+    with client.device("DEVICE_SERIAL") as device:
+        result = device.adb(["shell", "getprop", "ro.product.model"], timeout=10)
+        print(result.stdout)
+        device.adb(["shell", "input", "keyevent", "3"], timeout=10)
+        size = device.page_info()
+        device.adb(["shell", "input", "tap", str(size.width // 2), str(size.height // 2)], timeout=10)
+```
+
+`timeout` 为秒，SDK 转换为接口的 `timeout_ms`。ADB 参数不得包含可执行文件名、设备选择或宿主切换选项。SDK 检查 HTTP 响应及实际 `status/exit_code`；失败、截断输出或超时抛异常，不自动重试动作。HTTP 超时后的设备结果可能未知，不应直接重发。
+
+`CommandResult` 包含 `status/exit_code/stdout/stderr/truncated`；`PageInfo` 包含正整数 `width/height`。必需字段缺失或类型错误抛 `ProtocolError`，不猜替代字段。`CommandError.result` 保留命令结果，`HTTPError` 保留 `status/code/detail`；连接错误使用 `ConnectionError`。
+
+`Client(headers=...)` 接收显式请求头，默认验证 TLS，可传 CA 路径。不会读取未知凭据、自动启动主服务或修改 root logger。Client/Device 可重复关闭，关闭后的对象拒绝操作。
+
+应用任务会释放同一套 SDK 源文件，并提供连接环境变量；配置的 Python 环境仍需安装 `httpx`。导出的脚本可在其他目录通过安装本 SDK 独立运行，远程操作要求服务与设备可达。
+
+接口依据 `web/openapi.json` 的 `/api/adb/commands` 和 `/api/ui/page-info`。安装版与应用内释放版共享源码，避免两套运行库。仅本机和受控接口已验证，真机及 Windows/Linux 原生链路仍待验收。
+
+SDK 版本与仓库根目录 `VERSION` 一致，Python 包版本去掉 `v` 前缀。修改 `VERSION` 后运行 `node scripts/sync-version.mjs`，同时更新主程序与 SDK 版本。
+
+GitHub Actions 的 `Publish Python SDK` 工作流在主分支的版本、SDK 或发布配置变更时运行，也支持 `v*` 标签和手动触发；构建检查及安装测试通过后发布未发布的版本，已存在的完整版本会跳过。仓库需在 Settings → Secrets and variables → Actions 配置 `PYPI_API_TOKEN`，值为有此项目发布权限的 PyPI API Token。只修改 SDK 而不更新版本号不会覆盖 PyPI 上已有的版本。

mywebscrcpy_sdk-1.20.1/README.md

@@ -0,0 +1,50 @@
+# MyWebScrcpy Python SDK
+
+SDK 使用 HTTPX，支持 `Client`、绑定设备的 `Device.adb()`、`Device.page_info()` 和类型化结果。按键、点击、滑动及 ASCII 输入可通过明确的 ADB 参数执行。当前尚不提供视频解码、模板管理和匹配 API，也无需安装 OpenCV/PyAV。
+
+使用 Python 3.10+，从 PyPI 安装：
+
+```bash
+python -m pip install mywebscrcpy-sdk
+```
+
+也可从仓库根目录安装源码并运行示例：
+
+```bash
+python -m pip install ./packages/python-sdk
+python packages/python-sdk/examples/device_query.py DEVICE_SERIAL --base-url http://HOST:PORT
+```
+
+也可构建并安装 wheel：
+
+```bash
+python -m pip install build
+python -m build packages/python-sdk
+python -m pip install --find-links packages/python-sdk/dist mywebscrcpy-sdk
+```
+
+```python
+from mywebscrcpy import Client
+
+with Client("http://HOST:PORT") as client:
+    with client.device("DEVICE_SERIAL") as device:
+        result = device.adb(["shell", "getprop", "ro.product.model"], timeout=10)
+        print(result.stdout)
+        device.adb(["shell", "input", "keyevent", "3"], timeout=10)
+        size = device.page_info()
+        device.adb(["shell", "input", "tap", str(size.width // 2), str(size.height // 2)], timeout=10)
+```
+
+`timeout` 为秒，SDK 转换为接口的 `timeout_ms`。ADB 参数不得包含可执行文件名、设备选择或宿主切换选项。SDK 检查 HTTP 响应及实际 `status/exit_code`；失败、截断输出或超时抛异常，不自动重试动作。HTTP 超时后的设备结果可能未知，不应直接重发。
+
+`CommandResult` 包含 `status/exit_code/stdout/stderr/truncated`；`PageInfo` 包含正整数 `width/height`。必需字段缺失或类型错误抛 `ProtocolError`，不猜替代字段。`CommandError.result` 保留命令结果，`HTTPError` 保留 `status/code/detail`；连接错误使用 `ConnectionError`。
+
+`Client(headers=...)` 接收显式请求头，默认验证 TLS，可传 CA 路径。不会读取未知凭据、自动启动主服务或修改 root logger。Client/Device 可重复关闭，关闭后的对象拒绝操作。
+
+应用任务会释放同一套 SDK 源文件，并提供连接环境变量；配置的 Python 环境仍需安装 `httpx`。导出的脚本可在其他目录通过安装本 SDK 独立运行，远程操作要求服务与设备可达。
+
+接口依据 `web/openapi.json` 的 `/api/adb/commands` 和 `/api/ui/page-info`。安装版与应用内释放版共享源码，避免两套运行库。仅本机和受控接口已验证，真机及 Windows/Linux 原生链路仍待验收。
+
+SDK 版本与仓库根目录 `VERSION` 一致，Python 包版本去掉 `v` 前缀。修改 `VERSION` 后运行 `node scripts/sync-version.mjs`，同时更新主程序与 SDK 版本。
+
+GitHub Actions 的 `Publish Python SDK` 工作流在主分支的版本、SDK 或发布配置变更时运行，也支持 `v*` 标签和手动触发；构建检查及安装测试通过后发布未发布的版本，已存在的完整版本会跳过。仓库需在 Settings → Secrets and variables → Actions 配置 `PYPI_API_TOKEN`，值为有此项目发布权限的 PyPI API Token。只修改 SDK 而不更新版本号不会覆盖 PyPI 上已有的版本。

mywebscrcpy_sdk-1.20.1/examples/device_query.py

@@ -0,0 +1,26 @@
+import argparse
+import os
+from mywebscrcpy import Client
+
+
+def main():
+    parser = argparse.ArgumentParser(description="查询设备型号")
+    parser.add_argument("serial", help="ADB 设备序列号")
+    parser.add_argument("--base-url", default=os.environ.get("MYWEBSCRCPY_API_URL", ""))
+    parser.add_argument("--token", default=os.environ.get("MYWEBSCRCPY_API_TOKEN", ""))
+    options = parser.parse_args()
+    if not options.base_url:
+        raise SystemExit("请通过 --base-url 指定 MyWebScrcpy 服务地址")
+    headers = {}
+    if options.token:
+        headers["Authorization"] = "Bearer " + options.token
+
+    with Client(options.base_url, headers=headers) as client:
+        with client.device(options.serial) as device:
+            print("步骤 1：读取设备型号", flush=True)
+            result = device.adb(["shell", "getprop", "ro.product.model"], timeout=10)
+            print(result.stdout, end="", flush=True)
+
+
+if __name__ == "__main__":
+    main()

mywebscrcpy_sdk-1.20.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mywebscrcpy-sdk"
+version = "1.20.1"
+description = "Python client for MyWebScrcpy device automation"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28,<1"]
+
+[project.urls]
+Homepage = "https://github.com/liuzhuogood/MyWebScrcpy"
+Documentation = "https://github.com/liuzhuogood/MyWebScrcpy/blob/main/packages/python-sdk/README.md"
+Repository = "https://github.com/liuzhuogood/MyWebScrcpy"
+Issues = "https://github.com/liuzhuogood/MyWebScrcpy/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mywebscrcpy_sdk-1.20.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy/__init__.py

@@ -0,0 +1,9 @@
+"""Installable MyWebScrcpy SDK. Basic imports do not load vision dependencies."""
+from .client import Client
+from .device import Device
+from .errors import CommandError, ConnectionError, HTTPError, ProtocolError, SDKError
+from .models import CommandResult, PageInfo
+
+__version__ = "1.20.1"
+__all__ = ["Client", "Device", "CommandResult", "PageInfo", "SDKError", "CommandError",
+           "ConnectionError", "HTTPError", "ProtocolError"]

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy/client.py

@@ -0,0 +1,73 @@
+import logging
+from urllib.parse import urlsplit
+
+try:
+    import httpx
+except ImportError as error:
+    raise ImportError("请在当前 Python 环境安装 mywebscrcpy-sdk，或安装 httpx") from error
+
+from .errors import ConnectionError, HTTPError, ProtocolError, SDKError
+
+logger = logging.getLogger(__name__)
+
+
+class Client:
+    """HTTP client. No device process, service or Vision session starts implicitly."""
+
+    def __init__(self, base_url: str, *, headers: dict[str, str] | None = None,
+                 timeout: float = 30, verify: bool | str = True):
+        parsed = urlsplit(base_url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise ValueError("base_url 必须是无凭据的 HTTP(S) 服务地址")
+        if parsed.path not in {"", "/"}:
+            raise ValueError("base_url 不能包含接口路径")
+        if timeout <= 0:
+            raise ValueError("timeout 必须为正数秒")
+        if verify is False:
+            logger.warning("TLS certificate verification explicitly disabled")
+        self._http = httpx.Client(base_url=base_url.rstrip("/"), headers=headers,
+                                  timeout=timeout, verify=verify, trust_env=False)
+        self._closed = False
+
+    def device(self, serial: str):
+        from .device import Device
+        self._check_open()
+        return Device(self, serial)
+
+    def _check_open(self):
+        if self._closed:
+            raise SDKError("Client 已关闭")
+
+    def _request(self, method: str, path: str, *, serial: str, timeout: float, body=None):
+        self._check_open()
+        try:
+            response = self._http.request(method, path, params={"serial": serial}, json=body, timeout=timeout)
+        except httpx.RequestError as error:
+            logger.warning("HTTP connection failed: method=%s path=%s type=%s", method, path, type(error).__name__)
+            raise ConnectionError(f"{method} {path}: {type(error).__name__}") from error
+        try:
+            value = response.json()
+        except ValueError as error:
+            raise ProtocolError(f"{method} {path}: HTTP {response.status_code} 返回非 JSON") from error
+        if not isinstance(value, dict):
+            raise ProtocolError("API 响应必须是 JSON 对象")
+        if response.is_error:
+            # ErrorResponse's message is optional; code is always taken from error.
+            code = value.get("error", "")
+            detail = value.get("message", "")
+            if not isinstance(code, str) or not isinstance(detail, str):
+                raise ProtocolError("错误响应字段类型不合法")
+            raise HTTPError(response.status_code, code, detail)
+        return value
+
+    def close(self):
+        if not self._closed:
+            self._closed = True
+            self._http.close()
+
+    def __enter__(self):
+        self._check_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy/device.py

@@ -0,0 +1,84 @@
+import logging
+import math
+
+from .errors import CommandError, ProtocolError, SDKError
+from .models import CommandResult, PageInfo
+
+logger = logging.getLogger(__name__)
+
+
+def _seconds(value):
+    if type(value) not in {int, float} or not math.isfinite(value) or not 0 < value <= 600:
+        raise ValueError("timeout 必须在 0 到 600 秒之间")
+    return value
+
+
+class Device:
+    """Basic HTTP operations. Vision and matching APIs are added separately."""
+
+    def __init__(self, client, serial: str):
+        if not isinstance(serial, str) or not serial.strip():
+            raise ValueError("serial 必须为非空字符串")
+        self._client = client
+        self.serial = serial
+        self._closed = False
+
+    def _check_open(self):
+        if self._closed:
+            raise SDKError("Device 已关闭")
+        self._client._check_open()
+
+    def adb(self, args: list[str], timeout: float = 30) -> CommandResult:
+        self._check_open()
+        seconds = _seconds(timeout)
+        if not isinstance(args, list) or not 1 <= len(args) <= 128 or any(not isinstance(v, str) or not v or "\x00" in v for v in args):
+            raise ValueError("args 必须包含 1 到 128 个非空字符串")
+        forbidden = {"adb", "-s", "--serial", "-H", "-P", "-L"}
+        if any(v in forbidden or v.startswith(("-H", "-P", "-L")) for v in args):
+            raise ValueError("args 不得改变 ADB 宿主或目标设备")
+        logger.debug("ADB command started: serial=%s timeout=%s", self.serial, seconds)
+        value = self._client._request("POST", "/api/adb/commands", serial=self.serial,
+                                      timeout=seconds + 10,
+                                      body={"args": args, "timeout_ms": max(1, round(seconds * 1000))})
+        try:
+            status = value["status"]
+            if status not in {"queued", "running", "completed", "failed", "timed_out"}:
+                raise ValueError("status")
+            # A successful synchronous result must contain its actual exit code.
+            exit_code = value["exit_code"] if status == "completed" else value.get("exit_code")
+            if (status == "completed" and type(exit_code) is not int) or (exit_code is not None and type(exit_code) is not int):
+                raise ValueError("exit_code")
+            stdout, stderr = value.get("stdout", ""), value.get("stderr", "")
+            truncated = value.get("truncated", False)
+            if not isinstance(stdout, str) or not isinstance(stderr, str) or type(truncated) is not bool:
+                raise ValueError("output")
+        except (KeyError, ValueError, TypeError) as error:
+            raise ProtocolError("ADB 响应缺少字段或字段类型不合法") from error
+        result = CommandResult(status, exit_code, stdout, stderr, truncated)
+        if status != "completed" or exit_code != 0 or truncated:
+            logger.warning("ADB command failed: serial=%s status=%s exit_code=%s truncated=%s", self.serial, status, exit_code, truncated)
+            raise CommandError(result)
+        logger.debug("ADB command completed: serial=%s", self.serial)
+        return result
+
+    def page_info(self, timeout: float = 10) -> PageInfo:
+        self._check_open()
+        value = self._client._request("GET", "/api/ui/page-info", serial=self.serial, timeout=_seconds(timeout))
+        try:
+            display = value["display"]
+            width, height = display["width"], display["height"]
+            if type(width) is not int or type(height) is not int or width <= 0 or height <= 0:
+                raise ValueError("display dimensions")
+        except (KeyError, ValueError, TypeError) as error:
+            raise ProtocolError("响应缺少有效 display.width/height") from error
+        return PageInfo(width, height)
+
+    def close(self):
+        self._closed = True
+
+    def __enter__(self):
+        self._check_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy/errors.py

@@ -0,0 +1,27 @@
+"""Explicit SDK errors; device actions are never automatically retried."""
+
+
+class SDKError(RuntimeError):
+    pass
+
+
+class ConnectionError(SDKError):
+    pass
+
+
+class ProtocolError(SDKError):
+    pass
+
+
+class HTTPError(SDKError):
+    def __init__(self, status: int, code: str, detail: str):
+        self.status = status
+        self.code = code
+        self.detail = detail
+        super().__init__(f"HTTP {status}: {code}: {detail}")
+
+
+class CommandError(SDKError):
+    def __init__(self, result):
+        self.result = result
+        super().__init__(f"ADB command {result.status}, exit_code={result.exit_code}")

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy/models.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    status: str
+    exit_code: int | None
+    stdout: str
+    stderr: str
+    truncated: bool
+
+
+@dataclass(frozen=True)
+class PageInfo:
+    width: int
+    height: int

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy_sdk.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: mywebscrcpy-sdk
+Version: 1.20.1
+Summary: Python client for MyWebScrcpy device automation
+Project-URL: Homepage, https://github.com/liuzhuogood/MyWebScrcpy
+Project-URL: Documentation, https://github.com/liuzhuogood/MyWebScrcpy/blob/main/packages/python-sdk/README.md
+Project-URL: Repository, https://github.com/liuzhuogood/MyWebScrcpy
+Project-URL: Issues, https://github.com/liuzhuogood/MyWebScrcpy/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.28
+
+# MyWebScrcpy Python SDK
+
+SDK 使用 HTTPX，支持 `Client`、绑定设备的 `Device.adb()`、`Device.page_info()` 和类型化结果。按键、点击、滑动及 ASCII 输入可通过明确的 ADB 参数执行。当前尚不提供视频解码、模板管理和匹配 API，也无需安装 OpenCV/PyAV。
+
+使用 Python 3.10+，从 PyPI 安装：
+
+```bash
+python -m pip install mywebscrcpy-sdk
+```
+
+也可从仓库根目录安装源码并运行示例：
+
+```bash
+python -m pip install ./packages/python-sdk
+python packages/python-sdk/examples/device_query.py DEVICE_SERIAL --base-url http://HOST:PORT
+```
+
+也可构建并安装 wheel：
+
+```bash
+python -m pip install build
+python -m build packages/python-sdk
+python -m pip install --find-links packages/python-sdk/dist mywebscrcpy-sdk
+```
+
+```python
+from mywebscrcpy import Client
+
+with Client("http://HOST:PORT") as client:
+    with client.device("DEVICE_SERIAL") as device:
+        result = device.adb(["shell", "getprop", "ro.product.model"], timeout=10)
+        print(result.stdout)
+        device.adb(["shell", "input", "keyevent", "3"], timeout=10)
+        size = device.page_info()
+        device.adb(["shell", "input", "tap", str(size.width // 2), str(size.height // 2)], timeout=10)
+```
+
+`timeout` 为秒，SDK 转换为接口的 `timeout_ms`。ADB 参数不得包含可执行文件名、设备选择或宿主切换选项。SDK 检查 HTTP 响应及实际 `status/exit_code`；失败、截断输出或超时抛异常，不自动重试动作。HTTP 超时后的设备结果可能未知，不应直接重发。
+
+`CommandResult` 包含 `status/exit_code/stdout/stderr/truncated`；`PageInfo` 包含正整数 `width/height`。必需字段缺失或类型错误抛 `ProtocolError`，不猜替代字段。`CommandError.result` 保留命令结果，`HTTPError` 保留 `status/code/detail`；连接错误使用 `ConnectionError`。
+
+`Client(headers=...)` 接收显式请求头，默认验证 TLS，可传 CA 路径。不会读取未知凭据、自动启动主服务或修改 root logger。Client/Device 可重复关闭，关闭后的对象拒绝操作。
+
+应用任务会释放同一套 SDK 源文件，并提供连接环境变量；配置的 Python 环境仍需安装 `httpx`。导出的脚本可在其他目录通过安装本 SDK 独立运行，远程操作要求服务与设备可达。
+
+接口依据 `web/openapi.json` 的 `/api/adb/commands` 和 `/api/ui/page-info`。安装版与应用内释放版共享源码，避免两套运行库。仅本机和受控接口已验证，真机及 Windows/Linux 原生链路仍待验收。
+
+SDK 版本与仓库根目录 `VERSION` 一致，Python 包版本去掉 `v` 前缀。修改 `VERSION` 后运行 `node scripts/sync-version.mjs`，同时更新主程序与 SDK 版本。
+
+GitHub Actions 的 `Publish Python SDK` 工作流在主分支的版本、SDK 或发布配置变更时运行，也支持 `v*` 标签和手动触发；构建检查及安装测试通过后发布未发布的版本，已存在的完整版本会跳过。仓库需在 Settings → Secrets and variables → Actions 配置 `PYPI_API_TOKEN`，值为有此项目发布权限的 PyPI API Token。只修改 SDK 而不更新版本号不会覆盖 PyPI 上已有的版本。

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+MANIFEST.in
+README.md
+pyproject.toml
+examples/device_query.py
+src/mywebscrcpy/__init__.py
+src/mywebscrcpy/client.py
+src/mywebscrcpy/device.py
+src/mywebscrcpy/errors.py
+src/mywebscrcpy/models.py
+src/mywebscrcpy_sdk.egg-info/PKG-INFO
+src/mywebscrcpy_sdk.egg-info/SOURCES.txt
+src/mywebscrcpy_sdk.egg-info/dependency_links.txt
+src/mywebscrcpy_sdk.egg-info/requires.txt
+src/mywebscrcpy_sdk.egg-info/top_level.txt
+tests/test_basic.py

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.28

mywebscrcpy_sdk-1.20.1/src/mywebscrcpy_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+mywebscrcpy

mywebscrcpy_sdk-1.20.1/tests/test_basic.py

@@ -0,0 +1,116 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+import httpx
+from mywebscrcpy import Client, CommandError, HTTPError, ProtocolError, SDKError
+
+
+class BasicContractTests(unittest.TestCase):
+    def fixture(self, response):
+        seen = []
+        client = Client("http://test.invalid")
+        client._http.close()
+        def handle(request):
+            seen.append(request)
+            return httpx.Response(200, json=response)
+        client._http = httpx.Client(base_url="http://test.invalid", transport=httpx.MockTransport(handle))
+        self.addCleanup(client.close)
+        return client, seen
+
+    def test_binding_units_optional_output_and_close(self):
+        client, seen = self.fixture({"status": "completed", "exit_code": 0})
+        with client.device("phone-A") as device:
+            result = device.adb(["shell", "getprop", "ro.product.model"], timeout=1.25)
+            self.assertEqual(result.stdout, "")
+        request = seen[0]
+        self.assertEqual(request.url.params["serial"], "phone-A")
+        self.assertEqual(json.loads(request.content), {"args": ["shell", "getprop", "ro.product.model"], "timeout_ms": 1250})
+        with self.assertRaises(SDKError):
+            device.adb(["shell"])
+        client.close()
+        client.close()
+        with self.assertRaises(SDKError):
+            client.device("phone-A")
+
+    def test_command_failure_truncation_and_missing_fields(self):
+        for response in [{"status": "failed", "exit_code": 1}, {"status": "timed_out"}, {"status": "completed", "exit_code": 0, "truncated": True}]:
+            client, seen = self.fixture(response)
+            with self.assertRaises(CommandError):
+                client.device("phone").adb(["shell"])
+            self.assertEqual(len(seen), 1, "actions must never retry")
+        for response in [{}, {"state": "completed", "exit_code": 0}, {"status": "completed"}, {"status": "completed", "exit_code": "0"}, {"status": "completed", "exit_code": 0, "stdout": None}]:
+            client, _ = self.fixture(response)
+            with self.assertRaises(ProtocolError):
+                client.device("phone").adb(["shell"])
+
+    def test_target_override_and_timeouts_reject_before_request(self):
+        client, seen = self.fixture({"status": "completed", "exit_code": 0})
+        device = client.device("phone")
+        for args in [["-s", "other"], ["adb", "devices"], ["shell", "-Hhost"], [], ["shell", ""]]:
+            with self.assertRaises(ValueError):
+                device.adb(args)
+        for timeout in [0, -1, 601, float("nan"), True]:
+            with self.assertRaises(ValueError):
+                device.adb(["shell"], timeout=timeout)
+        self.assertEqual(seen, [])
+
+    def test_exact_page_info_fields(self):
+        client, _ = self.fixture({"display": {"width": 1080, "height": 2400}})
+        self.assertEqual(client.device("phone").page_info().height, 2400)
+        for response in [{"screen": {"width": 1080, "height": 2400}}, {"display": {"width": 0, "height": 2400}}]:
+            client, _ = self.fixture(response)
+            with self.assertRaises(ProtocolError):
+                client.device("phone").page_info()
+
+    def test_http_error_retains_exact_error_fields(self):
+        client = Client("http://test.invalid")
+        client._http.close()
+        client._http = httpx.Client(base_url="http://test.invalid", transport=httpx.MockTransport(lambda r: httpx.Response(400, json={"error": "invalid_request", "message": "bad args"})))
+        with client:
+            with self.assertRaises(HTTPError) as caught:
+                client.device("phone").adb(["shell"])
+        self.assertEqual((caught.exception.status, caught.exception.code, caught.exception.detail), (400, "invalid_request", "bad args"))
+
+    def test_portable_example_runs_outside_application_without_vision(self):
+        requests = []
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                requests.append((self.path, json.loads(self.rfile.read(int(self.headers["Content-Length"])))))
+                value = json.dumps({"status": "completed", "exit_code": 0, "stdout": "Portable Phone\n"}).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(value)))
+                self.end_headers()
+                self.wfile.write(value)
+            def log_message(self, *args):
+                pass
+        server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        thread = threading.Thread(target=server.serve_forever)
+        thread.start()
+        try:
+            sample = Path(__file__).resolve().parents[1] / "examples/device_query.py"
+            with tempfile.TemporaryDirectory() as directory:
+                copied = Path(directory) / "workflow.py"
+                copied.write_text(sample.read_text(), encoding="utf-8")
+                result = subprocess.run([sys.executable, str(copied), "portable-phone", "--base-url", f"http://127.0.0.1:{server.server_port}"], cwd=directory, capture_output=True, text=True, timeout=10)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertIn("Portable Phone", result.stdout)
+            self.assertEqual(requests[0][1]["timeout_ms"], 10000)
+            self.assertIn("serial=portable-phone", requests[0][0])
+            self.assertNotIn("cv2", sys.modules)
+            self.assertNotIn("av", sys.modules)
+        finally:
+            server.shutdown()
+            server.server_close()
+            thread.join()
+
+
+if __name__ == "__main__":
+    unittest.main()