Metadata-Version: 2.4
Name: tuitui-bot
Version: 1.0.11
Summary: 推推机器人 Python SDK
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: websockets<18,>=14
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Provides-Extra: samples
Requires-Dist: python-dotenv>=1; extra == 'samples'
Description-Content-Type: text/markdown

# tuitui-bot

推推机器人异步 Python SDK，移植自 npm 包 `@qihoo/tuitui-bot-sdk`。支持 Python 3.10 及以上版本。

## 安装

```bash
pip install tuitui-bot
```

## 发送消息

```python
import asyncio

from tuitui_bot import TuituiBotClient


async def main() -> None:
    client = TuituiBotClient("your-app-id", "your-app-secret")
    await client.im.send_text(
        to=client.to.account("user-account"),
        text="**你好**，这是一条 `Markdown` 消息。",
    )


asyncio.run(main())
```

`TuituiBotClient` 构造时不连接网络，默认 HTTP 会话由 SDK 在每次请求后自动关闭，
不需要 `async with` 或手动关闭客户端。

`client.to` 提供 `account()`、`uid()`、`group()`、`accounts()` 和 `uids()` 五种结构化目标。
IM 位于 `client.im`，频道和帖子能力位于 `client.teams`。

## 事件订阅

构造客户端或发送消息不会建立 WebSocket。只有调用 `client.event.subscribe()` 才会订阅事件：

```python
import asyncio

from tuitui_bot import TuituiBotClient, TuituiSubscribeOptions


async def main() -> None:
    client = TuituiBotClient("...", "...")

    async def on_event(raw: dict[str, object]) -> None:
        print(raw)

    subscription = client.event.subscribe(
        TuituiSubscribeOptions(on_event=on_event),
    )
    try:
        await asyncio.Event().wait()
    finally:
        await subscription.unsubscribe()


asyncio.run(main())
```

SDK 自动处理鉴权、ACK、保活过滤、去重、心跳超时和断线重连。原始事件字段会被保留；需要正文或
媒体时，显式使用 `client.event.render_message_body(data)` 和
`client.event.get_message_media(data)`。

## API 概览

- `client.im`：文本、图文混排、页面、链接、文件、交互卡片、编辑、表情和历史记录。
- `client.teams`：帖子、回复、编辑、文件、表情、频道、标签、公告、成员和帖子链。
- `client.file`：底层文件上传。
- `client.file_space`：文件空间节点、目录和文件。
- `client.property`：机器人信息、名称、头像、Webhook、交互地址和快捷指令。
- `client.event`：事件订阅、正文渲染和媒体提取。
- `client.request()`：调用尚未封装的 Bot API。

文本消息和帖子支持 Markdown；图文混排中的文字是纯文本。上传支持 bytes、Path、本地路径、二进制
文件对象、data URL 和 HTTP/HTTPS URL，最大 100MB。远程 URL 下载可通过
`TuituiClientOptions(fetch_with_ssrf=...)` 注入 SSRF 防护实现。
