devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/core/base_driver.py

@@ -0,0 +1,414 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""BaseDriver：跨平台设备驱动契约。
+
+命名原则：U2 风格 snake_case 为基准，语义化方法为补充。
+抽象层只定义跨平台通用接口，平台特有能力通过子类扩展提供。
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+    from devhelmkit.core.base_component import BaseComponent
+    from devhelmkit.core.base_window import BaseWindow
+
+
+class BaseDriver(ABC):
+    """跨平台设备驱动契约。"""
+
+    # ============================================================
+    # 生命周期
+    # ============================================================
+
+    @abstractmethod
+    def close(self) -> None:
+        """关闭驱动，释放连接资源。"""
+
+    def __enter__(self) -> 'BaseDriver':
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        self.close()
+        return False
+
+    @property
+    @abstractmethod
+    def device_sn(self) -> str:
+        """设备序列号。"""
+
+    @property
+    @abstractmethod
+    def platform(self) -> str:
+        """平台标识：'harmony' / 'android'。"""
+
+    # ============================================================
+    # 设备信息
+    # ============================================================
+
+    @property
+    @abstractmethod
+    def info(self) -> Dict[str, Any]:
+        """设备基本信息（品牌、型号、系统版本等）。"""
+
+    @abstractmethod
+    def get_display_size(self) -> Tuple[int, int]:
+        """获取屏幕分辨率 (width, height)。"""
+
+    @abstractmethod
+    def get_display_rotation(self) -> int:
+        """获取屏幕方向。"""
+
+    @abstractmethod
+    def set_display_rotation(self, rotation: int) -> None:
+        """设置屏幕方向。"""
+
+    @abstractmethod
+    def set_display_rotation_enabled(self, enabled: bool) -> None:
+        """自动旋转开关。"""
+
+    @abstractmethod
+    def get_device_type(self) -> str:
+        """设备类型（phone / tablet / 2in1 / wearable / ...）。"""
+
+    @abstractmethod
+    def get_os_type(self) -> str:
+        """操作系统类型标识。"""
+
+    # ============================================================
+    # 屏幕操作
+    # ============================================================
+
+    @abstractmethod
+    def screen_on(self) -> None:
+        """亮屏（唤醒屏幕）。"""
+
+    @abstractmethod
+    def screen_off(self) -> None:
+        """熄屏。"""
+
+    @abstractmethod
+    def is_screen_on(self) -> bool:
+        """屏幕是否点亮。"""
+
+    @abstractmethod
+    def is_screen_locked(self) -> bool:
+        """屏幕是否锁屏。"""
+
+    @abstractmethod
+    def unlock(self) -> None:
+        """解锁设备（亮屏 + 上滑/回车解除锁屏）。"""
+
+    @abstractmethod
+    def set_sleep_time(self, seconds: float) -> None:
+        """设置熄屏时间（秒）。"""
+
+    @abstractmethod
+    def restore_sleep_time(self) -> None:
+        """恢复默认熄屏时间。"""
+
+    # ============================================================
+    # 选择器入口（U2 风格）
+    # ============================================================
+
+    @abstractmethod
+    def __call__(self, **kwargs) -> 'BaseComponent':
+        """U2 风格选择器：d(text=, resourceId=, className=)，返回控件对象。
+
+        平台实现返回具体子类（协变），如 HarmonyDriver 返回 UiObject。
+        """
+
+    @abstractmethod
+    def xpath(self, xpath: str) -> 'BaseComponent':
+        """xpath 选择器，返回控件对象。"""
+
+    # ============================================================
+    # 应用管理
+    # ============================================================
+
+    @abstractmethod
+    def app_start(self, package: str, activity: Optional[str] = None,
+                  params: str = "", wait_time: float = 1) -> None:
+        """启动应用。"""
+
+    @abstractmethod
+    def app_stop(self, package: str, wait_time: float = 0.5) -> None:
+        """停止应用。"""
+
+    @abstractmethod
+    def app_current(self) -> Tuple[str, str]:
+        """获取当前前台应用 (package, activity)。"""
+
+    @abstractmethod
+    def app_list(self) -> List[str]:
+        """已安装应用列表。"""
+
+    @abstractmethod
+    def has_app(self, package: str) -> bool:
+        """查询是否已安装应用。"""
+
+    @abstractmethod
+    def clear_app_data(self, package: str) -> None:
+        """清除应用数据。"""
+
+    # ============================================================
+    # 坐标操作
+    # ============================================================
+
+    @abstractmethod
+    def click(self, x: int, y: int) -> None:
+        """坐标点击。"""
+
+    @abstractmethod
+    def long_click(self, x: int, y: int, duration: float = 0.5) -> None:
+        """坐标长按。"""
+
+    @abstractmethod
+    def double_click(self, x: int, y: int) -> None:
+        """坐标双击。"""
+
+    @abstractmethod
+    def swipe(self, x1: int, y1: int, x2: int, y2: int,
+              duration: float = 0.5) -> None:
+        """精确滑动（起止坐标）。"""
+
+    @abstractmethod
+    def swipe_dir(self, direction: str, distance: int = 60,
+                  area=None, speed=None) -> None:
+        """方向滑动：'UP' / 'DOWN' / 'LEFT' / 'RIGHT'。"""
+
+    @abstractmethod
+    def drag(self, x1: int, y1: int, x2: int, y2: int,
+             duration: float = 0.5) -> None:
+        """拖拽。"""
+
+    @abstractmethod
+    def fling(self, direction: str, distance: int = 50,
+              area=None, speed: str = "fast") -> None:
+        """抛滑（快速惯性滑动）。"""
+
+    # ============================================================
+    # 实时触控（支持 down/move/up 序列，用于实时拖拽等场景）
+    # ============================================================
+
+    @abstractmethod
+    def touch_down(self, x: int, y: int) -> None:
+        """按下触控点。"""
+
+    @abstractmethod
+    def touch_move(self, x: int, y: int) -> None:
+        """移动触控点（需先 touch_down）。"""
+
+    @abstractmethod
+    def touch_up(self, x: int, y: int) -> None:
+        """抬起触控点（结束触控序列）。"""
+
+    # ============================================================
+    # 按键
+    # ============================================================
+
+    @abstractmethod
+    def press(self, key: str) -> None:
+        """语义按键：'back' / 'home' / 'power' / 'volume_up' / ..."""
+
+    @abstractmethod
+    def press_keycode(self, keycode: int) -> None:
+        """按键码（平台原始按键码，由平台实现自行解释）。"""
+
+    @abstractmethod
+    def go_home(self) -> None:
+        """返回桌面（自动选最稳定路径）。"""
+
+    @abstractmethod
+    def go_back(self) -> None:
+        """返回上一级（自动选最稳定路径）。"""
+
+    @abstractmethod
+    def press_power(self) -> None:
+        """按下电源键。"""
+
+    @abstractmethod
+    def press_combination_key(self, key1: int, key2: int,
+                              key3: Optional[int] = None) -> None:
+        """按下组合键（支持 2 键或 3 键）。"""
+
+    # ============================================================
+    # Shell
+    # ============================================================
+
+    @abstractmethod
+    def shell(self, cmd: str, timeout: float = 60) -> str:
+        """执行 shell 命令，返回回显内容。"""
+
+    # ============================================================
+    # 截图
+    # ============================================================
+
+    @abstractmethod
+    def screenshot(self, filename: Optional[str] = None,
+                   area=None) -> Union['Image', str, None]:
+        """截图。
+
+        - filename 为 None：返回 PIL.Image.Image
+        - filename 指定：保存到文件，返回文件路径 str
+        - area 指定区域截图（Rect / SelectorSpec / None）
+        - 失败：返回 None
+        """
+
+    @abstractmethod
+    def dump_hierarchy(self, source: str = "rpc",
+                       filename: Optional[str] = None) -> Union[dict, str, None]:
+        """导出控件树。
+
+        - source: 获取方式
+            - "rpc": 走 uitest RPC（Captures.captureLayout），直接返回控件树 JSON，默认
+            - "hdc": 走 hdc shell（uitest dumpLayout -p），独立于 RPC 守护进程状态
+        - filename 为 None：返回解析后的 dict
+        - filename 指定：保存 JSON 到文件，返回文件路径 str
+        - 失败：返回 None
+        """
+
+    # ============================================================
+    # 等待
+    # ============================================================
+
+    @abstractmethod
+    def wait(self, seconds: float) -> None:
+        """强制等待指定秒数。"""
+
+    @abstractmethod
+    def wait_for_idle(self, idle_time: float = 0.7,
+                      timeout: float = 10) -> None:
+        """等待 UI 进入空闲状态。"""
+
+    @abstractmethod
+    def implicitly_wait(self, seconds: float) -> None:
+        """设置隐式等待。"""
+
+    # ============================================================
+    # 窗口
+    # ============================================================
+
+    @property
+    @abstractmethod
+    def window(self) -> 'BaseWindow':
+        """当前窗口对象。"""
+
+    @abstractmethod
+    def get_windows(self) -> List['BaseWindow']:
+        """获取所有窗口。"""
+
+    # ============================================================
+    # webview 自动化（可选实现，不支持时抛 NotImplementedError）
+    # ============================================================
+
+    def webview(self, bundle_name: str, **kwargs):
+        """连接应用 webview，返回 selenium webdriver 封装。
+
+        平台不支持 webview 测试时抛 NotImplementedError。
+        """
+        raise NotImplementedError("当前平台不支持 webview 自动化")
+
+    # ============================================================
+    # 文件操作
+    # ============================================================
+
+    @abstractmethod
+    def push_file(self, local_path: str, remote_path: str,
+                  timeout: int = 60) -> None:
+        """推送文件到设备。"""
+
+    @abstractmethod
+    def pull_file(self, remote_path: str,
+                  local_path: Optional[str] = None,
+                  timeout: int = 60) -> None:
+        """从设备拉取文件。"""
+
+    @abstractmethod
+    def has_file(self, path: str) -> bool:
+        """查询设备端文件是否存在。"""
+
+    # ============================================================
+    # 控件查找
+    # ============================================================
+
+    @abstractmethod
+    def find_component(self, target, scroll_target=None) -> Optional['BaseComponent']:
+        """查找控件返回对象。"""
+
+    @abstractmethod
+    def find_all_components(self, target) -> List['BaseComponent']:
+        """查找所有匹配控件。"""
+
+    @abstractmethod
+    def get_component_bound(self, target) -> Optional[Any]:
+        """获取控件边界 Rect，未找到返回 None。"""
+
+    @abstractmethod
+    def get_component_property(self, target, name: str) -> Any:
+        """获取控件指定属性（id/text/key/type/enabled/focused/clickable/scrollable/checked/checkable）。"""
+
+    # ============================================================
+    # 图片识别
+    # ============================================================
+
+    @abstractmethod
+    def find_image(self, image_path: str,
+                   mode: str = "sift") -> Optional[Any]:
+        """在屏幕上查找图片位置，返回 Rect 或 None。"""
+
+    @abstractmethod
+    def touch_image(self, image_path: str, mode: str = "normal",
+                    similarity: float = 0.95) -> None:
+        """点击图片位置。"""
+
+    # ============================================================
+    # 文本输入辅助
+    # ============================================================
+
+    @abstractmethod
+    def hide_keyboard(self) -> None:
+        """隐藏软键盘。"""
+
+    @abstractmethod
+    def input_text_on_cursor(self, text: str) -> None:
+        """在当前光标处输入文本（不依赖控件定位）。"""
+
+    @abstractmethod
+    def move_cursor(self, direction: str, times: int = 1) -> None:
+        """移动输入框光标：'LEFT' / 'RIGHT' / 'UP' / 'DOWN' / 'BEGIN' / 'END'。"""
+
+    # ============================================================
+    # 手势扩展
+    # ============================================================
+
+    @abstractmethod
+    def inject_gesture(self, gesture, speed: int = 2000) -> None:
+        """自定义手势。"""
+
+    # ============================================================
+    # 手势导航
+    # ============================================================
+
+    @abstractmethod
+    def swipe_to_home(self, times: int = 1) -> None:
+        """屏幕底端上滑回到桌面（需开启手势导航）。"""
+
+    @abstractmethod
+    def swipe_to_back(self, side: str = "LEFT", times: int = 1,
+                      height: float = 0.5) -> None:
+        """侧滑返回：side='LEFT'/'RIGHT'，height 为屏幕高度比例。"""
+
+    @abstractmethod
+    def swipe_to_recent_task(self) -> None:
+        """底端上滑停顿进入多任务界面。"""
+
+    # ============================================================
+    # 坐标转换
+    # ============================================================
+
+    @abstractmethod
+    def to_abs_pos(self, x: float, y: float) -> Tuple[int, int]:
+        """比例坐标转绝对坐标。"""

devhelmkit/core/base_window.py

@@ -0,0 +1,25 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""BaseWindow：跨平台窗口对象契约。"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Tuple
+
+
+class BaseWindow(ABC):
+    """窗口契约，平台实现需继承并实现全部抽象方法。"""
+
+    @property
+    @abstractmethod
+    def size(self) -> Tuple[int, int]:
+        """窗口大小 (width, height)。"""
+
+    @property
+    @abstractmethod
+    def info(self) -> Dict[str, Any]:
+        """窗口信息。"""
+
+    @abstractmethod
+    def get_windows(self) -> List['BaseWindow']:
+        """所有窗口对象列表。"""

devhelmkit/core/selector_spec.py

@@ -0,0 +1,102 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""SelectorSpec：纯数据选择器规格。
+
+对齐 U2 单对象模型：d(**kwargs) 直接返回 UiObject，SelectorSpec 仅作为
+内部纯数据类封装控件定位条件，不向用户暴露任何操作接口。所有操作与
+关系方法统一在 UiObject / BaseComponent 上。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class SelectorSpec:
+    """控件定位条件的纯数据封装（内部使用，不直接暴露给用户）。
+
+    用户通过 d(text="x", resourceId="y") 构造，由 UiObject 持有。
+    frozen=True 保证不可变，关系选择器衍生新实例时安全。
+    """
+
+    # 文本匹配
+    text: Optional[str] = None
+    text_contains: Optional[str] = None
+    text_starts_with: Optional[str] = None
+    text_ends_with: Optional[str] = None
+    text_matches: Optional[str] = None
+    text_matches_flags: Optional[int] = None
+
+    # 描述匹配
+    desc: Optional[str] = None
+    desc_contains: Optional[str] = None
+    desc_starts_with: Optional[str] = None
+    desc_ends_with: Optional[str] = None
+    desc_matches: Optional[str] = None
+
+    # 通用定位
+    resource_id: Optional[str] = None       # 对应 U2 resourceId / id
+    class_name: Optional[str] = None        # 对应 U2 className / class_
+    key: Optional[str] = None              # 鸿蒙 key 选择器
+    type: Optional[str] = None             # 鸿蒙 type 选择器
+    index: Optional[int] = None
+    instance: Optional[int] = None
+
+    # 关系选择器
+    parent: Optional['SelectorSpec'] = None
+    relation: Optional[str] = None          # 'child' / 'sibling' / 'after' / 'before'
+
+    # xpath
+    xpath: Optional[str] = None
+
+    def merge(self, **kwargs) -> 'SelectorSpec':
+        """合并新的选择条件，返回新实例（不可变）。"""
+        normalized = _normalize_aliases(kwargs)
+        merged = {**self.__dict__, **normalized}
+        return SelectorSpec(**merged)
+
+    @classmethod
+    def with_relation(cls, parent: 'SelectorSpec', relation: str,
+                      child: 'SelectorSpec') -> 'SelectorSpec':
+        """构造关系选择器，避免 parent/relation 重复传参。"""
+        child_data = {
+            key: value
+            for key, value in child.__dict__.items()
+            if key not in ('parent', 'relation')
+        }
+        return cls(parent=parent, relation=relation, **child_data)
+
+
+# U2 / 鸿蒙选择器别名 → 内部字段名
+_ALIAS_MAPPING = {
+    'className': 'class_name',
+    'class_': 'class_name',
+    'resourceId': 'resource_id',
+    'id': 'resource_id',
+    'description': 'desc',
+    'textContains': 'text_contains',
+    'textStartswith': 'text_starts_with',
+    'textStartsWith': 'text_starts_with',
+    'textEndswith': 'text_ends_with',
+    'textEndsWith': 'text_ends_with',
+    'textMatches': 'text_matches',
+    'flags': 'text_matches_flags',
+    'descContains': 'desc_contains',
+    'descStartswith': 'desc_starts_with',
+    'descStartsWith': 'desc_starts_with',
+    'descEndswith': 'desc_ends_with',
+    'descEndsWith': 'desc_ends_with',
+    'descMatches': 'desc_matches',
+}
+
+
+def _normalize_aliases(kwargs: Dict[str, Any]) -> Dict[str, Any]:
+    """U2 / 鸿蒙选择器别名归一化为内部字段。"""
+    return {_ALIAS_MAPPING.get(key, key): value for key, value in kwargs.items()}
+
+
+def build_selector(**kwargs) -> SelectorSpec:
+    """从用户 kwargs 构建 SelectorSpec（含别名归一化）。"""
+    normalized = _normalize_aliases(kwargs)
+    return SelectorSpec(**normalized)

devhelmkit/entry.py

@@ -0,0 +1,90 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""设备连接入口：平台识别、设备发现与平台分发。
+
+平台实现延迟导入，避免导入包时触发设备环境探测。
+"""
+from typing import Optional
+
+from devhelmkit.core.base_driver import BaseDriver
+from devhelmkit.exceptions import (
+    DeviceConnectError,
+    DeviceNotFoundError,
+    PlatformNotSupportedError,
+)
+from devhelmkit.utils.logger import setup_logger
+
+
+def connect(
+    serial: Optional[str] = None,
+    platform: str = "auto",
+    config=None,
+    log_level: int = None,
+    **kwargs
+) -> BaseDriver:
+    """连接设备。
+
+    Args:
+        serial: 设备序列号，None 时自动发现。
+        platform: 平台，"auto" | "harmony" | "android"。
+        config: 平台专用配置对象（如 HarmonyDriverConfig）。
+        log_level: 日志级别，None 默认 INFO。传入 logging.DEBUG 可开启调试日志。
+        **kwargs: 平台特定参数，覆盖 config 同名字段。
+
+    Returns:
+        BaseDriver: 设备驱动实例（具体平台子类）。
+
+    Raises:
+        DeviceNotFoundError: 未检测到可连接设备。
+        DeviceConnectError: 设备连接失败。
+        PlatformNotSupportedError: 平台不支持。
+    """
+    import logging
+    setup_logger(log_level if log_level is not None else logging.INFO)
+
+    if serial is None:
+        serial = _discover_serial()
+
+    selected_platform = _detect_platform(serial) if platform == "auto" else platform
+
+    if selected_platform == "harmony":
+        from devhelmkit.harmony.driver import HarmonyDriver
+        return HarmonyDriver(serial, config=config, **kwargs)
+
+    if selected_platform == "android":
+        raise PlatformNotSupportedError("Android 平台暂未接入，阶段四实现")
+
+    raise PlatformNotSupportedError("不支持的平台: %s" % selected_platform)
+
+
+def _discover_serial() -> str:
+    """自动发现首个可用设备序列号。"""
+    try:
+        from devhelmkit.harmony.device.hdc import HdcDevice
+        targets = HdcDevice.list_targets()
+    except Exception as exc:
+        raise DeviceConnectError("鸿蒙设备发现失败: %s" % exc) from exc
+
+    if not targets:
+        raise DeviceNotFoundError(
+            "未检测到可连接设备，请手动指定 serial 或 platform"
+        )
+    return targets[0]
+
+
+def _detect_platform(serial: Optional[str]) -> str:
+    """自动识别平台：当前仅识别鸿蒙设备。"""
+    try:
+        from devhelmkit.harmony.device.hdc import HdcDevice
+        targets = HdcDevice.list_targets()
+    except Exception as exc:
+        raise DeviceConnectError("鸿蒙设备发现失败: %s" % exc) from exc
+
+    if serial is None and targets:
+        return "harmony"
+    if serial is not None and serial in targets:
+        return "harmony"
+
+    raise DeviceNotFoundError(
+        "未检测到可连接设备，请手动指定 serial 或 platform"
+    )

devhelmkit/exceptions.py

@@ -0,0 +1,56 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""统一异常体系。
+
+异常类型单文件定义，避免各平台重复定义。命名约束：
+- DevhelmTimeoutError 不与 Python 内建 TimeoutError 同名冲突；
+- DeviceConnectError 作为设备连接失败的唯一命名；
+- ComponentNotFoundError 作为控件未找到的唯一命名。
+"""
+from typing import Optional
+
+
+class DevhelmError(Exception):
+    """框架基础异常，所有 devhelmkit 异常的根。"""
+
+
+class DeviceNotFoundError(DevhelmError):
+    """未检测到可连接设备。"""
+
+
+class DeviceConnectError(DevhelmError):
+    """设备连接失败（hdc 连接、RPC socket 建立失败等）。"""
+
+
+class PlatformNotSupportedError(DevhelmError):
+    """平台不支持（如阶段一调用 connect(platform="android")）。"""
+
+
+class DevhelmTimeoutError(DevhelmError):
+    """框架操作超时，刻意不与 Python 内建 TimeoutError 同名。"""
+
+
+class RpcError(DevhelmError):
+    """RPC 通信异常，携带 api 与原始 reply 上下文便于诊断。"""
+
+    def __init__(self, message: str, api: Optional[str] = None,
+                 reply: Optional[str] = None):
+        super().__init__(message)
+        self.api = api
+        self.reply = reply
+
+
+class BackendObjectDroppedError(RpcError):
+    """设备端远程对象引用已失效，需恢复后重试。"""
+
+
+class ComponentNotFoundError(DevhelmError):
+    """控件未找到。"""
+
+
+class ComponentDisappearedError(ComponentNotFoundError):
+    """控件查找到后又消失。"""
+
+
+class AgentError(DevhelmError):
+    """设备端 uitest / Agent 异常（进程崩溃、版本不支持等）。"""

devhelmkit/harmony/__init__.py

@@ -0,0 +1,3 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""HarmonyOS 平台实现包。"""