qqbot-md-sdk 0.1.0__tar.gz

qqbot_md_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.1
+Name: qqbot-md-sdk
+Version: 0.1.0
+Summary: QQ 官方机器人 Markdown 消息构造 SDK
+Keywords: qq,qqbot,markdown,keyboard,sdk
+Author: MimoKit
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Homepage, https://github.com/MimoKit/qgbot
+Project-URL: Repository, https://github.com/MimoKit/qgbot
+Project-URL: Issues, https://github.com/MimoKit/qgbot/issues
+Project-URL: Documentation, https://github.com/MimoKit/qgbot/tree/main/docs
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# qgbot
+
+_把 QQ 官方机器人那套 Markdown 语法和键盘 JSON，变成可组合的 Python 调用_
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.10-3776ab)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/文档-中文-8f5db7)](https://docs.example.com/)
+
+写插件时不用再手拼 `<qqbot-cmd-input>` 和按钮 JSON —— 一句 `md.image(url, 400, 300)` 就够。
+
+</div>
+
+## 为什么需要它
+
+QQ 官方机器人的 markdown 跟标准 markdown 不是一回事。图片尺寸得写在 alt 文本里（`![x #200px #300px](url)`）、分隔线是 `***` 不是 `---`、下划线是 `__` 不是 `<u>`、连续换行会被合并所以要多空一行得插零宽空格、@ 用户的标签从 `<@id>` 换成了 `<qqbot-at-user id="" />`。这些细节散在文档各处，每个插件都要重复踩一遍。
+
+按钮是另一层麻烦：平台要一段嵌套 JSON，`action.type` 区分链接 / 回调 / 指令 / 订阅，`permission.type` 区分所有人 / 管理员 / 指定用户 / 指定身份组，手写容易把 `type` 和 `style` 搞混。
+
+图片还有第三层：markdown 里的图必须是公网 URL，平台自己去拉；插件渲染出来的卡片只存在本地磁盘。官方图库的上传是**三步预签名流程**——声明元信息拿预签名地址、PUT 原始字节、回传 ETag 里的 MD5 收尾——不是一次 multipart 提交。
+
+qgbot 把这三块分别封成 `md`、`keyboard`、`media`，再加一个 `message` 负责组装发送用的 payload。
+
+## 特性
+
+- **零依赖** —— 纯标准库实现，不引入任何运行时包，`pip install` 不拉任何东西
+- **不绑框架** —— 没有 NoneBot / 自研框架的 import，任何 Python 环境都能直接用
+- **不碰网络** —— 素材上传只算签名、组请求、解响应，HTTP 由调用方注入，复用你自己的连接池与重试策略
+- **语法对齐平台** —— 分隔线、下划线、图片尺寸、零宽空格、@ 标签这些与标准 md 不同的地方全部按官方语法生成
+- **限制可见** —— 标题只支持两级、键盘最多 5 行、图片 10 MB、图库 100 张，都以常量形式暴露
+- **结构可测** —— 89 个用例覆盖每一处语法与上传流程，不需要起 mock server
+
+## 模块一览
+
+| 模块 | 覆盖内容 |
+| --- | --- |
+| `qgbot.md` | 标题、六种文字样式、行内链接与自动链接、带尺寸图片、两种列表（含二级缩进）、引用块、分隔线、多空行、正文内联指令按钮、@ 用户与 @ 全体、频道子频道跳转与系统表情 |
+| `qgbot.keyboard` | 链接 / 回调 / 指令三类按钮，权限限定，按行切分，字号设置 |
+| `qgbot.media` | 图库上传三步流程，含签名计算、错误码映射、列表解析与删除 |
+| `qgbot.message` | markdown 正文与键盘合成发送 body，带 `msg_id` / `msg_seq` 被动回复字段 |
+
+```python
+from qgbot import md, command, make_keyboard, Message
+
+content = md.render(
+    md.title("今日运势"),
+    md.image("https://example.com/card.png", 400, 300),
+    md.mention("user_openid"),
+    md.quote("宜：出门走走"),
+)
+
+payload = Message(
+    content,
+    keyboard=make_keyboard(command("再抽一次", "今日运势")),
+).to_payload(msg_id="收到的那条消息id")
+```
+
+## 边界
+
+**不做网络请求。** 素材上传只算 MD5 / SHA1、组装请求体、解析响应，实际 HTTP 由调用方注入的 `Transport` 完成。这样 SDK 不绑定 httpx / aiohttp / requests 中的任何一个，测试也不必起 mock server。
+
+**不管鉴权。** AccessToken 的获取与刷新属于调用方，SDK 产出的 payload 里不含凭据。
+
+**不做语法校验。** 平台限制以常量与注释暴露，但 SDK 不主动改写用户内容。两处例外：标题层级会被夹到合法范围（传 3 得到 2），键盘超过 5 行会被截断（平台本身就不渲染，抛错反而让整条消息发不出去）。
+
+**不解析已有 markdown。** 只有构造，没有反向解析。
+
+## 环境要求
+
+- Python `>= 3.10`
+
+## 开源协议
+
+[MIT](LICENSE)

qqbot_md_sdk-0.1.0/README.md

@@ -0,0 +1,75 @@
+<div align="center">
+
+# qgbot
+
+_把 QQ 官方机器人那套 Markdown 语法和键盘 JSON，变成可组合的 Python 调用_
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.10-3776ab)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/文档-中文-8f5db7)](https://docs.example.com/)
+
+写插件时不用再手拼 `<qqbot-cmd-input>` 和按钮 JSON —— 一句 `md.image(url, 400, 300)` 就够。
+
+</div>
+
+## 为什么需要它
+
+QQ 官方机器人的 markdown 跟标准 markdown 不是一回事。图片尺寸得写在 alt 文本里（`![x #200px #300px](url)`）、分隔线是 `***` 不是 `---`、下划线是 `__` 不是 `<u>`、连续换行会被合并所以要多空一行得插零宽空格、@ 用户的标签从 `<@id>` 换成了 `<qqbot-at-user id="" />`。这些细节散在文档各处，每个插件都要重复踩一遍。
+
+按钮是另一层麻烦：平台要一段嵌套 JSON，`action.type` 区分链接 / 回调 / 指令 / 订阅，`permission.type` 区分所有人 / 管理员 / 指定用户 / 指定身份组，手写容易把 `type` 和 `style` 搞混。
+
+图片还有第三层：markdown 里的图必须是公网 URL，平台自己去拉；插件渲染出来的卡片只存在本地磁盘。官方图库的上传是**三步预签名流程**——声明元信息拿预签名地址、PUT 原始字节、回传 ETag 里的 MD5 收尾——不是一次 multipart 提交。
+
+qgbot 把这三块分别封成 `md`、`keyboard`、`media`，再加一个 `message` 负责组装发送用的 payload。
+
+## 特性
+
+- **零依赖** —— 纯标准库实现，不引入任何运行时包，`pip install` 不拉任何东西
+- **不绑框架** —— 没有 NoneBot / 自研框架的 import，任何 Python 环境都能直接用
+- **不碰网络** —— 素材上传只算签名、组请求、解响应，HTTP 由调用方注入，复用你自己的连接池与重试策略
+- **语法对齐平台** —— 分隔线、下划线、图片尺寸、零宽空格、@ 标签这些与标准 md 不同的地方全部按官方语法生成
+- **限制可见** —— 标题只支持两级、键盘最多 5 行、图片 10 MB、图库 100 张，都以常量形式暴露
+- **结构可测** —— 89 个用例覆盖每一处语法与上传流程，不需要起 mock server
+
+## 模块一览
+
+| 模块 | 覆盖内容 |
+| --- | --- |
+| `qgbot.md` | 标题、六种文字样式、行内链接与自动链接、带尺寸图片、两种列表（含二级缩进）、引用块、分隔线、多空行、正文内联指令按钮、@ 用户与 @ 全体、频道子频道跳转与系统表情 |
+| `qgbot.keyboard` | 链接 / 回调 / 指令三类按钮，权限限定，按行切分，字号设置 |
+| `qgbot.media` | 图库上传三步流程，含签名计算、错误码映射、列表解析与删除 |
+| `qgbot.message` | markdown 正文与键盘合成发送 body，带 `msg_id` / `msg_seq` 被动回复字段 |
+
+```python
+from qgbot import md, command, make_keyboard, Message
+
+content = md.render(
+    md.title("今日运势"),
+    md.image("https://example.com/card.png", 400, 300),
+    md.mention("user_openid"),
+    md.quote("宜：出门走走"),
+)
+
+payload = Message(
+    content,
+    keyboard=make_keyboard(command("再抽一次", "今日运势")),
+).to_payload(msg_id="收到的那条消息id")
+```
+
+## 边界
+
+**不做网络请求。** 素材上传只算 MD5 / SHA1、组装请求体、解析响应，实际 HTTP 由调用方注入的 `Transport` 完成。这样 SDK 不绑定 httpx / aiohttp / requests 中的任何一个，测试也不必起 mock server。
+
+**不管鉴权。** AccessToken 的获取与刷新属于调用方，SDK 产出的 payload 里不含凭据。
+
+**不做语法校验。** 平台限制以常量与注释暴露，但 SDK 不主动改写用户内容。两处例外：标题层级会被夹到合法范围（传 3 得到 2），键盘超过 5 行会被截断（平台本身就不渲染，抛错反而让整条消息发不出去）。
+
+**不解析已有 markdown。** 只有构造，没有反向解析。
+
+## 环境要求
+
+- Python `>= 3.10`
+
+## 开源协议
+
+[MIT](LICENSE)

qqbot_md_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "qqbot-md-sdk"
+version = "0.1.0"
+description = "QQ 官方机器人 Markdown 消息构造 SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "MimoKit" },
+]
+keywords = [
+    "qq",
+    "qqbot",
+    "markdown",
+    "keyboard",
+    "sdk",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = []
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/MimoKit/qgbot"
+Repository = "https://github.com/MimoKit/qgbot"
+Issues = "https://github.com/MimoKit/qgbot/issues"
+Documentation = "https://github.com/MimoKit/qgbot/tree/main/docs"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "W",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+asyncio_mode = "auto"

qqbot_md_sdk-0.1.0/qgbot/__init__.py

@@ -0,0 +1,59 @@
+"""qgbot —— QQ 官方机器人 Markdown 消息构造 SDK。
+
+只做一件事：把 QQ 官方机器人那套 markdown 语法、键盘 JSON 和素材上传流程包装成可组合的
+Python API，让插件不用手拼字符串字面量。
+
+设计边界：
+- **不碰网络**。素材上传只算签名、组请求、解响应，实际 HTTP 由调用方注入的 transport 完成。
+- **不依赖框架**。纯标准库，任何框架（NoneBot / 自研 / 裸 requests）都能直接 import。
+- **不做语法校验**。平台限制（标题层级、按钮数量等）通过常量暴露，由调用方自己控制，
+  SDK 不擅自截断或改写用户的内容。
+
+    from qgbot import md
+
+    text = md.render(
+        md.title("今日运势", level=1),
+        md.quote("宜：出门走走"),
+        md.image("https://example.com/a.png", width=200, height=200),
+        md.mention("user_openid"),
+    )
+"""
+
+from . import md
+from .keyboard import (
+    MAX_ROWS,
+    STYLE_BLUE,
+    STYLE_GREY,
+    Button,
+    Keyboard,
+    callback,
+    command,
+    link,
+    make_keyboard,
+)
+from .media import MediaError, MediaImage, Transport, delete_image, upload_image
+from .message import Message, markdown_payload, markdown_with_keyboard
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MAX_ROWS",
+    "STYLE_BLUE",
+    "STYLE_GREY",
+    "Button",
+    "Keyboard",
+    "MediaError",
+    "MediaImage",
+    "Message",
+    "Transport",
+    "callback",
+    "command",
+    "delete_image",
+    "link",
+    "make_keyboard",
+    "markdown_payload",
+    "markdown_with_keyboard",
+    "md",
+    "upload_image",
+    "__version__",
+]

qqbot_md_sdk-0.1.0/qgbot/keyboard.py

@@ -0,0 +1,245 @@
+"""QQ 官方机器人的按钮 / 键盘构造。
+
+平台结构（发给 `keyboard` 字段）：
+
+    {
+      "content": {
+        "rows": [
+          {"buttons": [ {...}, {...} ]},
+          {"buttons": [ {...} ]}
+        ]
+      }
+    }
+
+单个按钮：
+
+    {
+      "id": "1",
+      "render_data": {"label": "显示文字", "visited_label": "点过之后", "style": 1},
+      "action": {"type": 2, "data": "指令", "permission": {"type": 2}}
+    }
+
+`action.type` 的取值：
+- 0 链接跳转，`data` 是 URL
+- 1 回调，点后平台推送 `INTERACTION_CREATE` 事件，`data` 是回调值
+- 2 指令，点后填入输入框（配 `enter: true` 则直接发送）
+- 4 订阅（`subscribe_data`）
+
+`permission.type` 的取值：
+- 0 指定用户，配 `specify_user_ids`
+- 1 仅管理员
+- 2 所有人
+- 3 指定身份组，配 `specify_role_ids`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# 按钮样式：0 灰色线框，1 蓝色线框
+STYLE_GREY = 0
+STYLE_BLUE = 1
+
+# 平台限制：键盘最多 5 行
+MAX_ROWS = 5
+# 每行最多 5 个按钮（平台未明确写死，但超过这个数会挤在一起，实际上按 3 个最舒服）
+MAX_BUTTONS_PER_ROW = 5
+
+# action.type
+ACTION_URL = 0
+ACTION_CALLBACK = 1
+ACTION_COMMAND = 2
+ACTION_SUBSCRIBE = 4
+
+# permission.type
+PERM_USER = 0
+PERM_ADMIN = 1
+PERM_EVERYONE = 2
+PERM_ROLE = 3
+
+
+@dataclass
+class Button:
+    """一个按钮。
+
+    用工厂函数 `link()` / `callback()` / `command()` 构造，比直接拼 dict 安全。
+    """
+
+    label: str
+    action_type: int
+    data: str = ""
+    visited_label: str = ""
+    style: int = STYLE_BLUE
+    enter: bool = False
+    reply: bool = False
+    permission: dict[str, Any] = field(default_factory=lambda: {"type": PERM_EVERYONE})
+    click_limit: int | None = None
+    unsupport_tips: str = ""
+    subscribe_data: dict[str, Any] | None = None
+    button_id: str = ""
+
+    def to_dict(self, index: int = 0) -> dict[str, Any]:
+        """转成平台要求的按钮结构。
+
+        `index` 用于在未显式指定 id 时生成一个稳定标识——平台要求按钮 id 在同一条消息
+        内唯一，重名会导致后一个覆盖前一个的点击状态。
+        """
+        render_data: dict[str, Any] = {
+            "label": self.label,
+            "visited_label": self.visited_label or self.label,
+            "style": self.style,
+        }
+        action: dict[str, Any] = {
+            "type": self.action_type,
+            "data": self.data,
+            "permission": self.permission,
+        }
+        if self.enter:
+            action["enter"] = True
+        if self.reply:
+            action["reply"] = True
+        if self.click_limit is not None:
+            action["click_limit"] = int(self.click_limit)
+        if self.unsupport_tips:
+            action["unsupport_tips"] = self.unsupport_tips
+        if self.subscribe_data is not None:
+            action["subscribe_data"] = self.subscribe_data
+
+        return {
+            "id": self.button_id or str(index),
+            "render_data": render_data,
+            "action": action,
+        }
+
+
+@dataclass
+class Keyboard:
+    """键盘：若干行，每行若干按钮。"""
+
+    rows: list[list[Button]] = field(default_factory=list)
+    font_size: str = ""  # "small" / "medium" / "large"
+
+    def add_row(self, *buttons: Button) -> Keyboard:
+        """追加一行。链式调用。"""
+        if buttons:
+            self.rows.append(list(buttons))
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """转成平台要求的 keyboard 结构。
+
+        超过 `MAX_ROWS` 的行会被丢弃——平台只认前 5 行，多出来的不会渲染。
+        这里截断而不是抛错：调用方可能批量生成按钮，硬失败会让整条消息发不出去。
+        """
+        counter = 0
+        rows = []
+        for row in self.rows[:MAX_ROWS]:
+            buttons = []
+            for btn in row[:MAX_BUTTONS_PER_ROW]:
+                buttons.append(btn.to_dict(counter))
+                counter += 1
+            if buttons:
+                rows.append({"buttons": buttons})
+
+        content: dict[str, Any] = {"rows": rows}
+        if self.font_size:
+            content["style"] = {"font_size": self.font_size}
+        return {"content": content}
+
+    def __bool__(self) -> bool:
+        """空键盘转成 False，方便调用方判断要不要带 keyboard 字段。"""
+        return any(row for row in self.rows)
+
+
+def link(label: str, url: str, *, visited_label: str = "", style: int = STYLE_BLUE) -> Button:
+    """跳转按钮：点击打开链接或客户端能识别的 scheme。"""
+    return Button(
+        label=label, action_type=ACTION_URL, data=url,
+        visited_label=visited_label, style=style,
+    )
+
+
+def callback(
+    label: str, value: str, *, visited_label: str = "", style: int = STYLE_BLUE,
+) -> Button:
+    """回调按钮：点击后平台推送 `INTERACTION_CREATE` 事件，`value` 原样带回来。"""
+    return Button(
+        label=label, action_type=ACTION_CALLBACK, data=value,
+        visited_label=visited_label, style=style,
+    )
+
+
+def command(
+    label: str,
+    command_text: str,
+    *,
+    visited_label: str = "",
+    style: int = STYLE_BLUE,
+    enter: bool = True,
+    reply: bool = False,
+) -> Button:
+    """指令按钮：点击后把指令填入输入框；`enter=True` 时直接发送。
+
+    `enter` 默认 True——用户的预期是"点一下就执行"，还要再按一次发送键会很烦。
+    `reply=True` 会让指令以"回复当前消息"的形式发出。
+    """
+    return Button(
+        label=label, action_type=ACTION_COMMAND, data=command_text,
+        visited_label=visited_label, style=style, enter=enter, reply=reply,
+    )
+
+
+def for_users(button: Button, user_ids: list[str]) -> Button:
+    """把按钮限定为只有指定用户可点。"""
+    button.permission = {"type": PERM_USER, "specify_user_ids": [str(u) for u in user_ids]}
+    return button
+
+
+def for_admins(button: Button) -> Button:
+    """把按钮限定为仅管理员可点。"""
+    button.permission = {"type": PERM_ADMIN}
+    return button
+
+
+def for_roles(button: Button, role_ids: list[str]) -> Button:
+    """把按钮限定为只有指定身份组可点（仅频道场景有效）。"""
+    button.permission = {"type": PERM_ROLE, "specify_role_ids": [str(r) for r in role_ids]}
+    return button
+
+
+def rows_of(buttons: list[Button], per_row: int = 3) -> list[list[Button]]:
+    """把一串按钮按每行 `per_row` 个切分成行。"""
+    per_row = max(1, min(MAX_BUTTONS_PER_ROW, int(per_row)))
+    return [buttons[i:i + per_row] for i in range(0, len(buttons), per_row)]
+
+
+def make_keyboard(*buttons: Button, per_row: int = 3, font_size: str = "") -> Keyboard:
+    """一次性构造键盘：按 `per_row` 自动分行。"""
+    return Keyboard(rows=rows_of(list(buttons), per_row), font_size=font_size)
+
+
+__all__ = [
+    "ACTION_CALLBACK",
+    "ACTION_COMMAND",
+    "ACTION_SUBSCRIBE",
+    "ACTION_URL",
+    "MAX_BUTTONS_PER_ROW",
+    "MAX_ROWS",
+    "PERM_ADMIN",
+    "PERM_EVERYONE",
+    "PERM_ROLE",
+    "PERM_USER",
+    "STYLE_BLUE",
+    "STYLE_GREY",
+    "Button",
+    "Keyboard",
+    "callback",
+    "command",
+    "for_admins",
+    "for_roles",
+    "for_users",
+    "make_keyboard",
+    "link",
+    "rows_of",
+]