devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/__init__.py

@@ -0,0 +1,44 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""devhelmkit：跨平台 UI 自动化框架。
+
+包根只导出稳定入口、公共契约与统一异常，平台实现延迟导入。
+"""
+from devhelmkit.entry import connect
+from devhelmkit.core.base_driver import BaseDriver
+from devhelmkit.core.base_component import BaseComponent
+from devhelmkit.core.base_window import BaseWindow
+from devhelmkit.core.selector_spec import SelectorSpec, build_selector
+from devhelmkit.exceptions import (
+    DevhelmError,
+    DeviceNotFoundError,
+    DeviceConnectError,
+    PlatformNotSupportedError,
+    DevhelmTimeoutError,
+    RpcError,
+    BackendObjectDroppedError,
+    ComponentNotFoundError,
+    ComponentDisappearedError,
+    AgentError,
+)
+
+__all__ = [
+    "connect",
+    "BaseDriver",
+    "BaseComponent",
+    "BaseWindow",
+    "SelectorSpec",
+    "build_selector",
+    "DevhelmError",
+    "DeviceNotFoundError",
+    "DeviceConnectError",
+    "PlatformNotSupportedError",
+    "DevhelmTimeoutError",
+    "RpcError",
+    "BackendObjectDroppedError",
+    "ComponentNotFoundError",
+    "ComponentDisappearedError",
+    "AgentError",
+]
+
+__version__ = "0.1.0"

devhelmkit/android/__init__.py

@@ -0,0 +1,7 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Android 平台预留骨架。
+
+首阶段不实现 Android 能力，connect(platform="android") 由入口层
+统一抛 PlatformNotSupportedError。
+"""

devhelmkit/android/driver.py

@@ -0,0 +1,18 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""AndroidDriver：Android 平台占位实现。
+
+首阶段不引入 AndroidUiObject、AdbDevice、uiautomator2 适配层。
+connect(platform="android") 由 entry.py 统一抛 PlatformNotSupportedError，
+不会到达本类。
+
+后续接入 Android 时，在此实现 BaseDriver 契约，并解除 entry.py 中的
+平台拦截。
+"""
+from devhelmkit.core.base_driver import BaseDriver
+
+
+class AndroidDriver(BaseDriver):
+    """Android 平台占位驱动，未实现任何契约方法。"""
+
+    pass

devhelmkit/core/__init__.py

@@ -0,0 +1,3 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""跨平台契约层：不包含任何平台实现。"""

devhelmkit/core/base_component.py

@@ -0,0 +1,214 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""BaseComponent：跨平台控件对象契约。
+
+对齐 U2 单对象模型：所有操作和关系方法统一在此定义。
+内部持有 SelectorSpec（纯数据），不依赖任何可操作选择器抽象。
+命名原则：U2 风格 snake_case 为基准，语义化方法为补充。
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Tuple, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+    from devhelmkit.core.selector_spec import SelectorSpec
+    from devhelmkit.core.base_driver import BaseDriver
+
+
+class BaseComponent(ABC):
+    """控件契约（查找到的控件对象）。"""
+
+    def __init__(self, driver: 'BaseDriver', selector: 'SelectorSpec'):
+        """
+        Args:
+            driver: 驱动实例
+            selector: 定位条件（纯数据）
+        """
+        self._driver = driver
+        self._selector = selector
+
+    # ============================================================
+    # 点击类
+    # ============================================================
+
+    @abstractmethod
+    def click(self) -> None:
+        """点击。"""
+
+    @abstractmethod
+    def long_click(self, duration: float = 0.5) -> None:
+        """长按。"""
+
+    @abstractmethod
+    def double_click(self) -> None:
+        """双击。"""
+
+    @abstractmethod
+    def click_exists(self, timeout: float = 0) -> bool:
+        """存在则点击，返回是否成功。"""
+
+    # ============================================================
+    # 文本类
+    # ============================================================
+
+    @abstractmethod
+    def set_text(self, text: str) -> None:
+        """输入文本。"""
+
+    @abstractmethod
+    def get_text(self) -> str:
+        """获取文本。"""
+
+    @abstractmethod
+    def clear_text(self) -> None:
+        """清空文本。"""
+
+    @abstractmethod
+    def input_text(self, text: str) -> None:
+        """输入文本（set_text 别名）。"""
+
+    # ============================================================
+    # 状态类
+    # ============================================================
+
+    @abstractmethod
+    def exists(self) -> bool:
+        """是否存在。"""
+
+    @abstractmethod
+    def wait(self, timeout: float) -> bool:
+        """等待出现。"""
+
+    @abstractmethod
+    def wait_gone(self, timeout: float) -> bool:
+        """等待消失。"""
+
+    # ============================================================
+    # 信息类
+    # ============================================================
+
+    @property
+    @abstractmethod
+    def info(self) -> Dict[str, Any]:
+        """控件信息（text/id/class/bounds/clickable/enabled/visible）。"""
+
+    @property
+    @abstractmethod
+    def bounds(self) -> Any:
+        """控件坐标 Rect(left, top, right, bottom)。"""
+
+    @abstractmethod
+    def center(self) -> Tuple[int, int]:
+        """控件中心点 (x, y)。"""
+
+    @abstractmethod
+    def get_attribute(self, name: str) -> Any:
+        """获取控件属性。"""
+
+    @abstractmethod
+    def screenshot(self, filename: Optional[str] = None) -> Union['Image', str, None]:
+        """控件截图。"""
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """description 属性。"""
+
+    @abstractmethod
+    def get_hint(self) -> str:
+        """获取 hint 属性。"""
+
+    @abstractmethod
+    def get_all_properties(self) -> dict:
+        """获取所有属性。"""
+
+    @abstractmethod
+    def get_original_text(self) -> str:
+        """获取原始文本。"""
+
+    # ============================================================
+    # 布尔属性
+    # ============================================================
+
+    @property
+    @abstractmethod
+    def is_long_clickable(self) -> bool:
+        """是否可长按。"""
+
+    @property
+    @abstractmethod
+    def is_checked(self) -> bool:
+        """是否已选中。"""
+
+    @property
+    @abstractmethod
+    def is_checkable(self) -> bool:
+        """是否可选中。"""
+
+    @property
+    @abstractmethod
+    def is_selected(self) -> bool:
+        """是否处于选中态。"""
+
+    # ============================================================
+    # 拖拽类
+    # ============================================================
+
+    @abstractmethod
+    def drag_to(self, x: int, y: int) -> None:
+        """拖拽到坐标。"""
+
+    @abstractmethod
+    def drag_to_component(self, other: 'BaseComponent') -> None:
+        """拖拽到另一控件。"""
+
+    # ============================================================
+    # 缩放类
+    # ============================================================
+
+    @abstractmethod
+    def pinch_in(self, scale: float = 0.5) -> None:
+        """控件上捏合缩小。"""
+
+    @abstractmethod
+    def pinch_out(self, scale: float = 1.5) -> None:
+        """控件上捏合放大。"""
+
+    # ============================================================
+    # 滚动类
+    # ============================================================
+
+    @abstractmethod
+    def scroll_search(self, target, vertical: bool = True,
+                      offset: Optional[int] = None) -> Optional['BaseComponent']:
+        """滚动查找子控件。"""
+
+    @abstractmethod
+    def scroll_to_top(self, speed: int = 600) -> None:
+        """滚动到顶部。"""
+
+    @abstractmethod
+    def scroll_to_bottom(self, speed: int = 600) -> None:
+        """滚动到底部。"""
+
+    # ============================================================
+    # 关系选择器（返回新的 BaseComponent，持有衍生 SelectorSpec）
+    # ============================================================
+
+    @abstractmethod
+    def child(self, **kwargs) -> 'BaseComponent':
+        """子控件。"""
+
+    @abstractmethod
+    def sibling(self, **kwargs) -> 'BaseComponent':
+        """兄弟控件。"""
+
+    @abstractmethod
+    def after(self, **kwargs) -> 'BaseComponent':
+        """之后控件。"""
+
+    @abstractmethod
+    def before(self, **kwargs) -> 'BaseComponent':
+        """之前控件。"""