🔖 PreRelease 2.0.0a7

archive/2.0.0a7/api/adapters/README.md

@@ -0,0 +1,362 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.adapters 模块
+
+## 协议适配基类
+
+各协议请继承以下基类，并使用 `driver.register_adapter` 注册适配器
+
+
+## _class_ `BaseBot`
+
+基类：`abc.ABC`
+
+Bot 基类。用于处理上报消息，并提供 API 调用接口。
+
+
+### _abstract_ `__init__(driver, connection_type, config, self_id, *, websocket=None)`
+
+
+* **参数**
+
+    
+    * `driver: Driver`: Driver 对象
+
+
+    * `connection_type: str`: http 或者 websocket
+
+
+    * `config: Config`: Config 对象
+
+
+    * `self_id: str`: 机器人 ID
+
+
+    * `websocket: Optional[WebSocket]`: Websocket 连接对象
+
+
+
+### `driver`
+
+Driver 对象
+
+
+### `connection_type`
+
+连接类型
+
+
+### `config`
+
+Config 配置对象
+
+
+### `self_id`
+
+机器人 ID
+
+
+### `websocket`
+
+Websocket 连接对象
+
+
+### _abstract property_ `type`
+
+Adapter 类型
+
+
+### _abstract async classmethod_ `check_permission(driver, connection_type, headers, body)`
+
+
+* **说明**
+
+    检查连接请求是否合法的函数，如果合法则返回当前连接 `唯一标识符`，通常为机器人 ID；如果不合法则抛出 `RequestDenied` 异常。
+
+
+
+* **参数**
+
+    
+    * `driver: Driver`: Driver 对象
+
+
+    * `connection_type: str`: 连接类型
+
+
+    * `headers: dict`: 请求头
+
+
+    * `body: Optional[dict]`: 请求数据，WebSocket 连接该部分为空
+
+
+
+* **返回**
+
+    
+    * `str`: 连接唯一标识符
+
+
+
+* **异常**
+
+    
+    * `RequestDenied`: 请求非法
+
+
+
+### _abstract async_ `handle_message(message)`
+
+
+* **说明**
+
+    处理上报消息的函数，转换为 `Event` 事件后调用 `nonebot.message.handle_event` 进一步处理事件。
+
+
+
+* **参数**
+
+    
+    * `message: dict`: 收到的上报消息
+
+
+
+### _abstract async_ `call_api(api, **data)`
+
+
+* **说明**
+
+    调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用
+
+
+
+* **参数**
+
+    
+    * `api: str`: API 名称
+
+
+    * `**data`: API 数据
+
+
+
+* **示例**
+
+
+```python
+await bot.call_api("send_msg", message="hello world"})
+await bot.send_msg(message="hello world")
+```
+
+
+### _abstract async_ `send(event, message, **kwargs)`
+
+
+* **说明**
+
+    调用机器人基础发送消息接口
+
+
+
+* **参数**
+
+    
+    * `event: Event`: 上报事件
+
+
+    * `message: Union[str, Message, MessageSegment]`: 要发送的消息
+
+
+    * `**kwargs`
+
+
+
+## _class_ `BaseEvent`
+
+基类：`abc.ABC`, `typing.Generic`
+
+Event 基类。提供上报信息的关键信息，其余信息可从原始上报消息获取。
+
+
+### `__init__(raw_event)`
+
+
+* **参数**
+
+    
+    * `raw_event: Union[dict, T]`: 原始上报消息
+
+
+
+### _property_ `raw_event`
+
+原始上报消息
+
+
+### _abstract property_ `id`
+
+事件 ID
+
+
+### _abstract property_ `name`
+
+事件名称
+
+
+### _abstract property_ `self_id`
+
+机器人 ID
+
+
+### _abstract property_ `time`
+
+事件发生时间
+
+
+### _abstract property_ `type`
+
+事件主类型
+
+
+### _abstract property_ `detail_type`
+
+事件详细类型
+
+
+### _abstract property_ `sub_type`
+
+事件子类型
+
+
+### _abstract property_ `user_id`
+
+触发事件的主体 ID
+
+
+### _abstract property_ `group_id`
+
+触发事件的主体群 ID
+
+
+### _abstract property_ `to_me`
+
+事件是否为发送给机器人的消息
+
+
+### _abstract property_ `message`
+
+消息内容
+
+
+### _abstract property_ `reply`
+
+回复的消息
+
+
+### _abstract property_ `raw_message`
+
+原始消息
+
+
+### _abstract property_ `plain_text`
+
+纯文本消息
+
+
+### _abstract property_ `sender`
+
+消息发送者信息
+
+
+## _class_ `BaseMessageSegment`
+
+基类：`abc.ABC`
+
+消息段基类
+
+
+### `type`
+
+
+* 类型: `str`
+
+
+* 说明: 消息段类型
+
+
+### `data`
+
+
+* 类型: `Dict[str, Union[str, list]]`
+
+
+* 说明: 消息段数据
+
+
+## _class_ `BaseMessage`
+
+基类：`list`, `abc.ABC`
+
+消息数组
+
+
+### `__init__(message=None, *args, **kwargs)`
+
+
+* **参数**
+
+    
+    * `message: Union[str, dict, list, BaseModel, MessageSegment, Message]`: 消息内容
+
+
+
+### `append(obj)`
+
+
+* **说明**
+
+    添加一个消息段到消息数组末尾
+
+
+
+* **参数**
+
+    
+    * `obj: Union[str, MessageSegment]`: 要添加的消息段
+
+
+
+### `extend(obj)`
+
+
+* **说明**
+
+    拼接一个消息数组或多个消息段到消息数组末尾
+
+
+
+* **参数**
+
+    
+    * `obj: Union[Message, Iterable[MessageSegment]]`: 要添加的消息数组
+
+
+
+### `reduce()`
+
+
+* **说明**
+
+    缩减消息数组，即按 MessageSegment 的实现拼接相邻消息段
+
+
+
+### `extract_plain_text()`
+
+
+* **说明**
+
+    提取消息内纯文本消息

archive/2.0.0a7/api/adapters/cqhttp.md

@@ -0,0 +1,442 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.adapters.cqhttp 模块
+
+
+## `escape(s, *, escape_comma=True)`
+
+
+* **说明**
+
+    对字符串进行 CQ 码转义。
+
+
+
+* **参数**
+
+    
+    * `s: str`: 需要转义的字符串
+
+
+    * `escape_comma: bool`: 是否转义逗号（`,`）。
+
+
+
+## `unescape(s)`
+
+
+* **说明**
+
+    对字符串进行 CQ 码去转义。
+
+
+
+* **参数**
+
+    
+    * `s: str`: 需要转义的字符串
+
+
+
+## _exception_ `CQHTTPAdapterException`
+
+基类：[`nonebot.exception.AdapterException`](../exception.md#nonebot.exception.AdapterException)
+
+
+## _exception_ `ActionFailed`
+
+基类：[`nonebot.exception.ActionFailed`](../exception.md#nonebot.exception.ActionFailed), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`
+
+
+* **说明**
+
+    API 请求返回错误信息。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `NetworkError`
+
+基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`
+
+
+* **说明**
+
+    网络错误。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `ApiNotAvailable`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`
+
+
+## _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`](README.md#nonebot.adapters.BaseBot)
+
+CQHTTP 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。
+
+
+### _property_ `type`
+
+
+* 返回: `"cqhttp"`
+
+
+### _async classmethod_ `check_permission(driver, connection_type, headers, body)`
+
+
+* **说明**
+
+    CQHTTP (OneBot) 协议鉴权。参考 [鉴权](https://github.com/howmanybots/onebot/blob/master/v11/specs/communication/authorization.md)
+
+
+
+### _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`](README.md#nonebot.adapters.BaseEvent)
+
+CQHTTP 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent) 。
+
+
+### _property_ `id`
+
+
+* 类型: `Optional[int]`
+
+
+* 说明: 事件/消息 ID
+
+
+### _property_ `name`
+
+
+* 类型: `str`
+
+
+* 说明: 事件名称，由类型与 `.` 组合而成
+
+
+### _property_ `self_id`
+
+
+* 类型: `str`
+
+
+* 说明: 机器人自身 ID
+
+
+### _property_ `time`
+
+
+* 类型: `int`
+
+
+* 说明: 事件发生时间
+
+
+### _property_ `type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件类型
+
+
+### _property_ `detail_type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件详细类型
+
+
+### _property_ `sub_type`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 事件子类型
+
+
+### _property_ `user_id`
+
+
+* 类型: `Optional[int]`
+
+
+* 说明: 事件主体 ID
+
+
+### _property_ `group_id`
+
+
+* 类型: `Optional[int]`
+
+
+* 说明: 事件主体群 ID
+
+
+### _property_ `to_me`
+
+
+* 类型: `Optional[bool]`
+
+
+* 说明: 消息是否与机器人相关
+
+
+### _property_ `message`
+
+
+* 类型: `Optional[Message]`
+
+
+* 说明: 消息内容
+
+
+### _property_ `reply`
+
+
+* 类型: `Optional[dict]`
+
+
+* 说明: 回复消息详情
+
+
+### _property_ `raw_message`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 原始消息
+
+
+### _property_ `plain_text`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 纯文本消息内容
+
+
+### _property_ `sender`
+
+
+* 类型: `Optional[dict]`
+
+
+* 说明: 消息发送者信息
+
+
+## _class_ `MessageSegment`
+
+基类：[`nonebot.adapters.BaseMessageSegment`](README.md#nonebot.adapters.BaseMessageSegment)
+
+CQHTTP 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。
+
+
+## _class_ `Message`
+
+基类：[`nonebot.adapters.BaseMessage`](README.md#nonebot.adapters.BaseMessage)
+
+CQHTTP 协议 Message 适配。

archive/2.0.0a7/api/adapters/ding.md

@@ -0,0 +1,380 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.adapters.ding 模块
+
+
+## _exception_ `DingAdapterException`
+
+基类：[`nonebot.exception.AdapterException`](../exception.md#nonebot.exception.AdapterException)
+
+
+* **说明**
+
+    钉钉 Adapter 错误基类
+
+
+
+## _exception_ `ActionFailed`
+
+基类：[`nonebot.exception.ActionFailed`](../exception.md#nonebot.exception.ActionFailed), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    API 请求返回错误信息。
+
+
+
+* **参数**
+
+    
+    * `errcode: Optional[int]`: 错误码
+
+
+    * `errmsg: Optional[str]`: 错误信息
+
+
+
+## _exception_ `ApiNotAvailable`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+## _exception_ `NetworkError`
+
+基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    网络错误。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `SessionExpired`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    发消息的 session 已经过期。
+
+
+
+## _class_ `Bot`
+
+基类：[`nonebot.adapters.BaseBot`](README.md#nonebot.adapters.BaseBot)
+
+钉钉 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。
+
+
+### _property_ `type`
+
+
+* 返回: `"ding"`
+
+
+### _async classmethod_ `check_permission(driver, connection_type, headers, body)`
+
+
+* **说明**
+
+    钉钉协议鉴权。参考 [鉴权](https://ding-doc.dingtalk.com/doc#/serverapi2/elzz1p)
+
+
+
+### _async_ `handle_message(body)`
+
+
+* **说明**
+
+    处理上报消息的函数，转换为 `Event` 事件后调用 `nonebot.message.handle_event` 进一步处理事件。
+
+
+
+* **参数**
+
+    
+    * `message: dict`: 收到的上报消息
+
+
+
+### _async_ `call_api(api, event=None, **data)`
+
+
+* **说明**
+
+    调用 钉钉 协议 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`](README.md#nonebot.adapters.BaseEvent)
+
+钉钉 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent) 。
+
+
+### _property_ `raw_event`
+
+原始上报消息
+
+
+### _property_ `id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 消息 ID
+
+
+### _property_ `name`
+
+
+* 类型: `str`
+
+
+* 说明: 事件名称，由 type.\`detail_type\` 组合而成
+
+
+### _property_ `self_id`
+
+
+* 类型: `str`
+
+
+* 说明: 机器人自身 ID
+
+
+### _property_ `time`
+
+
+* 类型: `int`
+
+
+* 说明: 消息的时间戳，单位 s
+
+
+### _property_ `type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件类型
+
+
+### _property_ `detail_type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件详细类型
+
+
+### _property_ `sub_type`
+
+
+* 类型: `None`
+
+
+* 说明: 钉钉适配器无事件子类型
+
+
+### _property_ `user_id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 发送者 ID
+
+
+### _property_ `group_id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 事件主体群 ID
+
+
+### _property_ `to_me`
+
+
+* 类型: `Optional[bool]`
+
+
+* 说明: 消息是否与机器人相关
+
+
+### _property_ `message`
+
+
+* 类型: `Optional[Message]`
+
+
+* 说明: 消息内容
+
+
+### _property_ `reply`
+
+
+* 类型: `None`
+
+
+* 说明: 回复消息详情
+
+
+### _property_ `raw_message`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 原始消息
+
+
+### _property_ `plain_text`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 纯文本消息内容
+
+
+### _property_ `sender`
+
+
+* 类型: `Optional[dict]`
+
+
+* 说明: 消息发送者信息
+
+
+## _class_ `MessageSegment`
+
+基类：[`nonebot.adapters.BaseMessageSegment`](README.md#nonebot.adapters.BaseMessageSegment)
+
+钉钉 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。
+
+
+### _static_ `actionCardSingleMultiBtns(title, text, btns=[], hideAvatar=False, btnOrientation='1')`
+
+
+* **参数**
+
+    
+    * `btnOrientation`: 0：按钮竖直排列 1：按钮横向排列
+
+
+    * `btns`: [{ "title": title, "actionURL": actionURL }, ...]
+
+
+
+### _static_ `feedCard(links=[])`
+
+
+* **参数**
+
+    
+    * `links`: [{ "title": xxx, "messageURL": xxx, "picURL": xxx }, ...]
+
+
+
+### _static_ `empty()`
+
+不想回复消息到群里
+
+
+## _class_ `Message`
+
+基类：[`nonebot.adapters.BaseMessage`](README.md#nonebot.adapters.BaseMessage)
+
+钉钉 协议 Message 适配。