devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/harmony/rpc/client.py

@@ -0,0 +1,126 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""RpcClient：设备端 API 调用与返回值处理。
+
+统一使用 bin 模式（proxy_v2），废弃 hap 模式。
+负责：
+- 构造 RPC 消息（api/this/args/message_type）
+- 调用 proxy_v2 发送
+- 处理返回值（解析 JSON、错误检测、异常分类）
+- 远程对象生命周期管理
+
+仅支持 HarmonyOS 5.0.0+（API 12+），设备端 uitest 服务统一使用
+api9+ 命名（Driver/Component/On），不再兼容 api8 旧命名。
+"""
+import json
+from typing import Any, Optional, TYPE_CHECKING
+
+from devhelmkit.exceptions import (
+    AgentError,
+    BackendObjectDroppedError,
+    RpcError,
+)
+from devhelmkit.harmony.rpc.proxy_v2 import rpc as rpc_send
+from devhelmkit.harmony.rpc.remote_object import RemoteObjectManager
+from devhelmkit.utils import logger
+
+if TYPE_CHECKING:
+    from devhelmkit.harmony.device.hdc import HdcDevice
+
+
+class RpcClient:
+    """RPC 客户端，统一使用 bin 模式。"""
+
+    def __init__(self, device: 'HdcDevice'):
+        self._device = device
+        self._remote_objects = RemoteObjectManager()
+
+    def call(self, api_name: str, this_ref: str, args: list) -> Any:
+        """调用设备端 API。
+
+        Args:
+            api_name: API 名称（api9+ 风格，如 "Driver.click"、"On.text"）
+            this_ref: 对象引用（如 'Driver#0'、'Component#3'）
+            args: 参数列表（递归处理 FrontEndClass → ref, JsonBase → dict, Enum → value）
+
+        Returns:
+            设备端返回结果
+
+        Raises:
+            RpcError: RPC 调用失败
+            BackendObjectDroppedError: 后端对象引用已失效
+            AgentError: 设备端 Agent 异常
+        """
+        msg = {
+            'api': api_name,
+            'this': this_ref,
+            'args': args,
+            'message_type': 'hypium'
+        }
+        logger.debug("RPC -> %s this=%s args=%r", api_name, this_ref, args)
+        reply = rpc_send(self._device, msg)
+        result = self._handle_reply(reply, api_name)
+        logger.debug("RPC <- %s result=%r", api_name, result)
+        return result
+
+    def _handle_reply(self, reply: str, api_name: str) -> Any:
+        """处理设备端返回值，解析 JSON 并检测错误。"""
+        try:
+            result = json.loads(reply)
+        except json.JSONDecodeError as e:
+            logger.error("RPC 返回值解析失败 [%s]: %s", api_name, reply[:200])
+            raise RpcError(
+                "RPC 返回值解析失败: %s" % e,
+                api=api_name, reply=reply
+            ) from e
+
+        error = result.get('error')
+        if error:
+            logger.warn("RPC 调用失败 [%s]: %s", api_name, error)
+            return self._raise_for_error(error, api_name, reply)
+
+        # 设备端异常时可能返回 {"exception":{"code":...,"message":...}}
+        exception = result.get('exception')
+        if exception:
+            msg = exception.get('message', str(exception))
+            logger.warn("RPC 调用异常 [%s]: %s", api_name, msg)
+            raise RpcError(
+                "RPC 调用异常: %s" % msg,
+                api=api_name, reply=reply
+            )
+
+        return result.get('result')
+
+    @staticmethod
+    def _raise_for_error(error: str, api_name: str, reply: str) -> None:
+        """根据错误信息抛出对应异常。"""
+        error_lower = str(error).lower()
+
+        # 后端对象引用失效
+        if 'object' in error_lower and ('dropped' in error_lower or
+                                         'released' in error_lower or
+                                         'invalid' in error_lower):
+            raise BackendObjectDroppedError(
+                "后端对象引用已失效: %s" % error,
+                api=api_name, reply=reply
+            )
+
+        # Agent 进程异常
+        if 'agent' in error_lower or 'uitest' in error_lower or \
+           'crash' in error_lower:
+            raise AgentError("Agent 异常: %s" % error)
+
+        raise RpcError(
+            "RPC 调用失败 [%s]: %s" % (api_name, error),
+            api=api_name, reply=reply
+        )
+
+    @property
+    def device(self) -> 'HdcDevice':
+        """底层设备通道，供 Captures/Gestures 等非 callHypiumApi 模块复用。"""
+        return self._device
+
+    @property
+    def remote_objects(self) -> RemoteObjectManager:
+        """远程对象管理器。"""
+        return self._remote_objects

devhelmkit/harmony/rpc/proxy_v2.py

@@ -0,0 +1,106 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""bin 模式 RPC 传输，保留设备端协议。
+
+proxy_v2 不读取 device 内部代理字段，只调用统一传输入口 device.rpc_call()。
+设备端协议消息格式：
+{
+    "module": "com.ohos.devicetest.hypiumApiHelper",
+    "method": "callHypiumApi",
+    "params": <内层消息字典>,
+    "request_id": "<时间戳>"
+}
+"""
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from devhelmkit.harmony.device.hdc import HdcDevice
+
+
+def _generate_request_id() -> str:
+    """生成基于时间戳的请求 ID。"""
+    return datetime.now().strftime("%Y%m%d%H%M%S%f")
+
+
+def _send(device: 'HdcDevice', method: str, params: dict) -> str:
+    """构造 bin 模式 RPC 消息并发送至设备端。
+
+    统一负责 request_id 生成、full_msg 组装、JSON 序列化与设备调用，
+    对外函数仅构造 params 后委托本函数。
+
+    Args:
+        device: HdcDevice 实例，提供 rpc_call 传输入口
+        method: 设备端协议 method 字段（如 callHypiumApi/Captures/Gestures）
+        params: 内层 params 消息字典
+
+    Returns:
+        设备端回显的 JSON 字符串
+    """
+    full_msg = {
+        "module": "com.ohos.devicetest.hypiumApiHelper",
+        "method": method,
+        "params": params,
+        "request_id": _generate_request_id()
+    }
+    full_msg_str = json.dumps(full_msg, ensure_ascii=False,
+                              separators=(',', ':'))
+    return device.rpc_call(full_msg_str)
+
+
+def rpc(device: 'HdcDevice', msg: dict) -> str:
+    """发送 bin 模式 RPC，返回设备端回显字符串。
+
+    Args:
+        device: HdcDevice 实例，提供 rpc_call 传输入口
+        msg: 内层消息字典（含 api/this/args/message_type）
+
+    Returns:
+        设备端回显的 JSON 字符串
+    """
+    return _send(device, "callHypiumApi", msg)
+
+
+def rpc_captures(device: 'HdcDevice', api: str, args: dict) -> str:
+    """发送 Captures 模块 RPC（如 captureLayout）。
+
+    Captures 模块协议与 callHypiumApi 不同：
+    - method 为 "Captures"
+    - params 中无 this/message_type，args 为对象而非数组
+
+    Args:
+        device: HdcDevice 实例
+        api: API 名称（如 "captureLayout"）
+        args: 参数对象
+
+    Returns:
+        设备端回显的 JSON 字符串
+    """
+    params = {
+        "api": api,
+        "args": args
+    }
+    return _send(device, "Captures", params)
+
+
+def rpc_gestures(device: 'HdcDevice', api: str, args: dict) -> str:
+    """发送 Gestures 模块 RPC（如 touchDown/touchMove/touchUp）。
+
+    Gestures 模块协议与 callHypiumApi 不同：
+    - method 为 "Gestures"
+    - params 中无 this/message_type，args 为对象（如 {x, y}）而非数组
+
+    Args:
+        device: HdcDevice 实例
+        api: API 名称（如 "touchDown"）
+        args: 参数对象
+
+    Returns:
+        设备端回显的 JSON 字符串
+    """
+    params = {
+        "api": api,
+        "args": args
+    }
+    return _send(device, "Gestures", params)

devhelmkit/harmony/rpc/remote_object.py

@@ -0,0 +1,48 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""远程对象生命周期管理。
+
+跟踪设备端远程对象引用（如 Driver#0、Component#3、On#seed）的创建与回收。
+活跃对象使用 WeakSet 跟踪，待回收对象累积超过 batch_size 时触发批量清理。
+"""
+from typing import Any, Set
+from weakref import WeakSet
+
+
+DEFAULT_BATCH_SIZE = 20
+
+
+class RemoteObjectManager:
+    """管理设备端远程对象引用的生命周期。"""
+
+    def __init__(self) -> None:
+        self.total_registered_objects = 0
+        self.total_removed_objects = 0
+        self.batch_size = DEFAULT_BATCH_SIZE
+        # 待回收的对象引用集合
+        self.pending_release_refs: Set[str] = set()
+        # 活跃对象弱引用集合（不阻止 GC）
+        self.active_objects = WeakSet()
+        # 标记是否已执行 release_all，禁止后续 add_object
+        self._released = False
+
+    def add_object(self, obj: Any) -> None:
+        """注册远程对象到活跃集合。"""
+        if self._released:
+            return
+        remains = len(self.active_objects)
+        self.active_objects.add(obj)
+        if len(self.active_objects) > remains:
+            self.total_registered_objects += 1
+
+    def remove_object(self, backend_obj_ref: str) -> None:
+        """标记远程对象引用为待回收。"""
+        self.total_removed_objects += 1
+        self.pending_release_refs.add(backend_obj_ref)
+
+    def release_all(self) -> None:
+        """释放所有远程对象。"""
+        self._released = True
+        for item in self.active_objects:
+            if hasattr(item, 'release'):
+                item.release()

devhelmkit/harmony/uiobject.py

@@ -0,0 +1,246 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""UiObject：HarmonyOS 平台控件对象。
+
+UiObject 只持有 SelectorSpec 与驱动引用，不直接拼底层 RPC 消息。
+控件查找、选择器转换、远程对象引用和弹窗处理统一交给 HarmonyDriver /
+ComponentFinder。每次操作都重新定位控件，对齐 U2 单对象模型。
+"""
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple, Union, TYPE_CHECKING
+
+from devhelmkit.core.base_component import BaseComponent
+from devhelmkit.core.selector_spec import SelectorSpec, build_selector
+from devhelmkit.model.rect import Rect
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+    from devhelmkit.harmony.driver import HarmonyDriver
+
+
+class UiObject(BaseComponent):
+    """HarmonyOS 平台控件对象。
+
+    所有操作通过 HarmonyDriver 门面委托给 ComponentFinder，
+    由 ComponentFinder 负责 By/On 链构造、findComponent 和方法调用。
+    """
+
+    # ============================================================
+    # 内部：控件操作门面
+    # ============================================================
+
+    def _call_component(self, method: str,
+                        args: Optional[list] = None) -> Any:
+        """通过驱动门面执行控件操作。"""
+        return self._driver.call_component(self._selector, method, args or [])
+
+    # ============================================================
+    # 点击类
+    # ============================================================
+
+    def click(self) -> None:
+        self._call_component("click")
+
+    def long_click(self, duration: float = 0.5) -> None:
+        self._call_component("longClick", [duration])
+
+    def double_click(self) -> None:
+        self._call_component("doubleClick")
+
+    def click_exists(self, timeout: float = 0) -> bool:
+        return self._call_component("clickIfExists", [timeout])
+
+    # ============================================================
+    # 文本类
+    # ============================================================
+
+    def set_text(self, text: str) -> None:
+        self._call_component("setText", [text])
+
+    def get_text(self) -> str:
+        return self._call_component("getText")
+
+    def clear_text(self) -> None:
+        self._call_component("clearText")
+
+    def input_text(self, text: str) -> None:
+        self.set_text(text)
+
+    # ============================================================
+    # 状态类
+    # ============================================================
+
+    def exists(self) -> bool:
+        return self._driver.component_exists(self._selector)
+
+    def wait(self, timeout: float) -> bool:
+        return self._driver.wait_component(self._selector, timeout)
+
+    def wait_gone(self, timeout: float) -> bool:
+        return self._driver.wait_component_gone(self._selector, timeout)
+
+    # ============================================================
+    # 信息类
+    # ============================================================
+
+    def _collect_properties(self) -> dict:
+        """收集控件共有属性（文本、类型、布尔状态）。
+
+        info 与 get_all_properties 共享此基础集合，
+        info 在此基础上补充 description 与 bounds。
+        """
+        return {
+            "text": self._call_component("getText"),
+            "id": self._call_component("getId"),
+            "type": self._call_component("getType"),
+            "enabled": self._call_component("isEnabled"),
+            "focused": self._call_component("isFocused"),
+            "selected": self._call_component("isSelected"),
+            "clickable": self._call_component("isClickable"),
+            "long_clickable": self._call_component("isLongClickable"),
+            "scrollable": self._call_component("isScrollable"),
+            "checkable": self._call_component("isCheckable"),
+            "checked": self._call_component("isChecked"),
+        }
+
+    @property
+    def info(self) -> dict:
+        """控件综合信息（文本、类型、状态、边界等）。
+
+        设备端无 getInfo API，逐项调用属性方法组装。
+        """
+        props = self._collect_properties()
+        props["description"] = self._call_component("getDescription")
+        props["bounds"] = self._call_component("getBounds")
+        return props
+
+    @property
+    def bounds(self) -> Rect:
+        result = self._call_component("getBounds")
+        return _to_rect(result)
+
+    def center(self) -> Tuple[int, int]:
+        return self.bounds.center.as_tuple()
+
+    def get_attribute(self, name: str) -> Any:
+        return self._call_component("getAttribute", [name])
+
+    def screenshot(self, filename: Optional[str] = None) -> Union['Image', str, None]:
+        return self._driver.screenshot(filename=filename, area=self._selector)
+
+    @property
+    def description(self) -> str:
+        return self._call_component("getDescription")
+
+    def get_hint(self) -> str:
+        return self._call_component("getHint")
+
+    def get_all_properties(self) -> dict:
+        """获取控件全部布尔属性与文本。"""
+        return self._collect_properties()
+
+    def get_original_text(self) -> str:
+        return self._call_component("getOriginalText")
+
+    # ============================================================
+    # 布尔属性
+    # ============================================================
+
+    @property
+    def is_long_clickable(self) -> bool:
+        return self._call_component("isLongClickable")
+
+    @property
+    def is_checked(self) -> bool:
+        return self._call_component("isChecked")
+
+    @property
+    def is_checkable(self) -> bool:
+        return self._call_component("isCheckable")
+
+    @property
+    def is_selected(self) -> bool:
+        return self._call_component("isSelected")
+
+    # ============================================================
+    # 拖拽类
+    # ============================================================
+
+    def drag_to(self, x: int, y: int) -> None:
+        self._call_component("dragTo", [x, y])
+
+    def drag_to_component(self, other: 'UiObject') -> None:
+        self._call_component("dragToComponent", [other._selector])
+
+    # ============================================================
+    # 缩放类
+    # ============================================================
+
+    def pinch_in(self, scale: float = 0.5) -> None:
+        self._call_component("pinchIn", [scale])
+
+    def pinch_out(self, scale: float = 1.5) -> None:
+        self._call_component("pinchOut", [scale])
+
+    # ============================================================
+    # 滚动类
+    # ============================================================
+
+    def scroll_search(self, target, vertical: bool = True,
+                      offset: Optional[int] = None) -> Optional['UiObject']:
+        return self._driver.scroll_search(
+            self._selector, target, vertical, offset
+        )
+
+    def scroll_to_top(self, speed: int = 600) -> None:
+        self._call_component("scrollToTop", [speed])
+
+    def scroll_to_bottom(self, speed: int = 600) -> None:
+        self._call_component("scrollToBottom", [speed])
+
+    # ============================================================
+    # 关系选择器：返回新的 UiObject，持有衍生 SelectorSpec
+    # ============================================================
+
+    def child(self, **kwargs) -> 'UiObject':
+        child_spec = build_selector(**kwargs)
+        new_spec = SelectorSpec.with_relation(self._selector, 'child', child_spec)
+        return UiObject(self._driver, new_spec)
+
+    def sibling(self, **kwargs) -> 'UiObject':
+        sibling_spec = build_selector(**kwargs)
+        new_spec = SelectorSpec.with_relation(
+            self._selector, 'sibling', sibling_spec
+        )
+        return UiObject(self._driver, new_spec)
+
+    def after(self, **kwargs) -> 'UiObject':
+        after_spec = build_selector(**kwargs)
+        new_spec = SelectorSpec.with_relation(self._selector, 'after', after_spec)
+        return UiObject(self._driver, new_spec)
+
+    def before(self, **kwargs) -> 'UiObject':
+        before_spec = build_selector(**kwargs)
+        new_spec = SelectorSpec.with_relation(self._selector, 'before', before_spec)
+        return UiObject(self._driver, new_spec)
+
+
+def _to_rect(data: Any) -> Rect:
+    """将设备端返回的坐标数据转为 Rect。
+
+    设备端 getBounds 可能返回字典或列表，统一转换为 Rect。
+    """
+    if isinstance(data, dict):
+        return Rect(
+            left=int(data.get('left', 0)),
+            top=int(data.get('top', 0)),
+            right=int(data.get('right', 0)),
+            bottom=int(data.get('bottom', 0)),
+        )
+    if isinstance(data, (list, tuple)) and len(data) >= 4:
+        return Rect(
+            left=int(data[0]), top=int(data[1]),
+            right=int(data[2]), bottom=int(data[3]),
+        )
+    return Rect(left=0, top=0, right=0, bottom=0)

devhelmkit/harmony/uiwindow.py

@@ -0,0 +1,43 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""UiWindow：HarmonyOS 平台窗口对象。
+
+窗口操作能力较控件操作少，当前阶段保留基础结构，
+后续按需补充基于 Driver.findWindow 的实现。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING
+
+from devhelmkit.core.base_window import BaseWindow
+
+if TYPE_CHECKING:
+    from devhelmkit.harmony.driver import HarmonyDriver
+    from devhelmkit.harmony.rpc.client import RpcClient
+
+
+class UiWindow(BaseWindow):
+    """HarmonyOS 平台窗口对象。
+
+    持有驱动引用，通过 RPC 调用设备端窗口 API。
+    """
+
+    def __init__(self, driver: 'HarmonyDriver',
+                 rpc: 'RpcClient', window_id: Optional[int] = None):
+        self._driver = driver
+        self._rpc = rpc
+        self._window_id = window_id
+
+    @property
+    def size(self) -> Tuple[int, int]:
+        """窗口大小，设备端暂无窗口级尺寸 API，回退为屏幕尺寸。"""
+        return self._driver.get_display_size()
+
+    @property
+    def info(self) -> Dict[str, Any]:
+        """窗口信息，设备端暂无窗口信息 API，返回空字典占位。"""
+        return {}
+
+    def get_windows(self) -> List['UiWindow']:
+        """获取所有窗口，设备端暂无枚举窗口 API，返回空列表占位。"""
+        return []

devhelmkit/harmony/webview/__init__.py

@@ -0,0 +1,17 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""webview 自动化子模块。
+
+提供 webview 页面级自动化能力，基于 selenium webdriver。
+
+使用方式：
+    from devhelmkit.harmony.webview import WebViewDriver
+
+    wv = WebViewDriver(device)
+    wv.connect("com.huawei.hmos.browser")
+    wv.driver.get("https://www.baidu.com")
+    wv.close()
+"""
+from devhelmkit.harmony.webview.webview_driver import WebViewDriver
+
+__all__ = ["WebViewDriver"]