ubox-py-sdk 0.1.8

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

优测 Python UBox

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

功能特性

• 🚀 简单易用: 提供直观的 Python API 接口
• 🔑 JWT Token管理: 自动token生成、过期检测和懒申请机制
• 🛡️ 错误处理: 完善的异常处理和错误信息
• 📚 类型提示: 完整的类型注解支持
• 🔧 上下文管理: 支持 with 语句自动管理连接

安装

使用 uv 安装（推荐）

# 安装 uv（如果还没有安装）

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

使用 pip 安装

确保python版本>=3.9.5

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. 本地模式

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

快速开始

运行示例

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

# 运行基础示例文件
python examples/example.py

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

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

基础使用

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}")

日志配置

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/                   # 使用示例目录
│   └── 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