Python API 使用规范

Python 2.x 从 bc_revo3_sdk.main_mod 导入公开对象，领域操作通过 Manager 和 Hand 完成。类型和精确签名以正式 API 参考手册为准。

生命周期与资源释放

• 在 asyncio 事件循环中调用返回 Awaitable 的方法，不要在同步回调中遗漏 await。
• 使用 async with，或在 try/finally 中依次关闭 Hand 和 Manager。
• 订阅和 ServoSession 拥有独立生命周期，必须在所有正常、异常和取消路径中关闭。
• 断线后先关闭旧对象，再通过 Manager 重新连接。旧的运动句柄、订阅和 ServoSession 不得复用。
• 应用退出时等待清理完成，避免串口、CAN 设备或后台任务仍被占用。

完整连接与清理结构见 quickstart.py，多设备资源管理见 multi_hand.py。

异步、超时与取消

• 运动方法返回 MotionHandle 不代表物理运动已经完成；等待结果时始终设置有限超时。
• 超时不等于指令未执行。若 operation_effect 为 Indeterminate，先读取 State 确认设备实际状态，再决定是否重试。
• 任务被取消时仍须执行 finally 清理。关闭订阅或会话，不要只取消外层 asyncio.Task。
• 高频目标使用 ServoSession，不要循环调用离散运动接口模拟流控。
• 为 Servo 设置明确的发送节拍和命令超时；应用调度频率不应被视为总线或固件的固定频率保证。

运动等待与取消见 trajectory_control.py，连续控制见 streaming_control.py。

错误与恢复

• 捕获 SdkError，根据 code、operation_effect、recovery_requirement 和 retryable 决定恢复流程，不要只匹配错误文本。
• 重试前判断操作是否可能已经生效；设备状态不确定时，优先读取 State 和 Health。
• 重连后重新执行设备信息、关节布局和健康状态预检，再恢复运动控制。
• 不通过无限重试掩盖端口占用、资源泄漏或持续硬件故障。

结构化错误处理流程见错误处理与恢复，连接恢复见连接、发现与多设备。

数据、并发与控制权

• 使用序列类型传入关节数组，并根据当前 JointLayout 验证长度；重连或更换设备后重新读取布局。
• 同一只手的运动控制应由一个明确的应用组件持有。不要让离散运动、Servo、示教或回放并发争用控制权。
• 订阅用于周期拉取，不保存历史数据；需要跨任务传递或持久化时，使用有界队列并定义丢帧策略。
• 不在订阅处理路径中执行长时间阻塞工作，以免影响事件循环中的清理、超时和控制任务。

状态订阅示例见 subscriptions.py。首次集成请从快速开始开始。