rustautogui-py 0.1.3

一个基于 **Rust + PyO3** 封装的高性能鼠标与键盘控制库，为 Python 提供了与人类操作无异的自动化输入功能。

🦀rustautogui_py

一个基于 Rust + PyO3 封装的高性能鼠标与键盘控制库，
为 Python 提供了与人类操作无异的自动化输入功能。

本项目基于 rustautogui 实现，
相比纯 Python 的 pyautogui，具有以下优势：

• 🚀 性能更高：底层使用 Rust 实现系统调用；
• 🧠 更安全：内存与线程安全；
• 🖱️ 功能全面：支持鼠标移动、拖拽、滚轮、键盘输入、多键组合、全屏截图、区域截图；
• 🧩 Python 无缝集成：通过 PyO3 封装，可直接在 Python 中调用。

📦 功能概述

rustautogui_py 提供以下功能：

• ✅ 获取屏幕分辨率与鼠标位置
• ✅ 控制鼠标移动、点击、拖拽
• ✅ 支持多种鼠标按键（左键、右键、中键）
• ✅ 键盘输入、组合键、特殊命令（如 Enter、Tab、F1 等）
• ✅ 滚轮操作（上、下、左、右）
• ✅ 屏幕截图（全屏截图、区域截图、自动命名、防冲突保存）

---

🧰 安装

从 PyPI

pip install rustautogui-py

🧪 使用示例

导入与初始化

from rustautogui_py import AutoController

# 创建控制器实例
controller = AutoController()

# 获取屏幕分辨率
width, height = controller.get_screen_size()
print("屏幕分辨率:", width, "x", height)

# 获取鼠标坐标
x, y = controller.get_mouse_position()
print("当前鼠标位置:", x, y)

鼠标控制示例

# 移动鼠标到指定坐标
controller.move_mouse_to_pos(100, 200)
controller.move_mouse_to_pos(100, 200, duration=0.5)

# 相对移动（往右100像素，下移50像素）
controller.move_mouse(100, 50)
controller.move_mouse(100, 50, duration=0.5)

# 单击、右键、双击
controller.click("left")
controller.click("right")
controller.click("left", x=100, y=200)
controller.double_click()

# 拖拽操作
controller.drag_mouse_to_pos(500, 500)
controller.drag_mouse_to_pos(500, 500, duration=0.5)

# 从当前位置偏移拖拽操作（往右100像素，下移50像素）
controller.drag_mouse(100, -50)
controller.drag_mouse(100, -50, duration=0.5)

滚轮控制示例

controller.scroll_up(5)
controller.scroll_down(10)
controller.scroll_left(3)
controller.scroll_right(3)

键盘控制示例

# 单个按键
controller.key_down("ctrl")
controller.key_up("ctrl")

# 输入文本
controller.keyboard_input("Hello Rust + Python!")

# 特殊命令
controller.keyboard_command("enter")

# 多组合键
controller.keyboard_multi_key("ctrl", "c")
controller.keyboard_multi_key("ctrl", "shift", "a")

屏幕截图

# 全屏截图，保存在当前目录
controller.save_screenshot()

# 区域截图，保存在当前目录
controller.save_screenshot(region=(100, 100, 200, 200))

# 全屏截图，保存在指定路径
controller.save_screenshot("src/images/screenshot.png")

# 区域截图，保存在指定路径
controller.save_screenshot("src/images/screenshot.png", region=(100, 100, 200, 200))

🧩 API 参考

方法名	功能说明
get_screen_size()	获取屏幕分辨率 (width, height)
get_mouse_position()	获取当前鼠标位置 (x, y)
move_mouse_to_pos(x, y, duration=None)	移动鼠标到指定坐标
move_mouse(x, y, duration=None)	相对移动鼠标
drag_mouse_to_pos(x, y, duration=None)	拖拽到指定坐标
drag_mouse(x, y, duration=None)	从当前位置偏移拖拽
click(button, x=None, y=None)	点击鼠标按键
click_down(button)	按下鼠标键（不松开）
click_up(button)	松开鼠标键
left_click()	左键点击
right_click()	右键点击
middle_click()	中键点击
double_click()	双击左键
scroll_up(intensity)	向上滚动
scroll_down(intensity)	向下滚动
scroll_left(intensity)	向左滚动
scroll_right(intensity)	向右滚动
key_down(key)	按下键盘按键
key_up(key)	松开键盘按键
keyboard_input(text)	输入文本
keyboard_command(command)	执行特殊命令（如 Enter、Tab）
keyboard_multi_key(key1, key2, key3=None)	同时按下多个按键
save_screenshot(file_path=None,region=None)	保存屏幕截图

⚠️ 异常与错误处理

• 所有方法均返回 PyResult<()>
• 成功执行返回 None
• 失败时抛出 Python 异常（PyException 或 PyValueError）

###示例

try:
    controller.click("invalid_button")
except Exception as e:
    print("错误:", e)

输出：

错误: Invalid button: invalid_button. Expected 'left', 'right', or 'middle'

🧰 开发环境

• Rust 1.90.0
• PyO3 0.25.0
• maturin 1.9.6
• Python 3.12.9

🧑‍💻 作者与许可

Author: 潘明辉 License: MIT

Rust 提供底层执行效率，Python 提供灵活调用接口。 让自动化更快、更稳定、更精准。