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

# 🦀rustautogui_py

一个基于 **Rust + PyO3** 封装的高性能鼠标与键盘控制库，  
为 Python 提供了与人类操作无异的自动化输入功能。

本项目基于 [rustautogui](https://crates.io/crates/rustautogui) 实现，  
相比纯 Python 的 `pyautogui`，具有以下优势：

- 🚀 **性能更高**：底层使用 Rust 实现系统调用；
- 🧠 **更安全**：内存与线程安全；
- 🖱️ **功能全面**：支持鼠标移动、拖拽、滚轮、键盘输入、多键组合、全屏截图、区域截图；
- 🧩 **Python 无缝集成**：通过 PyO3 封装，可直接在 Python 中调用。

## 📦 功能概述

`rustautogui_py` 提供以下功能：

- ✅ 获取屏幕分辨率与鼠标位置
- ✅ 控制鼠标移动、点击、拖拽
- ✅ 支持多种鼠标按键（左键、右键、中键）
- ✅ 键盘输入、组合键、特殊命令（如 Enter、Tab、F1 等）
- ✅ 滚轮操作（上、下、左、右）
- ✅ 屏幕截图（全屏截图、区域截图、自动命名、防冲突保存）

---

## 🧰 安装

### 从 PyPI

```bash
pip install rustautogui-py
```

## 🧪 使用示例

### 导入与初始化

```python
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)
```

### 鼠标控制示例

```python
# 移动鼠标到指定坐标
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)
```

### 滚轮控制示例

```python
controller.scroll_up(5)
controller.scroll_down(10)
controller.scroll_left(3)
controller.scroll_right(3)
```

### 键盘控制示例

```python
# 单个按键
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")
```

### 屏幕截图

```python
# 全屏截图，保存在当前目录
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）

###示例
```python
try:
    controller.click("invalid_button")
except Exception as e:
    print("错误:", e)
```
输出：
```plaintext
错误: 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 提供灵活调用接口。
让自动化更快、更稳定、更精准。