# Breeze SDK Python Package

此目录包含 Breeze SDK 的 Python 绑定。

## 📁 文件说明

```
breeze_sdk/
├── __init__.py          # Python 包入口
├── __init__.pyi         # 类型提示（主模块）
├── main_mod.abi3.so     # Rust 扩展模块（编译后生成）
└── main_mod.pyi         # 类型提示（扩展模块）
```

## 🔧 类型提示文件 (.pyi)

`.pyi` 文件为 IDE 提供类型信息，支持：

- ✅ **代码补全**：输入 `parser.` 会显示所有可用方法
- ✅ **类型检查**：mypy 或 Pylance 可以检查类型错误
- ✅ **文档提示**：悬停在函数/类上显示文档

### 示例

```python
from breeze_sdk import MessageParser, MsgType

# IDE 会提示构造函数参数类型
parser = MessageParser("device-id", MsgType.Breeze)
              # ↑ IDE 显示: device_id: str, msg_type: MsgType

# IDE 会显示 receive_data 的参数类型
parser.receive_data(b"...")
            # ↑ IDE 显示: data: bytes -> None
```

## 🛠️ 开发说明

### 手动更新类型提示

如果 API 发生变化，需要手动更新 `.pyi` 文件：

1. 编辑 `stubs/__init__.pyi` 和 `stubs/main_mod.pyi`（模板文件）
2. 确保类型定义与 Rust 代码一致
3. 重新构建：`maturin develop --features "python"`

### 自动生成类型提示

```bash
# 从 Rust 模块自动生成 .pyi
python ../../../scripts/generate_pyi_from_rust.py

# 如果满意，复制到模板目录
cp main_mod.pyi ../../stubs/main_mod.pyi
```

### 验证类型提示

```bash
# 检查 .pyi 文件是否存在
python ../../../scripts/generate_stubs.py

# 使用 mypy 检查类型（可选）
pip install mypy
# mypy examples/python/serial_example.py  # 示例：检查示例文件的类型
```

## 📚 更多信息

- [示例代码](../../examples/python/)
- [示例 README](../../examples/python/README.md)
