Metadata-Version: 2.5
Name: python-weixin-ilink
Version: 0.1.2
Summary: Pure Python synchronous WeChat iLink protocol implementation
Project-URL: Homepage, https://github.com/ecator/python-weixin-ilink
Project-URL: Repository, https://github.com/ecator/python-weixin-ilink
Author-email: Martin <qule520@126.com>
Requires-Python: >=3.13
Requires-Dist: cryptography>=42.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# python-weixin-ilink

微信 iLink 协议的纯 Python 3.13+ 同步实现库。
> 参考并移植自[Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin)
---

## 🌟 核心特性

- **纯协议层（Zero-Invasion & Pure Protocol）**：只负责 iLink 协议编解码、网络通信与加解密，不绑定任何特定 Bot/Web 框架。
- **零磁盘持久化（Zero Disk Persistence）**：严禁内部读写任何文件或持久化缓存；所有 Token、Session Key、上下文完全交由**调用方自管**并通过参数注入。
- **同步阻塞简洁模型（Sync-Only）**：清晰、直观、可靠的同步网络模型。
- **现代强类型安全**：基于 Pydantic V2 与 Python 3.13+ 强类型注解，支持 strict 模式类型检查。
- **完备的全中文协议文档**：详尽的技术规范、架构图与 Mermaid 协议时序图。

---

## 📚 协议技术文档 (`docs/`)

- [**README.md**](docs/README.md)：协议整体架构、模块调用依赖图（Mermaid）与端到端生命周期时序图。
- [**auth.md**](docs/auth.md)：二维码获取、8 种轮询状态机、Header 算法与 Token 换取/刷新时序。
- [**messages.md**](docs/messages.md)：消息信封结构、35s 长轮询机制、单项发送约束、Markdown 过滤与 Typing 状态。
- [**cdn.md**](docs/cdn.md)：AES-128-ECB PKCS#7 加解密、双 AES Key 兼容解析、分片上传与流式下载。
- [**errors.md**](docs/errors.md)：微信状态码字典、STALE_TOKEN (-14) 冷却机制与异常继承体系。

---

## 🚀 快速上手

### 1. 安装

```bash
pip install python-weixin-ilink
```

### 2. 快速使用示例

#### 二维码登录换取 Token

```python
from python_weixin_ilink import SyncClient, QrStatus

client = SyncClient()

# 1. 获取登录二维码
qr_res = client.get_qrcode()
print(f"请使用微信扫描登录: {qr_res.qrcode_img_content}")

# 2. 轮询扫码状态（完全由调用方控制）
while True:
    poll_res = client.poll_qrcode_status(qr_res.qrcode)
    if poll_res.status == QrStatus.CONFIRMED:
        print(f"登录成功！Bot ID: {poll_res.ilink_bot_id}, Token: {poll_res.bot_token}")
        break
```

#### 发送与接收消息（Session 由调用方注入）

> 💡 **关于 `base_url` 的默认值**：
> - `SyncClient` 与 `WeixinSession` 中的 `base_url` 均有官方默认值 `https://ilinkai.weixin.qq.com`，初始化时**无需手动指定**。
> - 在扫码登录过程中，如果微信服务器触发了跨 IDC 重定向（如香港或海外集群），库内部会自动更新为正确的 `base_url`。

```python
from python_weixin_ilink import SyncClient, WeixinSession, TextItem

# 调用方自管的 Session（base_url 默认为 "https://ilinkai.weixin.qq.com"，可省略）
session = WeixinSession(
    bot_token="your_bot_token",
    bot_id="your_bot_id",
)

client = SyncClient(session=session)

# 发送文本消息
resp = client.send_text(
    to_user_id="user_wx_id",
    text="你好，这是来自 python-weixin-ilink 的纯协议消息！"
)

# 长轮询拉取新消息
updates = client.get_updates(timeout_s=35)
for msg in updates.messages:
    for item in msg.item_list:
        if isinstance(item, TextItem):
            print(f"收到用户 {msg.from_user_id} 发送的消息: {item.text}")
```

更多示例请参阅 [`examples/`](examples/) 目录。

---

## 🛠️ 本地开发与测试

本项目采用 [`uv`](https://github.com/astral-sh/uv) 进行环境与依赖管理。

### 环境准备与依赖同步

```bash
# 克隆项目后同步开发依赖
uv sync
```

### 运行测试与质量检查

本项目包含 268+ 个单元与集成测试，覆盖率达 100%（全 Mock 离线运行）：

```bash
# 运行全量单元测试
uv run pytest -v

# 代码风格与静态类型检查
uv run ruff check
uv run mypy src tests
```

包含专门的无副作用断言测试 `test_no_disk_side_effects.py`，确保执行任何协议流程均不会产生隐蔽的磁盘读写。

---

## 📄 开源许可证

MIT License
