ubox-py-sdk 0.2.20

用于操作优测设备的python-sdk

优测 Python UBox

用于操作优测设备的 Python UBox 包，提供简单易用的 API 接口来与优测设备进行交互。

功能特性

• 🚀 简单易用: 提供直观的 Python API 接口
• 🔑 JWT Token管理: 自动token生成、过期检测和懒申请机制
• 🛡️ 错误处理: 完善的异常处理和错误信息
• 📚 类型提示: 完整的类型注解支持
• 🔧 上下文管理: 支持 with 语句自动管理连接
• 📱 设备操作: 支持点击、滑动、输入、截图、录制等设备操作
• 🔍 智能识别: 支持UI控件、图像匹配、OCR文字识别等多种定位方式
• 📊 性能监控: 支持设备性能数据采集和分析
• 📝 日志采集: 支持Android/鸿蒙设备logcat日志采集和过滤
• 🚨 ANR/Crash监控: 支持应用ANR和Crash问题检测，自动截图和日志收集

安装

使用 uv 安装（推荐）

# 安装 uv（如果还没有安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
或
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 创建虚拟环境
uv venv
# 安装包
uv pip install -U ubox-py-sdk -i https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

使用 pip 安装

确保python版本>=3.10,<3.12

python -m pip install ubox-py-sdk --index-url https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

架构说明

1. 默认模式（自动占用设备）

   • 特点：自动占用、续期、释放设备

2. 默认模式（使用预获取的authCode）

   • 适用：已有authCode
   • 特点：跳过占用流程，更稳定可靠

3. 本地模式

   • 适用：仅限本地设备调试
   • 特点：直接访问，性能更好
   • 注意：仅限本地调试自动化脚本

快速开始

运行示例

我们提供了完整的示例文件来帮助你快速上手：

# 运行基础示例文件（包含logcat功能演示）
python examples/example.py

# 运行事件处理示例
python examples/event_handler_example.py

# 运行设备列表示例
python examples/device_list_example.py

注意: example.py 包含了完整的功能演示，包括：

• 设备操作（点击、滑动、输入等）
• 截图录制功能
• 性能监控采集
• logcat日志采集（仅Android/鸿蒙设备）

基础使用

from ubox_py_sdk import UBox, UBoxConnectionError, UBoxAuthenticationError, OSType, RunMode

try:
    # 调试模式示例
    with UBox(secret_id="sid", secret_key="skey") as client:
        device = client.init_device(udid="device-001", os_type=OSType.ANDROID)

except UBoxAuthenticationError as e:
    print(f"认证失败: {e}")
except UBoxConnectionError as e:
    print(f"连接失败: {e}")
except Exception as e:
    print(f"其他错误: {e}")

设备连通性探测

在占用设备前，可以使用 probe_device 方法探测设备连通性，该方法不会占用设备：

is_connected = ubox.probe_device(
  udid="device-001",
  os_type=OSType.ANDROID,
  force_proxy=False  # 可选：是否强制使用代理
)

if is_connected:
  print("✅ 设备可以正常连接")
  # 现在可以安全地占用设备
  device = ubox.init_device(udid="device-001", os_type=OSType.ANDROID)
else:
  print("❌ 设备无法连接")

主要功能示例

设备操作

# 点击操作
device.click_pos([0.5, 0.5])  # 点击屏幕中心
# 滑动操作
device.slide_pos([0.1, 0.5], [0.9, 0.5])  # 左右滑动
# 文本输入
device.input_text("Hello World")

性能监控

# 开始性能采集
device.perf_start(
    container_bundle_identifier="com.example.app"
)
# 停止性能采集并保存数据
device.perf_stop("./perf_output")

日志采集（仅Android/鸿蒙）

# 启动logcat日志采集
task = device.logcat_start(
    file="./logcat_output/app_logs.txt",  # 用户指定的最终保存路径
    clear=True,
    re_filter=".*MyApp.*"  # 过滤包含MyApp的日志
)

# 运行一段时间后停止
time.sleep(10)
success = task.stop()  # 停止特定任务

if success:
    print(f"logcat日志已保存到: {task.file_path}")

ANR/Crash监控（仅Android/鸿蒙）

# 启动ANR/Crash监控（不采集AM监控日志）
success = device.anr_start(package_name="com.example.app")
if success:
    print("ANR监控已启动")
    
    # 运行一段时间后停止监控
    time.sleep(30)
    
    # 停止监控并下载文件
    result = device.anr_stop(output_directory="./anr_output")
    print(f"监控结果: ANR={result['anr_count']}, Crash={result['crash_count']}")
    print(f"截图文件: {result['screenshots']}")
    print(f"日志文件: {result['logcat_file']}")

# 启动ANR/Crash监控（采集AM监控日志）
success = device.anr_start(package_name="com.example.app", collect_am_monitor=True)
if success:
    print("ANR监控已启动（包含AM监控）")
    
    # 停止监控并下载文件
    result = device.anr_stop(output_directory="./anr_output")
    print(f"AM监控文件: {result['am_monitor_file']}")

日志配置

UBox SDK 提供了灵活的日志配置功能：

# 默认配置（仅控制台输出）
ubox = UBox(secret_id="sid", secret_key="skey")

# 自定义日志级别
ubox = UBox(
    secret_id="sid", 
    secret_key="skey",
    log_level="DEBUG"  # 显示详细调试信息
)

# 文件日志输出
ubox = UBox(
    secret_id="sid", 
    secret_key="skey",
    log_level="INFO",
    log_to_file=True,
    log_file_path="logs/ubox.log"  # 自动创建目录
)

# 生产环境配置
ubox = UBox(
    secret_id="sid", 
    secret_key="skey",
    log_level="WARNING",  # 只记录警告和错误
    log_to_file=True,
    log_file_path="logs/production.log"
)

PhonePlatform 枚举值说明

• PhonePlatform.ANDROID = 1: Android设备
• PhonePlatform.IOS = 2: iOS设备
• PhonePlatform.HARMONYOS = 3: 鸿蒙设备
• PhonePlatform.HARMONYOS_NEXT = 4: 鸿蒙NEXT设备

OSType

设备操作系统类型枚举：

• OSType.ANDROID: Android设备
• OSType.IOS: iOS设备
• OSType.HM: HarmonyOS设备

异常类

• UBoxError: 基础异常类
• UBoxConnectionError: 连接异常
• UBoxAuthenticationError: 认证异常
• UBoxValidationError: 数据验证异常
• UBoxTimeoutError: 超时异常
• UBoxRateLimitError: 速率限制异常
• UBoxDeviceError: 设备异常

项目结构

ubox-py-sdk/
├── src/                        # 源代码目录
│   └── ubox_py_sdk/           # 主包目录
│       ├── __init__.py         # 包初始化文件，导出主要API
│       ├── client.py           # 主要客户端类，管理连接和认证
│       ├── device.py           # 设备管理类，封装设备操作接口
│       ├── device_operations.py # 设备操作实现，包含各种操作的具体逻辑
│       ├── exceptions.py       # 异常定义，包含各种错误类型
│       ├── jwt_util.py         # JWT工具类，处理认证token
│       ├── logger.py           # 日志工具，提供统一的日志记录
│       └── models.py           # 数据模型，定义各种数据结构
├── examples/                   # 使用示例目录
│   ├── example.py             # 基础功能演示（包含logcat示例）
│   ├── event_handler_example.py # 事件处理示例
│   ├── device_list_example.py # 设备列表示例
│   └── README.md              # 示例说明文档
├── api.py                     # API接口定义文件
├── pyproject.toml             # 项目配置文件
├── Makefile                   # 构建和部署脚本
├── uv.lock                    # 依赖锁定文件
├── .python-version            # Python版本文件
├── README.md                  # 项目说明文档
├── ubox-py-sdk接口文档.md     # 详细接口文档
└── .gitignore                 # Git忽略文件

编译

uv build

发布包

uv publish --publish-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple