ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2025-10-30 22:46:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

👷 update doc ci

Browse Source
This commit is contained in:
yanyongyu
2021-12-02 03:17:10 +08:00
parent 0236746e65
commit 7d8a60b033
64 changed files with 257 additions and 8378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

574
website/docs/api/adapters/README.md
View File

@@ -1,574 +0,0 @@
# NoneBot.adapters 模块
## 协议适配基类
各协议请继承以下基类，并使用 `driver.register_adapter` 注册适配器
## _class_ `Bot`
基类：`abc.ABC`
Bot 基类。用于处理上报消息，并提供 API 调用接口。
### `driver`
Driver 对象
### `config`
Config 配置对象
### `_calling_api_hook`
* **类型**
`Set[T_CallingAPIHook]`
* **说明**
call_api 时执行的函数
### `_called_api_hook`
* **类型**
`Set[T_CalledAPIHook]`
* **说明**
call_api 后执行的函数
### `__init__(self_id, request)`
* **参数**
* `self_id: str`: 机器人 ID
* `request: HTTPConnection`: request 连接对象
### `self_id`
机器人 ID
### `request`
连接信息
### _abstract property_ `type`
Adapter 类型
### _classmethod_ `register(driver, config, **kwargs)`
* **说明**
`register` 方法会在 `driver.register_adapter` 时被调用，用于初始化相关配置
### _abstract async classmethod_ `check_permission(driver, request)`
* **说明**
检查连接请求是否合法的函数，如果合法则返回当前连接 `唯一标识符`，通常为机器人 ID；如果不合法则抛出 `RequestDenied` 异常。
* **参数**
* `driver: Driver`: Driver 对象
* `request: HTTPConnection`: request 请求详情
* **返回**
* `Optional[str]`: 连接唯一标识符，`None` 代表连接不合法
* `Optional[HTTPResponse]`: HTTP 上报响应
### _abstract async_ `handle_message(message)`
* **说明**
处理上报消息的函数，转换为 `Event` 事件后调用 `nonebot.message.handle_event` 进一步处理事件。
* **参数**
* `message: bytes`: 收到的上报消息
### _abstract async_ `_call_api(api, **data)`
* **说明**
`adapter` 实际调用 api 的逻辑实现函数，实现该方法以调用 api。
* **参数**
* `api: str`: API 名称
* `**data`: API 数据
### _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`
### _classmethod_ `on_calling_api(func)`
* **说明**
调用 api 预处理。
* **参数**
* `bot: Bot`: 当前 bot 对象
* `api: str`: 调用的 api 名称
* `data: Dict[str, Any]`: api 调用的参数字典
### _classmethod_ `on_called_api(func)`
* **说明**
调用 api 后处理。
* **参数**
* `bot: Bot`: 当前 bot 对象
* `exception: Optional[Exception]`: 调用 api 时发生的错误
* `api: str`: 调用的 api 名称
* `data: Dict[str, Any]`: api 调用的参数字典
* `result: Any`: api 调用的返回
## _class_ `MessageSegment`
基类：`Mapping`, `abc.ABC`, `Generic`[`nonebot.adapters._message.TM`]
消息段基类
### `type`
* 类型: `str`
* 说明: 消息段类型
### `data`
* 类型: `Dict[str, Union[str, list]]`
* 说明: 消息段数据
## _class_ `Message`
基类：`List`[`nonebot.adapters._message.TMS`], `abc.ABC`
消息数组
### `__init__(message=None, *args, **kwargs)`
* **参数**
* `message: Union[str, list, dict, MessageSegment, Message, Any]`: 消息内容
### _classmethod_ `template(format_string)`
* **说明**
根据创建消息模板, 用法和 `str.format` 大致相同, 但是可以输出消息对象, 并且支持以 `Message` 对象作为消息模板
并且提供了拓展的格式化控制符, 可以用适用于该消息类型的 `MessageSegment` 的工厂方法创建消息
* **示例**
```python
>>> Message.template("{} {}").format("hello", "world") # 基础演示
Message(MessageSegment(type='text', data={'text': 'hello world'}))
>>> Message.template("{} {}").format(MessageSegment.image("file///..."), "world") # 支持消息段等对象
Message(MessageSegment(type='image', data={'file': 'file///...'}), MessageSegment(type='text', data={'text': 'world'}))
>>> Message.template( # 支持以Message对象作为消息模板
... MessageSegment.text('test {event.user_id}') + MessageSegment.face(233) +
... MessageSegment.text('test {event.message}')).format(event={'user_id':123456, 'message':'hello world'})
Message(MessageSegment(type='text', data={'text': 'test 123456'}),
MessageSegment(type='face', data={'face': 233}),
MessageSegment(type='text', data={'text': 'test hello world'}))
>>> Message.template("{link:image}").format(link='https://...') # 支持拓展格式化控制符
Message(MessageSegment(type='image', data={'file': 'https://...'}))
```
* **参数**
* `format_string: str`: 格式化字符串
* **返回**
* `MessageFormatter[TM]`: 消息格式化器
### `append(obj)`
* **说明**
添加一个消息段到消息数组末尾
* **参数**
* `obj: Union[str, MessageSegment]`: 要添加的消息段
### `extend(obj)`
* **说明**
拼接一个消息数组或多个消息段到消息数组末尾
* **参数**
* `obj: Union[Message, Iterable[MessageSegment]]`: 要添加的消息数组
### `extract_plain_text()`
* **说明**
提取消息内纯文本消息
## _class_ `Event`
基类：`abc.ABC`, `pydantic.main.BaseModel`
Event 基类。提供获取关键信息的方法，其余信息可直接获取。
### _abstract_ `get_type()`
* **说明**
获取事件类型的方法，类型通常为 NoneBot 内置的四种类型。
* **返回**
* `Literal["message", "notice", "request", "meta_event"]`
* 其他自定义 `str`
### _abstract_ `get_event_name()`
* **说明**
获取事件名称的方法。
* **返回**
* `str`
### _abstract_ `get_event_description()`
* **说明**
获取事件描述的方法，通常为事件具体内容。
* **返回**
* `str`
### `get_log_string()`
* **说明**
获取事件日志信息的方法，通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，可以抛出 `NoLogException` 异常。
* **返回**
* `str`
* **异常**
* `NoLogException`
### _abstract_ `get_user_id()`
* **说明**
获取事件主体 id 的方法，通常是用户 id 。
* **返回**
* `str`
### _abstract_ `get_session_id()`
* **说明**
获取会话 id 的方法，用于判断当前事件属于哪一个会话，通常是用户 id、群组 id 组合。
* **返回**
* `str`
### _abstract_ `get_message()`
* **说明**
获取事件消息内容的方法。
* **返回**
* `Message`
### `get_plaintext()`
* **说明**
获取消息纯文本的方法，通常不需要修改，默认通过 `get_message().extract_plain_text` 获取。
* **返回**
* `str`
### _abstract_ `is_tome()`
* **说明**
获取事件是否与机器人有关的方法。
* **返回**
* `bool`
## _class_ `MessageTemplate`
基类：`string.Formatter`, `Generic`[`nonebot.adapters._template.TF`]
消息模板格式化实现类
### `__init__(template, factory=<class 'str'>)`
* **说明**
创建一个模板
* **参数**
* `template: Union[str, Message]`: 模板
* `factory: Union[str, Message]`: 消息构造类型，默认为 str
### `format(*args, **kwargs)`
* **说明**
根据模板和参数生成消息对象

329
website/docs/api/adapters/ding.md
View File

@@ -1,329 +0,0 @@
# NoneBot.adapters.ding 模块
## 钉钉群机器人 协议适配
协议详情请看: [钉钉文档](https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p)
# NoneBot.adapters.ding.config 模块
## _class_ `Config`
钉钉配置类
* **配置项**
* `access_token` / `ding_access_token`: 钉钉令牌
* `secret` / `ding_secret`: 钉钉 HTTP 上报数据签名口令
# NoneBot.adapters.ding.exception 模块
## _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_ `NetworkError`
基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.ding.exception.DingAdapterException`
* **说明**
网络错误。
* **参数**
* `retcode: Optional[int]`: 错误码
## _exception_ `SessionExpired`
基类：`nonebot.adapters.ding.exception.ApiNotAvailable`, `nonebot.adapters.ding.exception.DingAdapterException`
* **说明**
发消息的 session 已经过期。
# NoneBot.adapters.ding.bot 模块
## _class_ `Bot`
基类：[`nonebot.adapters._bot.Bot`](README.md#nonebot.adapters._bot.Bot)
钉钉 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。
### _property_ `type`
* 返回: `"ding"`
### _async classmethod_ `check_permission(driver, request)`
* **说明**
钉钉协议鉴权。参考 [鉴权](https://ding-doc.dingtalk.com/doc#/serverapi2/elzz1p)
### _async_ `call_api(api, event=None, **data)`
* **说明**
调用 钉钉 协议 API
* **参数**
* `api: str`: API 名称
* `event: Optional[MessageEvent]`: Event 对象
* `**data: Any`: API 参数
* **返回**
* `Any`: API 调用返回数据
* **异常**
* `NetworkError`: 网络错误
* `ActionFailed`: API 调用失败
### _async_ `send(event, message, at_sender=False, webhook=None, secret=None, **kwargs)`
* **说明**
根据 `event` 向触发事件的主体发送消息。
* **参数**
* `event: Event`: Event 对象
* `message: Union[str, Message, MessageSegment]`: 要发送的消息
* `at_sender: bool`: 是否 @ 事件主体
* `webhook: Optional[str]`: 该条消息将调用的 webhook 地址。不传则将使用 sessionWebhook，若其也不存在，该条消息不发送，使用自定义 webhook 时注意你设置的安全方式，如加关键词，IP地址，加签等等。
* `secret: Optional[str]`: 如果你使用自定义的 webhook 地址，推荐使用加签方式对消息进行验证，将 机器人安全设置页面，加签一栏下面显示的SEC开头的字符串 传入这个参数即可。
* `**kwargs`: 覆盖默认参数
* **返回**
* `Any`: API 调用返回数据
* **异常**
* `ValueError`: 缺少 `user_id`, `group_id`
* `NetworkError`: 网络错误
* `ActionFailed`: API 调用失败
# NoneBot.adapters.ding.message 模块
## _class_ `MessageSegment`
基类：[`nonebot.adapters._message.MessageSegment`](README.md#nonebot.adapters._message.MessageSegment)[`Message`]
钉钉 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。
### _static_ `atAll()`
@全体
### _static_ `atMobiles(*mobileNumber)`
@指定手机号人员
### _static_ `atDingtalkIds(*dingtalkIds)`
@指定 id，@ 默认会在消息段末尾。
所以你可以在消息中使用 @{senderId} 占位，发送出去之后 @ 就会出现在占位的位置：
``python
message = MessageSegment.text(f"@{event.senderId}，你好")
message += MessageSegment.atDingtalkIds(event.senderId)
``
### _static_ `text(text)`
发送 `text` 类型消息
### _static_ `image(picURL)`
发送 `image` 类型消息
### _static_ `extension(dict_)`
标记 text 文本的 extension 属性，需要与 text 消息段相加。
### _static_ `code(code_language, code)`
发送 code 消息段
### _static_ `markdown(title, text)`
发送 `markdown` 类型消息
### _static_ `actionCardSingleBtn(title, text, singleTitle, singleURL)`
发送 `actionCardSingleBtn` 类型消息
### _static_ `actionCardMultiBtns(title, text, btns, hideAvatar=False, btnOrientation='1')`
发送 `actionCardMultiBtn` 类型消息
* **参数**
* `btnOrientation`: 0：按钮竖直排列 1：按钮横向排列
* `btns`: `[{ "title": title, "actionURL": actionURL }, ...]`
### _static_ `feedCard(links)`
发送 `feedCard` 类型消息
* **参数**
* `links`: `[{ "title": xxx, "messageURL": xxx, "picURL": xxx }, ...]`
## _class_ `Message`
基类：[`nonebot.adapters._message.Message`](README.md#nonebot.adapters._message.Message)[`nonebot.adapters.ding.message.MessageSegment`]
钉钉 协议 Message 适配。
# NoneBot.adapters.ding.event 模块
## _class_ `Event`
基类：[`nonebot.adapters._event.Event`](README.md#nonebot.adapters._event.Event)
钉钉协议事件。各事件字段参考 [钉钉文档](https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p)
## _class_ `ConversationType`
基类：`str`, `enum.Enum`
An enumeration.
## _class_ `MessageEvent`
基类：`nonebot.adapters.ding.event.Event`
消息事件
## _class_ `PrivateMessageEvent`
基类：`nonebot.adapters.ding.event.MessageEvent`
私聊消息事件
## _class_ `GroupMessageEvent`
基类：`nonebot.adapters.ding.event.MessageEvent`
群消息事件

244
website/docs/api/adapters/feishu.md
View File

@@ -1,244 +0,0 @@
# NoneBot.adapters.feishu 模块
# NoneBot.adapters.feishu.config 模块
## _class_ `Config`
飞书配置类
* **配置项**
* `app_id` / `feishu_app_id`: 飞书开放平台后台“凭证与基础信息”处给出的 App ID
* `app_secret` / `feishu_app_secret`: 飞书开放平台后台“凭证与基础信息”处给出的 App Secret
* `encrypt_key` / `feishu_encrypt_key`: 飞书开放平台后台“事件订阅”处设置的 Encrypt Key
* `verification_token` / `feishu_verification_token`: 飞书开放平台后台“事件订阅”处设置的 Verification Token
* `tenant_access_token` / `feishu_tenant_access_token`: 请求飞书 API 后返回的租户密钥
* `is_lark` / `feishu_is_lark`: 是否使用Lark（飞书海外版），默认为 false
# NoneBot.adapters.feishu.exception 模块
## _exception_ `ActionFailed`
基类：[`nonebot.exception.ActionFailed`](../exception.md#nonebot.exception.ActionFailed), `nonebot.adapters.feishu.exception.FeishuAdapterException`
* **说明**
API 请求返回错误信息。
* **参数**
* `retcode: Optional[int]`: 错误码
## _exception_ `NetworkError`
基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.feishu.exception.FeishuAdapterException`
* **说明**
网络错误。
* **参数**
* `retcode: Optional[int]`: 错误码
# NoneBot.adapters.feishu.bot 模块
## `_check_at_me(bot, event)`
* **说明**
检查消息开头或结尾是否存在 @机器人，去除并赋值 `event.reply`, `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._bot.Bot`](README.md#nonebot.adapters._bot.Bot)
飞书 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。
### _async_ `handle_message(message)`
* **说明**
处理事件并转换为 [Event](#class-event)
### _async_ `call_api(api, **data)`
* **说明**
调用 飞书 协议 API
* **参数**
* `api: str`: API 名称
* `**data: Any`: API 参数
* **返回**
* `Any`: API 调用返回数据
* **异常**
* `NetworkError`: 网络错误
* `ActionFailed`: API 调用失败
# NoneBot.adapters.feishu.message 模块
## _class_ `MessageSegment`
基类：[`nonebot.adapters._message.MessageSegment`](README.md#nonebot.adapters._message.MessageSegment)[`Message`]
飞书 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。
## _class_ `Message`
基类：[`nonebot.adapters._message.Message`](README.md#nonebot.adapters._message.Message)[`nonebot.adapters.feishu.message.MessageSegment`]
飞书 协议 Message 适配。
## _class_ `MessageSerializer`
基类：`object`
飞书 协议 Message 序列化器。
## _class_ `MessageDeserializer`
基类：`object`
飞书 协议 Message 反序列化器。
# NoneBot.adapters.feishu.event 模块
## _class_ `Event`
基类：[`nonebot.adapters._event.Event`](README.md#nonebot.adapters._event.Event)
飞书协议事件。各事件字段参考 [飞书文档](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-list)
## `get_event_model(event_name)`
* **说明**
根据事件名获取对应 `Event Model` 及 `FallBack Event Model` 列表
* **返回**
* `List[Type[Event]]`

1896
website/docs/api/adapters/mirai.md
View File

File diff suppressed because it is too large Load Diff