viseron-qqbotpy 0.4.2__tar.gz

viseron_qqbotpy-0.4.2/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: viseron-qqbotpy
+Version: 0.4.2
+Summary: A modern, asyncio-based Python SDK for the QQ Open Platform Bot API (api-v2).
+Author: Viseron
+License: MIT
+Project-URL: Homepage, https://bot.q.qq.com/wiki/develop/api-v2/
+Project-URL: Documentation, https://bot.q.qq.com/wiki/develop/api-v2/
+Keywords: qq,qqbot,qq-bot,qq机器人,sdk,websocket,bot
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp<4,>=3.7.4
+Provides-Extra: ext
+Requires-Dist: PyYAML>=6; extra == "ext"
+Requires-Dist: APScheduler>=3.10; extra == "ext"
+Provides-Extra: webhook
+Requires-Dist: cryptography>=41; extra == "webhook"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: python-dotenv>=1; extra == "dev"
+
+# viseron-qqbotpy
+
+一个基于 **asyncio + aiohttp** 的 QQ 机器人 Python SDK，针对
+[QQ 机器人开放平台 API v2](https://bot.q.qq.com/wiki/develop/api-v2/) 重新设计。
+
+它参考了旧版 qq-botpy 的 API 形状，但内部实现是重写的：共享 HTTP 会话、
+无中断的 access_token 刷新、由 Hello 事件驱动的心跳、更清晰的错误与事件模型。
+
+## 特性
+
+- 使用 appid + secret 获取 access token，并支持 **过期前 60 秒无缝刷新**
+- WebSocket 网关：Identify / Resume / Heartbeat / 分片 / 断线重连
+- 覆盖频道、群聊、单聊、身份组、成员、消息、表情、日程、论坛、音频、公告、
+  接口权限、富媒体上传、入群审批、指令面板、自定义菜单等 API
+- 本地文件分片上传一键封装：upload_group_media / upload_c2c_media
+- 本地群聊状态管理：GroupStore 自动把机器人加入过的群记录到 groups.json
+- 群成员管理：群成员列表/详情、批量移除、群黑名单查询与操作（平台 2026-09-03 新增，内邀能力）
+- Markdown 素材管理：图片上传到平台并获取 qqbot-media:// 引用，一条 upload_markdown_image 搞定（平台 2026-10-21 新增）
+- 图文卡片消息（msg_type=8）与群聊 @全部成员常量 AT_EVERYONE（平台 2026-10-26 / 10-28 新增）
+- 指令面板管理：Panel / PanelStore 用 panels/panels.json 配置并同步到平台
+- 事件模型为 dataclass，同时保留完整原始 payload（raw 字段）
+- 可选 Webhook Ed25519 签名验证
+
+## 使用文档
+
+完整使用文档见 docs/ 目录：
+
+- docs/getting-started.md：安装、快速开始、Intents、直接调用 API
+- docs/core.md：SDK 基础能力，如 Client、TokenManager、BotAPI、日志、异常等
+- docs/events.md：事件监听、事件表、事件对象字段
+- docs/features.md：常见功能实现示例
+- docs/api-reference.md：API 方法参考
+- docs/ext.md：命令装饰器、颜色转换等扩展
+- docs/management.md：面板与群管理、本地配置同步
+- docs/automation.md：QQ 文档同步自动化任务与版本规则
+- docs/webhook.md：Webhook 签名验证
+- docs/publish.md：构建、上架 PyPI、安装与下载方式
+
+## 安装
+
+    cd viseron-botpy
+    pip install -e .
+
+开发模式安装额外依赖：
+
+    pip install -e ".[dev]"
+
+## 快速开始
+
+    import os
+    from pathlib import Path
+
+    from viseron_qqbotpy import Client, Intents, Message, configure_logging, load_env
+
+    # 读取项目根目录的 .env
+    load_env(Path(__file__).resolve().parents[1] / ".env")
+
+    # 使用 SDK 默认日志格式，并写入 logs/viseron_qqbotpy.log
+    configure_logging()
+
+    APPID = os.getenv("APPID", "")
+    APPSECRET = os.getenv("APPSECRET", "")
+
+
+    class MyBot(Client):
+        async def on_ready(self):
+            print("机器人已上线")
+
+        async def on_at_message_create(self, message: Message):
+            await message.reply(content=f"收到: {message.content}")
+
+
+    if __name__ == "__main__":
+        bot = MyBot(intents=Intents.default())
+        bot.run(appid=APPID, secret=APPSECRET)
+
+更多事件与用法见 examples/ 和 docs/。
+
+## 事件订阅
+
+创建客户端时传入 Intents：
+
+    intents = Intents.default()          # 公域事件
+    intents = Intents.all()              # 全部事件（需私域权限）
+    intents = Intents(guilds=True, public_guild_messages=True)
+
+网关事件名会映射为 on_<event_type小写>，例如：
+
+- AT_MESSAGE_CREATE -> on_at_message_create
+- GROUP_AT_MESSAGE_CREATE -> on_group_at_message_create
+- C2C_MESSAGE_CREATE -> on_c2c_message_create
+- INTERACTION_CREATE -> on_interaction_create
+- GROUP_MEMBER_ADD -> on_group_member_add
+- READY / RESUMED -> on_ready / on_resumed（无参数）
+
+## 本地面板与群聊状态
+
+SDK 可以把群聊状态和指令面板配置保存在本地：
+
+- groups.json：机器人加入过的群，由 Client 自动维护，无需手动调用。
+- panels/panels.json：你自己维护的面板配置；panels/store.json 由 SDK 记录 panel_id 映射。
+
+    from viseron_qqbotpy import Client, Intents, load_panels
+
+
+    class MyBot(Client):
+        async def on_ready(self):
+            # 把 panels/panels.json 同步到平台
+            store = await load_panels(self.api, root_dir="panels")
+            await store.sync_from_config()
+
+
+    if __name__ == "__main__":
+        bot = MyBot(
+            intents=Intents.default(),
+            group_store_path="data/groups.json",
+            group_store_retention_days=30,
+        )
+        bot.run(appid=APPID, secret=APPSECRET)
+
+详细说明见 docs/management.md。
+
+## 直接调用 API
+
+在 Client 子类中，可以直接使用 self.api：
+
+    class MyBot(Client):
+        async def on_ready(self):
+            guilds = await self.api.me_guilds()
+            print(guilds)
+
+如果只需要 HTTP API，不连接 WebSocket：
+
+    import asyncio
+
+    from viseron_qqbotpy import BotAPI, HTTPClient, TokenManager
+
+
+    async def main():
+        token = TokenManager("你的 AppID", "你的 AppSecret")
+        http = HTTPClient(token)
+        api = BotAPI(http)
+
+        me = await api.me()
+        print(me)
+
+        await http.close()
+        await token.close()
+
+
+    asyncio.run(main())
+
+## Access Token 刷新机制
+
+- 平台 access token 默认 7200 秒有效。
+- 在 token 剩余有效期进入最后 60 秒时，SDK 会透明地获取新 token 并切换；
+  此时新旧 token 都有效，因此不会中断正在执行的请求。
+- 如果刷新失败但旧 token 尚未过期，SDK 会继续使用旧 token，并在下一次调用时重试。
+- 可通过 TokenManager 单独使用该能力。
+
+## Webhook 签名验证
+
+    from viseron_qqbotpy.webhook import verify_signature, sign_validation
+
+    ok = verify_signature(
+        secret="AppSecret",
+        timestamp=request.headers["X-Signature-Timestamp"],
+        body=request.body.decode(),
+        signature_hex=request.headers["X-Signature-Ed25519"],
+    )
+
+## 项目结构
+
+    src/viseron_qqbotpy/
+      client.py       # Client 入口
+      api.py          # OpenAPI 封装
+      gateway.py      # WebSocket 网关/分片/重连
+      token.py        # access token 无缝刷新
+      http.py         # HTTP 客户端
+      env.py          # .env 文件加载
+      logging.py      # 默认日志与 configure_logging
+      dispatcher.py   # 事件解析与分发
+      models.py       # 事件 dataclass
+      types.py        # payload 类型提示
+      flags.py        # Intents / Permission
+      errors.py       # 异常体系
+      panel.py        # 指令面板：Panel / PanelStore
+      group_store.py  # 本地群聊状态：GroupStore
+      webhook.py      # 可选 Webhook 签名
+      ext/            # 命令、颜色、频道跳转等扩展
+
+## License
+
+MIT

viseron_qqbotpy-0.4.2/README.md

@@ -0,0 +1,194 @@
+# viseron-qqbotpy
+
+一个基于 **asyncio + aiohttp** 的 QQ 机器人 Python SDK，针对
+[QQ 机器人开放平台 API v2](https://bot.q.qq.com/wiki/develop/api-v2/) 重新设计。
+
+它参考了旧版 qq-botpy 的 API 形状，但内部实现是重写的：共享 HTTP 会话、
+无中断的 access_token 刷新、由 Hello 事件驱动的心跳、更清晰的错误与事件模型。
+
+## 特性
+
+- 使用 appid + secret 获取 access token，并支持 **过期前 60 秒无缝刷新**
+- WebSocket 网关：Identify / Resume / Heartbeat / 分片 / 断线重连
+- 覆盖频道、群聊、单聊、身份组、成员、消息、表情、日程、论坛、音频、公告、
+  接口权限、富媒体上传、入群审批、指令面板、自定义菜单等 API
+- 本地文件分片上传一键封装：upload_group_media / upload_c2c_media
+- 本地群聊状态管理：GroupStore 自动把机器人加入过的群记录到 groups.json
+- 群成员管理：群成员列表/详情、批量移除、群黑名单查询与操作（平台 2026-09-03 新增，内邀能力）
+- Markdown 素材管理：图片上传到平台并获取 qqbot-media:// 引用，一条 upload_markdown_image 搞定（平台 2026-10-21 新增）
+- 图文卡片消息（msg_type=8）与群聊 @全部成员常量 AT_EVERYONE（平台 2026-10-26 / 10-28 新增）
+- 指令面板管理：Panel / PanelStore 用 panels/panels.json 配置并同步到平台
+- 事件模型为 dataclass，同时保留完整原始 payload（raw 字段）
+- 可选 Webhook Ed25519 签名验证
+
+## 使用文档
+
+完整使用文档见 docs/ 目录：
+
+- docs/getting-started.md：安装、快速开始、Intents、直接调用 API
+- docs/core.md：SDK 基础能力，如 Client、TokenManager、BotAPI、日志、异常等
+- docs/events.md：事件监听、事件表、事件对象字段
+- docs/features.md：常见功能实现示例
+- docs/api-reference.md：API 方法参考
+- docs/ext.md：命令装饰器、颜色转换等扩展
+- docs/management.md：面板与群管理、本地配置同步
+- docs/automation.md：QQ 文档同步自动化任务与版本规则
+- docs/webhook.md：Webhook 签名验证
+- docs/publish.md：构建、上架 PyPI、安装与下载方式
+
+## 安装
+
+    cd viseron-botpy
+    pip install -e .
+
+开发模式安装额外依赖：
+
+    pip install -e ".[dev]"
+
+## 快速开始
+
+    import os
+    from pathlib import Path
+
+    from viseron_qqbotpy import Client, Intents, Message, configure_logging, load_env
+
+    # 读取项目根目录的 .env
+    load_env(Path(__file__).resolve().parents[1] / ".env")
+
+    # 使用 SDK 默认日志格式，并写入 logs/viseron_qqbotpy.log
+    configure_logging()
+
+    APPID = os.getenv("APPID", "")
+    APPSECRET = os.getenv("APPSECRET", "")
+
+
+    class MyBot(Client):
+        async def on_ready(self):
+            print("机器人已上线")
+
+        async def on_at_message_create(self, message: Message):
+            await message.reply(content=f"收到: {message.content}")
+
+
+    if __name__ == "__main__":
+        bot = MyBot(intents=Intents.default())
+        bot.run(appid=APPID, secret=APPSECRET)
+
+更多事件与用法见 examples/ 和 docs/。
+
+## 事件订阅
+
+创建客户端时传入 Intents：
+
+    intents = Intents.default()          # 公域事件
+    intents = Intents.all()              # 全部事件（需私域权限）
+    intents = Intents(guilds=True, public_guild_messages=True)
+
+网关事件名会映射为 on_<event_type小写>，例如：
+
+- AT_MESSAGE_CREATE -> on_at_message_create
+- GROUP_AT_MESSAGE_CREATE -> on_group_at_message_create
+- C2C_MESSAGE_CREATE -> on_c2c_message_create
+- INTERACTION_CREATE -> on_interaction_create
+- GROUP_MEMBER_ADD -> on_group_member_add
+- READY / RESUMED -> on_ready / on_resumed（无参数）
+
+## 本地面板与群聊状态
+
+SDK 可以把群聊状态和指令面板配置保存在本地：
+
+- groups.json：机器人加入过的群，由 Client 自动维护，无需手动调用。
+- panels/panels.json：你自己维护的面板配置；panels/store.json 由 SDK 记录 panel_id 映射。
+
+    from viseron_qqbotpy import Client, Intents, load_panels
+
+
+    class MyBot(Client):
+        async def on_ready(self):
+            # 把 panels/panels.json 同步到平台
+            store = await load_panels(self.api, root_dir="panels")
+            await store.sync_from_config()
+
+
+    if __name__ == "__main__":
+        bot = MyBot(
+            intents=Intents.default(),
+            group_store_path="data/groups.json",
+            group_store_retention_days=30,
+        )
+        bot.run(appid=APPID, secret=APPSECRET)
+
+详细说明见 docs/management.md。
+
+## 直接调用 API
+
+在 Client 子类中，可以直接使用 self.api：
+
+    class MyBot(Client):
+        async def on_ready(self):
+            guilds = await self.api.me_guilds()
+            print(guilds)
+
+如果只需要 HTTP API，不连接 WebSocket：
+
+    import asyncio
+
+    from viseron_qqbotpy import BotAPI, HTTPClient, TokenManager
+
+
+    async def main():
+        token = TokenManager("你的 AppID", "你的 AppSecret")
+        http = HTTPClient(token)
+        api = BotAPI(http)
+
+        me = await api.me()
+        print(me)
+
+        await http.close()
+        await token.close()
+
+
+    asyncio.run(main())
+
+## Access Token 刷新机制
+
+- 平台 access token 默认 7200 秒有效。
+- 在 token 剩余有效期进入最后 60 秒时，SDK 会透明地获取新 token 并切换；
+  此时新旧 token 都有效，因此不会中断正在执行的请求。
+- 如果刷新失败但旧 token 尚未过期，SDK 会继续使用旧 token，并在下一次调用时重试。
+- 可通过 TokenManager 单独使用该能力。
+
+## Webhook 签名验证
+
+    from viseron_qqbotpy.webhook import verify_signature, sign_validation
+
+    ok = verify_signature(
+        secret="AppSecret",
+        timestamp=request.headers["X-Signature-Timestamp"],
+        body=request.body.decode(),
+        signature_hex=request.headers["X-Signature-Ed25519"],
+    )
+
+## 项目结构
+
+    src/viseron_qqbotpy/
+      client.py       # Client 入口
+      api.py          # OpenAPI 封装
+      gateway.py      # WebSocket 网关/分片/重连
+      token.py        # access token 无缝刷新
+      http.py         # HTTP 客户端
+      env.py          # .env 文件加载
+      logging.py      # 默认日志与 configure_logging
+      dispatcher.py   # 事件解析与分发
+      models.py       # 事件 dataclass
+      types.py        # payload 类型提示
+      flags.py        # Intents / Permission
+      errors.py       # 异常体系
+      panel.py        # 指令面板：Panel / PanelStore
+      group_store.py  # 本地群聊状态：GroupStore
+      webhook.py      # 可选 Webhook 签名
+      ext/            # 命令、颜色、频道跳转等扩展
+
+## License
+
+MIT

viseron_qqbotpy-0.4.2/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viseron-qqbotpy"
+version = "0.4.2"
+description = "A modern, asyncio-based Python SDK for the QQ Open Platform Bot API (api-v2)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Viseron" }]
+keywords = ["qq", "qqbot", "qq-bot", "qq机器人", "sdk", "websocket", "bot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "aiohttp>=3.7.4,<4",
+]
+
+[project.optional-dependencies]
+ext = ["PyYAML>=6", "APScheduler>=3.10"]
+webhook = ["cryptography>=41"]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "python-dotenv>=1"]
+
+[project.urls]
+Homepage = "https://bot.q.qq.com/wiki/develop/api-v2/"
+Documentation = "https://bot.q.qq.com/wiki/develop/api-v2/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+viseron_qqbotpy = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

viseron_qqbotpy-0.4.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

viseron_qqbotpy-0.4.2/src/viseron_qqbotpy/__init__.py

@@ -0,0 +1,101 @@
+"""viseron-qqbotpy: a modern QQ Open Platform bot SDK.
+
+The package exposes the main Client, Intents, event models and exceptions.
+"""
+
+from .client import Client
+from .api import AT_EVERYONE, BotAPI
+from .env import load_env
+from .http import HTTPClient, Route
+from .token import AccessToken, TokenManager
+from .flags import Intents, Permission
+from .group_store import GroupStore, load_group_store
+from .panel import Panel, PanelItem, PanelStore, load_panels
+from .errors import (
+    APIError,
+    AuthenticationFailedError,
+    ForbiddenError,
+    MethodNotAllowedError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TokenError,
+    ViseronError,
+    WebSocketError,
+)
+from .models import (
+    AudioAction,
+    C2CManageEvent,
+    C2CMessage,
+    Channel,
+    DirectMessage,
+    ForumThread,
+    GroupJoinRequestEvent,
+    GroupManageEvent,
+    GroupMemberEvent,
+    GroupMessage,
+    Guild,
+    Interaction,
+    Member,
+    Message,
+    MessageAudit,
+    OpenForumThread,
+    PublicAudio,
+    Reaction,
+    SubscribeMessageStatusEvent,
+    User,
+)
+from .logging import configure_logging, get_logger
+
+__all__ = [
+    "APIError",
+    "AT_EVERYONE",
+    "AccessToken",
+    "AudioAction",
+    "BotAPI",
+    "AuthenticationFailedError",
+    "C2CManageEvent",
+    "C2CMessage",
+    "Channel",
+    "Client",
+    "DirectMessage",
+    "ForbiddenError",
+    "ForumThread",
+    "GroupJoinRequestEvent",
+    "GroupManageEvent",
+    "GroupMemberEvent",
+    "GroupMessage",
+    "GroupStore",
+    "Guild",
+    "Intents",
+    "HTTPClient",
+    "Interaction",
+    "load_env",
+    "Member",
+    "Message",
+    "MessageAudit",
+    "MethodNotAllowedError",
+    "NotFoundError",
+    "OpenForumThread",
+    "Panel",
+    "PanelItem",
+    "PanelStore",
+    "Permission",
+    "PublicAudio",
+    "RateLimitError",
+    "Reaction",
+    "Route",
+    "ServerError",
+    "SubscribeMessageStatusEvent",
+    "TokenError",
+    "TokenManager",
+    "User",
+    "ViseronError",
+    "WebSocketError",
+    "configure_logging",
+    "get_logger",
+    "load_group_store",
+    "load_panels",
+]
+
+__version__ = "0.4.2"