diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index aa2e8ea1..f32a481d 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -119,6 +119,10 @@ module.exports = context => ({ { title: "nonebot.exception 模块", path: "exception" + }, + { + title: "nonebot.adapters.cqhttp 模块", + path: "adapters/cqhttp" } ] } diff --git a/docs/api/README.md b/docs/api/README.md index 2fa1066a..1c8acf1b 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -29,3 +29,6 @@ * [nonebot.exception](exception.html) + + + * [nonebot.adapters.cqhttp](adapters/cqhttp.html) diff --git a/docs/api/adapters/cqhttp.md b/docs/api/adapters/cqhttp.md new file mode 100644 index 00000000..51436b12 --- /dev/null +++ b/docs/api/adapters/cqhttp.md @@ -0,0 +1,274 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.adapters.cqhttp 模块 + +## CQHTTP (OneBot) v11 协议适配 + +协议详情请看: [CQHTTP](http://cqhttp.cc/) | [OneBot](https://github.com/howmanybots/onebot) + + +## `log(level, message)` + + +* **说明** + + 用于打印 CQHTTP 日志。 + + + +* **参数** + + + * `level: str`: 日志等级 + + + * `message: str`: 日志信息 + + + +## `escape(s, *, escape_comma=True)` + + +* **说明** + + 对字符串进行 CQ 码转义。 + + + +* **参数** + + + * `s: str`: 需要转义的字符串 + + + * `escape_comma: bool`: 是否转义逗号(`,`)。 + + + +## `unescape(s)` + + +* **说明** + + 对字符串进行 CQ 码去转义。 + + + +* **参数** + + + * `s: str`: 需要转义的字符串 + + + +## `_b2s(b)` + +转换布尔值为字符串。 + + +## _async_ `_check_reply(bot, event)` + + +* **说明** + + 检查消息中存在的回复,去除并赋值 `event.reply`, `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_check_at_me(bot, event)` + + +* **说明** + + 检查消息开头或结尾是否存在 @机器人,去除并赋值 `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_check_nickname(bot, event)` + + +* **说明** + + 检查消息开头是否存在,去除并赋值 `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_handle_api_result(result)` + + +* **说明** + + 处理 API 请求返回值。 + + + +* **参数** + + + * `result: Optional[Dict[str, Any]]`: API 返回数据 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `ActionFailed`: API 调用失败 + + + +## _class_ `Bot` + +基类:`nonebot.adapters.BaseBot` + +CQHTTP 协议 Bot 适配 + + +### _property_ `type` + + +* 返回: `"cqhttp"` + + +### _async_ `handle_message(message)` + + +* **说明** + + 调用 [_check_reply](#async-check-reply-bot-event), [_check_at_me](#check-at-me-bot-event), [_check_nickname](#check-nickname-bot-event) 处理事件并转换为 [Event](#class-event) + + + +### _async_ `call_api(api, **data)` + + +* **说明** + + 调用 CQHTTP 协议 API + + + +* **参数** + + + * `api: str`: API 名称 + + + * `**data: Any`: API 参数 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `NetworkError`: 网络错误 + + + * `ActionFailed`: API 调用失败 + + + +### _async_ `send(event, message, at_sender=False, **kwargs)` + + +* **说明** + + 根据 `event` 向触发事件的主体发送消息。 + + + +* **参数** + + + * `event: Event`: Event 对象 + + + * `message: Union[str, Message, MessageSegment]`: 要发送的消息 + + + * `at_sender: bool`: 是否 @ 事件主体 + + + * `**kwargs`: 覆盖默认参数 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `ValueError`: 缺少 `user_id`, `group_id` + + + * `NetworkError`: 网络错误 + + + * `ActionFailed`: API 调用失败 + + + +## _class_ `Event` + +基类:`nonebot.adapters.BaseEvent` + + +## _class_ `MessageSegment` + +基类:`nonebot.adapters.BaseMessageSegment` + + +## _class_ `Message` + +基类:`nonebot.adapters.BaseMessage` diff --git a/docs_build/README.rst b/docs_build/README.rst index cb726c38..97f45a20 100644 --- a/docs_build/README.rst +++ b/docs_build/README.rst @@ -11,3 +11,4 @@ NoneBot Api Reference - `nonebot.permission `_ - `nonebot.utils `_ - `nonebot.exception `_ + - `nonebot.adapters.cqhttp `_ diff --git a/docs_build/adapters/cqhttp.rst b/docs_build/adapters/cqhttp.rst new file mode 100644 index 00000000..ddf78105 --- /dev/null +++ b/docs_build/adapters/cqhttp.rst @@ -0,0 +1,12 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +NoneBot.adapters.cqhttp 模块 +================= + +.. automodule:: nonebot.adapters.cqhttp + :members: + :private-members: + :show-inheritance: diff --git a/nonebot/adapters/cqhttp.py b/nonebot/adapters/cqhttp.py index 8d886919..0f6d0973 100644 --- a/nonebot/adapters/cqhttp.py +++ b/nonebot/adapters/cqhttp.py @@ -199,7 +199,8 @@ def _check_nickname(bot: "Bot", event: "Event"): first_msg_seg.data["text"] = first_text[m.end():] -def _handle_api_result(result: Optional[Dict[str, Any]]) -> Any: +def _handle_api_result( + result: Optional[Dict[str, Any]]) -> Union[Any, NoReturn]: """ :说明: @@ -208,6 +209,14 @@ def _handle_api_result(result: Optional[Dict[str, Any]]) -> Any: :参数: * ``result: Optional[Dict[str, Any]]``: API 返回数据 + + :返回: + + - ``Any``: API 调用返回数据 + + :异常: + + - ``ActionFailed``: API 调用失败 """ if isinstance(result, dict): if result.get("status") == "failed": @@ -246,6 +255,9 @@ class ResultStore: class Bot(BaseBot): + """ + CQHTTP 协议 Bot 适配 + """ def __init__(self, driver: Driver, @@ -266,10 +278,18 @@ class Bot(BaseBot): @property @overrides(BaseBot) def type(self) -> str: + """ + - 返回: ``"cqhttp"`` + """ return "cqhttp" @overrides(BaseBot) async def handle_message(self, message: dict): + """ + :说明: + + 调用 `_check_reply <#async-check-reply-bot-event>`_, `_check_at_me <#check-at-me-bot-event>`_, `_check_nickname <#check-nickname-bot-event>`_ 处理事件并转换为 `Event <#class-event>`_ + """ if not message: return @@ -293,6 +313,25 @@ class Bot(BaseBot): @overrides(BaseBot) async def call_api(self, api: str, **data) -> Union[Any, NoReturn]: + """ + :说明: + + 调用 CQHTTP 协议 API + + :参数: + + * ``api: str``: API 名称 + * ``**data: Any``: API 参数 + + :返回: + + - ``Any``: API 调用返回数据 + + :异常: + + - ``NetworkError``: 网络错误 + - ``ActionFailed``: API 调用失败 + """ if "self_id" in data: self_id = data.pop("self_id") if self_id: @@ -341,12 +380,36 @@ class Bot(BaseBot): raise NetworkError("HTTP request failed") @overrides(BaseBot) - async def send(self, event: "Event", message: Union[str, "Message", - "MessageSegment"], + async def send(self, + event: "Event", + message: Union[str, "Message", "MessageSegment"], + at_sender: bool = False, **kwargs) -> Union[Any, NoReturn]: + """ + :说明: + + 根据 ``event`` 向触发事件的主体发送消息。 + + :参数: + + * ``event: Event``: Event 对象 + * ``message: Union[str, Message, MessageSegment]``: 要发送的消息 + * ``at_sender: bool``: 是否 @ 事件主体 + * ``**kwargs``: 覆盖默认参数 + + :返回: + + - ``Any``: API 调用返回数据 + + :异常: + + - ``ValueError``: 缺少 ``user_id``, ``group_id`` + - ``NetworkError``: 网络错误 + - ``ActionFailed``: API 调用失败 + """ msg = message if isinstance(message, Message) else Message(message) - at_sender = kwargs.pop("at_sender", False) and bool(event.user_id) + at_sender = at_sender and bool(event.user_id) params = {} if event.user_id: