devicebase 2026.4.1__tar.gz

devicebase-2026.4.1/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pytest)",
+      "Bash(mypy src:*)",
+      "Bash(ruff check:*)",
+      "WebFetch(domain:localhost)",
+      "Bash(curl -s http://localhost:3410/openapi.json)",
+      "Bash(curl -s http://localhost:3410/docs)",
+      "Bash(pytest -v --tb=short)",
+      "Bash(ruff format:*)",
+      "Bash(pytest -v)",
+      "Bash(pytest --tb=short -q)"
+    ]
+  }
+}

devicebase-2026.4.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+dist/
+build/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.tox/
+.venv/
+venv/
+*.egg

devicebase-2026.4.1/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **DeviceBase Python SDK** — a client library for the TestClaw device automation API. It provides both HTTP and WebSocket interfaces for controlling Android devices.
+
+## Project Structure
+
+```
+src/devicebase/
+├── __init__.py          # Package exports
+├── client.py            # Main DeviceBaseClient (high-level interface)
+├── http_client.py       # DeviceBaseHttpClient (HTTP API)
+├── websocket_client.py  # MinicapClient & MinitouchClient (WebSocket streams)
+└── models.py            # Data models (Point, Bounds, DeviceInfo, etc.)
+
+tests/                   # Test suite (pytest)
+pyproject.toml           # Project config (hatch + pytest + mypy + ruff)
+```
+
+## Common Commands
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy src
+
+# Lint and format
+ruff check src tests --fix
+ruff format src tests
+```
+
+## Configuration
+
+The SDK supports configuration via environment variables or constructor parameters:
+
+- `DEVICEBASE_BASE_URL` / `base_url`: API base URL (default: https://api.devicebase.cn)
+- `DEVICEBASE_API_KEY` / `api_key`: JWT API key for authentication
+
+Both HTTP and HTTPS protocols are supported.
+
+## Architecture
+
+### Main Client (`DeviceBaseClient`)
+
+High-level interface that combines HTTP and WebSocket operations:
+
+```python
+from devicebase import DeviceBaseClient
+
+client = DeviceBaseClient()
+
+# HTTP operations
+info = client.get_device_info("device123")
+client.tap("device123", x=100, y=200)
+screenshot = client.get_screenshot("device123")
+
+# WebSocket clients
+minicap = client.minicap_client("device123")
+minitouch = client.minitouch_client("device123")
+```
+
+### HTTP Client (`DeviceBaseHttpClient`)
+
+Handles all REST API calls with JWT authentication:
+- Device info, touch operations, app control
+- Screenshots (JPEG bytes)
+- UI hierarchy dumping
+
+### WebSocket Clients
+
+- `MinicapClient`: Real-time screen streaming (JPEG frames)
+- `MinitouchClient`: Low-level touch event control
+
+### Models
+
+Immutable dataclasses for type safety:
+- `Point`, `Bounds`: Touch coordinates
+- `DeviceInfo`, `AppInfo`, `HierarchyInfo`: API responses
+- `OperationResult`: Command results
+
+## Error Handling
+
+Custom exceptions:
+- `AuthenticationError`: Missing/invalid API key
+- `DeviceNotFoundError`: Device not connected (404)
+- `ValidationError`: Invalid request parameters (422)
+- `DeviceBaseError`: Base exception for all SDK errors
+
+## Dependencies
+
+Runtime: `httpx`, `websockets`, `pydantic`
+Dev: `pytest`, `pytest-asyncio`, `mypy`, `ruff`, `respx`

devicebase-2026.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UUSENSE, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devicebase-2026.4.1/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: devicebase
+Version: 2026.4.1
+Summary: Devicebase Python SDK
+Project-URL: Homepage, https://github.com/uusense/python-devicebase
+Project-URL: Repository, https://github.com/uusense/python-devicebase
+Author: Richie
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Devicebase Python SDK
+
+Python SDK for the Devicebase device automation API. Control Android/HarmonyOS/iOS devices programmatically via HTTP and WebSocket interfaces.
+
+## Installation
+
+```bash
+pip install devicebase
+```
+
+## Quick Start
+
+```python
+from devicebase import DeviceBaseClient
+
+# Initialize client (reads DEVICEBASE_BASE_URL and DEVICEBASE_API_KEY from env)
+client = DeviceBaseClient()
+
+# Get device info
+info = client.get_device_info("device123")
+
+# Control the device
+client.tap("device123", x=100, y=200)
+client.swipe("device123", x1=0, y1=500, x2=500, y2=500)
+client.launch_app("device123", "com.example.app")
+
+# Take a screenshot
+screenshot_bytes = client.get_screenshot("device123")
+with open("screenshot.jpg", "wb") as f:
+    f.write(screenshot_bytes)
+```
+
+## Configuration
+
+Configure via environment variables or constructor parameters:
+
+```python
+import os
+
+# Option 1: Environment variables (optional, has default values)
+os.environ["DEVICEBASE_API_KEY"] = "your-jwt-token"
+# DEVICEBASE_BASE_URL defaults to https://api.devicebase.cn if not set
+client = DeviceBaseClient()
+
+# Option 2: Constructor parameters
+client = DeviceBaseClient(
+    base_url="https://api.devicebase.cn",  # or http://localhost:3410 for local server
+    api_key="your-jwt-token"
+)
+```
+
+Both HTTP and HTTPS protocols are supported.
+
+## Device Control
+
+### Touch Operations
+
+```python
+# Single tap
+client.tap("device123", x=100, y=200)
+
+# Double tap
+client.double_tap("device123", x=100, y=200)
+
+# Long press
+client.long_press("device123", x=100, y=200)
+
+# Swipe
+client.swipe("device123", x1=0, y1=500, x2=500, y2=500)
+```
+
+### Navigation
+
+```python
+# Press back button
+client.back("device123")
+
+# Press home button
+client.home("device123")
+```
+
+### App Operations
+
+```python
+# Launch an app
+client.launch_app("device123", "com.example.app")
+
+# Get current foreground app
+app_info = client.get_current_app("device123")
+print(app_info.data["package"])
+```
+
+### Text Input
+
+```python
+# Input text into focused field
+client.input_text("device123", "Hello World")
+
+# Clear text in focused field
+client.clear_text("device123")
+```
+
+### UI Hierarchy
+
+```python
+# Dump UI hierarchy (useful for automation)
+hierarchy = client.dump_hierarchy("device123")
+print(hierarchy.data)
+```
+
+## Screenshots
+
+```python
+# Get screenshot as JPEG bytes
+screenshot = client.get_screenshot("device123")
+
+# Download screenshot as file attachment
+download = client.download_screenshot("device123")
+```
+
+## WebSocket Streaming
+
+### Screen Streaming (Minicap)
+
+```python
+import asyncio
+
+async def stream_screen():
+    client = DeviceBaseClient()
+    minicap = client.minicap_client("device123")
+
+    async for frame in minicap.stream_frames():
+        # frame is JPEG bytes
+        with open("frame.jpg", "wb") as f:
+            f.write(frame)
+
+asyncio.run(stream_screen())
+```
+
+### Touch Control (Minitouch)
+
+```python
+import asyncio
+
+async def control_touch():
+    client = DeviceBaseClient()
+    minitouch = client.minitouch_client("device123")
+
+    async with minitouch:
+        # Tap at coordinates
+        await minitouch.tap(100, 200)
+
+        # Swipe gesture
+        await minitouch.swipe(0, 500, 500, 500, duration_ms=300)
+
+asyncio.run(control_touch())
+```
+
+## Error Handling
+
+```python
+from devicebase import (
+    DeviceBaseClient,
+    AuthenticationError,
+    DeviceNotFoundError,
+    ValidationError,
+)
+
+try:
+    client = DeviceBaseClient()
+    info = client.get_device_info("device123")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except DeviceNotFoundError:
+    print("Device not found or not connected")
+except ValidationError as e:
+    print(f"Invalid request: {e}")
+```
+
+## Development
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy src
+
+# Format and lint
+ruff check src tests --fix
+ruff format src tests
+```
+
+## License
+
+MIT

devicebase-2026.4.1/README.md

@@ -0,0 +1,199 @@
+# Devicebase Python SDK
+
+Python SDK for the Devicebase device automation API. Control Android/HarmonyOS/iOS devices programmatically via HTTP and WebSocket interfaces.
+
+## Installation
+
+```bash
+pip install devicebase
+```
+
+## Quick Start
+
+```python
+from devicebase import DeviceBaseClient
+
+# Initialize client (reads DEVICEBASE_BASE_URL and DEVICEBASE_API_KEY from env)
+client = DeviceBaseClient()
+
+# Get device info
+info = client.get_device_info("device123")
+
+# Control the device
+client.tap("device123", x=100, y=200)
+client.swipe("device123", x1=0, y1=500, x2=500, y2=500)
+client.launch_app("device123", "com.example.app")
+
+# Take a screenshot
+screenshot_bytes = client.get_screenshot("device123")
+with open("screenshot.jpg", "wb") as f:
+    f.write(screenshot_bytes)
+```
+
+## Configuration
+
+Configure via environment variables or constructor parameters:
+
+```python
+import os
+
+# Option 1: Environment variables (optional, has default values)
+os.environ["DEVICEBASE_API_KEY"] = "your-jwt-token"
+# DEVICEBASE_BASE_URL defaults to https://api.devicebase.cn if not set
+client = DeviceBaseClient()
+
+# Option 2: Constructor parameters
+client = DeviceBaseClient(
+    base_url="https://api.devicebase.cn",  # or http://localhost:3410 for local server
+    api_key="your-jwt-token"
+)
+```
+
+Both HTTP and HTTPS protocols are supported.
+
+## Device Control
+
+### Touch Operations
+
+```python
+# Single tap
+client.tap("device123", x=100, y=200)
+
+# Double tap
+client.double_tap("device123", x=100, y=200)
+
+# Long press
+client.long_press("device123", x=100, y=200)
+
+# Swipe
+client.swipe("device123", x1=0, y1=500, x2=500, y2=500)
+```
+
+### Navigation
+
+```python
+# Press back button
+client.back("device123")
+
+# Press home button
+client.home("device123")
+```
+
+### App Operations
+
+```python
+# Launch an app
+client.launch_app("device123", "com.example.app")
+
+# Get current foreground app
+app_info = client.get_current_app("device123")
+print(app_info.data["package"])
+```
+
+### Text Input
+
+```python
+# Input text into focused field
+client.input_text("device123", "Hello World")
+
+# Clear text in focused field
+client.clear_text("device123")
+```
+
+### UI Hierarchy
+
+```python
+# Dump UI hierarchy (useful for automation)
+hierarchy = client.dump_hierarchy("device123")
+print(hierarchy.data)
+```
+
+## Screenshots
+
+```python
+# Get screenshot as JPEG bytes
+screenshot = client.get_screenshot("device123")
+
+# Download screenshot as file attachment
+download = client.download_screenshot("device123")
+```
+
+## WebSocket Streaming
+
+### Screen Streaming (Minicap)
+
+```python
+import asyncio
+
+async def stream_screen():
+    client = DeviceBaseClient()
+    minicap = client.minicap_client("device123")
+
+    async for frame in minicap.stream_frames():
+        # frame is JPEG bytes
+        with open("frame.jpg", "wb") as f:
+            f.write(frame)
+
+asyncio.run(stream_screen())
+```
+
+### Touch Control (Minitouch)
+
+```python
+import asyncio
+
+async def control_touch():
+    client = DeviceBaseClient()
+    minitouch = client.minitouch_client("device123")
+
+    async with minitouch:
+        # Tap at coordinates
+        await minitouch.tap(100, 200)
+
+        # Swipe gesture
+        await minitouch.swipe(0, 500, 500, 500, duration_ms=300)
+
+asyncio.run(control_touch())
+```
+
+## Error Handling
+
+```python
+from devicebase import (
+    DeviceBaseClient,
+    AuthenticationError,
+    DeviceNotFoundError,
+    ValidationError,
+)
+
+try:
+    client = DeviceBaseClient()
+    info = client.get_device_info("device123")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except DeviceNotFoundError:
+    print("Device not found or not connected")
+except ValidationError as e:
+    print(f"Invalid request: {e}")
+```
+
+## Development
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy src
+
+# Format and lint
+ruff check src tests --fix
+ruff format src tests
+```
+
+## License
+
+MIT

devicebase-2026.4.1/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "devicebase"
+version = "2026.4.1"
+description = "Devicebase Python SDK"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Richie" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "websockets>=12.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-httpx>=0.30.0",
+    "mypy>=1.0",
+    "ruff>=0.3.0",
+    "respx>=0.22.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/uusense/python-devicebase"
+Repository = "https://github.com/uusense/python-devicebase"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/devicebase"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

devicebase-2026.4.1/src/devicebase/__init__.py

@@ -0,0 +1,44 @@
+"""DeviceBase Python SDK for TestClaw device automation."""
+
+from devicebase.client import DeviceBaseClient
+from devicebase.http_client import (
+    AuthenticationError,
+    DeviceBaseError,
+    DeviceNotFoundError,
+    ValidationError,
+)
+from devicebase.models import (
+    AppInfo,
+    Bounds,
+    DeviceInfo,
+    HierarchyInfo,
+    InputTextRequest,
+    LaunchAppRequest,
+    OperationResult,
+    Point,
+)
+from devicebase.websocket_client import MinicapClient, MinitouchClient
+
+__version__ = "2026.4.1"
+
+__all__ = [
+    # Main client
+    "DeviceBaseClient",
+    # Exceptions
+    "AuthenticationError",
+    "DeviceBaseError",
+    "DeviceNotFoundError",
+    "ValidationError",
+    # Models
+    "AppInfo",
+    "Bounds",
+    "DeviceInfo",
+    "HierarchyInfo",
+    "InputTextRequest",
+    "LaunchAppRequest",
+    "OperationResult",
+    "Point",
+    # WebSocket clients
+    "MinicapClient",
+    "MinitouchClient",
+]