qbotsdk 0.6.0__py3-none-any.whl

qbotsdk/__init__.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2026-present Half_nothing.
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .adapter import Adapter, AdapterContext, WebhookAdapter, WebSocketAdapter
+from .api import ApiClient
+from .bot import Bot
+from .exceptions import APIError, ErrorCode, QQBotError, RateLimitExceededError, TransportError
+from .gateway import WebhookServer, build_webhook_handler
+from .model import (
+    Channel,
+    ChannelMessageCreate,
+    ChannelMessageDraft,
+    Group,
+    GroupBotState,
+    GroupMember,
+    GroupMessageDraft,
+    GroupMessageReceipt,
+    GroupMuteState,
+    GroupUser,
+    Guild,
+    GuildUser,
+    InteractionCreate,
+    Member,
+    Message,
+    Role,
+    User,
+)
+from .options import ClientOptions
+from .storage import FileSessionStorage, MemorySessionStorage, SessionData, SessionStorage
+
+try:
+    __version__ = version("qbotsdk")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "APIError",
+    "Adapter",
+    "AdapterContext",
+    "ApiClient",
+    "Bot",
+    "Channel",
+    "ChannelMessageCreate",
+    "ChannelMessageDraft",
+    "ClientOptions",
+    "ErrorCode",
+    "FileSessionStorage",
+    "Group",
+    "GroupBotState",
+    "GroupMember",
+    "GroupMessageDraft",
+    "GroupMessageReceipt",
+    "GroupMuteState",
+    "GroupUser",
+    "Guild",
+    "GuildUser",
+    "InteractionCreate",
+    "Member",
+    "MemorySessionStorage",
+    "Message",
+    "QQBotError",
+    "RateLimitExceededError",
+    "Role",
+    "SessionData",
+    "SessionStorage",
+    "TransportError",
+    "User",
+    "WebSocketAdapter",
+    "WebhookAdapter",
+    "WebhookServer",
+    "__version__",
+    "build_webhook_handler",
+]

qbotsdk/adapter/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""适配器：核心不内置任何接入方式, 使用者显式选择或自己实现。"""
+
+from .base import Adapter, AdapterContext
+from .webhook import WebhookAdapter
+from .websocket import WebSocketAdapter
+
+__all__ = ["Adapter", "AdapterContext", "WebSocketAdapter", "WebhookAdapter"]

qbotsdk/adapter/base.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""适配器抽象：事件从哪里来由使用者决定, 核心只认这个接口。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qbotsdk.api import ApiClient
+    from qbotsdk.gateway.dispatcher import Dispatcher
+    from qbotsdk.module.http_client import HTTPClient
+
+
+@dataclass(slots=True)
+class AdapterContext:
+    """适配器启动时能拿到的东西, 由 Bot.start() 组装。"""
+
+    http: HTTPClient
+    api: ApiClient
+    dispatcher: Dispatcher
+
+
+class Adapter(ABC):
+    """接入方式的公共接口。"""
+
+    @abstractmethod
+    async def start(self, context: AdapterContext) -> None:
+        """开始收事件并立即返回, 后台任务由适配器自己持有。"""
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """停止收事件并释放资源, 允许重复调用。"""

qbotsdk/adapter/webhook.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""Webhook 适配器：由平台回调推事件, 自己不再连网关。"""
+
+from __future__ import annotations
+
+from ssl import SSLContext
+
+from qbotsdk.gateway.webhook_server import WebhookServer
+
+from .base import Adapter, AdapterContext
+
+
+class WebhookAdapter(Adapter):
+    """把 HTTP 回调收进同一个分发器, 与Websocket二选一。"""
+
+    def __init__(
+        self,
+        app_secret: str,
+        *,
+        host: str = "0.0.0.0",
+        port: int = 8443,
+        path: str = "/qbotsdk",
+        certfile: str | None = None,
+        keyfile: str | None = None,
+        ssl_context: SSLContext | None = None,
+    ) -> None:
+        """记录监听参数, 真正监听发生在 start()。
+
+        Args:
+            app_secret:  机器人密钥, 用于验签与 op 13 应答。
+            host:        监听地址。
+            port:        监听端口, 0 表示让操作系统挑一个空闲端口。
+            path:        回调路径, 管理端填的地址要与之对应。
+            certfile:    证书链路径, 必须与 keyfile 成对出现。
+            keyfile:     私钥路径。
+            ssl_context: 现成的 SSLContext, 与 certfile/keyfile 互斥。
+        """
+
+        self._app_secret = app_secret
+        self._host = host
+        self._port = port
+        self._path = path
+        self._certfile = certfile
+        self._keyfile = keyfile
+        self._ssl_context = ssl_context
+        self._server: WebhookServer | None = None
+
+    @property
+    def port(self) -> int:
+        """实际监听的端口, 传 0 时要等 start() 之后才有值。"""
+
+        if self._server is not None:
+            return self._server.port
+        return self._port
+
+    async def start(self, context: AdapterContext) -> None:
+        if self._server is not None:
+            raise RuntimeError("webhook adapter is already started")
+
+        server = WebhookServer(
+            context.dispatcher,
+            self._app_secret,
+            host=self._host,
+            port=self._port,
+            path=self._path,
+            certfile=self._certfile,
+            keyfile=self._keyfile,
+            ssl_context=self._ssl_context,
+        )
+        await server.start()
+        self._server = server
+        self._port = server.port
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            await self._server.close()
+            self._server = None

qbotsdk/adapter/websocket.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""WebSocket 适配器：连上网关、维持心跳、断线续连。"""
+
+from __future__ import annotations
+
+from asyncio import Task, create_task, gather
+
+from qbotsdk.gateway.connection import GatewayConnection
+from qbotsdk.gateway.payload import Intents
+from qbotsdk.storage import SessionStorage
+
+from .base import Adapter, AdapterContext
+
+
+class WebSocketAdapter(Adapter):
+    """用Websocket收事件。"""
+
+    def __init__(
+        self,
+        *,
+        intents: int | None = None,
+        shard: tuple[int, int] = (0, 1),
+        session_storage: SessionStorage | None = None,
+    ) -> None:
+        """记录连接参数, 真正连接发生在 start()。
+
+        Args:
+            intents:         订阅的事件位, 不传用 Intents.DEFAULT。
+            shard:           (分片序号, 分片总数), 单连接保持默认即可。
+            session_storage: 会话存储, 不传则用内存实现。
+        """
+
+        self._intents = intents if intents is not None else Intents.DEFAULT
+        self._shard = shard
+        self._storage = session_storage
+        self._connection: GatewayConnection | None = None
+        self._tasks: set[Task[None]] = set()
+
+    async def start(self, context: AdapterContext) -> None:
+        if self._connection is not None:
+            raise RuntimeError("websocket adapter is already started")
+
+        connection = GatewayConnection(
+            context.http,
+            options=context.http.options,
+            intents=self._intents,
+            shard=self._shard,
+            session_storage=self._storage,
+        )
+        self._connection = connection
+        self._tasks = {
+            create_task(connection.run()),
+            create_task(context.dispatcher.run(connection.events)),
+        }
+
+    async def stop(self) -> None:
+        if self._connection is not None:
+            await self._connection.close()
+        for task in list(self._tasks):
+            task.cancel()
+        if self._tasks:
+            await gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+        self._connection = None

qbotsdk/api/__init__.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""资源层，每个资源只负责拼路径、调 HTTPClient、把返回值转模型。"""
+
+from __future__ import annotations
+
+from qbotsdk.module.http_client import HTTPClient
+from qbotsdk.module.rate_limit import RateLimiter
+
+from .channel import ChannelResource
+from .group import GroupResource
+from .guild import GuildResource
+from .interaction import InteractionResource
+from .message import MessageResource
+from .reaction import ReactionResource
+from .user import UserResource
+from .user_message import UserMessageResource
+
+__all__ = [
+    "ApiClient",
+    "ChannelResource",
+    "GroupResource",
+    "GuildResource",
+    "InteractionResource",
+    "MessageResource",
+    "ReactionResource",
+    "UserMessageResource",
+    "UserResource",
+]
+
+
+class ApiClient:
+    """八个资源域的聚合入口，由 `Bot` 持有并暴露为 `bot.api`。"""
+
+    def __init__(self, http: HTTPClient) -> None:
+        options = http.options
+        # 关掉限流就整层不建桶, 资源层拿到的 limiter 为 None
+        limiter = RateLimiter(options.rate_limits) if options.respect_rate_limits else None
+        self.user = UserResource(http)
+        self.guild = GuildResource(http)
+        self.group = GroupResource(http, limiter=limiter)
+        self.channel = ChannelResource(http)
+        self.message = MessageResource(http)
+        self.user_message = UserMessageResource(http, limiter=limiter)
+        self.interaction = InteractionResource(http)
+        self.reaction = ReactionResource(http)

qbotsdk/api/_parse.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""响应形状校验。
+资源层只认对象与数组，形状不符说明接口契约变了，直接抛TransportError并带上 path。
+"""
+
+from __future__ import annotations
+
+from qbotsdk.exceptions import TransportError
+
+
+def expect_object(payload: object, path: str) -> dict[str, object]:
+    if not isinstance(payload, dict):
+        raise TransportError(
+            f"expected a JSON object from {path}, got {type(payload).__name__}",
+            method="GET",
+            path=path,
+        )
+    return payload
+
+
+def expect_list(payload: object, path: str) -> list[object]:
+    if not isinstance(payload, list):
+        raise TransportError(
+            f"expected a JSON array from {path}, got {type(payload).__name__}",
+            method="GET",
+            path=path,
+        )
+    return payload

qbotsdk/api/channel.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""子频道域接口。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from aiohttp import FormData
+
+from qbotsdk.model.channel import Channel
+from qbotsdk.model.draft import ChannelMessageDraft, MessageMarkdown, MessageReference
+from qbotsdk.model.message import Message
+from qbotsdk.module.http_client import HTTPClient
+
+from ._parse import expect_object
+
+# 官方支持 multipart 直传时就这几种图片类型, 其余按二进制流发
+_CONTENT_TYPES: dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+}
+
+
+def _content_type(file_name: str) -> str:
+    return _CONTENT_TYPES.get(Path(file_name).suffix.lower(), "application/octet-stream")
+
+
+class ChannelResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    async def get(self, channel_id: str) -> Channel:
+        """子频道详情。"""
+
+        path = f"/channels/{channel_id}"
+        return Channel.model_validate(expect_object(await self._http.get(path), path))
+
+    async def send_message(
+        self,
+        channel_id: str,
+        *,
+        content: str | None = None,
+        markdown: MessageMarkdown | None = None,
+        image: str | None = None,
+        file_image: bytes | None = None,
+        file_name: str = "image.png",
+        reply_to: str | None = None,
+        event_id: str | None = None,
+    ) -> Message:
+        """发子频道消息。
+
+        每个子频道主动与被动合计每秒最多5条
+        主动消息每个子频道每天 20 条、每天最多 2 个子频道
+        超限返回 `40034100` 等错误码
+
+        Args:
+            channel_id: 频道标识
+            content: 纯文本内容
+            markdown: markdown格式的内容
+            image: 传URL由平台转存, 与file_image参数互斥
+            file_image: 传字节走multipart, 与image参数互斥
+            file_name: 文件名
+            reply_to: 被动回复的msg_id, 有效期5分钟
+            event_id: 消息事件ID
+        """
+
+        if image is not None and file_image is not None:
+            raise ValueError("image and file_image are mutually exclusive")
+
+        path = f"/channels/{channel_id}/messages"
+        reference = MessageReference(message_id=reply_to) if reply_to is not None else None
+
+        if file_image is not None:
+            # Markdown 消息不带 content, 同传时以 markdown 为准
+            text = None if markdown is not None else content
+            file_bytes: bytes = file_image
+
+            def build_form() -> FormData:
+                form = FormData()
+                if text is not None:
+                    form.add_field("content", text)
+                if image is not None:
+                    form.add_field("image", image)
+                if event_id is not None:
+                    form.add_field("event_id", event_id)
+                if markdown is not None:
+                    form.add_field("markdown", _as_form_json(markdown))
+                if reference is not None:
+                    form.add_field("message_reference", _as_form_json(reference))
+                form.add_field(
+                    "file_image",
+                    file_bytes,
+                    filename=file_name,
+                    content_type=_content_type(file_name),
+                )
+                return form
+
+            data = await self._http.post_form(path, form=build_form)
+        else:
+            draft = ChannelMessageDraft(
+                content=None if markdown is not None else content,
+                markdown=markdown,
+                image=image,
+                event_id=event_id,
+                message_reference=reference,
+            )
+            data = await self._http.post(
+                path,
+                json=draft.model_dump(by_alias=True, exclude_none=True, mode="json"),
+            )
+
+        return Message.model_validate(expect_object(data, path))
+
+    async def recall_message(
+        self,
+        channel_id: str,
+        message_id: str,
+        *,
+        hide_tip: bool = False,
+    ) -> None:
+        """撤回消息, 发送后 2 分钟内有效。hidetip 是 query, 不是包体。"""
+
+        path = f"/channels/{channel_id}/messages/{message_id}"
+        await self._http.request(
+            "DELETE",
+            path,
+            params={"hidetip": "true" if hide_tip else "false"},
+        )
+
+
+def _as_form_json(model: MessageMarkdown | MessageReference) -> str:
+    """multipart 里的嵌套对象要序列化成字符串字段。"""
+
+    return model.model_dump_json(by_alias=True, exclude_none=True, ensure_ascii=False)

qbotsdk/api/group.py

@@ -0,0 +1,184 @@
+# Copyright (c) 2026-present Half_nothing.
+
+"""群组（QQ 群）域接口，读写。"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from aiohttp import FormData
+
+from qbotsdk.model.draft import GroupMessageDraft, MessageMarkdown
+from qbotsdk.model.group import Group, GroupBotState, GroupMember, GroupMembersPage, GroupMuteState
+from qbotsdk.model.keyboard import Keyboard
+from qbotsdk.model.media import FileType, MediaInfo, UploadedFile
+from qbotsdk.model.message import GroupMessageReceipt
+from qbotsdk.module.http_client import HTTPClient
+from qbotsdk.module.pagination import paginate
+from qbotsdk.module.rate_limit import RateLimiter
+
+from ._parse import expect_object
+
+# 二进制直传上限，官方文档对图片/语音写 20MB、视频 30MB、文件 200MB
+# 但 multipart 直传字段本身限制 5MB，超过要走 url 或分片上传。
+_MAX_UPLOAD_BYTES = 5 * 1024 * 1024
+
+
+class GroupResource:
+    def __init__(self, http: HTTPClient, *, limiter: RateLimiter | None = None) -> None:
+        self._http = http
+        self._limiter = limiter
+
+    async def get(self, group_openid: str) -> Group:
+        """群基本信息，频率限制 30 QPM。"""
+
+        path = f"/v2/groups/{group_openid}/info"
+        return Group.model_validate(expect_object(await self._http.get(path), path))
+
+    async def bot_state(self, group_openid: str) -> GroupBotState:
+        """机器人在群内的状态：是否收主动推送、接收消息范围、自身角色。"""
+
+        path = f"/v2/groups/{group_openid}/bot_state"
+        return GroupBotState.model_validate(expect_object(await self._http.get(path), path))
+
+    async def members(self, group_openid: str, *, cursor: str = "") -> GroupMembersPage:
+        """
+        群成员分页，每次最多 30 条。
+
+        `cursor` 首次不传，后续传上一页的 `next_cursor`；
+        返回整页而不是列表，因为末页标志 `next_cursor` 与成员在同一层。
+        """
+
+        path = f"/v2/groups/{group_openid}/members"
+        params = {"cursor": cursor} if cursor else None
+        payload = await self._http.get(path, params=params)
+        return GroupMembersPage.model_validate(expect_object(payload, path))
+
+    async def member(self, group_openid: str, member_openid: str) -> GroupMember:
+        """单个群成员。"""
+
+        path = f"/v2/groups/{group_openid}/members/{member_openid}"
+        return GroupMember.model_validate(expect_object(await self._http.get(path), path))
+
+    async def mute_setting(self, group_openid: str) -> GroupMuteState:
+        """群禁言状态，机器人为群管理员时才有权限（错误码 11253）。"""
+
+        path = f"/v2/groups/{group_openid}/restrict_chat_setting"
+        return GroupMuteState.model_validate(expect_object(await self._http.get(path), path))
+
+    async def iter_members(self, group_openid: str) -> AsyncIterator[GroupMember]:
+        """按 `next_cursor` 翻页遍历群成员，末页或空页结束。"""
+
+        state = {"next": ""}
+
+        async def fetch_page(cursor: str | None) -> list[GroupMember]:
+            page = await self.members(group_openid, cursor=cursor or "")
+            state["next"] = page.next_cursor
+            return page.members
+
+        def cursor_of(page: list[GroupMember]) -> str | None:
+            return state["next"] or None
+
+        async for member in paginate(fetch_page, cursor_of=cursor_of):
+            yield member
+
+    async def send_message(
+        self,
+        group_openid: str,
+        *,
+        content: str | None = None,
+        markdown: MessageMarkdown | None = None,
+        media: MediaInfo | None = None,
+        keyboard: Keyboard | None = None,
+        reply_to: str | None = None,
+        event_id: str | None = None,
+        msg_seq: int | None = None,
+    ) -> GroupMessageReceipt:
+        """发群消息。
+
+        被动回复有效期为 5 分钟, 每条消息最多回 5 次。
+        同一个 msg_id + msg_seq 重复发送会被拒
+        要回第二次请显式传 msg_seq=2
+
+        keyboard 只在 Markdown 消息上渲染: 只传 content + keyboard 时,
+        content 会被自动搬进 markdown 并把 msg_type 置 2。
+        """
+
+        path = f"/v2/groups/{group_openid}/messages"
+        if self._limiter is not None:
+            self._limiter.check("group", group_openid)
+        if reply_to is not None and msg_seq is None:
+            msg_seq = 1
+        draft = GroupMessageDraft(
+            content=content,
+            markdown=markdown,
+            media=media,
+            keyboard=keyboard,
+            msg_id=reply_to,
+            event_id=event_id,
+            msg_seq=msg_seq,
+        )
+        payload = await self._http.post(
+            path,
+            json=draft.model_dump(by_alias=True, exclude_none=True, mode="json"),
+        )
+        return GroupMessageReceipt.model_validate(expect_object(payload, path))
+
+    async def recall_message(self, group_openid: str, message_id: str) -> None:
+        """撤回群消息, 发送后 2 分钟内有效, 接口限制 10 QPS。"""
+
+        path = f"/v2/groups/{group_openid}/messages/{message_id}"
+        await self._http.request("DELETE", path)
+
+    async def upload_file(
+        self,
+        group_openid: str,
+        file_type: FileType,
+        /,
+        *,
+        url: str | None = None,
+        file_data: bytes | None = None,
+        file_name: str | None = None,
+        srv_send_msg: bool = False,
+    ) -> UploadedFile:
+        """上传群富媒体（图片 / 视频 / 语音 / 文件）。
+
+        url 与 file_data 二选一，前者交给服务端下载，后者按 multipart 直传，上限 5MB。
+        返回的 file_info 直接填进 send_message 的 media。
+        srv_send_msg=True 时服务端上传后立即发送，会占用主动消息频次。
+        """
+
+        if (url is None) == (file_data is None):
+            raise ValueError("upload_file needs exactly one of url or file_data")
+
+        path = f"/v2/groups/{group_openid}/files"
+
+        if url is not None:
+            payload = await self._http.post(
+                path,
+                json={
+                    "file_type": int(file_type),
+                    "url": url,
+                    "srv_send_msg": srv_send_msg,
+                },
+            )
+            return UploadedFile.model_validate(expect_object(payload, path))
+
+        assert file_data is not None  # 由上面的二选一校验保证
+        if len(file_data) > _MAX_UPLOAD_BYTES:
+            raise ValueError("file_data must not exceed 5 MB, use url instead")
+        if file_name is None:
+            raise ValueError("file_data needs file_name so the server can infer the type")
+
+        name = file_name
+
+        def build_form() -> FormData:
+            form = FormData()
+            form.add_field("file_type", str(int(file_type)))
+            form.add_field("srv_send_msg", "true" if srv_send_msg else "false")
+            form.add_field("file_data", file_data, filename=name)
+            form.add_field("file_name", name)
+            return form
+
+        payload = await self._http.post_form(path, form=build_form)
+        return UploadedFile.model_validate(expect_object(payload, path))