ascript 1.3.0__tar.gz → 1.3.2__tar.gz

{ascript-1.3.0 → ascript-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ascript
-Version: 1.3.0
+Version: 1.3.2
 Summary: Ascript Developer Library
 License: MIT
 Classifier: Operating System :: Microsoft :: Windows

{ascript-1.3.0 → ascript-1.3.2}/ascript/windows/__init__.py

@@ -1,3 +1,7 @@
+"""ascript.windows 模块 - Windows 平台自动化核心包。
+
+负责初始化 Windows 平台相关的路径配置和 RapidOCR Hook 注入。
+"""
 import os
 import sys
 

ascript-1.3.2/ascript/windows/daos/screen.py

@@ -0,0 +1,156 @@
+"""屏幕数据模型模块。
+
+定义屏幕操作中使用的基础数据结构，包括坐标点、颜色、尺寸和 OCR 识别结果。
+"""
+
+import json
+
+
+class Point:
+    """屏幕坐标点。
+
+    表示屏幕上的一个二维坐标点。
+    """
+
+    def __init__(self, x: int = 0, y: int = 0):
+        """初始化坐标点。
+
+        Args:
+            x: 横坐标，默认为 0。
+            y: 纵坐标，默认为 0。
+        """
+        self.x = x
+        self.y = y
+
+    def __str__(self):
+        """返回坐标点的 JSON 字符串表示。
+
+        Returns:
+            str: 包含 x 和 y 的 JSON 字符串，例如 '{"x": 100, "y": 200}'。
+        """
+        return json.dumps({'x': self.x, 'y': self.y})
+
+    def to_dict(self):
+        """将坐标点转换为字典。
+
+        Returns:
+            dict: 包含 'x' 和 'y' 键的字典。
+        """
+        return {'x': self.x, 'y': self.y}
+
+
+class Color:
+    """颜色值。
+
+    将十六进制颜色字符串解析为 RGB 分量。
+    """
+
+    def __init__(self, color: str):
+        """初始化颜色对象。
+
+        从十六进制颜色字符串（如 '#FF00AA'）中解析出 R、G、B 分量。
+
+        Args:
+            color: 十六进制颜色字符串，格式为 '#RRGGBB'。
+        """
+        self.r = int(color[1:3], 16)
+        self.g = int(color[3:5], 16)
+        self.b = int(color[5:], 16)
+
+    def to_rgb(self):
+        """将颜色转换为 RGB 列表。
+
+        Returns:
+            list: 包含 [R, G, B] 三个整数值的列表，每个值范围为 0-255。
+        """
+        return [self.r, self.g, self.b]
+
+
+class Size:
+    """尺寸大小。
+
+    表示宽度和高度的二维尺寸。
+    """
+
+    def __init__(self, width, height):
+        """初始化尺寸对象。
+
+        Args:
+            width: 宽度值。
+            height: 高度值。
+        """
+        self.width = width
+        self.height = height
+
+
+class Point:
+    """屏幕坐标点（重新定义）。
+
+    表示屏幕上的一个二维坐标点，覆盖了之前定义的 Point 类。
+    """
+
+    def __init__(self, x: int = 0, y: int = 0):
+        """初始化坐标点。
+
+        Args:
+            x: 横坐标，默认为 0。
+            y: 纵坐标，默认为 0。
+        """
+        self.x = x
+        self.y = y
+
+    def __str__(self):
+        """返回坐标点的 JSON 字符串表示。
+
+        Returns:
+            str: 包含 x 和 y 的 JSON 字符串。
+        """
+        return json.dumps({'x': self.x, 'y': self.y})
+
+    def to_dict(self):
+        """将坐标点转换为字典。
+
+        Returns:
+            dict: 包含 'x' 和 'y' 键的字典。
+        """
+        return {'x': self.x, 'y': self.y}
+
+
+class OcrRes:
+    """OCR 识别结果。
+
+    封装单条 OCR 文字识别的结果，包括识别文本、置信度和区域位置信息。
+    """
+
+    def __init__(self, text: str = None, confidence: float = None, region_position: list = None):
+        """初始化 OCR 识别结果。
+
+        Args:
+            text: 识别出的文本内容。
+            confidence: 识别置信度，取值范围为 0.0 到 1.0。
+            region_position: 文本区域的四个顶点坐标列表，
+                格式为 [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]。
+        """
+        self.text = text
+        self.confidence = float(confidence)
+        self.region_position = region_position
+        if self.region_position:
+            self.center_x = region_position[2][0] - region_position[0][0]
+            self.center_y = region_position[2][1] - region_position[0][1]
+
+    def to_dict(self):
+        """将 OCR 结果转换为字典。
+
+        Returns:
+            dict: 包含 'text'、'confidence' 和 'region_position' 键的字典。
+        """
+        return {'text': self.text, 'confidence': self.confidence, 'region_position': self.region_position}
+
+    def __str__(self):
+        """返回 OCR 结果的字符串表示。
+
+        Returns:
+            str: OCR 结果字典的字符串形式。
+        """
+        return self.to_dict().__str__()
+

ascript-1.3.2/ascript/windows/hardware/keyboard.py

@@ -0,0 +1,107 @@
+import time
+import pyautogui
+import pyperclip
+from typing import Union, List
+
+class Keyboard:
+    """键盘自动化操作类。
+
+    基于 PyAutoGUI 封装，支持中英文智能输入、组合键操作及链式调用。
+    中文输入通过剪贴板粘贴实现，英文输入通过模拟按键实现。
+    所有方法均为类方法，返回类本身以支持链式调用。
+    """
+
+    @classmethod
+    def input(cls, msg: str, interval: float = 0.0):
+        """自动识别中英文并输入文本。
+
+        如果文本包含非 ASCII 字符（如中文、全角符号），通过剪贴板粘贴实现；
+        如果是纯英文，通过模拟键盘敲击实现。
+
+        Args:
+            msg: 要输入的字符串内容。
+            interval: 仅对纯英文输入有效，每个字符之间敲击的间隔时间（秒），默认为 0.0。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        # 检查是否包含非 ASCII 字符（如中文、全角符号等）
+        if any(ord(c) > 127 for c in msg):
+            # 备份当前剪贴板（可选，如果需要更严谨可以记录后还原）
+            pyperclip.copy(msg)
+            time.sleep(0.1)  # 缓冲，确保系统剪贴板已更新
+            pyautogui.hotkey('ctrl', 'v')
+        else:
+            # 纯英文使用 write，比 typewrite 更现代
+            pyautogui.write(msg, interval=interval)
+        return cls
+
+    @classmethod
+    def key(cls, keys: Union[str, List[str]], presses: int = 1, interval: float = 0.1):
+        """按下并释放指定按键。
+
+        Args:
+            keys: 按键名称（如 'enter'、'esc'）或按键名称列表。
+            presses: 连续按下的次数，默认为 1。
+            interval: 连续按下之间的间隔时间（秒），默认为 0.1。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        pyautogui.press(keys, presses=presses, interval=interval)
+        return cls
+
+    @classmethod
+    def key_hot(cls, *args, interval: float = 0.1):
+        """执行组合键操作。
+
+        例如 key_hot('ctrl', 'c') 执行复制操作。
+
+        Args:
+            *args: 按键序列，例如 'ctrl', 'alt', 'delete'。
+            interval: 按键按下之间的间隔时间（秒），默认为 0.1。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        pyautogui.hotkey(*args, interval=interval)
+        return cls
+
+    @classmethod
+    def key_down(cls, key_str: str):
+        """按下指定按键不松开。
+
+        Args:
+            key_str: 按键名称，如 'shift'、'ctrl'。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        pyautogui.keyDown(key_str)
+        return cls
+
+    @classmethod
+    def key_up(cls, key_str: str):
+        """松开已按下的按键。
+
+        Args:
+            key_str: 按键名称，如 'shift'、'ctrl'。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        pyautogui.keyUp(key_str)
+        return cls
+
+    @classmethod
+    def wait(cls, seconds: float):
+        """在键盘操作链中插入等待。
+
+        Args:
+            seconds: 等待的时长（秒）。
+
+        Returns:
+            Keyboard 类本身，支持链式调用。
+        """
+        time.sleep(seconds)
+        return cls

{ascript-1.3.0 → ascript-1.3.2}/ascript/windows/hardware/logitech_driver.py

@@ -6,6 +6,18 @@ from ..system import R
 
 
 class LogitechDriver:
+    """罗技驱动级硬件操作类。
+
+    通过加载罗技 G HUB SDK 的 DLL，实现驱动级别的鼠标点击和移动操作。
+    需要系统已安装并运行罗技 G HUB 驱动程序。
+    支持 x86 和 x64 架构自动适配。
+
+    Attributes:
+        DLL_NAME: 罗技 SDK DLL 文件名。
+        _dll: 已加载的 DLL 对象实例。
+        _initialized: 驱动是否已完成初始化。
+    """
+
     DLL_NAME = "LogitechGkeyEnginesWrapper.dll"
 
     _dll = None
@@ -13,13 +25,24 @@ class LogitechDriver:
 
     @classmethod
     def _get_dll_path(cls):
-        """根据 Python 位数精准定位 DLL 路径"""
+        """根据当前 Python 解释器的位数定位对应架构的 DLL 文件路径。
+
+        Returns:
+            str: DLL 文件的完整路径。
+        """
         arch = "x64" if sys.maxsize > 2 ** 32 else "x86"
         return R.internal("windows", "resources", "libs", "logitech", arch, cls.DLL_NAME)
 
     @classmethod
     def _is_ghub_running(cls) -> bool:
-        """多重检测 G HUB 是否在运行"""
+        """检测罗技 G HUB 进程是否正在运行。
+
+        通过 tasklist 命令检查 lghub.exe、lghub_agent.exe、lghub_updater.exe
+        等进程是否存在。
+
+        Returns:
+            bool: G HUB 正在运行返回 True，否则返回 False。
+        """
         try:
             # 罗技 G HUB 可能存在于这三个进程中
             targets = {"lghub.exe", "lghub_agent.exe", "lghub_updater.exe"}
@@ -31,8 +54,14 @@ class LogitechDriver:
 
     @classmethod
     def init(cls) -> bool:
-        """
-        深度初始化逻辑
+        """初始化罗技驱动。
+
+        执行环境检查（G HUB 进程、DLL 文件），加载 DLL 并尝试调用
+        SDK 初始化函数。初始化成功后会等待 0.5 秒确保驱动就绪。
+        重复调用时若已初始化会直接返回 True。
+
+        Returns:
+            bool: 初始化成功返回 True，失败返回 False。
         """
         if cls._initialized:
             return True
@@ -79,7 +108,14 @@ class LogitechDriver:
 
     @classmethod
     def advanced_click_guide(cls):
-        """高级引导：检查权限与环境"""
+        """高级引导：检查运行权限与驱动环境。
+
+        检查当前是否以管理员权限运行，并尝试激活驱动模式。
+        在控制台输出检查结果供用户排查问题。
+
+        Returns:
+            bool: 驱动激活成功返回 True，失败返回 False。
+        """
         print("--- [Logitech] 底层引擎自检 ---")
 
         # 管理员权限检查
@@ -100,9 +136,16 @@ class LogitechDriver:
 
     @classmethod
     def click(cls, button: int = 1, duration: float = 0.05):
-        """
-        驱动级点击
-        :param button: 1=左键, 2=中键, 4=右键 (注意：SDK 中右键通常是 4)
+        """执行驱动级鼠标点击。
+
+        通过罗技 SDK 直接发送鼠标按键事件，可绕过部分反作弊检测。
+
+        Args:
+            button: 鼠标按键编号，1=左键，2=中键，4=右键（SDK 定义）。
+            duration: 按下与释放之间的间隔时间（秒），默认为 0.05。
+
+        Returns:
+            bool: 点击成功返回 True，失败（驱动未初始化或异常）返回 False。
         """
         if not cls.init():
             return False
@@ -116,7 +159,17 @@ class LogitechDriver:
 
     @classmethod
     def move_rel(cls, x: int, y: int):
-        """相对移动"""
+        """驱动级鼠标相对位移。
+
+        通过罗技 SDK 发送鼠标相对移动事件。
+
+        Args:
+            x: 水平方向的相对位移量（像素）。
+            y: 垂直方向的相对位移量（像素）。
+
+        Returns:
+            bool: 移动成功返回对应的 SDK 返回值，失败返回 False。
+        """
         if not cls.init():
             return False
         try:

ascript-1.3.2/ascript/windows/hardware/mouse.py

@@ -0,0 +1,202 @@
+import time
+import random
+import pydirectinput
+from ctypes import windll
+from typing import Optional
+
+# 启用 DPI 感知
+try:
+    windll.shcore.SetProcessDpiAwareness(1)
+except:
+    try:
+        windll.user32.SetProcessDPIAware()
+    except:
+        pass
+
+
+class Mouse:
+    """鼠标自动化控制类。
+
+    基于 PyDirectInput 封装，支持鼠标移动、点击、长按、滚动、拖拽等操作。
+    已启用 DPI 感知，自动处理 Windows 高分屏缩放。
+    所有方法均为类方法，返回类本身以支持链式调用。
+
+    Attributes:
+        LEFT: 左键标识符。
+        MIDDLE: 中键标识符。
+        RIGHT: 右键标识符。
+        DEFAULT_MOVE_DURATION: 默认鼠标移动耗时（秒）。
+    """
+
+    # 基础按键定义
+    LEFT = "left"
+    MIDDLE = "middle"
+    RIGHT = "right"
+
+    # 全局配置
+    pydirectinput.FAILSAFE = True
+    DEFAULT_MOVE_DURATION = 0.1
+
+    @classmethod
+    def mouse_move(cls, x: int, y: int, move_duration: float = DEFAULT_MOVE_DURATION):
+        """移动鼠标到屏幕上的指定坐标位置。
+
+        Args:
+            x: 目标位置的屏幕 X 坐标。
+            y: 目标位置的屏幕 Y 坐标。
+            move_duration: 鼠标移动过程的耗时（秒），默认为 0.1。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        pydirectinput.moveTo(x=x, y=y, duration=move_duration)
+        return cls
+
+    @classmethod
+    def mouse_down(cls, x: int = None, y: int = None, button: str = LEFT):
+        """按下鼠标按键不松开。
+
+        Args:
+            x: 按下时的屏幕 X 坐标，为 None 时在当前位置按下。
+            y: 按下时的屏幕 Y 坐标，为 None 时在当前位置按下。
+            button: 鼠标按键，可选 'left'、'middle'、'right'，默认为左键。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        pydirectinput.mouseDown(x=x, y=y, button=button)
+        return cls
+
+    @classmethod
+    def mouse_up(cls, x: int = None, y: int = None, button: str = LEFT):
+        """松开已按下的鼠标按键。
+
+        Args:
+            x: 松开时的屏幕 X 坐标，为 None 时在当前位置松开。
+            y: 松开时的屏幕 Y 坐标，为 None 时在当前位置松开。
+            button: 鼠标按键，可选 'left'、'middle'、'right'，默认为左键。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        pydirectinput.mouseUp(x=x, y=y, button=button)
+        return cls
+
+    @classmethod
+    def click(cls,
+              x: Optional[int] = None,
+              y: Optional[int] = None,
+              clicks: int = 1,
+              interval: float = 0.1,
+              button: str = LEFT,
+              move_duration: float = 0.0,
+              duration: float = 0.05,
+              offset: int = 0):
+        """模拟鼠标点击操作。
+
+        支持指定坐标、多次点击、随机偏移等功能。
+
+        Args:
+            x: 点击位置的屏幕 X 坐标，为 None 时在当前位置点击。
+            y: 点击位置的屏幕 Y 坐标，为 None 时在当前位置点击。
+            clicks: 点击次数，默认为 1。设为 2 可实现双击。
+            interval: 多次点击之间的间隔时间（秒），默认为 0.1。
+            button: 鼠标按键，可选 'left'、'middle'、'right'，默认为左键。
+            move_duration: 移动到目标位置的耗时（秒），默认为 0.0（瞬移）。
+            duration: 按下与弹起之间的物理间隔（秒），增大此值可提高点击成功率，默认为 0.05。
+            offset: 随机偏移范围（像素），大于 0 时会在目标坐标附近随机偏移，用于模拟人类操作。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        target_x, target_y = x, y
+
+        if offset > 0 and x is not None and y is not None:
+            target_x = max(0, x + random.randint(-offset, offset))
+            target_y = max(0, y + random.randint(-offset, offset))
+
+        if target_x is not None and target_y is not None:
+            cls.mouse_move(target_x, target_y, move_duration=move_duration)
+
+        for i in range(clicks):
+            cls.mouse_down(button=button)
+            time.sleep(max(0.01, duration))
+            cls.mouse_up(button=button)
+            if i < clicks - 1:
+                time.sleep(interval)
+        return cls
+
+    @classmethod
+    def long_press(cls, x: int = None, y: int = None, press_duration: float = 2.0, button: str = LEFT):
+        """模拟鼠标长按操作。
+
+        在指定位置按下鼠标并保持一段时间后松开。
+
+        Args:
+            x: 长按位置的屏幕 X 坐标，为 None 时在当前位置操作。
+            y: 长按位置的屏幕 Y 坐标，为 None 时在当前位置操作。
+            press_duration: 按住的持续时间（秒），默认为 2.0。
+            button: 鼠标按键，可选 'left'、'middle'、'right'，默认为左键。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        if x is not None and y is not None:
+            cls.mouse_move(x, y, move_duration=0.0)
+
+        cls.mouse_down(button=button)
+        time.sleep(press_duration)
+        cls.mouse_up(button=button)
+        return cls
+
+    @classmethod
+    def scroll(cls, clicks: int, x: int = None, y: int = None):
+        """模拟鼠标滚轮滚动。
+
+        Args:
+            clicks: 滚动量，正数向上滚动，负数向下滚动。
+            x: 滚动时的屏幕 X 坐标，为 None 时在当前位置滚动。
+            y: 滚动时的屏幕 Y 坐标，为 None 时在当前位置滚动。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        if x is not None and y is not None:
+            cls.mouse_move(x, y, move_duration=0.0)
+        pydirectinput.scroll(clicks)
+        return cls
+
+    @classmethod
+    def drag(cls, to_x: int, to_y: int, from_x: int = None, from_y: int = None, move_duration: float = 0.5):
+        """从指定位置拖拽鼠标到目标位置。
+
+        使用左键进行拖拽操作。如果不指定起始位置，则从当前鼠标位置开始拖拽。
+
+        Args:
+            to_x: 拖拽目标的屏幕 X 坐标。
+            to_y: 拖拽目标的屏幕 Y 坐标。
+            from_x: 拖拽起始的屏幕 X 坐标，为 None 时从当前位置开始。
+            from_y: 拖拽起始的屏幕 Y 坐标，为 None 时从当前位置开始。
+            move_duration: 拖拽移动过程的耗时（秒），默认为 0.5。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        if from_x is not None and from_y is not None:
+            cls.mouse_move(from_x, from_y, move_duration=0.0)
+
+        pydirectinput.dragTo(to_x, to_y, duration=move_duration, button=cls.LEFT)
+        return cls
+
+    @classmethod
+    def wait(cls, seconds: float):
+        """在鼠标操作链中插入等待。
+
+        Args:
+            seconds: 等待的时长（秒）。
+
+        Returns:
+            Mouse 类本身，支持链式调用。
+        """
+        time.sleep(seconds)
+        return cls

ascript-1.3.2/ascript/windows/license/__init__.py

@@ -0,0 +1,16 @@
+"""许可证加密模块。
+
+提供基于 AES 加密的许可证验证功能，包括加密通信和数据填充工具。
+
+Exports:
+    achttp: 加密 HTTP 通信模块。
+    AES: AES 加密算法。
+    pad: PKCS7 数据填充函数。
+    unpad: PKCS7 数据去填充函数。
+"""
+
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import pad, unpad
+from . import achttp
+
+__all__ = ['achttp', "AES", "pad", "unpad"]

{ascript-1.3.0 → ascript-1.3.2}/ascript/windows/resources/templates/build.py

@@ -5,6 +5,15 @@ import shutil
 
 
 def auto_build(entry_file, project_name):
+    """使用 Nuitka 将 Python 项目打包为独立的 Windows 可执行文件。
+
+    自动构造 Nuitka 编译命令，实时输出编译日志到控制台，
+    并在完成后报告编译结果。
+
+    Args:
+        entry_file: Python 入口文件路径（如 'main.py'）
+        project_name: 输出的可执行文件名称（不含 .exe 后缀）
+    """
     # 1. 确保入口文件存在
     if not os.path.exists(entry_file):
         print(f"❌ 错误: 找不到入口文件 {entry_file}")

{ascript-1.3.0 → ascript-1.3.2}/ascript/windows/resources/templates/windows/main.py

@@ -1,3 +1,7 @@
+"""AScript Windows 应用模板的入口程序。
+
+演示如何使用 FloatScriptWindow 创建带有启动/停止控制的自动化脚本应用。
+"""
 import multiprocessing
 import time
 import sys
@@ -10,12 +14,10 @@ app = FloatScriptWindow(R.img("logo.ico"), title="我的程序", auto_start=True
 
 @app.on('start')
 def task_start():
-    # ---------------------------------------------------------
-    # 入口程序 (Entry Point)
-    # ---------------------------------------------------------
-    """
-    [业务逻辑入口]
+    """业务逻辑入口函数。
+
     当用户点击启动按钮或触发自启动时，此函数将在独立的子进程中运行。
+    在此函数中编写自动化任务的核心业务逻辑。
     """
     print(">>> [系统] 业务进程已建立，开始执行自动化任务...")
     i= 0
@@ -29,11 +31,11 @@ def task_start():
 
 @app.on('stop')
 def task_stop():
-    """
-    [善后处理回调]
-    当用户手动停止或任务结束时触发。
-    注意：您有约 3 秒的时间进行资源释放（如关闭文件、数据库断开等）。
-    即使此处存在死循环，系统也会在超时后强制回收进程资源。
+    """任务停止时的善后处理回调。
+
+    当用户手动停止或任务结束时触发。可在此执行资源释放操作，
+    如关闭文件句柄、断开数据库连接等。注意约有 3 秒的执行时限，
+    超时后系统会强制回收进程资源。
     """
     print(">>> [系统] 接收到停止信号，正在释放系统资源...")
     # 模拟保存数据逻辑