Metadata-Version: 2.4
Name: rustautogui_py
Version: 0.1.2
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
License-File: LICENSE
Summary: 一个基于 **Rust + PyO3** 封装的高性能鼠标与键盘控制库，为 Python 提供了与人类操作无异的自动化输入功能。
Author-email: 潘明辉 <minghuip8@gmail.com>
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 🦀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
# 默认保存为当前目录的 screenshot.png
controller.save_screenshot()

# 自定义路径（自动创建文件夹）
controller.save_screenshot("images/test_shot.png")
```

## 🧩 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)	`          | 保存屏幕截图                   |






