# OLAPI_unofficial

**Repository Path**: sun-programing/olapi_unofficial

## Basic Information

- **Project Name**: OLAPI_unofficial
- **Description**: OL插件的非官方Python封装，完整类型提示，文档说明以及参数校验
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OLAPI - Python Wrapper for OLA Plugin

**完整的 OLA 插件 Python 封装，类型安全，易于使用**

## 简介

OLAPI 是 OLA 插件 COM 接口的完整 Python 面向对象封装，提供了类型安全、易于使用的 API，用于 Windows 自动化操作。

### 特性

- ✅ **完整功能**: 18 个 API 模块，437 个方法
- ✅ **类型安全**: 完整的类型提示和 .pyi 存根文件支持
- ✅ **中文文档**: 所有 API 提供完整的中文文档字符串
- ✅ **输入验证**: 全面的参数验证和清晰的错误提示
- ✅ **易于使用**: 统一的 API 接口和直观的方法名
- ✅ **生产就绪**: 无待办事项，无占位符，所有功能完整实现
- ✅ **Python 3.10+**: 兼容 Python 3.10, 3.11, 3.12
- ✅ **标准化结构**: 使用绝对导入路径，符合现代 Python 包规范

## 系统要求

- Python >= 3.10
- Windows 操作系统
- pywin32 >= 311
- OLA 插件 DLL 文件

## 安装

### 从打包好的whl安装

在仓库的 release 中下载编译后的 whl，然后执行,其中的x视具体的版本号而定

```bash
pip install olapi-x.x.x-py3-none-any.whl
```

### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/yourusername/olapi.git
cd olapi

# 使用 uv 构建和安装
uv build
pip install dist/olapi-x.x.x-py3-none-any.whl
```

### 开发模式安装

```bash
# 安装开发依赖
pip install -e .
```

## 快速开始

```python
from olapi import OlApi

# 初始化 API
api = OlApi(
    dll_path="C:/OlaPlug/OlaPlug.dll",
    usercode="YOUR_USER_CODE",
    softcode="YOUR_SOFT_CODE"
)

print(f"DLL版本: {api.settings.Ver()}")
api.MoveTo(100, 100)
api.LeftClick()

# 查找窗口
hwnd = api.window.FindWindow("", "记事本")
if hwnd:
    print(f"找到窗口: {hwnd}")
```

## API 模块

| 模块 | 类名 | 方法数 | 说明 |
|------|------|--------|------|
| mouse | MouseAPI | 21 | 鼠标移动、点击、滚轮操作 |
| window | WindowAPI | 46 | 窗口查找、绑定、控制操作 |
| keyboard | KeyboardAPI | 8 | 键盘按键、字符串输入 |
| memory | MemoryAPI | 48 | 内存读写、搜索、分配 |
| system | SystemAPI | 17 | 进程管理、延迟、系统设置 |
| json | JsonAPI | 18 | JSON 创建、解析、操作 |
| database | DatabaseAPI | 25 | SQLite 数据库操作 |
| algorithm | AlgorithmAPI | 25 | 图算法、路径规划 |
| hotkey | HotkeyAPI | 12 | 热键和鼠标钩子 |
| settings | SettingsAPI | 9 | 版本、路径、编码设置 |
| config | ConfigAPI | 6 | 数据库配置管理 |
| image_processing | ImageProcessingAPI | 97 | 图像处理、滤镜、形态学 |
| image_recognition | ImageRecognitionAPI | 21 | 图像识别、匹配 |
| screen_drawing | ScreenDrawingAPI | 37 | 屏幕绘制、GUI 操作 |
| text_recognition | TextRecognitionAPI | 30 | OCR 文字识别 |
| image_database | ImageDatabaseAPI | 7 | 图像数据库管理 |
| assembly | AssemblyAPI | 3 | 汇编和反汇编 |
| other | OtherAPI | 5 | 其他工具函数 |

**总计**: 437 个方法，完整的中文文档

## 使用示例

### 窗口操作

```python
from olapi import OlApi
from olapi.api.window_api import DisplayMode, MouseMode, KeyboardMode

api = OlApi("path/to/dll", "usercode", "softcode")

# 查找窗口
hwnd = api.window.FindWindow("", "记事本")

# 绑定窗口（三种模式）
if hwnd:
    result = api.window.BindWindow(
        hwnd, 
        DisplayMode.NORMAL,    # 显示模式
        MouseMode.NORMAL,      # 鼠标模式
        KeyboardMode.NORMAL    # 键盘模式
    )
    print(f"绑定结果: {result}")
```

### 图像识别

```python
from olapi import OlApi
from olapi.api.image_recognition_api import MatchType

api = OlApi("path/to/dll", "usercode", "softcode")

# 从文件路径匹配图像
result = api.image_recognition.MatchImageFromPath(
    source_path="screen.bmp",
    template_path="template.bmp",
    similarity=0.8,
    match_type=MatchType.COLOR
)

if result:
    print(f"找到匹配: 位置({result.x}, {result.y}), 相似度: {result.similarity}")
```

### 内存操作

```python
from olapi import OlApi

api = OlApi("path/to/dll", "usercode", "softcode")

# 读取整数
pid = 1234
base_addr = 0x400000
value = api.memory.ReadInt(pid, base_addr, 4)
print(f"读取的值: {value}")

# 写入整数
success = api.memory.WriteInt(pid, base_addr, 4, 100)
print(f"写入成功: {success}")
```

## IDE 支持

本项目提供完整的类型提示支持：

- **自动补全**: IDE 会自动提示所有可用方法和参数
- **类型检查**: 静态类型检查器（如 Pylance）会验证参数类型
- **文档悬停**: 鼠标悬停在方法上会显示完整的中文文档
- **参数提示**: 输入函数时会显示参数列表和类型

所有类型信息都包含在 `olapi/ol_api.pyi` 存根文件中，自动被 IDE 识别。

## 项目结构

```
OLAPI/
├── olapi/                      # 主包目录
│   ├── __init__.py            # 包入口，导出 OlApi
│   ├── ol_api.py              # OlApi 主类
│   ├── ol_api.pyi             # 类型存根文件
│   ├── dll_handler.py         # DLL 单例管理器
│   ├── common.py              # 通用验证工具
│   └── api/                   # API 子模块
│       ├── __init__.py        # API 包入口
│       ├── mouse_api.py       # 鼠标 API
│       ├── window_api.py      # 窗口 API
│       ├── keyboard_api.py    # 键盘 API
│       └── ...                # 其他 15 个 API 模块
├── scripts/                    # 构建和工具脚本
│   ├── generate_pyi.py        # 生成类型存根文件
│   └── check_py310_compat.py  # Python 3.10 兼容性检查
├── tests/                      # 测试文件
│   └── test_ol_api_aliasing.py
├── pyproject.toml             # 项目配置
└── README.md                  # 本文件
```

## 开发

### 生成类型存根文件

```bash
python scripts/generate_pyi.py
```

这会重新生成 `olapi/ol_api.pyi` 文件，包含所有 API 方法的类型提示和中文文档。

### 运行测试

```bash
pytest tests/
```

### 构建包

```bash
# 使用 uv 构建
uv build
```

## 许可证

MIT License - 请查看 LICENSE 文件以了解详细信息

## 贡献

欢迎贡献！请确保：
1. 所有代码兼容 Python 3.10+
2. 使用绝对导入路径（`from olapi.xxx`）
3. 提供完整的中文文档字符串
4. 运行 `scripts/check_py310_compat.py` 检查兼容性
5. 修改后重新生成 .pyi 文件（`scripts/generate_pyi.py`）