devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/model/keys.py

@@ -0,0 +1,375 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""KeyCode：OpenHarmony 按键码枚举。
+
+重要：使用 OpenHarmony 按键码体系（非 Android KeyEvent），数值从
+2000 起步。禁止套用 Android 数值。
+采用 IntEnum 以支持数值比较。
+"""
+from enum import IntEnum
+
+
+class KeyCode(IntEnum):
+    """OpenHarmony 按键码。"""
+
+    # 功能与系统按键
+    FN = 0
+    UNKNOWN = -1
+    HOME = 1
+    BACK = 2
+    POWER = 18
+    CAMERA = 19
+    VOLUME_MUTE = 22
+    MUTE = 23
+    SLEEP = 2600
+    WAKE_UP = 2802
+    SCREENLOCK = 2809
+    VIRTUAL_MULTITASK = 2210
+
+    # 音量按键
+    VOLUME_UP = 16
+    VOLUME_DOWN = 17
+
+    # 亮度按键
+    BRIGHTNESS_UP = 40
+    BRIGHTNESS_DOWN = 41
+
+    # 多媒体按键
+    MEDIA_PLAY_PAUSE = 10
+    MEDIA_STOP = 11
+    MEDIA_NEXT = 12
+    MEDIA_PREVIOUS = 13
+    MEDIA_REWIND = 14
+    MEDIA_FAST_FORWARD = 15
+    MEDIA_PLAY = 2085
+    MEDIA_PAUSE = 2086
+    MEDIA_CLOSE = 2087
+    MEDIA_EJECT = 2088
+    MEDIA_RECORD = 2089
+
+    # 导航键
+    DPAD_UP = 2012
+    DPAD_DOWN = 2013
+    DPAD_LEFT = 2014
+    DPAD_RIGHT = 2015
+    DPAD_CENTER = 2016
+    PAGE_UP = 2068
+    PAGE_DOWN = 2069
+    MOVE_HOME = 2081
+    MOVE_END = 2082
+
+    # 数字键
+    NUM_0 = 2000
+    NUM_1 = 2001
+    NUM_2 = 2002
+    NUM_3 = 2003
+    NUM_4 = 2004
+    NUM_5 = 2005
+    NUM_6 = 2006
+    NUM_7 = 2007
+    NUM_8 = 2008
+    NUM_9 = 2009
+    STAR = 2010
+    POUND = 2011
+
+    # 字母键 A-Z
+    A = 2017
+    B = 2018
+    C = 2019
+    D = 2020
+    E = 2021
+    F = 2022
+    G = 2023
+    H = 2024
+    I = 2025
+    J = 2026
+    K = 2027
+    L = 2028
+    M = 2029
+    N = 2030
+    O = 2031
+    P = 2032
+    Q = 2033
+    R = 2034
+    S = 2035
+    T = 2036
+    U = 2037
+    V = 2038
+    W = 2039
+    X = 2040
+    Y = 2041
+    Z = 2042
+
+    # 标点与符号
+    COMMA = 2043
+    PERIOD = 2044
+    GRAVE = 2056
+    MINUS = 2057
+    EQUALS = 2058
+    LEFT_BRACKET = 2059
+    RIGHT_BRACKET = 2060
+    BACKSLASH = 2061
+    SEMICOLON = 2062
+    APOSTROPHE = 2063
+    SLASH = 2064
+    AT = 2065
+    PLUS = 2066
+
+    # 编辑与控制键
+    TAB = 2049
+    SPACE = 2050
+    SYM = 2051
+    EXPLORER = 2052
+    ENVELOPE = 2053
+    ENTER = 2054
+    DEL = 2055
+    ESCAPE = 2070
+    FORWARD_DEL = 2071
+    INSERT = 2083
+    FORWARD = 2084
+    MENU = 2067
+
+    # 修饰键
+    ALT_LEFT = 2045
+    ALT_RIGHT = 2046
+    SHIFT_LEFT = 2047
+    SHIFT_RIGHT = 2048
+    CTRL_LEFT = 2072
+    CTRL_RIGHT = 2073
+    CAPS_LOCK = 2074
+    SCROLL_LOCK = 2075
+    META_LEFT = 2076
+    META_RIGHT = 2077
+    FUNCTION = 2078
+    SYSRQ = 2079
+    BREAK = 2080
+
+    # 功能键 F1-F24
+    F1 = 2090
+    F2 = 2091
+    F3 = 2092
+    F4 = 2093
+    F5 = 2094
+    F6 = 2095
+    F7 = 2096
+    F8 = 2097
+    F9 = 2098
+    F10 = 2099
+    F11 = 2100
+    F12 = 2101
+    F13 = 2816
+    F14 = 2817
+    F15 = 2818
+    F16 = 2819
+    F17 = 2820
+    F18 = 2821
+    F19 = 2822
+    F20 = 2823
+    F21 = 2824
+    F22 = 2825
+    F23 = 2826
+    F24 = 2827
+
+    # 小键盘
+    NUM_LOCK = 2102
+    NUMPAD_0 = 2103
+    NUMPAD_1 = 2104
+    NUMPAD_2 = 2105
+    NUMPAD_3 = 2106
+    NUMPAD_4 = 2107
+    NUMPAD_5 = 2108
+    NUMPAD_6 = 2109
+    NUMPAD_7 = 2110
+    NUMPAD_8 = 2111
+    NUMPAD_9 = 2112
+    NUMPAD_DIVIDE = 2113
+    NUMPAD_MULTIPLY = 2114
+    NUMPAD_SUBTRACT = 2115
+    NUMPAD_ADD = 2116
+    NUMPAD_DOT = 2117
+    NUMPAD_COMMA = 2118
+    NUMPAD_ENTER = 2119
+    NUMPAD_EQUALS = 2120
+    NUMPAD_LEFT_PAREN = 2121
+    NUMPAD_RIGHT_PAREN = 2122
+    NUMPAD_PLUSMINUS = 2611
+
+    # 日文/韩文键
+    ZENKAKU_HANKAKU = 2601
+    ND = 2602
+    RO = 2603
+    KATAKANA = 2604
+    HIRAGANA = 2605
+    HENKAN = 2606
+    KATAKANA_HIRAGANA = 2607
+    MUHENKAN = 2608
+    LINEFEED = 2609
+    MACRO = 2610
+    SCALE = 2612
+    HANGUEL = 2613
+    HANJA = 2614
+    YEN = 2615
+
+    # 多媒体扩展键
+    STOP = 2616
+    AGAIN = 2617
+    PROPS = 2618
+    UNDO = 2619
+    COPY = 2620
+    OPEN = 2621
+    PASTE = 2622
+    FIND = 2623
+    CUT = 2624
+    HELP = 2625
+    CALC = 2626
+    FILE = 2627
+    BOOKMARKS = 2628
+    NEXT = 2629
+    PLAYPAUSE = 2630
+    PREVIOUS = 2631
+    STOPCD = 2632
+    CONFIG = 2634
+    REFRESH = 2635
+    EXIT = 2636
+    EDIT = 2637
+    SCROLLUP = 2638
+    SCROLLDOWN = 2639
+    NEW = 2640
+    REDO = 2641
+    CLOSE = 2642
+    PLAY = 2643
+    BASSBOOST = 2644
+    PRINT = 2645
+    CHAT = 2646
+    FINANCE = 2647
+    CANCEL = 2648
+    KBDILLUM_TOGGLE = 2649
+    KBDILLUM_DOWN = 2650
+    KBDILLUM_UP = 2651
+    SEND = 2652
+    REPLY = 2653
+    FORWARDMAIL = 2654
+    SAVE = 2655
+    DOCUMENTS = 2656
+    VIDEO_NEXT = 2657
+    VIDEO_PREV = 2658
+    BRIGHTNESS_CYCLE = 2659
+    BRIGHTNESS_ZERO = 2660
+    DISPLAY_OFF = 2661
+    BTN_MISC = 2662
+    GOTO = 2663
+    INFO = 2664
+    PROGRAM = 2665
+    PVR = 2666
+    SUBTITLE = 2667
+    FULL_SCREEN = 2668
+    KEYBOARD = 2669
+    ASPECT_RATIO = 2670
+    PC = 2671
+    TV = 2672
+    TV2 = 2673
+    VCR = 2674
+    VCR2 = 2675
+    SAT = 2676
+    CD = 2677
+    TAPE = 2678
+    TUNER = 2679
+    PLAYER = 2680
+    DVD = 2681
+    AUDIO = 2682
+    VIDEO = 2683
+    MEMO = 2684
+    CALENDAR = 2685
+    RED = 2686
+    GREEN = 2687
+    YELLOW = 2688
+    BLUE = 2689
+    CHANNELUP = 2690
+    CHANNELDOWN = 2691
+    LAST = 2692
+    RESTART = 2693
+    SLOW = 2694
+    SHUFFLE = 2695
+    VIDEOPHONE = 2696
+    GAMES = 2697
+    ZOOMIN = 2698
+    ZOOMOUT = 2699
+    ZOOMRESET = 2700
+    WORDPROCESSOR = 2701
+    EDITOR = 2702
+    SPREADSHEET = 2703
+    GRAPHICSEDITOR = 2704
+    PRESENTATION = 2705
+    DATABASE = 2706
+    NEWS = 2707
+    VOICEMAIL = 2708
+    ADDRESSBOOK = 2709
+    MESSENGER = 2710
+    BRIGHTNESS_TOGGLE = 2711
+    SPELLCHECK = 2712
+    COFFEE = 2713
+    MEDIA_REPEAT = 2714
+    IMAGES = 2715
+    BUTTONCONFIG = 2716
+    TASKMANAGER = 2717
+    JOURNAL = 2718
+    CONTROLPANEL = 2719
+    APPSELECT = 2720
+    SCREENSAVER = 2721
+    ASSISTANT = 2722
+    KBD_LAYOUT_NEXT = 2723
+    BRIGHTNESS_MIN = 2724
+    BRIGHTNESS_MAX = 2725
+    KBDINPUTASSIST_PREV = 2726
+    KBDINPUTASSIST_NEXT = 2727
+    KBDINPUTASSIST_PREVGROUP = 2728
+    KBDINPUTASSIST_NEXTGROUP = 2729
+    KBDINPUTASSIST_ACCEPT = 2730
+    KBDINPUTASSIST_CANCEL = 2731
+
+    # 其他系统键
+    FRONT = 2800
+    SETUP = 2801
+    SENDFILE = 2803
+    DELETEFILE = 2804
+    XFER = 2805
+    PROG1 = 2806
+    PROG2 = 2807
+    MSDOS = 2808
+    DIRECTION_ROTATE_DISPLAY = 2810
+    CYCLEWINDOWS = 2811
+    COMPUTER = 2812
+    EJECTCLOSECD = 2813
+    ISO = 2814
+    MOVE = 2815
+    PROG3 = 2828
+    PROG4 = 2829
+    DASHBOARD = 2830
+    SUSPEND = 2831
+    HP = 2832
+    SOUND = 2833
+    QUESTION = 2834
+    CONNECT = 2836
+    SPORT = 2837
+    SHOP = 2838
+    ALTERASE = 2839
+    SWITCHVIDEOMODE = 2841
+    BATTERY = 2842
+    BLUETOOTH = 2843
+    WLAN = 2844
+    UWB = 2845
+    WWAN_WIMAX = 2846
+    RFKILL = 2847
+
+    # 频道与游戏手柄按键
+    CHANNEL = 3001
+    BTN_0 = 3100
+    BTN_1 = 3101
+    BTN_2 = 3102
+    BTN_3 = 3103
+    BTN_4 = 3104
+    BTN_5 = 3105
+    BTN_6 = 3106
+    BTN_7 = 3107
+    BTN_8 = 3108
+    BTN_9 = 3109

devhelmkit/model/match_pattern.py

@@ -0,0 +1,15 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""MatchPattern：匹配模式枚举。"""
+from enum import IntEnum
+
+
+class MatchPattern(IntEnum):
+    """匹配模式，用于控件文本/属性的匹配方式。"""
+
+    EQUALS = 0          # 精确匹配（默认）
+    CONTAINS = 1        # 包含
+    STARTS_WITH = 2     # 开头匹配
+    ENDS_WITH = 3       # 结尾匹配
+    REGEXP = 4          # 正则匹配
+    REGEXP_ICASE = 5    # 正则匹配（忽略大小写）

devhelmkit/model/page.py

@@ -0,0 +1,13 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""页面信息类型。"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class BasicPage:
+    """页面信息。"""
+    screenshot_path: Optional[str] = None
+    layout_path: Optional[str] = None
+    display_id: int = 0

devhelmkit/model/params.py

@@ -0,0 +1,42 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""UI 操作参数类型：WindowFilter / UiParam / DeviceType / InputTextMode。"""
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Optional
+
+
+class InputTextMode(IntEnum):
+    """输入文本模式。"""
+    DEFAULT = 0
+    CLEAR_FIRST = 1
+    APPEND = 2
+
+
+class DeviceType(IntEnum):
+    """设备类型。"""
+    PHONE = 0
+    TABLET = 1
+    TV = 2
+    WATCH = 3
+    CAR = 4
+
+
+@dataclass
+class WindowFilter:
+    """窗口过滤条件。"""
+    bundle: Optional[str] = None
+    title: Optional[str] = None
+    display_id: Optional[int] = None
+
+
+class UiParam:
+    """UI 操作控制相关常量（类常量风格）。"""
+
+    NORMAL = "normal"
+    LONG = "long"
+    DOUBLE = "double"
+    LEFT = "LEFT"
+    RIGHT = "RIGHT"
+    UP = "UP"
+    DOWN = "DOWN"

devhelmkit/model/rect.py

@@ -0,0 +1,58 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Rect 与 Point：坐标矩形与坐标点。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Tuple
+
+
+@dataclass
+class Point:
+    """坐标点。"""
+    x: int
+    y: int
+
+    def as_tuple(self) -> Tuple[int, int]:
+        return (self.x, self.y)
+
+
+@dataclass
+class Rect:
+    """矩形坐标。"""
+
+    left: int
+    top: int
+    right: int
+    bottom: int
+
+    @property
+    def width(self) -> int:
+        return self.right - self.left
+
+    @property
+    def height(self) -> int:
+        return self.bottom - self.top
+
+    @property
+    def center(self) -> Point:
+        return Point(
+            x=(self.left + self.right) // 2,
+            y=(self.top + self.bottom) // 2
+        )
+
+    @property
+    def top_left(self) -> Point:
+        return Point(x=self.left, y=self.top)
+
+    @property
+    def bottom_right(self) -> Point:
+        return Point(x=self.right, y=self.bottom)
+
+    def contains(self, point: Point) -> bool:
+        """判断点是否在矩形内。"""
+        return (self.left <= point.x <= self.right and
+                self.top <= point.y <= self.bottom)
+
+    def as_tuple(self) -> Tuple[int, int, int, int]:
+        return (self.left, self.top, self.right, self.bottom)

devhelmkit/model/runnable.py

@@ -0,0 +1,18 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Runnable：可执行任务封装。"""
+
+
+class Runnable:
+    """延迟执行任务封装（函数 + 参数）。"""
+
+    def __init__(self, func, args, kwargs):
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs
+
+    def run(self):
+        self.func(*self.args, **self.kwargs)
+
+    def __str__(self):
+        return "%s%s-%s" % (self.func.__name__, self.args, self.kwargs)

devhelmkit/utils/__init__.py

@@ -0,0 +1,3 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""通用工具层：只放跨平台、无业务语义的基础工具。"""

devhelmkit/utils/logger.py

@@ -0,0 +1,72 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""轻量日志：Error / Warn / Info / Debug / Trace。
+
+仅控制台输出，无轮转、无脱敏。RPC 运行时默认不使用通用重试，
+避免点击、输入等有副作用操作被重复执行。
+"""
+import logging
+import sys
+
+_LOGGER_NAME = "devhelmkit"
+_logger = logging.getLogger(_LOGGER_NAME)
+_logger.addHandler(logging.NullHandler())
+
+
+class _LogLevel:
+    ERROR = logging.ERROR
+    WARN = logging.WARNING
+    INFO = logging.INFO
+    DEBUG = logging.DEBUG
+    TRACE = 5
+
+
+logging.addLevelName(_LogLevel.TRACE, "TRACE")
+
+
+def _trace(self, message, *args, **kwargs):
+    if self.isEnabledFor(_LogLevel.TRACE):
+        self._log(_LogLevel.TRACE, message, args, **kwargs)
+
+
+logging.Logger.trace = _trace  # type: ignore[attr-defined]
+
+
+def setup_logger(level: int = logging.INFO) -> logging.Logger:
+    """配置并返回 devhelmkit logger，附加控制台 handler。"""
+    _logger.setLevel(level)
+    if not any(isinstance(h, logging.StreamHandler) and h.stream is sys.stderr
+               for h in _logger.handlers):
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(
+            logging.Formatter("[%(asctime)s][%(levelname)s][devhelmkit] %(message)s",
+                               datefmt="%H:%M:%S")
+        )
+        _logger.addHandler(handler)
+    return _logger
+
+
+def get_logger() -> logging.Logger:
+    """获取 devhelmkit logger。"""
+    return _logger
+
+
+def error(msg, *args, **kwargs):
+    _logger.error(msg, *args, **kwargs)
+
+
+def warn(msg, *args, **kwargs):
+    _logger.warning(msg, *args, **kwargs)
+
+
+def info(msg, *args, **kwargs):
+    _logger.info(msg, *args, **kwargs)
+
+
+def debug(msg, *args, **kwargs):
+    _logger.debug(msg, *args, **kwargs)
+
+
+def trace(msg, *args, **kwargs):
+    if _logger.isEnabledFor(_LogLevel.TRACE):
+        _logger._log(_LogLevel.TRACE, msg, args, **kwargs)

devhelmkit/utils/retry.py

@@ -0,0 +1,46 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""可控重试工具：仅用于连接阶段与无副作用流程。
+
+RPC 运行时（控件查找、点击、输入等）默认不重试，避免副作用操作被重复执行。
+"""
+import time
+from typing import Callable, Optional, Tuple, Type
+
+from devhelmkit.utils.logger import get_logger
+
+_logger = get_logger()
+
+
+def retry(func: Callable, retries: int = 3, delay: float = 1.0,
+          backoff: float = 2.0,
+          exceptions: Tuple[Type[BaseException], ...] = (Exception,),
+          sleep: Optional[Callable[[float], None]] = None) -> object:
+    """指数退避重试。
+
+    Args:
+        func: 待重试的可调用对象。
+        retries: 最大重试次数（不含首次）。
+        delay: 首次失败后等待秒数。
+        backoff: 退避倍率，每次等待 = delay * backoff ** attempt。
+        exceptions: 触发重试的异常类型。
+        sleep: 自定义 sleep 函数，便于测试注入。
+
+    Returns:
+        func 的返回值。
+
+    Raises:
+        最后一次失败的异常。
+    """
+    _sleep = sleep or time.sleep
+    attempt = 0
+    while True:
+        try:
+            return func()
+        except exceptions as exc:
+            attempt += 1
+            if attempt > retries:
+                raise
+            wait = delay * (backoff ** (attempt - 1))
+            _logger.debug("第 %d 次重试，等待 %.2fs：%s", attempt, wait, exc)
+            _sleep(wait)

devhelmkit/utils/timeout.py

@@ -0,0 +1,64 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""超时与状态轮询工具。"""
+import time
+from typing import Callable, Optional, Tuple, Type
+
+from devhelmkit.exceptions import DevhelmTimeoutError
+
+
+def wait_for(predicate: Callable[[], bool], timeout: float = 10.0,
+             interval: float = 0.5,
+             sleep: Optional[Callable[[float], None]] = None) -> bool:
+    """轮询等待条件成立。
+
+    Args:
+        predicate: 返回 bool 的可调用对象，True 表示条件满足。
+        timeout: 总超时秒数。
+        interval: 轮询间隔秒数。
+        sleep: 自定义 sleep 函数，便于测试注入。
+
+    Returns:
+        True 若在超时内条件成立，否则 False。
+    """
+    _sleep = sleep or time.sleep
+    deadline = time.monotonic() + timeout
+    while True:
+        if predicate():
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        _sleep(min(interval, max(0.0, deadline - time.monotonic())))
+
+
+def wait_for_raise(predicate: Callable[[], bool], timeout: float = 10.0,
+                    interval: float = 0.5,
+                    exceptions: Tuple[Type[BaseException], ...] = (Exception,),
+                    sleep: Optional[Callable[[float], None]] = None) -> bool:
+    """轮询等待条件成立，predicate 抛异常时视为未满足继续轮询。
+
+    超时后返回 False 而非抛异常，调用方可自行决定是否抛 DevhelmTimeoutError。
+    """
+    _sleep = sleep or time.sleep
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            if predicate():
+                return True
+        except exceptions:
+            pass
+        if time.monotonic() >= deadline:
+            return False
+        _sleep(min(interval, max(0.0, deadline - time.monotonic())))
+
+
+def ensure_timeout(timeout: Optional[float], default: float) -> float:
+    """规范化超时：None 取默认值，负数视为 0。"""
+    if timeout is None:
+        return default
+    return max(0.0, float(timeout))
+
+
+def raise_on_timeout(timeout: float, condition_desc: str) -> None:
+    """显式抛 DevhelmTimeoutError。"""
+    raise DevhelmTimeoutError("等待超时（%.2fs）：%s" % (timeout, condition_desc))