openarm-sdk 0.1.0__py3-none-any.whl

openarm_sdk/__init__.py

@@ -0,0 +1,191 @@
+"""Public API for the OpenArm Python SDK."""
+
+from .client import OpenArmClient
+from .end_effectors import EndEffectorClient
+from .teleop import TeleopClient
+from .joint_servo import JointServoClient, JointServoSession
+from .enums import (
+    Arm,
+    CartesianAxis,
+    DependencyKind,
+    EndEffectorOperation,
+    EndEffectorType,
+    FaultSeverity,
+    HealthServingStatus,
+    JogDirection,
+    JogSessionState,
+    JogStopReason,
+    JogType,
+    MotorFaultFlag,
+    MotionExecutionMode,
+    MotionTaskState,
+    MotionTaskType,
+    OperationMode,
+    PositionUnit,
+    ReadinessState,
+    RecordingState,
+    RecordingSource,
+    TeleopSource,
+    TeleopState,
+    JointServoState,
+    QnBotControlMode,
+    QnBotGripperControlMode,
+)
+from .jog import JogClient, JogSessionHandle
+from .joint_parameters import JointParametersClient
+from .mode import ModeClient
+from .safety import SafetyClient
+from .recording import RecordingClient
+from .errors import (
+    ClientClosedError,
+    IncompatibleServerError,
+    OpenArmError,
+    OpenArmOperationError,
+    ProtocolError,
+    ResourceExhaustedError,
+    RpcTimeoutError,
+    RpcTransportError,
+    TeleopOperationError,
+)
+from .models import (
+    CapabilityStatus,
+    ArmHardwareState,
+    ArmJointParameters,
+    JointParameters,
+    JointGains,
+    RecordingInfo,
+    RecordingKeypoint,
+    RecordingSegment,
+    RecordingTimelineItem,
+    RecordingImportResult,
+    RecordingCsvChunk,
+    EmergencyStopState,
+    CartesianPose,
+    CartesianPosition,
+    ControllerStatus,
+    DependencyStatus,
+    EndEffectorPose,
+    EndEffectorPoseSnapshot,
+    EndEffectorInfo,
+    EndEffectorInfoSnapshot,
+    EndEffectorOperationCapability,
+    EndEffectorState,
+    EndEffectorStateSnapshot,
+    JointState,
+    JogSession,
+    JogStopResult,
+    MotorStatus,
+    MotorStatusSnapshot,
+    MotionCommandResult,
+    MotionTask,
+    MotionTaskWaitResult,
+    OperationResult,
+    Quaternion,
+    ServerInfo,
+    SystemArmStatus,
+    SystemFault,
+    SystemStatus,
+    SystemTeleoperationStatus,
+    TeleopSourceStatus,
+    JointServoFeedback,
+    TeleopManagerStatus,
+    TeleopManagerResult,
+    TeleopRunningStatus,
+    QnBotScalingAndOffset,
+    QnBotTeleopConfig,
+)
+
+__all__ = [
+    "JointServoClient",
+    "JointServoSession",
+    "JointServoState",
+    "JointServoFeedback",
+    "TeleopClient",
+    "TeleopSource",
+    "TeleopState",
+    "TeleopSourceStatus",
+    "TeleopManagerStatus",
+    "TeleopManagerResult",
+    "TeleopRunningStatus",
+    "TeleopOperationError",
+    "QnBotControlMode",
+    "QnBotGripperControlMode",
+    "QnBotScalingAndOffset",
+    "QnBotTeleopConfig",
+    "Arm",
+    "RecordingClient",
+    "RecordingState",
+    "RecordingSource",
+    "RecordingInfo",
+    "RecordingKeypoint",
+    "RecordingSegment",
+    "RecordingTimelineItem",
+    "RecordingImportResult",
+    "RecordingCsvChunk",
+    "ArmHardwareState",
+    "ArmJointParameters",
+    "JointParameters",
+    "JointParametersClient",
+    "JointGains",
+    "EmergencyStopState",
+    "SafetyClient",
+    "CapabilityStatus",
+    "CartesianPose",
+    "CartesianPosition",
+    "CartesianAxis",
+    "ClientClosedError",
+    "ControllerStatus",
+    "DependencyKind",
+    "DependencyStatus",
+    "EndEffectorPose",
+    "EndEffectorPoseSnapshot",
+    "EndEffectorClient",
+    "EndEffectorInfo",
+    "EndEffectorInfoSnapshot",
+    "EndEffectorOperation",
+    "EndEffectorOperationCapability",
+    "EndEffectorState",
+    "EndEffectorStateSnapshot",
+    "EndEffectorType",
+    "FaultSeverity",
+    "HealthServingStatus",
+    "IncompatibleServerError",
+    "JogClient",
+    "JogDirection",
+    "JogSession",
+    "JogSessionHandle",
+    "JogSessionState",
+    "JogStopReason",
+    "JogStopResult",
+    "JogType",
+    "JointState",
+    "MotorFaultFlag",
+    "MotorStatus",
+    "MotorStatusSnapshot",
+    "MotionCommandResult",
+    "MotionExecutionMode",
+    "MotionTask",
+    "MotionTaskState",
+    "MotionTaskType",
+    "MotionTaskWaitResult",
+    "ModeClient",
+    "OpenArmClient",
+    "OpenArmError",
+    "OpenArmOperationError",
+    "OperationResult",
+    "OperationMode",
+    "PositionUnit",
+    "ProtocolError",
+    "ReadinessState",
+    "Quaternion",
+    "ResourceExhaustedError",
+    "RpcTimeoutError",
+    "RpcTransportError",
+    "ServerInfo",
+    "SystemArmStatus",
+    "SystemFault",
+    "SystemStatus",
+    "SystemTeleoperationStatus",
+]
+
+__version__ = "0.1.0"

openarm_sdk/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal SDK helpers; not part of the public API."""

openarm_sdk/_internal/validation.py

@@ -0,0 +1,202 @@
+"""Shared validation helpers."""
+
+from __future__ import annotations
+
+import math
+
+from ..enums import Arm
+
+
+def validate_timeout(timeout: float | None, *, name: str = "timeout") -> None:
+    """校验 RPC 超时时间，允许使用 None 取消 deadline。
+
+    参数：
+        timeout: 本次 gRPC deadline，单位秒；None 表示不设置 deadline。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+
+    原有说明：
+    Validate a gRPC timeout while allowing None for no deadline.
+    """
+
+    if timeout is None:
+        return
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError(f"{name} must be a positive finite number or None")
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError(f"{name} must be a positive finite number or None")
+
+
+def encode_arm(arm: Arm, *, allow_both: bool = True) -> int:
+    """校验机械臂枚举并转换为协议中的机械臂编号。
+
+    参数：
+        arm: 机械臂枚举 Arm.LEFT、Arm.RIGHT 或 Arm.BOTH，BOTH 在协议中编码为 0。
+        allow_both: 是否允许把 Arm.BOTH 作为本次请求目标。
+
+    原有说明：
+    Validate a public Arm and return its current protobuf wire value.
+    """
+
+    if not isinstance(arm, Arm):
+        raise TypeError("arm must be an openarm_sdk.Arm value")
+    if arm is Arm.UNKNOWN:
+        raise ValueError("Arm.UNKNOWN cannot be sent to RCG")
+    if not allow_both and arm is Arm.BOTH:
+        raise ValueError("Arm.BOTH is not allowed for this operation")
+    return int(arm)
+
+
+def validate_rate_hz(rate_hz: int, *, maximum: int) -> None:
+    """校验订阅频率的整数类型和上限，0 表示由服务端选择默认频率。
+
+    参数：
+        rate_hz: 请求订阅频率，单位 Hz，允许 0～100 的整数；0 选择服务端默认。
+        maximum: 允许的频率上限，单位 Hz。
+
+    原有说明：
+    Validate a requested polling rate, where zero selects the default.
+    """
+
+    if isinstance(rate_hz, bool) or not isinstance(rate_hz, int):
+        raise TypeError("rate_hz must be an integer")
+    if rate_hz < 0 or rate_hz > maximum:
+        raise ValueError(f"rate_hz must be between 0 and {maximum}")
+
+
+def validate_percent(value: int, *, name: str, allow_zero: bool = True) -> int:
+    """校验控制参数是否为允许范围内的整数百分比。
+
+    参数：
+        value: 待校验的整数百分比数值。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+        allow_zero: 百分比校验是否允许取 0；False 时最小值为 1。
+
+    原有说明：
+    Validate an integer percentage used by the current motion contract.
+    """
+
+    minimum = 0 if allow_zero else 1
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer")
+    if value < minimum or value > 100:
+        raise ValueError(f"{name} must be between {minimum} and 100")
+    return value
+
+
+def validate_finite_values(
+    values: object, *, name: str, length: int
+) -> tuple[float, ...]:
+    """校验定长数值序列并转换为有限浮点数元组。
+
+    参数：
+        values: 需要校验或转换的输入值序列。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+        length: 要求的序列元素数量。
+
+    原有说明：
+    Validate a fixed-size numeric sequence and return normalized floats.
+    """
+
+    if isinstance(values, (str, bytes)):
+        raise TypeError(f"{name} must be a sequence of numbers")
+    try:
+        raw_values = tuple(values)  # type: ignore[arg-type]
+    except TypeError as error:
+        raise TypeError(f"{name} must be a sequence of numbers") from error
+    if any(isinstance(value, bool) for value in raw_values):
+        raise TypeError(f"{name} must not contain bool values")
+    try:
+        normalized = tuple(float(value) for value in raw_values)
+    except (TypeError, ValueError) as error:
+        raise TypeError(f"{name} must be a sequence of numbers") from error
+    if len(normalized) != length:
+        raise ValueError(f"{name} must contain exactly {length} values")
+    if not all(math.isfinite(value) for value in normalized):
+        raise ValueError(f"{name} values must all be finite")
+    return normalized
+
+
+def validate_finite_sequence(
+    values: object, *, name: str, allow_empty: bool = False
+) -> tuple[float, ...]:
+    """校验可变长度数值序列并转换为有限浮点数元组。
+
+    参数：
+        values: 需要校验或转换的输入值序列。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+        allow_empty: 是否允许空序列；True 不豁免非空序列的数值检查。
+
+    原有说明：
+    Validate a finite numeric sequence of dynamic length.
+    """
+
+    if isinstance(values, (str, bytes)):
+        raise TypeError(f"{name} must be a sequence of numbers")
+    try:
+        raw_values = tuple(values)  # type: ignore[arg-type]
+    except TypeError as error:
+        raise TypeError(f"{name} must be a sequence of numbers") from error
+    if not allow_empty and not raw_values:
+        raise ValueError(f"{name} must not be empty")
+    if any(isinstance(value, bool) for value in raw_values):
+        raise TypeError(f"{name} must not contain bool values")
+    try:
+        normalized = tuple(float(value) for value in raw_values)
+    except (TypeError, ValueError) as error:
+        raise TypeError(f"{name} must be a sequence of numbers") from error
+    if not all(math.isfinite(value) for value in normalized):
+        raise ValueError(f"{name} values must all be finite")
+    return normalized
+
+
+def validate_identifier(value: str, *, name: str) -> str:
+    """校验资源标识是否为非空字符串。
+
+    参数：
+        value: 待校验的资源标识或文本字段值。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+
+    原有说明：
+    Validate a non-empty opaque server identifier.
+    """
+
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    if not value.strip():
+        raise ValueError(f"{name} must not be empty")
+    return value
+
+
+def validate_uint32(value: int, *, name: str) -> int:
+    """校验无符号 32 位整数，拒绝布尔值及越界值。
+
+    参数：
+        value: 需要校验、转换或编码的单个输入值。
+        name: 字段或参数名称，用于读取对应字段或生成错误信息。
+
+    原有说明：
+    Validate a protobuf uint32 value without accepting bool.
+    """
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer")
+    if value < 0 or value > 0xFFFFFFFF:
+        raise ValueError(f"{name} must be between 0 and 4294967295")
+    return value
+
+
+def validate_joint_id(joint_id: int) -> int:
+    """校验从 0 开始的手臂关节索引，合法范围为 0～6。
+
+    参数：
+        joint_id: 手臂关节的零起始索引，普通单关节操作要求 0～6。
+
+    原有说明：
+    Validate a zero-based OpenArm arm-joint index.
+    """
+
+    if isinstance(joint_id, bool) or not isinstance(joint_id, int):
+        raise TypeError("joint_id must be an integer")
+    if joint_id < 0 or joint_id > 6:
+        raise ValueError("joint_id must be between 0 and 6")
+    return joint_id