tuitui-bot 1.0.11__tar.gz

tuitui_bot-1.0.11/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+node_modules
+dist/
+coverage/
+build/
+*.egg-info/
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.package-install-test/
+tests/e2e/config.local.json
+samples/.env
+samples/dist/
+package-lock.json
+.wolf
+.wiscode/
+docs/
+governance/
+.build-stage/
+.cc-connect

tuitui_bot-1.0.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tuitui.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tuitui_bot-1.0.11/PKG-INFO

@@ -0,0 +1,113 @@
+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 防护实现。

tuitui_bot-1.0.11/README.md

@@ -0,0 +1,80 @@
+# 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 防护实现。

tuitui_bot-1.0.11/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tuitui-bot"
+version = "1.0.11"
+description = "推推机器人 Python SDK"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27,<1",
+  "websockets>=14,<18",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "hatchling>=1.27",
+  "mypy>=1.13",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "pytest-cov>=6",
+  "pytest-timeout>=2.3",
+  "respx>=0.22",
+  "ruff>=0.9",
+  "twine>=6,<7",
+]
+samples = ["python-dotenv>=1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tuitui_bot"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.codex",
+  "/AGENTS.md",
+  "/MIGRATION.md",
+  "/dist",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+asyncio_mode = "auto"
+testpaths = ["tests/mock"]
+markers = ["e2e: 调用真实推推服务的测试"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["tuitui_bot"]
+mypy_path = "src"

tuitui_bot-1.0.11/samples/.env.example

@@ -0,0 +1,2 @@
+TUITUI_BOT_APPID=
+TUITUI_BOT_SECRET=

tuitui_bot-1.0.11/samples/README.md

@@ -0,0 +1,34 @@
+# SDK 使用示例
+
+所有示例都需要机器人的 App ID 和 App Secret。复制 `.env.example` 为 `.env`
+并填写：
+
+```dotenv
+TUITUI_BOT_APPID=机器人 App ID
+TUITUI_BOT_SECRET=机器人 App Secret
+```
+
+安装 SDK 和示例依赖：
+
+```bash
+pip install -e ".[samples]"
+```
+
+发送目标通过命令行参数指定，与 JavaScript 版示例一致：
+
+```bash
+python samples/send_text.py --account alice
+python samples/send_text.py --uid 123456
+python samples/send_text.py --group 987654
+
+python samples/send_file.py --account alice
+python samples/send_mixed.py --account alice
+python samples/send_interactive.py --account alice
+python samples/send_post.py --team 123456 --channel 789012
+python samples/receive.py
+```
+
+所有 `send_*.py` 示例都会在发送成功后输出服务端返回的完整 JSON。
+
+`receive.py` 连接成功后会立即输出监听状态，随后持续输出原始事件和解析文本。
+按 `Ctrl+C` 取消订阅并退出。`.env` 已被 Git 忽略，不要提交真实凭证。

tuitui_bot-1.0.11/samples/config.py

@@ -0,0 +1,22 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+@dataclass(frozen=True, slots=True)
+class SampleConfig:
+    app_id: str
+    app_secret: str
+
+
+def load_sample_config() -> SampleConfig:
+    env_path = Path(__file__).with_name(".env")
+    load_dotenv(dotenv_path=env_path)
+
+    app_id = os.getenv("TUITUI_BOT_APPID", "").strip()
+    app_secret = os.getenv("TUITUI_BOT_SECRET", "").strip()
+    if not app_id or not app_secret:
+        raise RuntimeError(f"请设置 TUITUI_BOT_APPID 和 TUITUI_BOT_SECRET，或在 {env_path} 中填写")
+    return SampleConfig(app_id=app_id, app_secret=app_secret)

tuitui_bot-1.0.11/samples/receive.py

@@ -0,0 +1,76 @@
+import asyncio
+import json
+import sys
+from datetime import datetime, timezone
+
+from config import load_sample_config
+
+from tuitui_bot import TuituiBotClient, TuituiRawEvent, TuituiSubscribeOptions
+
+
+def timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def js_value(value: object) -> str:
+    if value is None:
+        return "undefined"
+    if isinstance(value, bool):
+        return str(value).lower()
+    return str(value)
+
+
+async def main() -> None:
+    config = load_sample_config()
+    client = TuituiBotClient(config.app_id, config.app_secret)
+
+    def on_connected() -> None:
+        print(f"[{timestamp()}] 已连接bot({config.app_id})，正在监听事件", flush=True)
+
+    def on_event(event: TuituiRawEvent) -> None:
+        body = event.get("body")
+        event_name = body.get("event", "unknown") if isinstance(body, dict) else "unknown"
+
+        print(f"[{timestamp()}] 收到事件:{event_name}", flush=True)
+        print(json.dumps(event, ensure_ascii=False, indent=2), flush=True)
+
+        if not isinstance(body, dict):
+            return
+        data = body.get("data")
+
+        if event_name == client.event.SINGLE_CHAT:
+            text = client.event.render_message_body(data)
+            print(f"[{timestamp()}] 单聊解析文本:\n{text}", flush=True)
+        elif event_name == client.event.GROUP_CHAT:
+            text = client.event.render_message_body(data)
+            print(f"[{timestamp()}] 群聊解析文本:\n{text}", flush=True)
+            at_me = data.get("at_me", False) if isinstance(data, dict) else False
+            print(f"[{timestamp()}] 群聊是否@自己:{js_value(at_me)}", flush=True)
+        elif event_name in (client.event.TEAMS_POST_CREATE, client.event.TEAMS_POST_MODIFY):
+            content = data.get("content", "") if isinstance(data, dict) else ""
+            at_me = data.get("at_me") if isinstance(data, dict) else None
+            print(f"[{timestamp()}] 团队帖子解析文本:\n{content}", flush=True)
+            print(f"[{timestamp()}] 团队帖子是否@自己:{js_value(at_me)}", flush=True)
+
+    def on_error(error: Exception) -> None:
+        print(f"[{timestamp()}] WebSocket 错误", error, file=sys.stderr, flush=True)
+
+    subscription = client.event.subscribe(
+        TuituiSubscribeOptions(
+            on_connected=on_connected,
+            on_event=on_event,
+            on_error=on_error,
+        )
+    )
+    try:
+        await asyncio.Event().wait()
+    finally:
+        print(f"\n[{timestamp()}] 停止监听", flush=True)
+        await subscription.unsubscribe()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

tuitui_bot-1.0.11/samples/send_file.py

@@ -0,0 +1,40 @@
+import asyncio
+import json
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+
+from config import load_sample_config
+
+from tuitui_bot import ToTarget, TuituiBotClient
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser(description="发送 IM 文件")
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--account", help="接收者账号")
+    target.add_argument("--uid", help="接收者 UID")
+    target.add_argument("--group", help="接收群 ID")
+    return parser.parse_args()
+
+
+def resolve_target(client: TuituiBotClient, args: Namespace) -> ToTarget:
+    if args.account:
+        return client.to.account(args.account)
+    if args.uid:
+        return client.to.uid(args.uid)
+    return client.to.group(args.group)
+
+
+async def main() -> None:
+    args = parse_args()
+    config = load_sample_config()
+    client = TuituiBotClient(config.app_id, config.app_secret)
+    response = await client.im.send_file(
+        to=resolve_target(client, args),
+        source=Path(__file__).with_name("README.md"),
+    )
+    print("文件发送成功")
+    print(json.dumps(response, ensure_ascii=False, indent=2))
+
+
+asyncio.run(main())

tuitui_bot-1.0.11/samples/send_interactive.py

@@ -0,0 +1,60 @@
+import asyncio
+import json
+from argparse import ArgumentParser, Namespace
+
+from config import load_sample_config
+
+from tuitui_bot import ToTarget, TuituiBotClient
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser(description="发送 IM 交互消息")
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--account", help="接收者账号")
+    target.add_argument("--uid", help="接收者 UID")
+    target.add_argument("--group", help="接收群 ID")
+    return parser.parse_args()
+
+
+def resolve_target(client: TuituiBotClient, args: Namespace) -> ToTarget:
+    if args.account:
+        return client.to.account(args.account)
+    if args.uid:
+        return client.to.uid(args.uid)
+    return client.to.group(args.group)
+
+
+async def main() -> None:
+    args = parse_args()
+    config = load_sample_config()
+    interactive = {
+        "head": {"text": "交互消息示例"},
+        "body": {"content": "请选择确认或取消"},
+        "action": [
+            {
+                "text": "确认",
+                "name": "confirm",
+                "value": "confirm",
+                "color": "FFFFFF",
+                "bgcolor": "#3873FA",
+            },
+            {
+                "text": "取消",
+                "name": "cancel",
+                "value": "cancel",
+                "color": "FFFFFF",
+                "bgcolor": "#FA5151",
+            },
+        ],
+    }
+
+    client = TuituiBotClient(config.app_id, config.app_secret)
+    response = await client.im.send_interactive(
+        to=resolve_target(client, args),
+        interactive=interactive,
+    )
+    print("交互消息发送成功")
+    print(json.dumps(response, ensure_ascii=False, indent=2))
+
+
+asyncio.run(main())

tuitui_bot-1.0.11/samples/send_mixed.py

@@ -0,0 +1,47 @@
+import asyncio
+import json
+from argparse import ArgumentParser, Namespace
+
+from config import load_sample_config
+
+from tuitui_bot import ToTarget, TuituiBotClient, TuituiMixedItem
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser(description="发送 IM Mixed 消息")
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--account", help="接收者账号")
+    target.add_argument("--uid", help="接收者 UID")
+    target.add_argument("--group", help="接收群 ID")
+    return parser.parse_args()
+
+
+def resolve_target(client: TuituiBotClient, args: Namespace) -> ToTarget:
+    if args.account:
+        return client.to.account(args.account)
+    if args.uid:
+        return client.to.uid(args.uid)
+    return client.to.group(args.group)
+
+
+async def main() -> None:
+    args = parse_args()
+    config = load_sample_config()
+    sample_image = (
+        "data:image/png;base64,"
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42Y"
+        "AAAAASUVORK5CYII="
+    )
+    items: list[TuituiMixedItem] = [
+        {"type": "text", "text": "Mixed 消息中的第一段文字"},
+        {"type": "image", "source": sample_image},
+        {"type": "text", "text": "Mixed 消息中的第二段文字"},
+    ]
+
+    client = TuituiBotClient(config.app_id, config.app_secret)
+    response = await client.im.send_mixed(to=resolve_target(client, args), items=items)
+    print("Mixed 消息发送成功")
+    print(json.dumps(response, ensure_ascii=False, indent=2))
+
+
+asyncio.run(main())

tuitui_bot-1.0.11/samples/send_post.py

@@ -0,0 +1,30 @@
+import asyncio
+import json
+from argparse import ArgumentParser, Namespace
+
+from config import load_sample_config
+
+from tuitui_bot import TuituiBotClient
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser(description="发送频道帖子")
+    parser.add_argument("--team", required=True, help="团队 ID")
+    parser.add_argument("--channel", required=True, help="频道 ID")
+    return parser.parse_args()
+
+
+async def main() -> None:
+    args = parse_args()
+    config = load_sample_config()
+    client = TuituiBotClient(config.app_id, config.app_secret)
+    response = await client.teams.send_post(
+        team_id=args.team,
+        channel_id=args.channel,
+        text="**Python SDK** 频道帖子",
+    )
+    print("频道帖子发送成功")
+    print(json.dumps(response, ensure_ascii=False, indent=2))
+
+
+asyncio.run(main())

tuitui_bot-1.0.11/samples/send_text.py

@@ -0,0 +1,39 @@
+import asyncio
+import json
+from argparse import ArgumentParser, Namespace
+
+from config import load_sample_config
+
+from tuitui_bot import ToTarget, TuituiBotClient
+
+
+def parse_args() -> Namespace:
+    parser = ArgumentParser(description="发送 IM 文本消息")
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--account", help="接收者账号")
+    target.add_argument("--uid", help="接收者 UID")
+    target.add_argument("--group", help="接收群 ID")
+    return parser.parse_args()
+
+
+def resolve_target(client: TuituiBotClient, args: Namespace) -> ToTarget:
+    if args.account:
+        return client.to.account(args.account)
+    if args.uid:
+        return client.to.uid(args.uid)
+    return client.to.group(args.group)
+
+
+async def main() -> None:
+    args = parse_args()
+    config = load_sample_config()
+    client = TuituiBotClient(config.app_id, config.app_secret)
+    response = await client.im.send_text(
+        to=resolve_target(client, args),
+        text="**你好**，这是一条来自 Python SDK 的消息。",
+    )
+    print("消息发送成功")
+    print(json.dumps(response, ensure_ascii=False, indent=2))
+
+
+asyncio.run(main())