ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2025-07-28 08:41:29 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

🔀 Merge pull request #790

Browse Source 
Release: 2.0.0-beta.2
This commit is contained in:
Ju4tCode
2022-02-14 23:55:05 +08:00
committed by GitHub
parent 80bf73e0e9 6ceaf51af7
commit 803223f31c
213 changed files with 9246 additions and 14264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
website/babel.config.js
View File

@ -1,3 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
};

18
website/docs/README.md
View File

@ -8,7 +8,7 @@ slug: /
NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架，它基于 Python 的类型注解和异步特性，能够为你的需求实现提供便捷灵活的支持。
需要注意的是，NoneBot 仅支持 **Python 3.7.3 以上版本**
需要注意的是，NoneBot2 仅支持 **Python 3.7.3 以上版本**
## 特色
@ -18,15 +18,15 @@ NoneBot2 基于 Python [asyncio](https://docs.python.org/3/library/asyncio.html)
### 完整的类型注解
NoneBot2 参考 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 等 PEP 完整实现了类型注解，通过 `pyright`/`pylance` 检查。配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](./start/editor-support))。
NoneBot2 参考 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 等 PEP 完整实现了类型注解，通过 `pyright`/`pylance` 检查。配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中（[编辑器支持](./start/editor-support)）。
### 开箱即用
NoneBot2 提供了使用便捷、具有交互式功能的命令行工具 -- `nb-cli`，使得初次接触 NoneBot 时更容易上手。详细使用方法请参考各文档章节以及 [使用脚手架](./start/nb-cli)。
NoneBot2 提供了使用便捷、具有交互式功能的命令行工具--`nb-cli`，使得初次接触 NoneBot2 时更容易上手。详细使用方法请参考各文档章节以及[使用脚手架](./start/nb-cli)。
### 插件系统
插件系统是 NoneBot 的核心，通过它可以实现机器人的模块化以及功能扩展，便于维护和管理。
插件系统是 NoneBot2 的核心，通过它可以实现机器人的模块化以及功能扩展，便于维护和管理。
### 依赖注入系统
@ -34,15 +34,15 @@ NoneBot2 采用了一套自行定义的依赖注入系统，可以让事件的
#### 什么是依赖注入
[**"依赖注入"**](https://zh.m.wikipedia.org/wiki/%E6%8E%A7%E5%88%B6%E5%8F%8D%E8%BD%AC)意思是，在编程中，有一种方法可以让你的代码声明它工作和使用所需要的东西, 即"**依赖**"。
[**“依赖注入”**](https://zh.m.wikipedia.org/wiki/%E6%8E%A7%E5%88%B6%E5%8F%8D%E8%BD%AC)意思是，在编程中，有一种方法可以让你的代码声明它工作和使用所需要的东西，即**“依赖”**。
系统 (在这里是指 `NoneBot` ) 将负责做任何需要的事情，为你的代码提供这些必要依赖 (即"**注入**"依赖性)
系统（在这里是指 NoneBot2）将负责做任何需要的事情，为你的代码提供这些必要依赖（即**“注入”**依赖性）
这在你有以下情形的需求时非常有用:
这在你有以下情形的需求时非常有用：
- 这部分代码拥有共享的逻辑(同样的代码逻辑多次重复)
- 这部分代码拥有共享的逻辑（同样的代码逻辑多次重复）
- 共享数据库以及网络请求连接会话
- 比如 `httpx.AsyncClient`, `aiohttp.ClientSession` 和 `sqlalchemy.Session`
- 比如 `httpx.AsyncClient`、`aiohttp.ClientSession` 和 `sqlalchemy.Session`
- 用户权限检查以及认证
- 还有更多...

173
website/docs/advanced/README.md
View File

@ -1,6 +1,6 @@
---
id: index
slug: /advanced
slug: /advanced/
options:
menu:
@ -16,33 +16,33 @@ options:
## 它如何工作？
如同[概览](../README.md)所言:
如同[概览](../README.md)所言：
> NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的事件进行解析和处理，并以插件化的形式，按优先级分发给事件所对应的事件响应器，来完成具体的功能。
`Nonebot2` 是一个可以对机器人上报的事件进行处理并完成具体功能的机器人框架，在这里，我们将简要讲述它的工作内容。
NoneBot2 是一个可以对机器人上报的事件进行处理并完成具体功能的机器人框架，在这里，我们将简要讲述它的工作内容。
**便捷起见，以下内容对 `Nonebot2` 会被称为 `nonebot`，与 `Nonebot2` 交互的机器人实现会被称为 `协议端`**。
**便捷起见，以下内容对 NoneBot2 会被称为 NoneBot，与 NoneBot2 交互的机器人实现会被称为协议端**。
在实际应用中，`nonebot` 会充当一个高性能，轻量级的 Python 微服务框架。协议端可以通过 `http`, `websocket` 等方式与之通信，这个通信往往是双向的：一方面，协议端可以上报数据给 `nonebot`，`nonebot` 会处理数据并返回响应给协议端；另一方面，`nonebot` 可以主动推送数据给协议端。而 `nonebot` 便是围绕双向通信进行工作的。
在实际应用中，NoneBot 会充当一个高性能，轻量级的 Python 微服务框架。协议端可以通过 http、websocket 等方式与之通信，这个通信往往是双向的：一方面，协议端可以上报数据给 NoneBot，NoneBot 会处理数据并返回响应给协议端；另一方面，NoneBot 可以主动推送数据给协议端。而 NoneBot 便是围绕双向通信进行工作的。
在开始工作之前，`nonebot` 需要进行准备工作：
在开始工作之前，NoneBot 需要进行准备工作：
1. **运行 `nonebot.init` 初始化函数**，它会读取配置文件，并初始化 `nonebot` 和后端驱动 `driver` 对象。
2. **注册协议适配器 `adapter`** 。
1. **运行 `nonebot.init` 初始化函数**，它会读取配置文件，并初始化 NoneBot 和后端驱动 `Driver` 对象。
2. **注册协议适配器 `Adapter`**。
3. **加载插件**。
准备工作完成后，`nonebot` 会利用 `uvicorn` 启动，并运行 `on_startup` 钩子函数。
准备工作完成后，NoneBot 会利用 uvicorn 启动，并运行 `on_startup` 钩子函数。
随后，倘若一个协议端与 `nonebot` 进行了连接，`nonebot` 的后端驱动 `driver` 就会将 `adapter` 实例化为 `bot`，`nonebot` 便会利用 `bot` 开始工作，它的工作内容分为两个方面：
随后，倘若一个协议端与 NoneBot 进行了连接，NoneBot 的后端驱动 `Driver` 就会将数据交给 `Adapter`，然后会实例化 `Bot`，NoneBot 便会利用 `Bot` 开始工作，它的工作内容分为两个方面：
1. **事件处理**，`bot` 会将协议端上报的数据转化为 `事件`(`Event`)，之后 `nonebot` 会根据一套既定流程来处理 `事件`。
1. **事件处理**，`Bot` 会将协议端上报的数据转化为 `Event`（事件），之后 NoneBot 会根据一套既定流程来处理事件。
2. **调用 `API`**, 在**事件处理**的过程中，`nonebot` 可以通过 `bot` 调用协议端指定的 `API` 来获取更多数据，或者反馈响应给协议端; `nonebot` 也可以通过调用 `API` 向协议端主动请求数据或者主动推送数据。
2. **调用 `API`**，在**事件处理**的过程中，NoneBot 可以通过 `Bot` 调用协议端指定的 `API` 来获取更多数据，或者反馈响应给协议端；NoneBot 也可以通过调用 `API` 向协议端主动请求数据或者主动推送数据。
在**指南**模块， 我们已经叙述了[如何配置 nonebot](../tutorial/configuration.md), [如何注册协议适配器](../tutorial/register-adapter.md)，[如何加载插件](../tutorial/plugin/load-plugin.md), 在这里便不再赘述。
在**指南**模块，我们已经叙述了[如何配置 NoneBot](../tutorial/configuration.md)、[如何注册协议适配器](../tutorial/register-adapter.md)以及[如何加载插件](../tutorial/plugin/load-plugin.md)，这里便不再赘述。
下面，我们将对**事件处理**， **调用 API**进行说明。
下面，我们将对**事件处理**，**调用 API** 进行说明。
## 事件处理
@ -50,143 +50,156 @@ options:
![handle-event](./images/Handle-Event.png)
在流程图里，我们可以看到，`nonebot` 会有三个阶段来处理事件：
在流程图里，我们可以看到，NoneBot 会有三个阶段来处理事件：
1. **driver 处理上报数据**
2. **adapter 处理原始数据**
3. **nonebot 处理 Event**
1. **Driver 接收上报数据**
2. **Adapter 处理原始数据**
3. **NoneBot 处理 Event**
我们将顺序说明这三个阶段。其中，会将第三个阶段拆分成**概念解释**，**处理 Event**，**特殊异常处理**三个部分来说明。
### driver 处理上报数据
### Driver 接收上报数据
1. 协议端会通过 `websocket` 或者 `http` 等方式与 `nonebot` 的后端驱动 `driver` 连接，`driver` 会根据之前注册的 `adapter` 和配置文件的内容来进行鉴权，从而获得这个连接的唯一识别 id `self-id`，随后 `adapter` 就会利用 `self-id` 实例化为 `bot` 对象。
1. 协议端会通过 websocket 或 http 等方式与 NoneBot 的后端驱动 `Driver` 连接，协议端上报数据后，`Driver` 会将原始数据交给 `Adapter` 处理。
::: tip
需要注意的是，如果协议端通过 `websocket` 与 `nonebot` 连接，这个步骤只会在建立连接时进行，并在之后运行 `on_bot_connect` 钩子函数；通过 `http` 方式连接时，会在协议端每次上报数据时都进行这个步骤。
:::
:::warning
连接之前必须要注册 `Adapter`
:::
::: warning
连接之前必须要注册 `adapter`
:::
### Adapter 处理原始数据
::: warning
`self-id` 是帐号的唯一识别 ID，这意味着不能出现相同的 `self-id`。
:::
1. `Adapter` 检查授权许可，并获取 `self-id` 作为唯一识别 id 。
2. `driver` 会将接收到的数据转交给 `bot` 对象进一步处理。
:::tip
如果协议端通过 websocket 上报数据，这个步骤只会在建立连接时进行，并在之后运行 `on_bot_connect` 钩子函数；通过 http 方式连接时，会在协议端每次上报数据时都进行这个步骤。
:::
### adapter 处理原始数据
:::warning
`self-id` 是帐号的唯一识别 ID ，这意味着不能出现相同的 `self-id`。
:::
1. `bot` 会利用事先定义好的 `Event Model` 对上报的数据进行分析处理，将数据转化为 `nonebot` 可以处理的 `Event` 对象。
2. 根据 `self-id` 实例化 `Adapter` 相应的 `Bot` 。
::: tip
`adapter` 在转换数据格式的同时可以进行一系列的特殊操作，例如 `CQHTTP` 会对 `reply` 信息进行提取。
:::
3. 根据 `Event Model` 将原始数据转化为 NoneBot 可以处理的 `Event` 对象。
2. `Event` 会传入 `nonebot` 做进一步处理。
:::tip
`Adapter` 在转换数据格式的同时可以进行一系列的特殊操作，例如 OneBot 适配器会对 reply 信息进行提取。
:::
### nonebot 处理 Event
4. `Bot` 和 `Event` 交由 NoneBot 进一步处理。
### NoneBot 处理 Event
在讲述这个阶段之前，我们需要先对几个概念进行解释。
#### 概念解释
1. **hook**，或者说**钩子函数**，它们可以在 `nonebot` 处理 `Event` 的不同时刻进行拦截，修改或者扩展，在 `nonebot` 中，钩子函数分为 `事件预处理hook`，`运行预处理hook`，`运行后处理hook` 和 `事件后处理hook`。
1. **hook** ，或者说**钩子函数**，它们可以在 NoneBot 处理 `Event` 的不同时刻进行拦截，修改或者扩展，在 NoneBot 中，事件钩子函数分为`事件预处理 hook`、`运行预处理 hook`、`运行后处理 hook` 和`事件后处理 hook`。
::: tip
关于`hook`的更多信息，可以查阅[这里](./runtime-hook.md)
:::
:::tip
关于 `hook` 的更多信息，可以查阅[这里](./runtime-hook.md)。
:::
2. **Matcher**与**matcher**，在**指南**中，我们讲述了[如何注册事件响应器](../tutorial/plugin/create-matcher.md)，这里的事件响应器或者说 `Matcher` 并不是一个具体的实例 `instance`，而是一个具有特定属性的类 `class`。只有当 `Matcher` **响应事件**时，才会实例化为具体的 `instance`，也就是 `matcher`。`matcher` 可以认为是 `nonebot` 处理 `Event` 的基本单位，运行 `matcher` 是`nonebot`工作的主要内容。
2. **Matcher** 与 **matcher**，在**指南**中，我们讲述了[如何注册事件响应器](../tutorial/plugin/create-matcher.md)，这里的事件响应器或者说 `Matcher` 并不是一个具体的实例 `instance`，而是一个具有特定属性的类 `class`。只有当 `Matcher` **响应事件**时，才会实例化为具体的 `instance`，也就是 `matcher` 。`matcher` 可以认为是 NoneBot 处理 `Event` 的基本单位，运行 `matcher` 是 NoneBot 工作的主要内容。
3. **handler**，或者说**事件处理函数**, 它们可以认为是 `nonebot` 处理 `Event` 的最小单位。在不考虑 `hook` 的情况下，**运行 matcher 就是顺序运行 matcher.handlers**，这句话换种表达方式就是，`handler` 只有添加到 `matcher.handlers` 时，才可以参与到 `nonebot` 的工作中来。
3. **handler**，或者说**事件处理函数**，它们可以认为是 NoneBot 处理 `Event` 的最小单位。在不考虑 `hook` 的情况下，**运行 matcher 就是顺序运行 matcher.handlers**，这句话换种表达方式就是，`handler` 只有添加到 `matcher.handlers` 时，才可以参与到 NoneBot 的工作中来。
::: tip
如何让 `handler` 添加到 `matcher.handlers`？
:::tip
如何让 `handler` 添加到 `matcher.handlers`？
一方面，我们可以参照[这里](../tutorial/plugin/create-handler.md)利用装饰器来添加；另一方面，我们在用 `on()` 或者 `on_*()` 注册事件响应器时，可以添加 `handlers=[handler1, handler2, ...]` 这样的关键词参数来添加。
:::
一方面，我们可以参照[这里](../tutorial/plugin/create-handler.md)利用装饰器来添加；另一方面，我们在用 `on()` 或者 `on_*()` 注册事件响应器时，可以添加 `handlers=[handler1, handler2, ...]` 这样的关键词参数来添加。
:::
#### 处理 Event
1. **执行事件预处理 hook**， `nonebot` 接收到 `Event` 后，会传入到 `事件预处理hook` 中进行处理。
1. **执行事件预处理 hook**， NoneBot 接收到 `Event` 后，会传入到 `事件预处理 hook` 中进行处理。
::: warning
需要注意的是，执行多个 `事件预处理hook` 时并无顺序可言，它们是**并行运行**的。这个原则同样适用于其他的 `hook`。
:::
:::warning
需要注意的是，执行多个 `事件预处理 hook` 时并无顺序可言，它们是**并发运行**的。这个原则同样适用于其他的 `hook`。
:::
2. **按优先级升序选出同一优先级的 Matcher**，`nonebot` 提供了一个全局字典 `matchers`，这个字典的 `key` 是优先级 `priority`，`value` 是一个 `list`，里面存放着同一优先级的 `Matcher`。在注册 `Matcher` 时，它和优先级 `priority` 会添加到里面。
2. **按优先级升序选出同一优先级的 Matcher**，NoneBot 提供了一个全局字典 `matchers`，这个字典的 `key` 是优先级 `priority`，`value` 是一个 `list`，里面存放着同一优先级的 `Matcher`。在注册 `Matcher` 时，它和优先级 `priority` 会添加到里面。
在执行 `事件预处理hook` 后，`nonebot` 会对 `matchers` 的 `key` 升序排序并选择出当前最小优先级的 `Matcher`。
在执行 `事件预处理 hook` 后，NoneBot 会对 `matchers` 的 `key` 升序排序并选择出当前最小优先级的 `Matcher`。
3. **根据 Matcher 定义的 Rule, Permission 判断是否运行**，在选出 `Matcher` 后，`nonebot` 会将 `bot`，`Event` 传入到 `Matcher.check_rule` 和 `Matcher.check_perm` 两个函数中，两个函数分别对 Matcher 定义的 Rule, Permission 进行 check，当 check 通过后，这个 `Matcher` 就会响应事件。但是当同一个优先级的所有 `Matcher` 均没有响应时，`nonebot` 会返回到上一个步骤，选择出下一优先级的 `Matcher`。
3. **根据 Matcher 定义的 Rule、Permission 判断是否运行**，在选出 `Matcher` 后，NoneBot 会将 `bot`，`Event` 传入到 `Matcher.check_rule` 和 `Matcher.check_perm` 两个函数中，两个函数分别对 Matcher 定义的 `Rule`、`Permission` 进行 check，当 check 通过后，这个 `Matcher` 就会响应事件。当同一个优先级的所有 `Matcher` 均没有响应时，NoneBot 会返回到上一个步骤，选择出下一优先级的 `Matcher`。
4. **实例化 matcher 并执行运行预处理 hook**，当 `Matcher` 响应事件后，它便会实例化为 `matcher`，并执行 `运行预处理hook`。
4. **实例化 matcher 并执行运行预处理 hook**，当 `Matcher` 响应事件后，它便会实例化为 `matcher`，并执行 `运行预处理 hook`。
5. **顺序运行 matcher 的所有 handlers**，`运行预处理hook` 执行完毕后，便会运行 `matcher`，也就是**顺序运行**它的 `handlers`。
5. **顺序运行 matcher 的所有 handlers**，`运行预处理 hook` 执行完毕后，便会运行 `matcher`，也就是**顺序运行**它的 `handlers`。
::: tip
`matcher` 运行 `handlers` 的顺序是: 先运行该 `matcher` 的类 `Matcher` 注册时添加的 `handlers`(如果有的话)，再按照装饰器装饰顺序运行装饰的 `handlers`。
:::
:::tip
`matcher` 运行 `handlers` 的顺序是：先运行该 `matcher` 的类 `Matcher` 注册时添加的 `handlers`(如果有的话)，再按照装饰器装饰顺序运行装饰的 `handlers`。
:::
6. **执行运行后处理 hook**，`matcher` 的 `handlers` 运行完毕后，会执行 `运行后处理hook`。
6. **执行运行后处理 hook**，`matcher` 的 `handlers` 运行完毕后，会执行 `运行后处理 hook`。
7. **判断是否停止事件传播**，`nonebot` 会根据当前优先级所有 `matcher` 的 `block` 参数或者 `StopPropagation` 异常判断是否停止传播 `Event`，如果事件没有停止传播，`nonebot` 便会返回到第 2 步， 选择出下一优先级的 `Matcher`。
7. **判断是否停止事件传播**，NoneBot 会根据当前优先级所有 `matcher` 的 `block` 参数或者 `StopPropagation` 异常判断是否停止传播 `Event`，如果事件没有停止传播，NoneBot 便会返回到第 2 步， 选择出下一优先级的 `Matcher`。
8. **执行事件后处理 hook**，在 `Event` 停止传播或执行完所有响应的 `Matcher` 后，`nonebot` 会执行 `事件后处理hook`。
8. **执行事件后处理 hook**，在 `Event` 停止传播或执行完所有响应的 `Matcher` 后，NoneBot 会执行 `事件后处理 hook`。
当 `事件后处理hook` 执行完毕后，当前`Event`的处理周期就顺利结束了。
当 `事件后处理 hook` 执行完毕后，当前 `Event` 的处理周期就顺利结束了。
#### 特殊异常处理
在这个阶段，`nonebot` 规定了几个特殊的异常，当 `nonebot` 捕获到它们时，会用特定的行为来处理它们。
在这个阶段，NoneBot 规定了几个特殊的异常，当 NoneBot 捕获到它们时，会用特定的行为来处理它们。
1. **IgnoredException**
这个异常可以在 `事件预处理hook` 和 `运行预处理hook` 抛出。
这个异常可以在 `事件预处理 hook` 和 `运行预处理 hook` 抛出。
当 `事件预处理hook` 抛出它时，`nonebot` 会忽略当前的 `Event`，不进行处理。
当 `事件预处理 hook` 抛出它时，NoneBot 会忽略当前的 `Event`，不进行处理。
当 `运行预处理hook` 抛出它时，`nonebot` 会忽略当前的 `matcher`，结束当前 `matcher` 的运行。
当 `运行预处理 hook` 抛出它时，NoneBot 会忽略当前的 `matcher`，结束当前 `matcher` 的运行。
::: warning
当 `hook` 需要抛出这个异常时，要写明原因。
:::
:::warning
当 `hook` 需要抛出这个异常时，要写明原因。
:::
2. **PausedException**
这个异常可以在 `handler` 中由 `Matcher.pause` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将后续的 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行后续的 handlers。
当 NoneBot 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将后续的 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行后续的 `handler`。
3. **RejectedException**
这个异常可以在 `handler` 中由 `Matcher.reject` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将当前 handler 和后续 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行当前 `handler` 和后续的 `handler`。
当 NoneBot 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将当前 handler 和后续 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行当前 `handler` 和后续的 `handler` 。
4. **FinishedException**
这个异常可以在 `handler` 中由 `Matcher.finish` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行。
当 NoneBot 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行。
5. **StopPropagation**
这个异常一般会在执行 `运行后处理hook` 后抛出。
这个异常一般会在执行 `运行后处理 hook` 后抛出。
当 `nonebot` 捕获到它时， 会停止传播当前 `Event`，不再寻找下一优先级的 `Matcher`，直接执行 `事件后处理hook`。
当 NoneBot 捕获到它时， 会停止传播当前 `Event` ，不再寻找下一优先级的 `Matcher` ，直接执行 `事件后处理 hook` 。
## 调用 API
`nonebot` 可以通过 `bot` 来调用 `API` ，`API` 可以向协议端发送数据，也可以向协议端请求更多的数据。
NoneBot 可以通过 `bot` 来调用 `API`，`API` 可以向协议端发送数据，也可以向协议端请求更多的数据。
::: tip
NoneBot 调用 `API` 会有如下过程：
1. 调用 `calling_api_hook` 预处理钩子。
2. `adapter` 将信息处理为原始数据，并转交 `driver`，`driver` 交给协议端处理。
3. `driver` 接收协议端的结果，交给`adapter` 处理之后将结果反馈给 NoneBot 。
4. 调用 `called_api_hook` 后处理钩子。
在调用 `API` 时同样规定了特殊的异常，叫做 `MockApiException` 。该异常会由预处理钩子和后处理钩子触发，当预处理钩子触发时，NoneBot 会跳过之后的调用过程，直接执行后处理钩子。
:::tip
不同 `adapter` 规定了不同的 API，对应的 API 列表请参照协议规范。
:::
一般来说，我们可以用 `bot.*` 来调用 `API`(\*是 `API` 的 `action` 或者 `endpoint`)。
一般来说，我们可以用 `bot.*` 来调用 `API`（\*是 `API` 的 `action` 或者 `endpoint`）。
对于发送消息而言，一方面可以调用既有的 API；另一方面 `nonebot` 实现了两个便捷方法，`bot.send(event, message, **kwargs)` 方法和可以在 `handler` 中使用的 `Matcher.send(message, **kwargs)` 方法，来向事件主体发送消息。
对于发送消息而言，一方面可以调用既有的 `API` ；另一方面 NoneBot 实现了两个便捷方法，`bot.send(event, message, **kwargs)` 方法和可以在 `handler` 中使用的 `Matcher.send(message, **kwargs)` 方法，来向事件主体发送消息。

262
website/docs/advanced/di/dependency-injection.md
View File

@ -10,91 +10,85 @@ options:
# 简介
受 [`FastApi`](https://fastapi.tiangolo.com/tutorial/dependencies/) 启发，NoneBot 同样编写了一个简易的依赖注入模块，使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。
受 [FastAPI](https://fastapi.tiangolo.com/tutorial/dependencies/) 启发，NoneBot 同样编写了一个简易的依赖注入模块，使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。
## 什么是依赖注入？
~~交给 mix 了~~
[依赖注入](https://zh.wikipedia.org/wiki/%E4%BE%9D%E8%B5%96%E6%B3%A8%E5%85%A5)
> 在软件工程中，**依赖注入**（dependency injection）的意思为，给予调用方它所需要的事物。 “依赖”是指可被方法调用的事物。依赖注入形式下，调用方不再直接使用“依赖”，取而代之是“注入” 。“注入”是指将“依赖”传递给调用方的过程。在“注入”之后，调用方才会调用该“依赖。 传递依赖给调用方，而不是让让调用方直接获得依赖，这个是该设计的根本需求。
依赖注入往往起到了分离依赖和调用方的作用，这样一方面能让代码更为整洁可读，一方面可以提升代码的复用性。
## 使用依赖注入
以下通过一个简单的例子来说明依赖注入的使用方法：
### 编写依赖函数
这里我们编写了一个简单的函数 `depend` 作为依赖函数
```python {7-9}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
```python {2,7-8,11}
from nonebot import on_command
from nonebot.params import Depends # 1.引用 Depends
from nonebot.adapters.onebot.v11 import MessageEvent
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
async def depend(event: MessageEvent): # 2.编写依赖函数
return {"uid": event.get_user_id(), "nickname": event.sender.nickname}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
async def _(x: dict = Depends(depend)): # 3.在事件处理函数里声明依赖项
print(x["uid"], x["nickname"])
```
它和普通的事件处理函数并无区别，同样可以接受 `bot`, `event` 等参数，你可以把它当作一个普通的事件处理函数但是去除了装饰器（并没有使用 `matcher.handle()` 等来进行装饰），并且它可以返回任何类型的值。
如注释所言，可以用三步来说明依赖注入的使用过程：
在这个例子中，依赖函数接受一个参数：
1. 引用 `Depends` 。
- `state: dict`：当前事件处理状态字典。
2. 编写依赖函数。依赖函数和普通的事件处理函数并无区别，同样可以接收 `bot`, `event`, `state` 等参数，你可以把它当作一个普通的事件处理函数，但是去除了装饰器（没有使用 `matcher.handle()` 等来装饰），并且可以返回任何类型的值。
并且返回了一个 `state` 的复制以及一个附加的键值 `depend` 。
在这里我们接受了 `event`，并以 `onebot` 的 `MessageEvent` 作为类型标注，返回一个新的字典，包括 `uid` 和 `nickname` 两个键值。
### Import `Depends`
```python {2}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
```
### 在事件处理函数里声明依赖函数
与 FastAPI 类似，你可以在函数中添加一个新的参数，并且使用 `Depends` 来声明它的依赖。
```python {12}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
```
你需要给 `Depends` 指定一个依赖函数，这个依赖函数的返回值会被作为 `x` 的值。
`Depends` 的首个参数即是依赖函数，或者其他 `Callable` 对象，在之后会对更多形式的依赖对象进行介绍。
3. 在事件处理函数中声明依赖项。依赖项必须要 `Depends` 包裹依赖函数作为默认值。
:::tip
参数 `x` 的类型标注并不会影响事件处理函数的运行，类型检查并不会对依赖函数的返回值以及类型标注进行检查。
请注意，参数 `x` 的类型标注将会影响到事件处理函数的运行，与类型标注不符的值将会导致事件处理函数被跳过。
:::
当接收到事件时，NoneBot 会进行以下处理：
:::tip
事实上，bot、event、state 它们本身只是依赖注入的一个特例，它们无需声明这是依赖即可注入。
:::
虽然声明依赖项的方式和其他参数如 `bot`, `event` 并无二样，但他的参数有一些限制，必须是**可调用对象**，函数自然是可调用对象，类和生成器也是，我们会在接下来的小节说明。
一般来说，当接收到事件时，`NoneBot2` 会进行以下处理：
1. 准备依赖函数所需要的参数。
2. 调用依赖函数并获得返回值。
3. 将返回值作为事件处理函数中的参数值传入。
## 依赖缓存
在使用 `Depends` 包裹依赖函数时，有一个参数 `use_cache` ，它默认为 `True` ，这个参数会决定 `Nonebot2` 在依赖注入的处理中是否使用缓存。
```python {11}
import random
from nonebot import on_command
from nonebot.params import Depends
test = on_command("123")
async def always_run():
return random.randint(1, 100)
@test.handle()
async def _(x: int = Depends(always_run, use_cache=False)):
print(x)
```
:::tip
缓存是针对单次事件处理来说的，在事件处理中 `Depends` 第一次被调用时，结果存入缓存，在之后都会直接返回缓存中的值，在事件处理结束后缓存就会被清除。
:::
当使用缓存时，依赖注入会这样处理：
1. 查询缓存，如果缓存中有相应的值，则直接返回。
2. 准备依赖函数所需要的参数。
@ -102,8 +96,148 @@ async def _(x: dict = Depends(depend)):
4. 将返回值存入缓存。
5. 将返回值作为事件处理函数中的参数值传入。
## 依赖缓存
## 同步支持
我们在编写依赖函数时，可以简单地用同步函数，`NoneBot2` 的内部流程会进行处理：
```python {2,8-9,12}
from nonebot.log import logger
from nonebot.params import Depends # 1.引用 Depends
from nonebot import on_command, on_message
from nonebot.adapters.onebot.v11 import MessageEvent
test = on_command("123")
def depend(event: MessageEvent): # 2.编写同步依赖函数
return {"uid": event.get_user_id(), "nickname": event.sender.nickname}
@test.handle()
async def _(x: dict = Depends(depend)): # 3.在事件处理函数里声明依赖项
print(x["uid"], x["nickname"])
```
## Class 作为依赖
## Generator 作为依赖
我们可以看下面的代码段：
```python
class A:
def __init__(self):
pass
a = A()
```
在我们实例化类 `A` 的时候，其实我们就在**调用**它，类本身也是一个**可调用对象**，所以类可以被 `Depends` 包裹成为依赖项。
因此我们对第一节的代码段做一下改造：
```python {2,7-10,13}
from nonebot import on_command
from nonebot.params import Depends # 1.引用 Depends
from nonebot.adapters.onebot.v11 import MessageEvent
test = on_command("123")
class DependClass: # 2.编写依赖类
def __init__(self, event: MessageEvent):
self.uid = event.get_user_id()
self.nickname = event.sender.nickname
@test.handle()
async def _(x: DependClass = Depends(DependClass)): # 3.在事件处理函数里声明依赖项
print(x.uid, x.nickname)
```
依然可以用三步说明如何用类作为依赖项：
1. 引用 `Depends` 。
2. 编写依赖类。类的 `__init__` 函数可以接收 `bot`, `event`, `state` 等参数，在这里我们接受了 `event`，并以 `onebot` 的 `MessageEvent` 作为类型标注。
3. 在事件处理函数中声明依赖项。当用类作为依赖项时，它会是一个对应的实例，在这里 `x` 就是 `DependClass` 实例。
### 另一种依赖项声明方式
当使用类作为依赖项时，`Depends` 的参数可以为空，`NoneBot2` 会根据参数的类型标注进行推断并进行依赖注入。
```python
@test.handle()
async def _(x: DependClass = Depends()): # 在事件处理函数里声明依赖项
print(x.uid, x.nickname)
```
## 生成器作为依赖
:::warning
`yield` 语句只能写一次，否则会引发异常。
如果对此有疑问并想探究原因，可以看 [contextmanager](https://docs.python.org/zh-cn/3/library/contextlib.html#contextlib.contextmanager) 和 [asynccontextmanager](https://docs.python.org/zh-cn/3/library/contextlib.html#contextlib.asynccontextmanager) 文档，实际上，`Nonebot2` 的内部就使用了这两个装饰器。
:::
:::tips
生成器是 `Python` 高级特性，如果你对此处文档感到疑惑那说明暂时你还用不上这个功能。
:::
与 `FastAPI` 一样，`NoneBot2` 的依赖注入支持依赖项在事件处理结束后进行一些额外的工作，比如数据库 session 或者网络 IO 的关闭，互斥锁的解锁等等。
要实现上述功能，我们可以用生成器函数作为依赖项，我们用 `yield` 关键字取代 `return` 关键字，并在 `yield` 之后进行额外的工作。
我们可以看下述代码段, 使用 `httpx.AsyncClient` 异步网络 IO：
```python {3,7-10,13}
import httpx
from nonebot import on_command
from nonebot.params import Depends # 1.引用 Depends
test = on_command("123")
async def get_client(): # 2.编写异步生成器函数
async with httpx.AsyncClient() as client:
yield client
print("调用结束")
@test.handle()
async def _(x: httpx.AsyncClient = Depends(get_client)): # 3.在事件处理函数里声明依赖项
resp = await x.get("https://v2.nonebot.dev")
# do something
```
我们用 `yield` 代码段作为生成器函数的“返回”，在事件处理函数里用返回出来的 `client` 做自己需要的工作。在 `NoneBot2` 结束事件处理时，会执行 `yield` 之后的代码。
## 创造可调用对象作为依赖
:::tips
魔法方法 `__call__` 是 `Python` 高级特性，如果你对此处文档感到疑惑那说明暂时你还用不上这个功能。
:::
在 `Python` 的里，类的 `__call__` 方法会让类的实例变成**可调用对象**，我们可以利用这个魔法方法做一个简单的尝试：
```python{3,9-14,16,19}
from typing import Type
from nonebot.log import logger
from nonebot.params import Depends # 1.引用 Depends
from nonebot import on_command
from nonebot.adapters.onebot.v11 import MessageEvent, GroupMessageEvent
test = on_command("123")
class EventChecker: # 2.编写需要的类
def __init__(self, EventClass: Type[MessageEvent]):
self.event_class = EventClass
def __call__(self, event: MessageEvent) -> bool:
return isinstance(event, self.event_class)
checker = EventChecker(GroupMessageEvent) # 3.将类实例化
@test.handle()
async def _(x: bool = Depends(checker)): # 4.在事件处理函数里声明依赖项
if x:
print("这是群聊消息")
else:
print("这不是群聊消息")
```
这是判断 `onebot` 的消息事件是不是群聊消息事件的一个例子，我们可以用四步来说明这个例子：
1. 引用 `Depends` 。
2. 编写需要的类。类的 `__init__` 函数接收参数 `EventClass`，它将接收事件类本身。类的 `__call__` 函数将接受消息事件对象，并返回一个 `bool` 类型的判定结果。
3. 将类实例化。我们传入群聊消息事件作为参数实例化 `checker` 。
4. 在事件处理函数里声明依赖项。`NoneBot2` 将会调用 `checker` 的 `__call__` 方法，返回给参数 `x` 相应的判断结果。

26
website/docs/advanced/di/overload.md
View File

@ -10,19 +10,17 @@ options:
# 事件处理函数重载
当我们在编写 `nonebot2` 应用时，常常会遇到这样一个问题：该怎么让同一类型的不同事件执行不同的响应逻辑？又或者如何让不同的 `adapter` 针对同一类型的事件作出不同响应？
当我们在编写 NoneBot2 应用时，常常会遇到这样一个问题：该怎么让同一类型的不同事件执行不同的响应逻辑？又或者如何让不同的 `bot` 针对同一类型的事件作出不同响应？
针对这个问题， `nonebot2` 提供一个便捷而高效的解决方案：事件处理函数重载机制。简单地说，`handler` (事件处理函数) 会根据其参数的 `type hints` ([PEP484 类型标注](https://www.python.org/dev/peps/pep-0484/)) 来对相对应的 `adapter` 和 `Event` 进行响应，并且会忽略不符合其参数类型标注的情况。
针对这个问题， NoneBot2 提供一个便捷而高效的解决方案：事件处理函数重载机制。简单地说，`handler`（事件处理函数）会根据其参数的 `type hints`（[PEP484 类型标注](https://www.python.org/dev/peps/pep-0484/)）来对相对应的 `bot` 和 `event` 进行响应，并且会忽略不符合其参数类型标注的情况。
<!-- 必须要注意的是，该机制利用了 `inspect` 标准库获取到了事件处理函数的 `singnature` (签名) ，进一步获取到参数名称和类型标注。故而，我们在编写 `handler` 时，参数的名称和类型标注必须要符合 `T_Handler` 规定，详情可以参看 **指南** 中的[事件处理](../../guide/creating-a-handler)。 -->
<!-- 必须要注意的是，该机制利用了 `inspect` 标准库获取到了事件处理函数的 `signature`（签名），进一步获取到参数名称和类型标注。故而，我们在编写 `handler` 时，参数的名称和类型标注必须要符合 `T_Handler` 规定，详情可以参看**指南**中的[事件处理](../../guide/creating-a-handler)。 -->
:::tip 提示
如果想了解更多关于 `inspect` 标准库的信息，可以查看[官方文档](https://docs.python.org/zh-cn/3.9/library/inspect.html)。
:::
下面，我们会以 `CQHTTP` 中的 `群聊消息事件` 和 `私聊消息事件` 为例，对该机制的应用进行简单的介绍。
下面，我们会以 OneBot 适配器中的群聊消息事件和私聊消息事件为例，对该机制的应用进行简单的介绍。
## 一个例子
@ -30,16 +28,16 @@ options:
```python
from nonebot import on_command
from nonebot.adapters.cqhttp import Bot, GroupMessageEvent, PrivateMessageEvent
from nonebot.adapters.onebot.v11 import Bot, GroupMessageEvent, PrivateMessageEvent
```
之后，我们可以注册一个 `Matcher` 来响应 `消息事件` 。
之后，我们可以注册一个 `Matcher` 来响应消息事件。
```python
matcher = on_command("testoverload")
matcher = on_command("test_overload")
```
最后, 我们编写不同的 `handler` 并编写不同的类型标注来实现事件处理函数重载：
最后，我们编写不同的 `handler` 并编写不同的类型标注来实现事件处理函数重载：
```python
@matcher.handle()
@ -52,13 +50,13 @@ async def _(bot: Bot, event: PrivateMessageEvent):
await matcher.send("私聊消息事件响应成功！")
```
此时，我们可以在群聊或私聊中对我们的机器人发送 `testoverload` ，它会在不同的场景做出不同的应答。
此时，我们可以在群聊或私聊中对我们的机器人发送 `test_overload`，它会在不同的场景做出不同的应答。
这样一个简单的事件处理函数重载就完成了。
## 进阶
事件处理函数重载机制同样支持被 `matcher.got` 等装饰器装饰的函数。 例如：
事件处理函数重载机制同样支持被 `matcher.got` 等装饰器装饰的函数。例如：
```python
@matcher.got("key1", prompt="群事件提问")
@ -72,3 +70,7 @@ async def _(bot: Bot, event: PrivateMessageEvent):
```
只有触发事件符合的函数才会触发装饰器。
:::warning 注意
bot 和 event 参数具有最高的检查优先级，因此，如果参数类型不符合，所有的依赖项 `Depends` 等都不会被执行。
:::

11
website/docs/advanced/di/sync-support.md
View File

@ -1,11 +0,0 @@
---
sidebar_position: 2
description: 同步函数作为依赖
options:
menu:
weight: 61
category: advanced
---
# 同步支持

48
website/docs/advanced/export-and-require.md
View File

@ -7,32 +7,32 @@ options:
# 跨插件访问
由于 `nonebot2` 独特的插件加载机制，在使用 python 原有的 import 机制来进行插件之间的访问时，很可能会有奇怪的或者意料以外的情况发生。为了避免这种情况的发生，您可以有两种方法来实现跨插件访问：
由于 NoneBot2 独特的插件加载机制，直接使用 Python 原生 import 机制来进行插件之间的访问时，很可能会发生奇怪或意料以外的情况。为了避免这种情况发生，您可以使用如下方法来实现跨插件访问：
1. 将插件间的要使用的公共代码剥离出来，作为公共文件或者文件夹，提供给插件加以调用。
2. 使用 `nonebot2` 提供的 `export` 和 `require` 机制，来实现插件间的互相调用。
2. 使用 NoneBot2 提供的 export 和 require 机制，来实现插件间的互相调用。
3. 在保证插件被加载的情况下，可以采用 import 来访问。
第一种方法比较容易理解和实现，这里不再赘述，但需要注意的是，请不要将公共文件或者公共文件夹作为**插件**被 `nonebot2` 加载。
第一种方法比较容易理解和实现，这里不再赘述，但需要注意的是，请不要将公共文件或者公共文件夹作为**插件**被 NoneBot2 加载。
第三种方法需要保证插件被加载，插件加载的方式可以参阅[加载插件](../tutorial/plugin/load-plugin)。
下面将介绍第二种方法—— `export` 和 `require` 机制：
下面将介绍第二种方法——export 和 require 机制：
## 使用 export 和 require
现在，假定有两个插件 `pluginA` 和 `pluginB`，需要在 `pluginB` 中调用 `pluginA` 中的一个变量 `varA` 和一个函数 `funcA`。
现在，假定有两个插件 pluginA 和 pluginB，需要在 pluginB 中调用 pluginA 中的一个变量 `varA` 和一个函数 `funcA`。
在上面的条件中涉及到了两种操作：一种是在 `pluginA` 的 `导出对象` 操作；而另一种是在 `pluginB` 的 `导入对象` 操作。在 `nonebot2` 中，`导出对象` 的操作用 `export` 机制来实现，`导入对象` 的操作用 `require` 机制来实现。下面，我们将逐一进行介绍。
在上面的条件中涉及到了两种操作：一种是在 pluginA 的导出对象操作；而另一种是在 pluginB 的导入对象操作。在 NoneBot2 中，导出对象的操作用 export 机制来实现，导入对象的操作用 require 机制来实现。下面，我们将逐一进行介绍。
:::warning 警告
使用这个方法进行跨插件访问时，**需要先加载`导出对象`的插件，再加载`导入对象`的插件。**
使用这个方法进行跨插件访问时，**需要先加载导出对象的插件，再加载导入对象的插件。**
:::
### 使用 export
在 `pluginA` 中，我们调用 `export` 机制 `导出对象`。
在 pluginA 中，我们调用 export 机制 导出对象。
在 `export` 机制调用前，我们需要保证导出的对象已经被定义，比如：
在 export 机制调用前，我们需要保证导出的对象已经被定义，比如：
```python
varA = "varA"
@ -42,7 +42,7 @@ def funcA():
return "funcA"
```
在确保定义之后，我们可以从 `nonebot.plugin` 导入 `export()` 方法, `export()` 方法会返回一个特殊的字典 `export`：
在确保定义之后，我们可以从 `nonebot.plugin` 导入 `export()` 方法，`export()` 方法会返回一个特殊的字典 `export`：
```python
from nonebot.plugin import export
@ -50,21 +50,21 @@ from nonebot.plugin import export
export=export()
```
这个字典可以用来装载导出的对象，它的 key 是对象导出后的命名，value 是对象本身，我们可以直接创建新的 `key` - `value` 对导出对象：
这个字典可以用来装载导出的对象，它的 key 是对象导出后的命名，value 是对象本身，我们可以直接创建新的 key - value 对导出对象：
```python
export.vA = varA
export.fA = funcA
```
除此之外，也支持 `嵌套` 导出对象：
除此之外，也支持嵌套导出对象：
```python
export.sub.vA = varA
export.sub.fA = funcA
```
特别地，对于 `函数对象` 而言，`export` 支持用 `装饰器` 的方法来导出，因此，我们可以这样定义 `funcA`：
特别地，对于函数对象而言，export 支持用装饰器的方法来导出，因此，我们可以这样定义 `funcA`：
```python
@export.sub
@ -72,7 +72,7 @@ def funcA():
return "funcA"
```
或者:
或者：
```python
@export
@ -80,7 +80,7 @@ def funcA():
return "funcA"
```
通过 `装饰器` 的方法导出函数时，命名固定为函数的命名，也就是说，上面的两个例子等同于：
通过装饰器的方法导出函数时，命名固定为函数的命名，也就是说，上面的两个例子等同于：
```python
export.sub.funcA = funcA
@ -90,16 +90,14 @@ export.funcA = funcA
这样，我们就成功导出 `varA` 和 `funcA` 对象了。
下面我们将介绍如何在 `pluginB` 中导入这些对象。
下面我们将介绍如何在 pluginB 中导入这些对象。
### 使用 require
在 `pluginB` 中，我们调用 `require` 机制 `导入对象`。
在 pluginB 中，我们调用 require 机制导入对象。
:::warning 警告
在导入来自其他插件的对象时, 请确保导出该对象的插件在引用该对象的插件之前加载。如果该插件并未被加载，则会尝试加载，加载失败则会返回 `None`。
在导入来自其他插件的对象时，请确保导出该对象的插件在引用该对象的插件之前加载。如果该插件并未被加载，则会尝试加载，加载失败则会返回 `None`。
:::
我们可以从 `nonebot.plugin` 中导入 `require()` 方法：
@ -108,17 +106,17 @@ export.funcA = funcA
from nonebot.plugin import require
```
`require()` 方法的参数是插件名, 它会返回在指定插件中，用 `export()` 方法创建的字典。
`require()` 方法的参数是插件名，它会返回在指定插件中，用 `export()` 方法创建的字典。
```python
require_A = require('pluginA')
```
在之前，这个字典已经存入了 `'vA'` - `varA`, `'fA'` - `funcA` 或 `'funcA'` - `funcA` 这样的 `key` - `value` 对。因此在这里我们直接用 `属性` 的方法来获取导入对象:
在之前，这个字典已经存入了 `'vA'` - `varA`、`'fA'` - `funcA` 或 `'funcA'` - `funcA` 这样的 key - value 对。因此在这里我们直接调用属性来获取导入对象：
```python
varA = require_A.vA
funcA = require_A.fA or require_A.funcA
```
这样，我们就在 `pluginB` 中成功导入了 `varA` 和 `funcA` 对象了。
这样，我们就在 pluginB 中成功导入了 `varA` 和 `funcA` 对象了。

BIN
website/docs/advanced/images/Handle-Event.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 127 KiB

After

Width:  |  Height:  |  Size: 376 KiB

37
website/docs/advanced/permission.md
View File

@ -7,66 +7,61 @@ options:
# 权限控制
**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot` 提供了十分完善且灵活的权限控制机制—— `Permission` 机制。接下来我们将对这个机制进行简单的说明。
**权限控制**是机器人在实际应用中需要解决的重点问题之一，NoneBot2 提供了灵活的权限控制机制——`Permission`，接下来我们将简单说明。
## 应用
如同 `Rule` 一样, `Permission` 可以在[注册事件响应器](../tutorial/plugin/create-matcher.md)时添加 `permission` 参数来加以应用，这样 `Nonebot` 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例，对该机制的应用做一下介绍。
如同 `Rule` 一样，`Permission` 可以在[注册事件响应器](../tutorial/plugin/create-matcher.md)时添加 `permission` 参数来加以应用，这样 NoneBot2 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例，对该机制的应用做一下介绍。
```python
from nonebot.permission import SUPERUSER
from nonebot.adapters import Bot
from nonebot import on_command
matcher = on_command("测试超管", permission=SUPERUSER)
@matcher.handle()
async def _(bot: Bot):
async def _():
await matcher.send("超管命令测试成功")
@matcher.got("key1", "超管提问")
async def _(bot: Bot, event: Event):
await matcher.send("超管命令got成功")
async def _():
await matcher.send("超管命令 got 成功")
```
在这段代码中，我们事件响应器指定了 `SUPERUSER` 这样一个权限，那么机器人只会响应超级管理员的 `测试超管` 命令，并且会响应该超级管理员的连续对话。
::: tip 提示
在这里需要强调的是，`Permission` 与 `Rule` 的表现并不相同， `Rule` 只会在初次响应时生效，在余下的对话中并没有限制事件；但是 `Permission` 会持续生效，在连续对话中会一直对事件主体加以限制。
:::tip 提示
在这里需要强调的是，`Permission` 与 `Rule` 的表现并不相同， `Rule` 只会在初次响应时生效，在余下的对话中并没有限制事件；但是 `Permission` 会持续生效，在连续对话中一直对事件主体加以限制。
:::
## 进阶
`Permission` 除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数 `handler` 时主动调用，我们可以利用这个特性在一个 `handler` 里对不同权限的事件主体进行区别响应，下面我们以 `CQHTTP` 中的 `GROUP_ADMIN` (普通管理员非群主)和 `GROUP_OWNER` 为例，说明下怎么进行主动调用。
`Permission` 除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数 `handler` 时主动调用，我们可以利用这个特性在一个 `handler` 里对不同权限的事件主体进行区别响应，下面我们以 OneBot 适配器中的 `GROUP_ADMIN`（普通管理员非群主）和 `GROUP_OWNER` 为例，说明下怎么进行主动调用。
```python
from nonebot import on_command
from nonebot.adapters.cqhttp import Bot
from nonebot.adapters.cqhttp import GroupMessageEvent
from nonebot.adapters.cqhttp import GROUP_ADMIN, GROUP_OWNER
from nonebot.adapters.onebot.v11 import GroupMessageEvent
from nonebot.adapters.onebot.v11 import GROUP_ADMIN, GROUP_OWNER
matcher = on_command("测试权限")
@matcher.handle()
async def _(bot: Bot, event: GroupMessageEvent):
if await GROUP_ADMIN(bot, event):
async def _(event: GroupMessageEvent):
if await GROUP_ADMIN(event):
await matcher.send("管理员测试成功")
elif await GROUP_OWNER(bot, event):
elif await GROUP_OWNER(event):
await matcher.send("群主测试成功")
else:
await matcher.send("群员测试成功")
```
在这段代码里，我们并没有对命令的权限指定，这个命令会响应所有在群聊中的 `测试权限` 命令，但是在 `handler` 里，我们对两个 `Permission` 进行主动调用，从而可以对不同的角色进行不同的响应。
## 自定义
如同 `Rule` 一样, `Permission` 也是由非负数个 `PermissionChecker` 组成的，但只需其中一个返回 `True` 时就会匹配成功。下面则是 `PermissionChecker` 和 `Permission` 示例：
如同 `Rule` 一样，`Permission` 也是由非负数个 `PermissionChecker` 组成的，但只需其中一个返回 `True` 时就会匹配成功。下面是自定义 `PermissionChecker` 和 `Permission` 的示例：
```python
from nonebot.adapters import Bot, Event
@ -86,7 +81,7 @@ def check(arg1, arg2):
return Permission(_checker)
```
`Permission` 和 `PermissionChecker` 之间可以使用 `或 |` 互相组合：
`Permission` 和 `PermissionChecker` 之间可以使用 `|`（或符号）互相组合：
```python
from nonebot.permission import Permission
@ -94,4 +89,4 @@ from nonebot.permission import Permission
Permission(async_checker1) | sync_checker | async_checker2
```
同样地，如果想用 `Permission(*checkers)` 包裹构造 `Permission` ，函数必须是异步的；但是在利用 `或 |` 符号连接构造时， `Nonebot` 会自动包裹同步函数为异步函数。
同样地，如果想用 `Permission(*checkers)` 包裹构造 `Permission`，函数必须是异步的；但是在利用 `|`（或符号）连接构造时，NoneBot2 会自动包裹同步函数为异步函数。

44
website/docs/advanced/publish-plugin.md
View File

@ -9,61 +9,61 @@ options:
## 前注
本章节仅包含插件发布流程指导，插件开发请查阅 **[创建插件](../tutorial/plugin/config-plugin.md)** 章节与 **[Plugin API 文档](../api/plugin.md)** 。
本章节仅包含插件发布流程指导，插件开发请查阅[**创建插件**](../tutorial/plugin/introduction.md)章节与[**Plugin API 文档**](../api/plugin/index.md)。
## 插件发布流程
### 发布到 PyPI
您可以选择任意自己喜欢的方式将您的插件发布到 **[PyPI](https://pypi.org/)** ，如使用 **[setuptools](https://pypi.org/project/setuptools/)** 或 **[poetry](https://pypi.org/project/poetry/)** 进行 PyPI 发布。
您可以选择自己喜欢的方式将插件发布到 [**PyPI**](https://pypi.org/)，如使用 [**setuptools**](https://pypi.org/project/setuptools/) 或 [**Poetry**](https://pypi.org/project/poetry/)。
发布时，请您为自己的插件取一个清晰易懂的名字。通常而言，一款 NoneBot2 插件名称使用 `nonebot-plugin-` 作为前缀(如`nonebot-plugin-foo`)，以 `nonebot_plugin_` 作为导入名的前缀(如`nonebot_plugin_foo`)，这并非是强制规范, 而是为了防止与其他 PyPI 包产生冲突, 所以我们推荐您在没有特殊需求的情况下这样做。
发布时，请您为自己的插件取一个清晰易懂的名字。通常而言，一款 NoneBot2 插件名称使用 `nonebot-plugin-` 作为前缀（如`nonebot-plugin-foo`），以 `nonebot_plugin_` 作为包名的前缀（如`nonebot_plugin_foo`），这并非强制规范，而是为了防止与其他 PyPI 包产生冲突，所以我们推荐您在没有特殊需求的情况下这样做。
发布后，请确保您的插件已能公开的从 PyPI 访问到，请检查您的插件在 PyPI 的地址：`https://pypi.org/project/<您的Nonebot2插件项目名>`
发布后，请确保您的插件已能公开的从 PyPI 访问到，试着检查您的插件在 PyPI 的地址，如 `https://pypi.org/project/<您的 NoneBot2 插件项目名>`。
### 托管您的插件源代码
将插件源代码及相关构建文件（如`pyproject.toml`或`setup.py`等与 PyPI 包构建相关的文件）托管在公开代码仓。
将插件源代码及相关构建文件（如 `pyproject.toml` 或 `setup.py` 等与 PyPI 包构建相关的文件）托管在公开代码仓。
请确保您的代码仓地址能够被正确的访问，检查您的插件在代码仓的地址，如 `https://github.com/<您的Github用户名>/<您的插件Github项目名>` 。
请确保您的代码仓库地址能够被正确的访问，检查您的插件在代码仓的地址，如 `https://github.com/<您的 Github 用户名>/<您的插件 Github 项目名>`。
### 申请发布到 Nonebot2 插件商店
### 申请发布到 NoneBot2 插件商店
完成在 PyPI 的插件发布流程与源代码托管流程后，请您前往 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** 页面，切换到 **插件** 页签，点击 **发布插件** 按钮。
完成在 PyPI 的插件发布流程与源代码托管流程后，请您前往 [**NoneBot2 商店**](https://v2.nonebot.dev/store.html)页面，切换到**插件**页签，点击**发布插件**按钮。
![插件发布界面](./images/plugin_store_publish.png)
如图所示，在弹出的插件信息提交表单内，填入您所要发布的相应插件信息：
```text
插件名称： 您的Nonebot2插件名称
插件介绍： 为您的插件提供的简短介绍信息
PyPI项目名： 您的插件所在的PyPI Project名，如 nonebot-plugin-xxxx
import包名： 您的插件通过Python导入时使用的包名，如 nonebot_plugin_xxxx
仓库/主页： 您的插件托管地址，如 https://github.com/<您的Github用户名>/nonebot-plugin-xxxx
标签： 一个或多个可选颜色的TAG，每填写一个点击添加标签，若要删除，点击标签即可；标签长度不超过10字符，标签个数不超过3个
特定标签内容Adapter：点击Type的Adapter，将创建一个 a: 开头的标签，填入内容以指定您插件使用的adapter
特定标签内容Topic：点击Type的Topic，将创建一个 t: 开头的标签，填入内容以指定您插件的主题
插件名称：您的 NoneBot2 插件名称
插件介绍：为您的插件提供的简短介绍信息
PyPI 项目名：您的插件所在的 PyPI Project 名，如 nonebot-plugin-xxxx
import 包名：您的插件通过 Python 导入时使用的包名，如 nonebot_plugin_xxxx
仓库/主页：您的插件托管地址，如 https://github.com/<您的 Github 用户名>/nonebot-plugin-xxxx
标签：一个或多个可选颜色的 TAG，每填写一个点击添加标签，若要删除，点击标签即可；标签长度不超过 10 字符，标签个数不超过 3 个
特定标签内容 Adapter：点击 Type 的 Adapter，将创建一个 a: 开头的标签，填入内容以指定您插件使用的 adapter
特定标签内容 Topic：点击 Type 的 Topic，将创建一个 t: 开头的标签，填入内容以指定您插件的主题
```
![插件信息填写](./images/plugin_store_publish_2.png)
完成填写后，请点击 **发布** 按钮，这将自动在 **[NoneBot2](https://github.com/nonebot/nonebot2)** 代码仓内创建发布您的插件的对应 Issue。
完成填写后，请点击**发布**按钮，这将自动在[**NoneBot2**](https://github.com/nonebot/nonebot2)代码仓内创建发布您的插件的对应 Issue。
### 等待插件发布处理
您的插件发布 Issue 创建后，将会经过*Nonebot2 Publish Bot*的检查，以确保插件信息正确无误。
您的插件发布 Issue 创建后，将会经过 _NoneBot2 Publish Bot_ 的检查，以确保插件信息正确无误。
若您的插件发布 Issue 未通过检查，您可以 **直接修改** Issue 内容以更新发布请求。*Nonebot2 Publish Bot*在您修改 Issue 内容后将会自动重新执行检查。您无需关闭、重新提交发布申请。
若您的插件发布 Issue 未通过检查，您可以**直接修改** Issue 内容以更新发布请求。_NoneBot2 Publish Bot_ 在您修改 Issue 内容后将会自动重新执行检查。您无需关闭、重新提交发布申请。
之后，NoneBot2 的维护者们将会对插件进行进一步的检查，以确保用户能够正常安装并使用该插件。
完成这些步骤后，您的插件将会被合并到 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** ，而您也将成为 **[NoneBot2 贡献者](https://github.com/nonebot/nonebot2/graphs/contributors)** 的一员。
完成这些步骤后，您的插件将会被合并到 [**NoneBot2 商店**](https://v2.nonebot.dev/store.html)，而您也将成为 [**NoneBot2 贡献者**](https://github.com/nonebot/nonebot2/graphs/contributors)中的一员。
## 完成
恭喜您，经过上述的发布流程，您的插件已经成功发布到 Nonebot2 商店了。
恭喜您，经过上述的发布流程，您的插件已经成功发布到 NoneBot2 商店了。
此时，您可以在 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** 的插件页签查找到您的插件。同时，欢迎您成为 **[NoneBot2 贡献者](https://github.com/nonebot/nonebot2/graphs/contributors)** ！
此时，您可以在 [**NoneBot2 商店**](https://v2.nonebot.dev/store.html)的插件页签查找到您的插件。同时，欢迎您成为 [**NoneBot2 贡献者**](https://github.com/nonebot/nonebot2/graphs/contributors)！
**Congratulations!**

46
website/docs/advanced/runtime-hook.md
View File

@ -7,17 +7,17 @@ options:
# 钩子函数
[`钩子编程`](https://zh.wikipedia.org/wiki/%E9%92%A9%E5%AD%90%E7%BC%96%E7%A8%8B)
[钩子编程](https://zh.wikipedia.org/wiki/%E9%92%A9%E5%AD%90%E7%BC%96%E7%A8%8B)
> 钩子编程（hooking），也称作“挂钩”，是计算机程序设计术语，指通过拦截软件模块间的函数调用、消息传递、事件传递来修改或扩展操作系统、应用程序或其他软件组件的行为的各种技术。处理被拦截的函数调用、事件、消息的代码，被称为钩子（hook）。
在 `nonebot2` 中有一系列预定义的钩子函数，分为两类：`全局钩子函数` 和 `事件钩子函数` ，这些钩子函数可以用装饰器的形式来使用。
在 NoneBot2 中有一系列预定义的钩子函数，分为两类：**全局钩子函数**和**事件钩子函数**，这些钩子函数可以用装饰器的形式来使用。
## 全局钩子函数
全局钩子函数是指 `nonebot2` 针对其本身运行过程的钩子函数。
全局钩子函数是指 NoneBot2 针对其本身运行过程的钩子函数。
这些钩子函数是由其后端驱动 `driver`来运行的，故需要先获得全局 `driver` 对象：
这些钩子函数是由其后端驱动 `Driver` 来运行的，故需要先获得全局 `Driver` 对象：
```python
from nonebot import get_driver
@ -30,7 +30,7 @@ driver=get_driver()
### 启动准备
这个钩子函数会在 `nonebot2` 启动时运行。
这个钩子函数会在 NoneBot2 启动时运行。
```python
@driver.on_startup
@ -40,7 +40,7 @@ async def do_something():
### 终止处理
这个钩子函数会在 `nonebot2` 终止时运行。
这个钩子函数会在 NoneBot2 终止时运行。
```python
@driver.on_shutdown
@ -48,9 +48,9 @@ async def do_something():
pass
```
### bot 连接处理
### Bot 连接处理
这个钩子函数会在 `bot` 通过 `websocket` 连接到 `nonebot2` 时运行。
这个钩子函数会在 `Bot` 通过 websocket 连接到 NoneBot2 时运行。
```python
@driver.on_bot_connect
@ -60,7 +60,7 @@ async def do_something(bot: Bot):
### bot 断开处理
这个钩子函数会在 `bot` 断开与 `nonebot2` 的 `websocket` 连接时运行。
这个钩子函数会在 `Bot` 断开与 NoneBot2 的 websocket 连接时运行。
```python
@driver.on_bot_disconnect
@ -92,17 +92,15 @@ async def handle_api_result(bot: Bot, exception: Optional[Exception], api: str,
pass
```
## 事件处理钩子
## 事件钩子函数
这些钩子函数指的是影响 `nonebot2` 进行 `事件处理` 的函数。
这些钩子函数指的是影响 NoneBot2 进行**事件处理**的函数, 这些函数可以认为跟普通的事件处理函数一样，接受相应的参数。
:::tip 提示
关于 `事件处理` 的流程，可以在[这里](./README.md)查阅。
关于**事件处理**的流程，可以在[这里](./README.md)查阅。
:::
:::warning 注意
:::warning
1.在事件处理钩子函数中，与 `matcher` 运行状态相关的函数将不可用，如 `matcher.finish()`
@ -113,7 +111,7 @@ from nonebot.exception import IgnoredException
@event_preprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
async def do_something():
raise IgnoredException("reason")
```
@ -123,48 +121,48 @@ async def do_something(bot: Bot, event: Event, state: T_State):
### 事件预处理
这个钩子函数会在 `Event` 上报到 `nonebot2` 时运行
这个钩子函数会在 `Event` 上报到 NoneBot2 时运行
```python
from nonebot.message import event_preprocessor
@event_preprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
async def do_something():
pass
```
### 事件后处理
这个钩子函数会在 `nonebot2` 处理 `Event` 后运行
这个钩子函数会在 NoneBot2 处理 `Event` 后运行
```python
from nonebot.message import event_postprocessor
@event_postprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
async def do_something():
pass
```
### 运行预处理
这个钩子函数会在 `nonebot2`运行 `matcher` 前运行。
这个钩子函数会在 NoneBot2 运行 `matcher` 前运行。
```python
from nonebot.message import run_preprocessor
@run_preprocessor
async def do_something(matcher: Matcher, bot: Bot, event: Event, state: T_State):
async def do_something():
pass
```
### 运行后处理
这个钩子函数会在 `nonebot2`运行 `matcher` 后运行。
这个钩子函数会在 NoneBot2 运行 `matcher` 后运行。
```python
from nonebot.message import run_postprocessor
@run_postprocessor
async def do_something(matcher: Matcher, exception: Optional[Exception], bot: Bot, event: Event, state: T_State):
async def do_something():
pass
```

28
website/docs/advanced/scheduler.md
View File

@ -7,33 +7,33 @@ options:
# 定时任务
[`APScheduler`](https://apscheduler.readthedocs.io/en/3.x/) —— Advanced Python Scheduler
[APScheduler](https://apscheduler.readthedocs.io/en/3.x/) —— Advanced Python Scheduler
> Advanced Python Scheduler (APScheduler) is a Python library that lets you schedule your Python code to be executed later, either just once or periodically. You can add new jobs or remove old ones on the fly as you please. If you store your jobs in a database, they will also survive scheduler restarts and maintain their state. When the scheduler is restarted, it will then run all the jobs it should have run while it was offline.
## 从 NoneBot v1 迁移
`APScheduler` 作为 `nonebot` v1 的可选依赖，为众多 bot 提供了方便的定时任务功能。`nonebot2` 已将 `APScheduler` 独立为 `nonebot_plugin_apscheduler` 插件，你可以在 [商店](https://v2.nonebot.dev/store.html) 中找到它。
`APScheduler` 作为 NoneBot v1 的可选依赖，为众多 bot 提供了方便的定时任务功能。NoneBot2 已将 `APScheduler` 独立为 nonebot_plugin_apscheduler 插件，你可以在[商店](https://v2.nonebot.dev/store.html)中找到它。
相比于 `nonebot` v1，`nonebot` v2 只需要安装插件并修改 `scheduler` 的导入方式即可完成迁移。
相比于 NoneBot v1，NoneBot v2 只需要安装插件并修改 `scheduler` 的导入方式即可完成迁移。
## 安装插件
### 通过 nb-cli
如正在使用 `nb-cli` 构建项目，你可以从插件市场复制安装命令或手动输入以下命令以添加 `nonebot_plugin_apscheduler`。
如正在使用 nb-cli 构建项目，你可以从插件市场复制安装命令或手动输入以下命令以添加 nonebot_plugin_apscheduler。
```bash
nb plugin install nonebot_plugin_apscheduler
```
:::tip 提示
`nb-cli` 默认通过 `pypi` 安装，你可以添加命令参数 `-i [mirror]` 或 `--index [mirror]` 以使用镜像源安装。
nb-cli 默认通过 PyPI 安装，你可以添加命令参数 `-i [mirror]` 或 `--index [mirror]` 以使用镜像源安装。
:::
### 通过 poetry
### 通过 Poetry
执行以下命令以添加 `nonebot_plugin_apscheduler`
执行以下命令以添加 nonebot_plugin_apscheduler
```bash
poetry add nonebot-plugin-apscheduler
@ -45,7 +45,7 @@ poetry add nonebot-plugin-apscheduler
## 快速上手
1. 在需要设置定时任务的插件中，通过 `nonebot.require` 从 `nonebot_plugin_apscheduler` 导入 `scheduler` 对象
1. 在需要设置定时任务的插件中，通过 `nonebot.require` 从 nonebot_plugin_apscheduler 导入 `scheduler` 对象
2. 在该对象的基础上，根据 `APScheduler` 的使用方法进一步配置定时任务
@ -69,11 +69,11 @@ scheduler.add_job(run_every_day_from_program_start, "interval", days=1, id="xxx"
为了使插件能够实现定时任务，需要先将 `scheduler` 对象导入插件。
`nonebot2` 提供了 `nonebot.require` 方法来实现导入其他插件的内容，此处我们使用这个方法来导入 `scheduler` 对象。
NoneBot2 提供了 `nonebot.require` 方法来实现导入其他插件的内容，此处我们使用这个方法来导入 `scheduler` 对象。
`nonebot` 使用的 `scheduler` 对象为 `AsyncScheduler` 。
NoneBot2 使用的 `scheduler` 对象为 `AsyncScheduler` 。
> 使用该方法传入的插件本身也需要有对应实现，关于该方法的更多介绍可以参阅 [这里](./export-and-require.md)
> 使用该方法传入的插件本身也需要有对应实现，关于该方法的更多介绍可以参阅[这里](./export-and-require.md)
```python
from nonebot import require
@ -87,10 +87,10 @@ scheduler = require("nonebot_plugin_apscheduler").scheduler
### 配置插件选项
根据项目的 `.env` 文件设置，向 `.env.*` 或 `bot.py` 文件添加 `nonebot_plugin_apscheduler` 的可选配置项
根据项目的 `.env` 文件设置，向 `.env.*` 或 `bot.py` 文件添加 nonebot_plugin_apscheduler 的可选配置项
:::warning 注意
`.env.*` 文件的编写应遵循 nonebot2 对 `.env.*` 文件的编写要求
`.env.*` 文件的编写应遵循 NoneBot2 对 `.env.*` 文件的编写要求
:::
#### `apscheduler_autostart`
@ -101,7 +101,7 @@ scheduler = require("nonebot_plugin_apscheduler").scheduler
是否自动启动 `APScheduler`。
对于大多数情况，我们需要在 `nonebot2` 项目被启动时启动定时任务，则此处设为 `true`
对于大多数情况，我们需要在 NoneBot2 项目被启动时启动定时任务，则此处设为 `true`
##### 在 `.env` 中添加

2
website/docs/api/adapters/_category_.json
View File

@ -1,3 +1,3 @@
{
"position": 14
"position": 15
}

0
website/versioned_docs/version-2.0.0-beta.1/api/drivers/_category_.json → website/docs/api/dependencies/_category_.json
View File

2
website/docs/api/drivers/_category_.json
View File

@ -1,3 +1,3 @@
{
"position": 13
"position": 14
}

3
website/docs/api/plugin/_category_.json Normal file
View File

@ -0,0 +1,3 @@
{
"position": 12
}

2
website/docs/start/editor-support.md
View File

@ -5,7 +5,7 @@ description: 编辑器支持
# 编辑器支持
框架基于 [PEP484](https://www.python.org/dev/peps/pep-0484/), [PEP 561](https://www.python.org/dev/peps/pep-0517/), [PEP8](https://www.python.org/dev/peps/pep-0008/) 等规范进行开发并且是 **Fully Typed**。框架使用 `pyright` (`pylance`) 工具进行类型检查，确保代码可以被编辑器正确解析。
框架基于 [PEP484](https://www.python.org/dev/peps/pep-0484/)、[PEP 561](https://www.python.org/dev/peps/pep-0517/)、[PEP8](https://www.python.org/dev/peps/pep-0008/) 等规范进行开发并且是 **Fully Typed**。框架使用 `pyright`（`pylance`）工具进行类型检查，确保代码可以被编辑器正确解析。
## 编辑器推荐配置

40
website/docs/start/install-adapter.md
View File

@ -1,40 +0,0 @@
---
sidebar_position: 2
description: 通过脚手架, pip 安装适配器
---
# 安装协议适配器
## 查看
前往 [商店](/store) 即可查看所有协议适配器。
或者使用 `nb-cli` 命令行查看：
```bash
nb adapter list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb adapter install <adapter-name>
```
或者使用交互模式安装：
```bash
nb adapter install
```
也可以使用 `pip` 安装
```bash
pip install <adapter-name>
```
<!-- TODO: asciinema for install adapter -->

45
website/docs/start/install-adapter.mdx Normal file
View File

@ -0,0 +1,45 @@
---
sidebar_position: 2
description: 通过脚手架或 pip 安装适配器
---
import Asciinema from "@site/src/components/Asciinema";
# 安装协议适配器
## 查看
前往[商店](/store)即可查看所有协议适配器。
或者使用 nb-cli 命令行查看:
```bash
nb adapter list
```
## 安装
前往[商店](/store)点击复制 nb-cli 安装命令至命令行执行即可安装。
或者自行输入命令安装:
```bash
nb adapter install <adapter-name>
```
或者使用交互模式安装:
```bash
nb adapter install
```
也可以使用 pip 安装
```bash
pip install <adapter-name>
```
<Asciinema
url="https://asciinema.org/a/464727.cast"
options={{ theme: "monokai", poster: "npt:2.0" }}
/>

42
website/docs/start/install-driver.md
View File

@ -1,42 +0,0 @@
---
sidebar_position: 1
description: 通过脚手架, pip 安装驱动器
---
# 安装驱动器
NoneBot 在默认安装情况下内置了 `fastapi` 服务端驱动器，其他驱动器如 `httpx`, `aiohttp` 则需要额外安装。
## 查看
前往 [商店](/store) 即可查看所有驱动器。
或者使用 `nb-cli` 命令行查看：
```bash
nb driver list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb driver install <driver-name>
```
或者使用交互模式安装：
```bash
nb driver install
```
也可以使用 `pip` 安装
```bash
pip install <driver-name>
```
<!-- TODO: asciinema for install driver -->

47
website/docs/start/install-driver.mdx Normal file
View File

@ -0,0 +1,47 @@
---
sidebar_position: 1
description: 通过脚手架或 pip 安装驱动器
---
import Asciinema from "@site/src/components/Asciinema";
# 安装驱动器
NoneBot 在默认安装情况下内置了 `fastapi` 服务端驱动器，其他驱动器如 `httpx`、`aiohttp` 则需要额外安装。
## 查看
前往[商店](/store)即可查看所有驱动器。
或者使用 nb-cli 命令行查看:
```bash
nb driver list
```
## 安装
前往[商店](/store)点击复制 nb-cli 安装命令至命令行执行即可安装。
或者自行输入命令安装:
```bash
nb driver install <driver-name>
```
或者使用交互模式安装:
```bash
nb driver install
```
也可以使用 pip 安装
```bash
pip install <driver-name>
```
<Asciinema
url="https://asciinema.org/a/464686.cast"
options={{ theme: "monokai", poster: "npt:2.8" }}
/>

40
website/docs/start/install-plugin.md
View File

@ -1,40 +0,0 @@
---
sidebar_position: 3
description: 通过脚手架, pip 安装插件
---
# 安装第三方插件
## 查看
前往 [商店](/store) 即可查看所有发布的插件。
或者使用 `nb-cli` 命令行查看：
```bash
nb plugin list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb plugin install <plugin-name>
```
或者使用交互模式安装：
```bash
nb plugin install
```
也可以使用 `pip` 安装
```bash
pip install <plugin-name>
```
<!-- TODO: asciinema for install plugin -->

45
website/docs/start/install-plugin.mdx Normal file
View File

@ -0,0 +1,45 @@
---
sidebar_position: 3
description: 通过脚手架或 pip 安装插件
---
import Asciinema from "@site/src/components/Asciinema";
# 安装第三方插件
## 查看
前往[商店](/store)即可查看所有发布的插件。
或者使用 nb-cli 命令行查看:
```bash
nb plugin list
```
## 安装
前往[商店](/store)点击复制 nb-cli 安装命令至命令行执行即可安装。
或者自行输入命令安装:
```bash
nb plugin install <plugin-name>
```
或者使用交互模式安装:
```bash
nb plugin install
```
也可以使用 pip 安装
```bash
pip install <plugin-name>
```
<Asciinema
url="https://asciinema.org/a/464735.cast"
options={{ theme: "monokai", poster: "npt:4.3" }}
/>

75
website/docs/start/installation.md
View File

@ -1,75 +0,0 @@
---
sidebar_position: 0
description: 通过脚手架, PyPI, GitHub 安装 NoneBot
options:
menu:
weight: 10
category: guide
---
# 安装 NoneBot
:::warning 注意
请确保你的 Python 版本 >= 3.7.3。
:::
:::warning 注意
请在安装 NoneBot v2 之前卸载 NoneBot v1
```bash
pip uninstall nonebot
```
:::
## 通过脚手架安装 (推荐)
1. (可选) 使用你喜欢的 Python 环境管理工具 (如 `poetry`, `venv`, `conda` 等) 创建新的虚拟环境
2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装
```bash
pip install nb-cli
```
<!-- TODO: asciinema for installation -->
:::important 提示
`nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md)
:::
## 不使用脚手架 (纯净安装)
如果你不想使用脚手架，可以直接安装 `nonebot2`，并自行完成开发配置。
```bash
pip install nonebot2
# 也可以通过 poetry 安装
poetry add nonebot2
```
## 从 GitHub 安装
如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
:::warning 注意
直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
在任何情况下请不要将其应用于生产环境!
:::
```bash title="Install From Github"
# master分支
poetry add git+https://github.com/nonebot/nonebot2.git#master
# dev分支
poetry add git+https://github.com/nonebot/nonebot2.git#dev
```
或者在克隆 Git 仓库后手动安装：
```bash
git clone https://github.com/nonebot/nonebot2.git
cd nonebot2
poetry install --no-dev # 推荐
pip install . # 不推荐
```

80
website/docs/start/installation.mdx Normal file
View File

@ -0,0 +1,80 @@
---
sidebar_position: 0
description: 通过脚手架、PyPI 或 GitHub 安装 NoneBot2
options:
menu:
weight: 10
category: guide
---
import Asciinema from "@site/src/components/Asciinema";
# 安装 NoneBot2
:::warning 注意
请确保你的 Python 版本 >= 3.7.3。
:::
:::warning 注意
请在安装 NoneBot v2 之前卸载 NoneBot v1
```bash
pip uninstall nonebot
```
:::
## 通过脚手架安装（推荐）
1. （可选）使用你喜欢的 Python 环境管理工具（如 Poetry、venv、Conda 等）创建新的虚拟环境
2. 使用 pip 或其他包管理工具安装 nb-cli，NoneBot2 会作为其依赖被一起安装
```bash
pip install nb-cli
```
<Asciinema
url="https://asciinema.org/a/464654.cast"
options={{ theme: "monokai", poster: "npt:2.8" }}
/>
:::important 提示
nb-cli 的使用方法详见[使用脚手架](./nb-cli.md)
:::
## 不使用脚手架（纯净安装）
如果你不想使用脚手架，可以直接安装 NoneBot2，并自行完成开发配置。
```bash
pip install nonebot2
# 也可以通过 Poetry 安装
poetry add nonebot2
```
## 从 GitHub 安装
如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装:
:::warning 注意
直接从 GitHub 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
在任何情况下请不要将其应用于生产环境!
:::
```bash title="Install From GitHub"
# master分支
poetry add git+https://github.com/nonebot/nonebot2.git#master
# dev分支
poetry add git+https://github.com/nonebot/nonebot2.git#dev
```
或者在克隆 Git 仓库后手动安装:
```bash
git clone https://github.com/nonebot/nonebot2.git
cd nonebot2
poetry install --no-dev # 推荐
pip install . # 不推荐
```

73
website/docs/start/nb-cli.md
View File

@ -10,4 +10,75 @@ options:
# 使用脚手架
<!-- TODO: nb-cli docs -->
## 安装
```bash
pip install nb-cli
```
## 初次使用
在安装完成之后，即可在命令行使用 nb-cli 的命令 `nb` 进行开发：
```bash
# 直接使用 nb 命令
nb
# 或使用 Python 执行 module
python -m nb_cli
```
:::warning 注意
通常情况下，你可以直接在命令行使用 `nb` 命令，但如果命令行出现 `Command not found` 错误，这是由于环境变量 `PATH` 没有正确配置或未配置导致的，可以使用第二种方式代替。
:::
## 使用方式
nb-cli 具有两种使用方式：
1. 命令行指令
查看帮助信息：
```bash
$ nb --help
Usage: nb [OPTIONS] COMMAND [ARGS]...
Options:
-V, --version Show the version and exit.
--help Show this message and exit.
...
```
查看子命令帮助：
```bash
$ nb plugin --help
Usage: nb plugin [OPTIONS] COMMAND [ARGS]...
Manage Bot Plugin.
Options:
--help Show this message and exit.
...
```
2. 交互式选择（支持鼠标）
交互式选择菜单：
```bash
$ nb
Welcome to NoneBot CLI!
[?] What do you want to do? (Use ↑ and ↓ to choose, Enter to submit)
...
```
交互式子命令菜单：
```bash
$ nb plugin
[?] What do you want to do? (Use ↑ and ↓ to choose, Enter to submit)
...
```

12
website/docs/start/question.md
View File

@ -7,22 +7,22 @@ description: 如何获取帮助
如果在安装或者开发过程中遇到了任何问题，可以通过以下方式解决：
1. 点击下方链接前往 GitHub ~~点击 star~~ ，前往 Issues 页面，在 `New Issue` Template 中选择 `Question`
1. 点击下方链接前往 GitHub，前往 Issues 页面，在 `New Issue` Template 中选择 `Question`
NoneBot2: [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
NoneBot2：[![NoneBot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
2. 通过 QQ 群 (点击下方链接直达)
2. 通过 QQ 群（点击下方链接直达）
[![QQ Chat](https://img.shields.io/badge/QQ%E7%BE%A4-768887710-orange?style=social)](https://jq.qq.com/?_wv=1027&k=5OFifDh)
3. 通过 QQ 频道
前往 QQ 频道搜索 `NoneBot` 点击加入
前往 QQ 频道搜索 NoneBot 点击加入
4. 通过 Telegram 群 (点击下方链接直达)
4. 通过 Telegram 群（点击下方链接直达）
[![Telegram Chat](https://img.shields.io/badge/telegram-cqhttp-blue?style=social)](https://t.me/cqhttp)
5. 通过 Discord 服务器 (点击下方链接直达)
5. 通过 Discord 服务器（点击下方链接直达）
[![Discord Server](https://discordapp.com/api/guilds/847819937858584596/widget.png?style=shield)](https://discord.gg/VKtE6Gdc4h)

42
website/docs/tutorial/add-custom-api.md Normal file
View File

@ -0,0 +1,42 @@
---
sidebar_position: 10
description: 扩展自定义服务端 API
---
# 添加自定义 API
由于 NoneBot2 可以使用 `ReverseDriver` （即服务端框架）来进行驱动，因此可以将 NoneBot2 来作为一个服务端程序来提供 API 接口等功能。
在扩展 API 之前，你首先需要确保 NoneBot2 使用的是 `ReverseDriver`，详情可以参考 [选择驱动器](./choose-driver.md)。下面我们以 FastAPI 驱动器为例，来演示如何添加自定义 API。
## 获取 APP 实例
在定义 API 接口之前，需要先获取到驱动器框架的 APP 实例。
```python {4}
import nonebot
from fastapi import FastAPI
app: FastAPI = nonebot.get_app()
@app.get("/api")
async def custom_api():
return {"message": "Hello, world!"}
```
## 添加接口
在获取到当前驱动器的 APP 实例后，即可以直接使用驱动器框架提供的方法来添加 API 接口。
在下面的代码中，我们添加了一个 `GET` 类型的 `/api` 接口，具体方法参考 [FastAPI 文档](https://fastapi.tiangolo.com/)。
```python {6-8}
import nonebot
from fastapi import FastAPI
app: FastAPI = nonebot.get_app()
@app.get("/api")
async def custom_api():
return {"message": "Hello, world!"}
```

29
website/docs/tutorial/call-api.md Normal file
View File

@ -0,0 +1,29 @@
---
sidebar_position: 8
description: 调用机器人平台 API，完成更多的功能
options:
menu:
weight: 29
category: guide
---
# 调用平台 API
在使用机器人功能时，除了发送消息以外，还可能需要调用机器人平台的 API 来完成更多的功能。
NoneBot 提供了两种方式来调用机器人平台 API，两种方式都需要首先获得 Bot 实例，然后调用相应的方法。
例如，如果需要调用机器人平台的 `get_user_info` API，可以这样做：
```python
from nonebot import get_bot
bot = get_bot("bot_id")
result = await bot.get_user_info(user_id=12345678)
await bot.call_api("get_user_info", user_id=12345678)
```
:::tip 提示
API 由平台提供，请参考平台文档。
:::

130
website/docs/tutorial/choose-driver.md
View File

@ -15,17 +15,17 @@ options:
:::
:::tip 提示
如何**安装**驱动器请参考 [安装驱动器](../start/install-driver.md)
如何**安装**驱动器请参考[安装驱动器](../start/install-driver.mdx)。
如何**使用**驱动器请参考 [配置](./configuration.md#driver)
如何**使用**驱动器请参考[配置](./configuration.md#driver)。
:::
## 驱动器的类型
驱动器的类型有两种：
- `ForwardDriver`: 即客户端类型驱动器，多用于使用 HTTP 轮询，WebSocket 连接服务器的情形。
- `ReverseDriver`: 即服务端类型驱动器，多用于使用 WebHook 情形。
- `ForwardDriver`：即客户端类型驱动器，多用于使用 HTTP 轮询，WebSocket 连接服务器的情形。
- `ReverseDriver`：即服务端类型驱动器，多用于使用 WebHook 情形。
其中 `ReverseDriver` 可以配合 `ForwardDriver` 一起使用，即可以同时使用客户端功能和服务端功能。
@ -35,8 +35,8 @@ options:
### ForwardDriver
1. 异步发送 HTTP 请求，自定义 `HTTP Method`, `URL`, `Header`, `Body`, `Cookie`, `Proxy`, `Timeout` 等。
2. 异步建立 WebSocket 连接上下文，自定义 `WebSocket URL`, `Header`, `Cookie`, `Proxy`, `Timeout` 等。
1. 异步发送 HTTP 请求，自定义 `HTTP Method`、`URL`、`Header`、`Body`、`Cookie`、`Proxy`、`Timeout` 等。
2. 异步建立 WebSocket 连接上下文，自定义 `WebSocket URL`、`Header`、`Cookie`、`Proxy`、`Timeout` 等。
### ReverseDriver
@ -46,17 +46,17 @@ options:
## 内置驱动器
### FastAPI （默认）
### FastAPI（默认）
类型: `ReverseDriver`
类型：`ReverseDriver`
> FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.
FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编写体验，可以挂载其他 ASGI, WSGI 应用。
FastAPI 是一个易上手、高性能的异步 Web 框架，具有极佳的编写体验，可以挂载其他 ASGI、WSGI 应用。
FastAPI: [文档](https://fastapi.tiangolo.com/), [仓库](https://github.com/tiangolo/fastapi)
FastAPI：[文档](https://fastapi.tiangolo.com/)、[仓库](https://github.com/tiangolo/fastapi)
驱动器: [API](../api/drivers/fastapi.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/fastapi.py)
驱动器：[API](../api/drivers/fastapi.md)、[源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/fastapi.py)
```env
DRIVER=~fastapi
@ -66,27 +66,33 @@ DRIVER=~fastapi
##### `fastapi_openapi_url`
类型: `Optional[str]`
默认值: `None`
说明: `FastAPI` 提供的 `OpenAPI` JSON 定义地址，如果为 `None`，则不提供 `OpenAPI` JSON 定义。
类型：`Optional[str]`
默认值：`None`
说明：`FastAPI` 提供的 `OpenAPI` JSON 定义地址，如果为 `None`，则不提供 `OpenAPI` JSON 定义。
##### `fastapi_docs_url`
类型: `Optional[str]`
默认值: `None`
说明: `FastAPI` 提供的 `Swagger` 文档地址，如果为 `None`，则不提供 `Swagger` 文档。
类型：`Optional[str]`
默认值：`None`
说明：`FastAPI` 提供的 `Swagger` 文档地址，如果为 `None`，则不提供 `Swagger` 文档。
##### `fastapi_redoc_url`
类型: `Optional[str]`
默认值: `None`
说明: `FastAPI` 提供的 `ReDoc` 文档地址，如果为 `None`，则不提供 `ReDoc` 文档。
类型：`Optional[str]`
默认值：`None`
说明：`FastAPI` 提供的 `ReDoc` 文档地址，如果为 `None`，则不提供 `ReDoc` 文档。
##### `fastapi_include_adapter_schema`
类型：`bool`
默认值：`True`
说明：`FastAPI` 提供的 `OpenAPI` JSON 定义中是否包含适配器路由的 `Schema`。
##### `fastapi_reload`
类型: `bool`
默认值: `False`
说明: 是否开启 `uvicorn` 的 `reload` 功能，需要提供 asgi 应用路径。
类型：`bool`
默认值：`False`
说明：是否开启 `uvicorn` 的 `reload` 功能，需要提供 asgi 应用路径。
```python title=bot.py
app = nonebot.get_asgi()
@ -95,39 +101,39 @@ nonebot.run(app="bot:app")
##### `fastapi_reload_dirs`
类型: `Optional[List[str]]`
默认值: `None`
说明: 重载监控文件夹列表，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：重载监控文件夹列表，默认为 uvicorn 默认值
##### `fastapi_reload_delay`
类型: `Optional[float]`
默认值: `None`
说明: 重载延迟，默认为 uvicorn 默认值
类型：`Optional[float]`
默认值：`None`
说明：重载延迟，默认为 uvicorn 默认值
##### `fastapi_reload_includes`
类型: `Optional[List[str]]`
默认值: `None`
说明: 要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
##### `fastapi_reload_excludes`
类型: `Optional[List[str]]`
默认值: `None`
说明: 不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
### Quart
类型: `ReverseDriver`
类型：`ReverseDriver`
> Quart is an asyncio reimplementation of the popular Flask microframework API.
Quart 是一个类 Flask 的异步版本，拥有与 Flask 非常相似的接口和使用方法。
Quart: [文档](https://pgjones.gitlab.io/quart/), [仓库](https://gitlab.com/pgjones/quart)
Quart：[文档](https://pgjones.gitlab.io/quart/)、[仓库](https://gitlab.com/pgjones/quart)
驱动器: [API](../api/drivers/quart.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/quart.py)
驱动器：[API](../api/drivers/quart.md)、[源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/quart.py)
```env
DRIVER=~quart
@ -137,9 +143,9 @@ DRIVER=~quart
##### `quart_reload`
类型: `bool`
默认值: `False`
说明: 是否开启 `uvicorn` 的 `reload` 功能，需要提供 asgi 应用路径。
类型：`bool`
默认值：`False`
说明：是否开启 `uvicorn` 的 `reload` 功能，需要提供 asgi 应用路径。
```python title=bot.py
app = nonebot.get_asgi()
@ -148,31 +154,31 @@ nonebot.run(app="bot:app")
##### `quart_reload_dirs`
类型: `Optional[List[str]]`
默认值: `None`
说明: 重载监控文件夹列表，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：重载监控文件夹列表，默认为 uvicorn 默认值
##### `quart_reload_delay`
类型: `Optional[float]`
默认值: `None`
说明: 重载延迟，默认为 uvicorn 默认值
类型：`Optional[float]`
默认值：`None`
说明：重载延迟，默认为 uvicorn 默认值
##### `quart_reload_includes`
类型: `Optional[List[str]]`
默认值: `None`
说明: 要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
##### `quart_reload_excludes`
类型: `Optional[List[str]]`
默认值: `None`
说明: 不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
类型：`Optional[List[str]]`
默认值：`None`
说明：不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
### HTTPX
类型: `ForwardDriver`
类型：`ForwardDriver`
:::warning 注意
本驱动器仅支持 HTTP 请求，不支持 WebSocket 请求。
@ -180,9 +186,9 @@ nonebot.run(app="bot:app")
> HTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.
HTTPX: [文档](https://www.python-httpx.org/), [仓库](https://github.com/encode/httpx/)
HTTPX：[文档](https://www.python-httpx.org/)、[仓库](https://github.com/encode/httpx/)
驱动器: [API](../api/drivers/httpx.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/httpx.py)
驱动器：[API](../api/drivers/httpx.md)、[源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/httpx.py)
```env
DRIVER=~httpx
@ -194,7 +200,7 @@ DRIVER=~httpx
### websockets
类型: `ForwardDriver`
类型：`ForwardDriver`
:::warning 注意
本驱动器仅支持 WebSocket 请求，不支持 HTTP 请求。
@ -202,9 +208,9 @@ DRIVER=~httpx
> websockets is a library for building WebSocket servers and clients in Python with a focus on correctness, simplicity, robustness, and performance.
websockets: [文档](https://websockets.readthedocs.io/en/stable/), [仓库](https://github.com/aaugustin/websockets)
websockets：[文档](https://websockets.readthedocs.io/en/stable/)、[仓库](https://github.com/aaugustin/websockets)
驱动器: [API](../api/drivers/websockets.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/websockets.py)
驱动器：[API](../api/drivers/websockets.md)、[源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/websockets.py)
```env
DRIVER=~websockets
@ -216,13 +222,13 @@ DRIVER=~websockets
### AIOHTTP
类型: `ForwardDriver`
类型：`ForwardDriver`
> Asynchronous HTTP Client/Server for asyncio and Python.
AIOHTTP: [文档](https://docs.aiohttp.org/en/stable/), [仓库](https://github.com/aio-libs/aiohttp)
AIOHTTP：[文档](https://docs.aiohttp.org/en/stable/)、[仓库](https://github.com/aio-libs/aiohttp)
驱动器: [API](../api/drivers/aiohttp.md), [源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/aiohttp.py)
驱动器：[API](../api/drivers/aiohttp.md)、[源码](https://github.com/nonebot/nonebot2/blob/master/nonebot/drivers/aiohttp.py)
```env
DRIVER=~aiohttp

125
website/docs/tutorial/configuration.md
View File

@ -20,12 +20,12 @@ options:
### .env 文件
NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。
NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT`（大小写不敏感），默认值为 `prod`。
这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。
`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。
NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置处理，并对 `pydantic` 的行为做出了更改，详见下方说明。
NoneBot 使用 [Pydantic](https://pydantic-docs.helpmanual.io/) 进行配置处理，并对 Pydantic 的行为做出了更改，详见下方说明。
现在，我们在 `.env` 文件中写入当前环境信息：
@ -42,29 +42,29 @@ CUSTOM_CONFIG=common config # 这个配置项在任何环境中都会被加载
:::
:::warning 提示
由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如：
由于 Pydantic 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如：
```bash
list=["123456789", "987654321", 1]
test={"hello": "world"}
```
如果配置项值解析失败将作为 **字符串** 处理。
如果配置项值解析失败将作为**字符串**处理。
特别的，如果配置项 **为空** ，则会从 **系统环境变量** 中获取值，如果不存在则为空字符串。
特别的，如果配置项**为空**，则会从**系统环境变量**中获取值，如果不存在则为空字符串。
:::
### .env.\* 文件
NoneBot 默认会从 `.env.{ENVIRONMENT}` 文件加载配置，但是可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。
NoneBot 默认会从 `.env.{ENVIRONMENT}` 文件加载配置，但是可以在 NoneBot 初始化时指定加载某个环境配置文件：`nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。
配置语法与 `.env` 文件相同。
示例及说明：
```bash
HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名
PORT=8080 # 配置 NoneBot 监听的端口
HOST=0.0.0.0 # 配置 NoneBot2 监听的 IP/主机名
PORT=8080 # 配置 NoneBot2 监听的端口
SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户
NICKNAME=["awesome", "bot"] # 配置机器人的昵称
COMMAND_START=["/", ""] # 配置命令起始字符
@ -75,7 +75,7 @@ CUSTOM_CONFIG1="config in env file"
CUSTOM_CONFIG2= # 留空则从系统环境变量读取，如不存在则为空字符串
```
详细的配置项可以参考 [配置项](#详细配置项) 。
详细的配置项可以参考[配置项](#详细配置项)。
### 系统环境变量
@ -100,11 +100,11 @@ config.custom_config4 = "new config after init"
## 配置优先级
`bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env`, `.env.*` 文件
`bot.py` 文件（`nonebot.init`）> 系统环境变量 > `.env`、`.env.*` 文件
## 读取配置项
配置项可以通过三种类型的对象获取：`driver`, `adapter`, `bot`。
配置项可以通过三种类型的对象获取：`driver`、`adapter`、`bot`。
```python
import nonebot
@ -125,13 +125,13 @@ nonebot.get_driver()._adapters["adapter_name"].config.custom_config
- **类型**: `str`
- **默认值**: `"~fastapi"`
NoneBot 运行所使用的驱动器。主要分为 `ForwardDriver`, `ReverseDriver` 即客户端和服务端两类。
NoneBot2 运行所使用的驱动器。主要分为 `ForwardDriver`、`ReverseDriver` 即客户端和服务端两类。
配置格式采用特殊语法：`<module>[:<Driver>][+<module>[:<Mixin>]]*`
其中 `<module>` 为驱动器模块名，可以使用 `~` 作为 `nonebot.drivers.` 的简写；`<Driver>` 为驱动器类名，默认为 `Driver`；`<Mixin>` 为驱动器混入的类名，默认为 `Mixin`。
NoneBot 内置了几个常用驱动器，包括了各类常用功能，常见驱动器配置如下：
NoneBot2 内置了几个常用驱动器，包括了各类常用功能，常见驱动器配置如下：
```env
DRIVER=~fastapi
@ -140,6 +140,101 @@ DRIVER=~fastapi+~httpx+~websockets
DRIVER=~fastapi+~aiohttp
```
各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。
各驱动器的功能与区别请参考[选择驱动器](./choose-driver.md)。
<!-- TODO -->
### Host
- **类型**: `IPvAnyAddress`
- **默认值**: `127.0.0.1`
使用 `ReversedDriver` 时，NoneBot2 监听的 IP/主机名。
```env
HOST=127.0.0.1
```
### Port
- **类型**: `int`
- **默认值**: `8080`
使用 `ReversedDriver` 时，NoneBot2 监听的端口。
```env
PORT=8080
```
### Log Level
- **类型**: `int | str`
- **默认值**: `INFO`
NoneBot2 日志输出等级，可以为 `int` 类型等级或等级名称
参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
```env
LOG_LEVEL=INFO
```
:::tip 提示
日志等级名称应为大写，如 `INFO`。
:::
### API Timeout
- **类型**: `Optional[float]`
- **默认值**: `30.0`
API 请求超时时间，单位为秒。
```env
API_TIMEOUT=30.0
```
### SuperUsers
- **类型**: `Set[str]`
- **默认值**: `set()`
机器人超级用户，可以使用权限 [`SUPERUSER`](../api/permission.md#SUPERUSER)。
```env
SUPERUSERS=["1234567890"]
```
### Nickname
- **类型**: `Set[str]`
- **默认值**: `set()`
机器人昵称，通常协议适配器会根据用户是否 @user 或者是否以机器人昵称开头来判断是否是向机器人发送的消息。
```env
NICKNAME=["bot"]
```
### Command Start 和 Command Separator
- **类型**: `Set[str]`
- **默认值**:
- Command Start: `{"/"}`
- Command Separator: `{"."}`
命令消息的起始符和分隔符。用于 [`command`](../api/rule.md#command) 规则。
```env
COMMAND_START={"/", "!"}
COMMAND_SEP={".", "/"}
```
### Session Expire Timeout
- **类型**: `timedelta`
- **默认值**: `timedelta(minutes=2)`
用户会话超时时间，配置格式参考 [Datetime Types](https://pydantic-docs.helpmanual.io/usage/types/#datetime-types)。
```env
SESSION_EXPIRE_TIMEOUT=120
```

67
website/docs/tutorial/create-project.md
View File

@ -1,67 +0,0 @@
---
sidebar_position: 0
description: 创建并运行项目
options:
menu:
weight: 20
category: guide
---
# 创建项目
可以使用 `nb-cli` 或者自行创建完整的项目目录：
```bash
nb create
```
## 目录结构
```bash title=Project
AweSome-Bot
├── "awesome_bot" # 或是 src
│ └── "plugins"
├── ".env" # 可选的
├── ".env.dev" # 可选的
├── ".env.prod" # 可选的
├── .gitignore
├── "bot.py"
├── docker-compose.yml
├── Dockerfile
├── "pyproject.toml"
└── README.md
```
- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
- `.env`, `.env.dev`, `.env.prod`: 各环境配置文件
- `bot.py`: bot 入口文件
- `pyproject.toml`: 项目插件配置文件
- `Dockerfile`, `docker-compose.yml`: Docker 镜像配置文件
## 启动 Bot
:::warning 提示
如果您使用如 `VSCode` / `PyCharm` 等 IDE 启动 nonebot，请检查 IDE 当前工作空间目录是否与当前侧边栏打开目录一致。
> 注意：在二者不一致的环境下可能导致 nonebot 读取配置文件和插件等不符合预期
:::
1. 通过 `nb-cli`
```bash
nb run [--file=bot.py] [--app=app]
```
其中 `--file` 参数可以指定 bot 入口文件，默认为 `bot.py`，`--app` 参数可以指定 asgi server，默认为 `app`。
2. 直接通过 `python` 启动
```bash
python bot.py
```
:::tip 提示
如果在 bot 入口文件内定义了 asgi server， `nb-cli` 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot 实例）
:::

79
website/docs/tutorial/create-project.mdx Normal file
View File

@ -0,0 +1,79 @@
---
sidebar_position: 0
description: 创建并运行项目
options:
menu:
weight: 20
category: guide
---
import Asciinema from "@site/src/components/Asciinema";
# 创建项目
可以使用 `nb-cli` 或者自行创建完整的项目目录:
```bash
nb create
```
<Asciinema
url="https://asciinema.org/a/464654.cast"
options={{ theme: "monokai", startAt: 4.5, poster: "npt:6.5" }}
/>
## 目录结构
```tree title=Project
📦 AweSome-Bot
├── 📂 awesome_bot # 或是 src
│ └── 📜 plugins
├── 📜 .env # 可选的
├── 📜 .env.dev # 可选的
├── 📜 .env.prod # 可选的
├── 📜 .gitignore
├── 📜 bot.py
├── 📜 docker-compose.yml
├── 📜 Dockerfile
├── 📜 pyproject.toml
└── 📜 README.md
```
- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
- `.env`、`.env.dev`、`.env.prod`: 各环境配置文件
- `bot.py`: bot 入口文件
- `pyproject.toml`: 项目插件配置文件
- `Dockerfile`、`docker-compose.yml`: Docker 镜像配置文件
## 启动 Bot
:::warning 提示
如果您使用如 `VSCode` / `PyCharm` 等 IDE 启动 nonebot，请检查 IDE 当前工作空间目录是否与当前侧边栏打开目录一致。
> 注意: 在二者不一致的环境下可能导致 nonebot 读取配置文件和插件等不符合预期
:::
1. 通过 nb-cli
```bash
nb run [--file=bot.py] [--app=app]
```
其中 `--file` 参数可以指定 bot 入口文件，默认为 `bot.py`，`--app` 参数可以指定 asgi server，默认为 `app`。
<Asciinema
url="https://asciinema.org/a/464654.cast"
options={{ theme: "monokai", startAt: 15.3, poster: "npt:20.3" }}
/>
2. 直接通过 Python 启动
```bash
python bot.py
```
:::tip 提示
如果在 bot 入口文件内定义了 asgi server，nb-cli 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot2 实例）
:::

53
website/docs/tutorial/custom-logger.md
View File

@ -4,3 +4,56 @@ description: 修改日志级别与输出
---
# 自定义日志
NoneBot 使用 [Loguru](https://loguru.readthedocs.io/) 进行日志记录，并提供了一些内置的格式和过滤器等。
## 默认日志
NoneBot 启动时会添加一个默认的日志 handler。此 handler 将会将日志输出到 **stdout**，并且根据配置的日志级别进行过滤。
[默认格式](../api/log.md#default_format)):
```python
default_format: str = (
"<g>{time:MM-DD HH:mm:ss}</g> "
"[<lvl>{level}</lvl>] "
"<c><u>{name}</u></c> | "
"{message}"
)
from nonebot.log import default_format
```
[默认过滤器](../api/log.md#default_filter):
```python
from nonebot.log import default_filter
```
## 转移 logging 日志
NoneBot 提供了一个 logging handler 用于将日志输出转移至 loguru 处理。将 logging 的默认 handler 替换为 `LoguruHandler` 即可。
```python
from nonebot.log import LoguruHandler
```
## 自定义日志记录
如果需要移除 NoneBot 的默认日志 handler，可以在 `nonebot.init` 之前进行如下操作：
```python
from nonebot.log import logger, logger_id
logger.remove(logger_id)
```
如果需要添加自定义的日志 handler，可以在 `nonebot.init` 之前添加 handler，参考 [loguru 文档](https://loguru.readthedocs.io/)。
示例：
```python
from nonebot.log import logger, default_format
logger.add("error.log", level="ERROR", format=default_format, rotation="1 week")
```

230
website/docs/tutorial/deployment.md Normal file
View File

@ -0,0 +1,230 @@
---
sidebar_position: 11
description: 部署你的机器人
---
# 部署
在编写完成后，你需要部署你的机器人来使得用户能够使用它。通常，会将机器人部署在服务器上，来保证服务持久运行。
在开发时机器人运行的环境称为开发环境，而在部署后机器人运行的环境称为生产环境。与开发环境不同的是，在生产环境中，开发者通常不能随意地修改/添加/删除代码，开启或停止服务。
## 部署前准备
在生产环境中，为确保机器人能够正常运行，你需要固定你的依赖库版本。下面提供了几种常见的文件格式与生成方式：
- `poetry.lock`
[poetry](https://python-poetry.org/) 依赖管理工具使用的 lock 文件，通常会在安装依赖时自动生成，或者使用 `poetry lock` 来生成。
- `pdm.lock`
[pdm](https://pdm.fming.dev/) 依赖管理工具使用的 lock 文件，通常会在安装依赖时自动生成，或者使用 `pdm lock` 来生成。
- `Pipfile.lock`
[Pipenv](https://pipenv.pypa.io/en/latest/) 依赖管理工具使用的 lock 文件，通常会在安装依赖时自动生成，或者使用 `pipenv lock` 来生成。
- `requirements.txt`
如果你未使用任何依赖管理工具，你可以使用 `pip freeze` 来生成这个文件。
## 使用 Docker 部署（推荐）
请自行参考 [Docker 官方文档](https://docs.docker.com/engine/install/) 安装 Docker。
在生产环境安装 [docker-compose](https://docs.docker.com/compose/) 工具以便部署机器人。
### 编译镜像与部署配置
在项目目录下添加以下两个文件（以 poetry 和 FastAPI 驱动器为例）：
```dockerfile title=Dockerfile
FROM python:3.9 as requirements-stage
WORKDIR /tmp
COPY ./pyproject.toml ./poetry.lock* /tmp/
RUN curl -sSL https://install.python-poetry.org -o install-poetry.py
RUN python install-poetry.py --yes
ENV PATH="${PATH}:/root/.local/bin"
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9
WORKDIR /app
COPY --from=requirements-stage /tmp/requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt
RUN rm requirements.txt
COPY ./ /app/
```
```yaml title=docker-compose.yml
version: "3"
services:
nonebot:
build: .
ports:
- "8080:8080" # 映射端口到宿主机 宿主机端口:容器端口
env_file:
- ".env.prod" # fastapi 使用的环境变量文件
environment:
- ENVIRONMENT=prod
- APP_MODULE=bot:app
- MAX_WORKERS=1
network_mode: bridge
```
配置完成后即可使用 `docker-compose up -d` 命令来启动机器人并在后台运行。
### CI/CD
配合 GitHub Actions 可以完成 CI/CD，在 GitHub 上发布 Release 时自动部署至生产环境。
在 [Docker Hub](https://hub.docker.com/) 上创建仓库，并将下方 workflow 文件中高亮行中的仓库名称替换为你的仓库名称。
前往项目仓库的 `Settings` > `Secrets` > `actions` 栏目 `New Repository Secret` 添加部署所需的密钥：
- `DOCKERHUB_USERNAME`: 你的 Docker Hub 用户名
- `DOCKERHUB_PASSWORD`: 你的 Docker Hub PAT（[创建方法](https://docs.docker.com/docker-hub/access-tokens/)）
- `DEPLOY_HOST`: 部署服务器 IP 地址
- `DEPLOY_USER`: 部署服务器用户名
- `DEPLOY_KEY`: 部署服务器私钥
- `DEPLOY_PATH`: 部署服务器上的项目路径
将以下文件添加至项目下的 `.github/workflows/` 目录下：
```yaml title=.github/workflows/build.yml {30}
name: Docker Hub Release
on:
push:
tags:
- "v*"
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup Docker
uses: docker/setup-buildx-action@v1
- name: Login to DockerHub
uses: docker/login-action@v1
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
- name: Generate Tags
uses: docker/metadata-action@v3
id: metadata
with:
images: |
{organization}/{repository}
tags: |
type=semver,pattern={{version}}
type=sha
- name: Build and Publish
uses: docker/build-push-action@v2
with:
context: .
push: true
tags: ${{ steps.metadata.outputs.tags }}
labels: ${{ steps.metadata.outputs.labels }}
```
```yaml title=.github/workflows/deploy.yml
name: Deploy
on:
workflow_run:
workflows:
- Docker Hub Release
types:
- completed
jobs:
deploy:
runs-on: ubuntu-latest
if: ${{ github.event.workflow_run.conclusion == 'success' }}
steps:
- name: start deployment
uses: bobheadxi/deployments@v0.6
id: deployment
with:
step: start
token: ${{ secrets.GITHUB_TOKEN }}
env: official-bot
- name: remote ssh command
uses: appleboy/ssh-action@master
env:
DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_KEY }}
envs: DEPLOY_PATH
script: |
cd $DEPLOY_PATH
docker-compose down
docker-compose pull
docker-compose up -d
- name: update deployment status
uses: bobheadxi/deployments@v0.6
if: always()
with:
step: finish
token: ${{ secrets.GITHUB_TOKEN }}
status: ${{ job.status }}
deployment_id: ${{ steps.deployment.outputs.deployment_id }}
```
将上一部分的 `docker-compose.yml` 文件以及 `.env.prod` 配置文件添加至 `DEPLOY_PATH` 目录下，并修改 `docker-compose.yml` 文件中的镜像配置，替换为 Docker Hub 的仓库名称。
```diff
- build: .
+ image: {organization}/{repository}:latest
```
## 使用 Supervisor 部署
参考：[Uvicorn - Supervisor](https://www.uvicorn.org/deployment/#supervisor)
```ini
[supervisord]
[fcgi-program:nonebot]
socket=tcp://localhost:8080
command=python3 -m uvicorn --fd 0 bot:app
directory=/path/to/bot
autorestart=true
startsecs=10
startretries=3
numprocs=1
process_name=%(program_name)s-%(process_num)d
stdout_logfile=/path/to/log/nonebot.out.log
stdout_logfile_maxbytes=2MB
```
:::warning 警告
请配合虚拟环境使用，如 venv 等，请勿直接在 Linux 服务器系统环境中安装。
:::
## 使用 PM2 部署
<!-- TODO -->

4
website/docs/tutorial/plugin/config-plugin.md
View File

@ -9,7 +9,7 @@ description: 规范定义插件配置项
## 定义配置模型
在 NoneBot 中，我们使用强大高效的 [Pydantic](https://pydantic-docs.helpmanual.io/) 来定义配置模型，这个模型可以被用于配置的读取和类型检查等。例如，我们可以定义一个配置模型包含一个 string 类型的配置项：
在 NoneBot2 中，我们使用强大高效的 [Pydantic](https://pydantic-docs.helpmanual.io/) 来定义配置模型，这个模型可以被用于配置的读取和类型检查等。例如，我们可以定义一个配置模型包含一个 string 类型的配置项：
```python title=config.py {3,4}
from pydantic import BaseModel, Extra
@ -19,7 +19,7 @@ class Config(BaseModel, extra=Extra.ignore):
```
:::important 参考
更多丰富的模型定义方法（默认值，自定义 validator 等），请参考 [Pydantic](https://pydantic-docs.helpmanual.io/) 文档。
更多丰富的模型定义方法（默认值、自定义 validator 等），请参考 [Pydantic](https://pydantic-docs.helpmanual.io/) 文档。
:::
## 读取配置

104
website/docs/tutorial/plugin/create-handler.md
View File

@ -14,7 +14,7 @@ options:
## 添加一个处理依赖
在事件响应器中，事件处理流程由一个或多个处理依赖组成，每个处理依赖都是一个 `Dependent`，详情可以参考 [进阶 - 依赖注入](../../advanced/di/dependency-injection.md)。下面介绍如何添加一个处理依赖。
在事件响应器中，事件处理流程由一个或多个处理依赖组成，每个处理依赖都是一个 `Dependent`，详情可以参考[进阶 - 依赖注入](../../advanced/di/dependency-injection.md)。下面介绍如何添加一个处理依赖。
### 使用 `handle` 装饰器
@ -28,7 +28,7 @@ async def handle_func():
如上方示例所示，我们使用 `matcher` 响应器的 `handle` 装饰器装饰了一个函数 `handle_func` 。`handle_func` 函数会被自动转换为 `Dependent` 对象，并被添加到 `matcher` 的事件处理流程中。
在 `handle_func` 函数中，我们可以编写任何事件响应逻辑，如：操作数据库，发送消息等。上下文信息可以通过依赖注入的方式获取，参考：[获取上下文信息](#获取上下文信息)。发送消息可以通过 [事件响应器操作](./matcher-operation.md) 或者直接调用 Bot 的方法（ API 等，由协议适配器决定）。
在 `handle_func` 函数中，我们可以编写任何事件响应逻辑，如：操作数据库，发送消息等。上下文信息可以通过依赖注入的方式获取，参考：[获取上下文信息](#获取上下文信息)。发送消息可以通过[事件响应器操作](./matcher-operation.md)或者直接调用 Bot 的方法（ API 等，由协议适配器决定）。
:::warning 注意
`handle_func` 函数虽然会被装饰器自动转换为 `Dependent` 对象，但 `handle_func` 仍然为原本的函数，因此 `handle_func` 函数可以进行复用。如：
@ -57,9 +57,9 @@ async def handle_func(e: Event = Received("id")):
`receive` 装饰器与 `handle` 装饰器一样，可以装饰一个函数添加到事件响应器的事件处理流程中。但与 `handle` 装饰器不同的是，`receive` 装饰器会中断当前事件处理流程，等待接收一个新的事件，就像是会话状态等待用户一个新的事件。可以接收的新的事件类型取决于事件响应器的 [`type`](./create-matcher.md#事件响应器类型-type) 更新值以及 [`permission`](./create-matcher.md#事件触发权限-permission) 更新值，可以通过自定义更新方法来控制会话响应（如进行非消息交互、多人会话、跨群会话等）。
`receive` 装饰器接受一个可选参数 `id` ，用于标识当前需要接收的事件，如果不指定，则默认为空 `""`。
`receive` 装饰器接受一个可选参数 `id`，用于标识当前需要接收的事件，如果不指定，则默认为空 `""`。
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的事件，参考：[`Received`](#received), [`LastReceived`](#lastreceived)。
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的事件，参考：[`Received`](#received)、[`LastReceived`](#lastreceived)。
:::important 提示
`receive` 装饰器可以和自身与 `got` 装饰器嵌套使用
@ -93,7 +93,7 @@ async def handle_func(key: Message = Arg()):
`got` 装饰器接受一个参数 `key` 和一个可选参数 `prompt`，当 `key` 不存在时，会向用户发送 `prompt` 消息，并等待用户回复。
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的消息，参考：[`Arg`](#arg), [`ArgStr`](#argstr), [`ArgPlainText`](#argplaintext)。
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的消息，参考：[`Arg`](#arg)、[`ArgStr`](#argstr)、[`ArgPlainText`](#argplaintext)。
:::important 提示
`got` 装饰器可以和自身与 `receive` 装饰器嵌套使用
@ -113,12 +113,16 @@ matcher = on_message(
## 事件处理流程
<!-- TODO -->
在一个事件响应器中，事件被添加的处理依赖依次执行，直到所有处理依赖都执行完毕，或者遇到了某个处理依赖需要更多的事件来进行下一步的处理。在下一个事件到来并符合响应要求时，继续执行。更多有关 NoneBot 事件分发与处理流程的详细信息，请参考[进阶 - 深入](../../advanced/README.md)。
## 获取上下文信息
在事件处理流程中，事件响应器具有自己独立的上下文，例如：当前的事件、机器人等信息，可以通过依赖注入的方式来获取。
### Bot
获取当前事件的 Bot 对象。
```python {7-9}
from typing import Union
@ -133,6 +137,8 @@ async def _(bot): ... # 兼容性处理
### Event
获取当前事件。
```python {6-8}
from typing import Union
@ -146,6 +152,8 @@ async def _(event): ... # 兼容性处理
### EventType
获取当前事件的类型。
```python {3}
from nonebot.params import EventType
@ -154,6 +162,8 @@ async def _(foo: str = EventType()): ...
### EventMessage
获取当前事件的消息。
```python {4}
from nonebot.adapters import Message
from nonebot.params import EventMessage
@ -163,6 +173,8 @@ async def _(foo: str = EventMessage()): ...
### EventPlainText
获取当前事件的消息纯文本部分。
```python {3}
from nonebot.params import EventPlainText
@ -171,6 +183,8 @@ async def _(foo: str = EventPlainText()): ...
### EventToMe
获取当前事件是否与机器人相关。
```python {3}
from nonebot.params import EventToMe
@ -179,15 +193,18 @@ async def _(foo: bool = EventToMe()): ...
### State
获取当前事件处理上下文状态，State 为一个字典，用户可以向 State 中添加数据来保存状态等操作。（请注意不要随意覆盖 State 中 NoneBot 的数据）
```python {4}
from nonebot.params import State
from nonebot.typing import T_State
async def _(foo: T_State = State()): ...
async def _(foo: T_State): ...
```
### Command
获取当前命令型消息的元组形式命令名。
```python {7}
from nonebot import on_command
from nonebot.params import Command
@ -198,8 +215,32 @@ matcher = on_command("cmd")
async def _(foo: Tuple[str, ...] = Command()): ...
```
:::tip 提示
命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。
:::
### RawCommand
获取当前命令型消息的文本形式命令名。
```python {7}
from nonebot import on_command
from nonebot.params import RawCommand
matcher = on_command("cmd")
@matcher.handle()
async def _(foo: str = RawCommand()): ...
```
:::tip 提示
命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。
:::
### CommandArg
获取命令型消息命令后跟随的参数。
```python {8}
from nonebot import on_command
from nonebot.adapters import Message
@ -211,22 +252,41 @@ matcher = on_command("cmd")
async def _(foo: Message = CommandArg()): ...
```
:::tip 提示
命令详情只能在首次接收到命令型消息时获取，如果在事件处理后续流程中获取，则会获取到不同的值。
:::
### ShellCommandArgs
```python {7}
from nonebot import on_command
获取 shell 命令解析后的参数。
:::tip 提示
如果参数解析失败，则为 [`ParserExit`](../../api/exception.md#ParserExit) 异常，并携带错误码与错误信息。
由于 `ArgumentParser` 在解析到 `--help` 参数时也会抛出异常，这种情况下错误码为 `0` 且错误信息即为帮助信息。
:::
```python {8,12}
from nonebot import on_shell_command
from nonebot.params import ShellCommandArgs
matcher = on_shell_command("cmd", parser)
# 解析失败
@matcher.handle()
async def _(foo: ParserExit = ShellCommandArgs()): ...
# 解析成功
@matcher.handle()
async def _(foo: Dict[str, Any] = ShellCommandArgs()): ...
```
### ShellCommandArgv
获取 shell 命令解析前的参数列表。
```python {7}
from nonebot import on_command
from nonebot import on_shell_command
from nonebot.params import ShellCommandArgs
matcher = on_shell_command("cmd")
@ -237,6 +297,8 @@ async def _(foo: List[str] = ShellCommandArgv()): ...
### RegexMatched
获取正则匹配结果。
```python {7}
from nonebot import on_regex
from nonebot.params import RegexMatched
@ -249,6 +311,8 @@ async def _(foo: str = RegexMatched()): ...
### RegexGroup
获取正则匹配结果的 group 元组。
```python {7}
from nonebot import on_regex
from nonebot.params import RegexGroup
@ -261,6 +325,8 @@ async def _(foo: Tuple[Any, ...] = RegexGroup()): ...
### RegexDict
获取正则匹配结果的 group 字典。
```python {7}
from nonebot import on_regex
from nonebot.params import RegexDict
@ -273,6 +339,8 @@ async def _(foo: Dict[str, Any] = RegexDict()): ...
### Matcher
获取当前事件响应器实例。
```python {7}
from nonebot import on_message
from nonebot.matcher import Matcher
@ -285,6 +353,8 @@ async def _(matcher: Matcher): ...
### Received
获取某次 `receive` 接收的事件。
```python {8}
from nonebot import on_message
from nonebot.adapters import Event
@ -298,6 +368,8 @@ async def _(foo: Event = Received("id")): ...
### LastReceived
获取最近一次 `receive` 接收的事件。
```python {8}
from nonebot import on_message
from nonebot.adapters import Event
@ -311,6 +383,8 @@ async def _(foo: Event = LastReceived()): ...
### Arg
获取某次 `got` 接收的参数。
```python {8-9}
from nonebot.params import Arg
from nonebot import on_message
@ -325,6 +399,8 @@ async def _(foo: Message = Arg("key")): ...
### ArgStr
获取某次 `got` 接收的参数，并转换为字符串。
```python {7-8}
from nonebot import on_message
from nonebot.params import ArgStr
@ -338,6 +414,8 @@ async def _(foo: str = ArgStr("key")): ...
### ArgPlainText
获取某次 `got` 接收的参数的纯文本部分。
```python {7-8}
from nonebot import on_message
from nonebot.params import ArgPlainText
@ -351,6 +429,8 @@ async def _(foo: str = ArgPlainText("key")): ...
### Exception
获取事件响应器运行中抛出的异常。
```python {4}
from nonebot.message import run_postprocessor
@ -360,6 +440,8 @@ async def _(e: Exception): ...
### Default
带有默认值的参数，便于复用依赖。
```python {1}
async def _(foo="bar"): ...
```

20
website/docs/tutorial/plugin/create-matcher.md
View File

@ -10,15 +10,15 @@ options:
# 定义事件响应器
事件响应器 (`Matcher`) 是对接收到的事件进行响应的基本单元，所有的事件响应器都继承自 `Matcher` 基类。为方便编写插件，NoneBot 在 `nonebot.plugin` 模块中为插件开发定义了一些辅助函数，以便插件开发者可以简化插件开发。首先，让我们来了解一下 `Matcher` 由哪些部分组成。
事件响应器（`Matcher`）是对接收到的事件进行响应的基本单元，所有的事件响应器都继承自 `Matcher` 基类。为了方便开发者编写插件，NoneBot2 在 `nonebot.plugin` 模块中为插件开发定义了一些辅助函数。首先，让我们来了解一下 `Matcher` 由哪些部分组成。
## 事件响应器的基本组成
### 事件响应器类型 `type`
事件响应器的类型即是该响应器所要响应的事件类型，只有在接收到的事件类型与该响应器的类型相同时，才会触发该响应器。如果类型留空，则该响应器将会响应所有类型的事件。
事件响应器的类型即是该响应器所要响应的事件类型，只有在接收到的事件类型与该响应器的类型相同时，才会触发该响应器。如果类型留空，该响应器将会响应所有类型的事件。
NoneBot 内置了四种主要类型：`meta_event`, `message`, `notice`, `request`。通常情况下，协议适配器会将事件合理的分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
NoneBot 内置了四种主要类型：`meta_event`、`message`、`notice`、`request`。通常情况下，协议适配器会将事件合理地分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
<!-- TODO: move session updater to advanced -->
@ -37,11 +37,11 @@ async def update_type():
:::
### 事件匹配规则 `rule`
### 事件匹配规则
事件响应器的匹配规则是一个 `Rule` 对象，它是一系列 `checker` 的集合，当所有的 `checker` 都返回 `True` 时，才会触发该响应器。
规则编写方法参考 [自定义规则](#自定义规则)。
规则编写方法参考[自定义规则](#自定义规则)。
:::warning 注意
当会话状态更新时，`rule` 会被清空，以便会话收到新事件时能够正确匹配。
@ -51,12 +51,12 @@ async def update_type():
事件响应器的触发权限是一个 `Permission` 对象，它也是一系列 `checker` 的集合，当其中一个 `checker` 返回 `True` 时，就会触发该响应器。
权限编写方法参考 [自定义权限](#自定义权限)。
权限编写方法参考[自定义权限](#自定义权限)。
:::warning 注意
与 `rule` 不同的是，`permission` 不会在会话状态更新时丢失，因此 `permission` 通常用于会话的响应控制。
并且, 当会话状态更新时，会执行 `permission_updater` 以更新 `permission`。默认情况下，`permission_updater` 会在原有的 `permission` 基础上添加一个 `USER` 条件，以检查事件的 `session_id` 是否与当前会话一致。
并且，当会话状态更新时，会执行 `permission_updater` 以更新 `permission`。默认情况下，`permission_updater` 会在原有的 `permission` 基础上添加一个 `USER` 条件，以检查事件的 `session_id` 是否与当前会话一致。
你可以自行定义 `permission_updater` 来控制会话的响应权限更新。`permission_updater` 是一个返回 `Permission` 的函数，可选依赖注入参数参考类型 `T_PermissionUpdater`。
@ -75,7 +75,7 @@ async def update_type(matcher: Matcher):
事件响应器的优先级代表事件响应器的执行顺序
:::warning 警告
同一优先级的事件响应器会 **同时执行**，优先级数字 **越小** 越先响应！优先级请从 `1` 开始排序！
同一优先级的事件响应器会**同时执行**，优先级数字**越小**越先响应！优先级请从 `1` 开始排序！
:::
### 阻断 `block`
@ -94,7 +94,7 @@ async def handle(matcher: Matcher):
matcher.stop_propagation()
```
### 有效期 `temp` / `expire_time`
### 有效期 `temp`/`expire_time`
事件响应器可以设置有效期，当事件响应器超过有效期时，将会被移除。
@ -111,7 +111,7 @@ from nonebot import on_message
matcher = on_message()
```
用于定义事件响应器的辅助函数已经在 `nonebot` 主模块中被 `re-export` ，所以直接从 `nonebot` 导入即可。
用于定义事件响应器的辅助函数已经在 `nonebot` 主模块中被 `re-export`，所以直接从 `nonebot` 导入即可。
辅助函数有以下几种：

66
website/docs/tutorial/plugin/introduction.md
View File

@ -9,51 +9,51 @@ description: 插件入门
在编写插件之前，首先我们需要了解一下插件的概念。
在 NoneBot 中，插件可以是 Python 的一个模块 `module` ，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
在 NoneBot 中，插件可以是 Python 的一个模块 `module`，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
下面详细介绍两种插件的结构：
### 模块插件（单文件形式）
在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../create-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
在合适的路径创建一个 `.py` 文件即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
```bash title=Project {4}
AweSome-Bot
├── awesome_bot
│ └── plugins
| └── foo.py
├── .env
├── .env.dev
├── .env.prod
├── .gitignore
├── bot.py
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
└── README.md
```tree title=Project {4}
📦 AweSome-Bot
├── 📂 awesome_bot
│ └── 📂 plugins
| └── 📜 foo.py
├── 📜 .env
├── 📜 .env.dev
├── 📜 .env.prod
├── 📜 .gitignore
├── 📜 bot.py
├── 📜 docker-compose.yml
├── 📜 Dockerfile
├── 📜 pyproject.toml
└── 📜 README.md
```
这个时候它已经可以被称为一个插件了，尽管它还什么都没做。
### 包插件（文件夹形式）
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../create-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
```bash title=Project {4,5}
AweSome-Bot
├── awesome_bot
│ └── plugins
| └── foo.py
| └── __init__.py
├── .env
├── .env.dev
├── .env.prod
├── .gitignore
├── bot.py
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
└── README.md
```tree title=Project {4,5}
📦 AweSome-Bot
├── 📂 awesome_bot
│ └── 📂 plugins
| └── 📂 foo
| └── 📜 __init__.py
├── 📜 .env
├── 📜 .env.dev
├── 📜 .env.prod
├── 📜 .gitignore
├── 📜 bot.py
├── 📜 docker-compose.yml
├── 📜 Dockerfile
├── 📜 pyproject.toml
└── 📜 README.md
```
这个时候 `foo` 就是一个合法的 Python 包了，同时也是合法的 NoneBot 插件，插件内容可以在 `__init__.py` 中编写。
@ -64,7 +64,7 @@ AweSome-Bot
请注意，插件名称不能存在重复，即所有模块插件的文件名和所有包插件的文件夹名不能存在相同。
:::
除了通过手动创建的方式以外，还可以通过 `nb-cli` 来创建插件，`nb-cli` 会为你在合适的位置创建一个模板包插件。
除了通过手动创建的方式以外，还可以通过 nb-cli 来创建插件，nb-cli 会为你在合适的位置创建一个模板包插件。
```bash
nb plugin create

6
website/docs/tutorial/plugin/load-plugin.md
View File

@ -11,10 +11,10 @@ options:
# 加载插件
:::danger 警告
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot 无法将其转换为插件而损失部分功能。
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot2 无法将其转换为插件而损失部分功能。
:::
加载插件通常在机器人的入口文件进行，例如在 [创建项目](../create-project.md) 中创建的项目中的 `bot.py` 文件。在 NoneBot 初始化完成后即可加载插件。
加载插件通常在机器人的入口文件进行，例如在[创建项目](../create-project.mdx)中创建的项目中的 `bot.py` 文件。在 NoneBot2 初始化完成后即可加载插件。
```python title=bot.py {5}
import nonebot
@ -50,7 +50,7 @@ nonebot.load_plugins("src/plugins", "path/to/your/plugins")
## `load_all_plugins`
这种加载方式是以上两种方式的融合，加载所有传入的插件模块名称，以及所有给定目录下的插件。例如：
这种加载方式是以上两种方式的混合，加载所有传入的插件模块名称，以及所有给定目录下的插件。例如：
```python
nonebot.load_all_plugins(["path.to.your.plugin"], ["path/to/your/plugins"])

109
website/docs/tutorial/plugin/matcher-operation.md
View File

@ -10,28 +10,137 @@ options:
# 事件响应器操作
在事件处理流程中，我们可以使用事件响应器操作来进行一些交互或改变事件处理流程。
## send
向用户回复一条消息。回复的方式或途径由协议适配器自行实现。
可以是 `str`、[`Message`](../../api/adapters/index.md#Message)、[`MessageSegment`](../../api/adapters/index.md#MessageSegment) 或 [`MessageTemplate`](../../api/adapters/index.md#MessageTemplate)。
这个操作等同于使用 `bot.send(event, message, **kwargs)` 但不需要自行传入 `event`。
```python {3}
@matcher.handle()
async def _():
await matcher.send("Hello world!")
```
## finish
向用户回复一条消息（可选），并立即结束当前事件的整个处理流程。
参数与 [`send`](#send) 相同。
```python {3}
@matcher.handle()
async def _():
await matcher.finish("Hello world!")
# something never run
...
```
## pause
向用户回复一条消息（可选），并立即结束当前事件处理依赖并等待接收一个新的事件后进入下一个事件处理依赖。
类似于 `receive` 的行为但可以根据事件来决定是否接收新的事件。
```python {4}
@matcher.handle()
async def _():
if serious:
await matcher.pause("Confirm?")
@matcher.handle()
async def _():
...
```
## reject
向用户回复一条消息（可选），并立即结束当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。
通常用于拒绝当前 `receive` 接收的事件或 `got` 接收的参数（如：不符合格式或标准）。
```python {4}
@matcher.got("arg")
async def _(arg: str = ArgPlainText()):
if not is_valid(arg):
await matcher.reject("Invalid arg!")
```
## reject_arg
向用户回复一条消息（可选），并立即结束当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。
用于拒绝指定 `got` 接收的参数，通常在嵌套装饰器时使用。
```python {4}
@matcher.got("a")
@matcher.got("b")
async def _(a: str = ArgPlainText(), b: str = ArgPlainText()):
if a not in b:
await matcher.reject_arg("a", "Invalid a!")
```
## reject_receive
向用户回复一条消息（可选），并立即结束当前事件处理依赖并等待接收一个新的事件后再次执行当前事件处理依赖。
用于拒绝指定 `receive` 接收的事件，通常在嵌套装饰器时使用。
```python {4}
@matcher.receive("a")
@matcher.receive("b")
async def _(a: Event = Received("a"), b: Event = Received("b")):
if a.get_user_id() != b.get_user_id():
await matcher.reject_receive("a")
```
## skip
立即结束当前事件处理依赖，进入下一个事件处理依赖。
通常在子依赖中使用，用于跳过当前事件处理依赖的执行。
```python {2}
async def dependency(matcher: Matcher):
matcher.skip()
@matcher.handle()
async def _(sub=Depends(dependency)):
# never run
...
```
## get_receive
获取一个 `receive` 接收的事件。
## set_receive
设置/覆盖一个 `receive` 接收的事件。
## get_last_receive
获取最近一次 `receive` 接收的事件。
## get_arg
获取一个 `got` 接收的参数。
## set_arg
设置/覆盖一个 `got` 接收的参数。
## stop_propagation
阻止事件向更低优先级的事件响应器传播。
```python
@foo.handle()
async def _(matcher: Matcher):
matcher.stop_propagation()
```

252
website/docs/tutorial/process-message.md Normal file
View File

@ -0,0 +1,252 @@
---
sidebar_position: 9
description: 处理消息序列与消息段
options:
menu:
weight: 30
category: guide
---
# 处理消息
## NoneBot2 中的消息
在不同平台中，一条消息可能会有承载有各种不同的表现形式，它可能是一段纯文本、一张图片、一段语音、一篇富文本文章，也有可能是多种类型的组合等等。
在 NoneBot2 中，为确保消息的正常处理与跨平台兼容性，采用了扁平化的消息序列形式，即 `Message` 对象。
`Message` 是多个消息段 `MessageSegment` 的集合，它继承自 `List[MessageSegment]`，并在此基础上添加或强化了一些特性。
`MessageSegment` 是一个 [`dataclass`](https://docs.python.org/zh-cn/3/library/dataclasses.html#dataclasses.dataclass) ，它具有一个类型标识 `type`，以及一些对应的数据信息 `data`。
此外，NoneBot2 还提供了 `MessageTemplate` ，用于构建支持消息序列以及消息段的特殊消息模板。
## 使用消息序列
通常情况下，适配器在接收到消息时，会将消息转换为消息序列，可以通过 [`EventMessage`](./plugin/create-handler.md#EventMessage) 作为依赖注入, 或者使用 `event.get_message()` 获取。
由于它是`List[MessageSegment]`的子类, 所以你总是可以用和操作 List 类似的方式来处理消息序列
```python
>>> message = Message([
MessageSegment(type='text', data={'text':'hello'}),
MessageSegment(type='image', data={'url':'http://example.com/image.png'}),
MessageSegment(type='text', data={'text':'world'}),
])
>>> for segment in message:
... print(segment.type, segment.data)
...
text {'text': 'hello'}
image {'url': 'http://example.com/image.png'}
text {'text': 'world'}
>>> len(message)
3
```
### 构造消息序列
在使用事件响应器操作发送消息时，既可以使用 `str` 作为消息，也可以使用 `Message`、`MessageSegment` 或者 `MessageTemplate`。那么，我们就需要先构造一个消息序列。
#### 直接构造
`Message` 类可以直接实例化，支持 `str`、`MessageSegment`、`Iterable[MessageSegment]` 或适配器自定义类型的参数。
```python
# str
Message("Hello, world!")
# MessageSegment
Message(MessageSegment.text("Hello, world!"))
# List[MessageSegment]
Message([MessageSegment.text("Hello, world!")])
```
#### 运算构造
`Message` 对象可以通过 `str`、`MessageSegment` 相加构造，详情请参考[拼接消息](#拼接消息)。
#### 从字典数组构造
`Message` 对象支持 Pydantic 自定义类型构造，可以使用 Pydantic 的 `parse_obj_as` (`parse_raw_as`) 方法进行构造。
```python
from pydantic import parse_obj_as
# 由字典构造消息段
parse_obj_as(
MessageSegment, {"type": "text", "data": {"text": "text"}}
) == MessageSegment.text("text")
# 由字典数组构造消息序列
parse_obj_as(
Message,
[MessageSegment.text("text"), {"type": "text", "data": {"text": "text"}}],
) == Message([MessageSegment.text("text"), MessageSegment.text("text")])
```
:::tip 提示
以上示例中的字典数据仅做参考，具体的数据格式由适配器自行定义。
:::
### 获取消息纯文本
由于消息中存在各种类型的消息段，因此 `str(message)` 通常并不能得到消息的纯文本，而是一个消息序列的字符串表示。
NoneBot2 为消息段定义了一个方法 `is_text()` ，可以用于判断消息段是否为纯文本；也可以使用 `message.extract_plain_text()` 方法获取消息纯文本。
```python
# 判断消息段是否为纯文本
MessageSegment.text("text").is_text() == True
# 提取消息纯文本字符串
Message(
[MessageSegment.text("text"), MessageSegment.at(123)]
).extract_plain_text() == "text"
```
### 遍历
`Message` 继承自 `List[MessageSegment]` ，因此可以使用 `for` 循环遍历消息段。
```python
for segment in message:
...
```
### 索引与切片
`Message` 对列表的索引与切片进行了增强，在原有列表 int 索引与切片的基础上，支持 `type` 过滤索引与切片。
```python
message = Message(
[
MessageSegment.text("test"),
MessageSegment.image("test2"),
MessageSegment.image("test3"),
MessageSegment.text("test4"),
]
)
# 索引
message[0] == MessageSegment.text("test")
# 切片
message[0:2] == Message(
[MessageSegment.text("test"), MessageSegment.image("test2")]
)
# 类型过滤
message["image"] == Message(
[MessageSegment.image("test2"), MessageSegment.image("test3")]
)
# 类型索引
message["image", 0] == MessageSegment.image("test2")
# 类型切片
message["image", 0:2] == Message(
[MessageSegment.image("test2"), MessageSegment.image("test3")]
)
```
同样的，`Message` 对列表的 `index`、`count` 方法也进行了增强，可以用于索引指定类型的消息段。
```python
# 指定类型首个消息段索引
message.index("image") == 1
# 指定类型消息段数量
message.count("image") == 2
```
此外，`Message` 添加了一个 `get` 方法，可以用于获取指定类型指定个数的消息段。
```python
# 获取指定类型指定个数的消息段
message.get("image", 1) == Message([MessageSegment.image("test2")])
```
### 拼接消息
`str`、`Message`、`MessageSegment` 对象之间可以直接相加，相加均会返回一个新的 `Message` 对象。
```python
# 消息序列与消息段相加
Message([MessageSegment.text("text")]) + MessageSegment.text("text")
# 消息序列与字符串相加
Message([MessageSegment.text("text")]) + "text"
# 消息序列与消息序列相加
Message([MessageSegment.text("text")]) + Message([MessageSegment.text("text")])
# 字符串与消息序列相加
"text" + Message([MessageSegment.text("text")])
# 消息段与消息段相加
MessageSegment.text("text") + MessageSegment.text("text")
# 消息段与字符串相加
MessageSegment.text("text") + "text"
# 消息段与消息序列相加
MessageSegment.text("text") + Message([MessageSegment.text("text")])
# 字符串与消息段相加
"text" + MessageSegment.text("text")
```
如果需要在当前消息序列后直接拼接新的消息段，可以使用 `Message.append`、`Message.extend` 方法，或者使用自加。
```python
msg = Message([MessageSegment.text("text")])
# 自加
msg += "text"
msg += MessageSegment.text("text")
msg += Message([MessageSegment.text("text")])
# 附加
msg.append("text")
msg.append(MessageSegment.text("text"))
# 扩展
msg.extend([MessageSegment.text("text")])
```
## 使用消息模板
为了提供安全可靠的跨平台模板字符, 我们提供了一个消息模板功能来构建消息序列
它在以下常见场景中尤其有用:
- 多行富文本编排(包含图片,文字以及表情等)
- 客制化(由 Bot 最终用户提供消息模板时)
在事实上, 它的用法和`str.format`极为相近, 所以你在使用的时候, 总是可以参考[Python 文档](https://docs.python.org/zh-cn/3/library/stdtypes.html#str.format)来达到你想要的效果
这里给出几个简单的例子:
:::tip
这里面所有的`Message`均是用对应 Adapter 的实现导入的, 而不是抽象基类
:::
```python title="基础格式化用法"
>>> Message.template("{} {}").format("hello", "world")
Message(
MessageSegment.text("hello"),
MessageSegment.text(" "),
MessageSegment.text("world")
)
```
```python title="对消息段进行安全的拼接"
>>> Message.template("{} {}").format(MessageSegment.image("file:///..."), "world")
Message(
MessageSegment(type='image', data={'file': 'file:///...'}),
MessageSegment(type='text', data={'text': 'world'})
)
```
```python title="以消息对象作为模板"
>>> Message.template(
... MessageSegment.text('test {user_id}') + MessageSegment.face(233) +
... MessageSegment.text('test {message}')).format_map({'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'})
)
```
```python title="使用消息段的拓展格式规格"
>>> Message.template("{link:image}").format(link='https://...')
Message(MessageSegment(type='image', data={'file': 'https://...'}))
```

10
website/docs/tutorial/register-adapter.md
View File

@ -11,20 +11,20 @@ options:
# 使用适配器
:::tip 提示
如何**安装**协议适配器请参考 [安装协议适配器](../start/install-adapter.md)
如何**安装**协议适配器请参考[安装协议适配器](../start/install-adapter.mdx)。
:::
## 协议适配器的功能
由于 NoneBot 的跨平台特性，需要支持不同的协议，因此需要对特定的平台协议编写一个转换器。
由于 NoneBot2 的跨平台特性，需要支持不同的协议，因此需要对特定的平台协议编写一个转换器。
协议适配器即是充当中间人的转换器，它将驱动器所收到的数据转换为可以被 NoneBot 处理的事件 Event，并将事件传递给 NoneBot。
协议适配器即是充当中间人的转换器，它将驱动器所收到的数据转换为可以被 NoneBot2 处理的事件 Event，并将事件传递给 NoneBot2。
同时，协议适配器还会处理 API 调用，转换为可以被驱动器处理的数据发送出去。
## 注册协议适配器
NoneBot 在默认情况下并不会加载任何协议适配器，需要自己手动注册。下方是个加载协议适配器的例子：
NoneBot2 在默认情况下并不会加载任何协议适配器，需要自己手动注册。下方是个加载协议适配器的例子：
```python title=bot.py
import nonebot
@ -56,7 +56,7 @@ nonebot.run()
### 获得驱动器实例
加载协议适配器需要通过驱动器来进行，因此，你需要先初始化 NoneBot，并获得驱动器实例。
加载协议适配器需要通过驱动器来进行，因此，你需要先初始化 NoneBot2，并获得驱动器实例。
```python title=bot.py {4,5}
import nonebot

12
website/docusaurus.config.js
View File

@ -22,7 +22,7 @@ const config = {
"zh-Hans": { label: "简体中文" },
},
},
scripts: ["/unregister-sw.js"],
presets: [
@ -36,6 +36,12 @@ const config = {
editUrl: "https://github.com/nonebot/nonebot2/edit/master/website/",
showLastUpdateAuthor: true,
showLastUpdateTime: true,
// exclude: [
// "**/_*.{js,jsx,ts,tsx,md,mdx}",
// "**/_*/**",
// "**/*.test.{js,jsx,ts,tsx}",
// "**/__tests__/**",
// ],
},
sitemap: {
changefreq: "daily",
@ -149,15 +155,13 @@ const config = {
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
additionalLanguages: ["docker", "ini"],
},
algolia: {
appId: "X0X5UACHZQ",
apiKey: "ac03e1ac2bd0812e2ea38c0cc1ea38c5",
indexName: "nonebot",
contextualSearch: true,
// searchParameters: {
// facetFilters: ["lang:zh-CN"],
// },
},
tailwindConfig: require("./tailwind.config"),
customCss: [require.resolve("./src/css/custom.css")],

1
website/package.json
View File

@ -41,6 +41,7 @@
"devDependencies": {
"@docusaurus/module-type-aliases": "2.0.0-beta.9",
"@tsconfig/docusaurus": "^1.0.4",
"asciinema-player": "^3.0.0-rc.1",
"typescript": "^4.3.5"
},
"browserslist": {

35
website/src/components/Asciinema/container.tsx Normal file
View File

@ -0,0 +1,35 @@
import * as AsciinemaPlayer from "asciinema-player";
import React, { useEffect, useRef } from "react";
export type AsciinemaOptions = {
cols: number;
rows: number;
autoPlay: boolean;
preload: boolean;
loop: boolean;
startAt: number | string;
speed: number;
idleTimeLimit: number;
theme: string;
poster: string;
fit: string;
fontSize: string;
};
export type AsciinemaProps = {
url: string;
options?: Partial<AsciinemaOptions>;
};
export default function AsciinemaContainer({
url,
options = {},
}: AsciinemaProps): JSX.Element {
const ref = useRef<HTMLDivElement>(null);
useEffect(() => {
AsciinemaPlayer.create(url, ref.current, options);
}, []);
return <div ref={ref} className="not-prose w-full max-w-full my-4"></div>;
}

18
website/src/components/Asciinema/index.tsx Normal file
View File

@ -0,0 +1,18 @@
import "asciinema-player/dist/bundle/asciinema-player.css";
import "./styles.css";
import React from "react";
import BrowserOnly from "@docusaurus/BrowserOnly";
export default function Asciinema(props): JSX.Element {
return (
<BrowserOnly fallback={<div></div>}>
{() => {
const AsciinemaContainer = require("./container.tsx").default;
return <AsciinemaContainer {...props} />;
}}
</BrowserOnly>
);
}

3
website/src/components/Asciinema/styles.css Normal file
View File

@ -0,0 +1,3 @@
.asciinema-player svg {
display: inline-block;
}

1
website/src/components/Card/index.tsx
View File

@ -3,7 +3,6 @@ import copy from "copy-to-clipboard";
import React, { useState } from "react";
import Link from "@docusaurus/Link";
import type { IconName } from "@fortawesome/fontawesome-common-types";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
import type { Obj } from "../../libs/store";

25
website/src/components/Paginate/index.tsx
View File

@ -1,5 +1,5 @@
import clsx from "clsx";
import React, { useCallback, useRef } from "react";
import React, { useCallback, useState } from "react";
import { usePagination } from "react-use-pagination";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
@ -16,19 +16,25 @@ export default function Paginate({
previousEnabled,
nextEnabled,
}: ReturnType<typeof usePagination>): JSX.Element {
const ref = useRef<HTMLElement>();
const maxWidth = useContentWidth(ref.current?.parentElement ?? undefined);
const [containerElement, setContainerElement] = useState<HTMLElement | null>(
null
);
const ref = useCallback(
(element: HTMLElement | null) => {
setContainerElement(element);
},
[setContainerElement]
);
const maxWidth = useContentWidth(
containerElement?.parentElement ?? undefined
);
const maxLength = Math.min(
(maxWidth && Math.floor(maxWidth / 50) - 2) || totalPages,
totalPages
);
const onPageChange = useCallback(
(selectedItem: { selected: number }) => {
setPage(selectedItem.selected);
},
[setPage]
);
const range = useCallback((start: number, end: number) => {
const result = [];
start = start > 0 ? start : 1;
@ -38,7 +44,6 @@ export default function Paginate({
return result;
}, []);
// FIXME: responsive width
const pages: (React.ReactNode | number)[] = [];
const ellipsis = <FontAwesomeIcon icon="ellipsis-h" />;

1
website/src/components/Paginate/styles.module.css
View File

@ -24,7 +24,6 @@
@apply bg-hero text-white border-hero;
}
.disabled {
@apply opacity-60 pointer-events-none;
}

13
website/src/pages/changelog.md
View File

@ -4,6 +4,19 @@ description: Changelog
# 更新日志
## Latest Changes
- 修复 `receive`, `got` 在参数为空消息时依旧会反复询问
- 修复文档商店分页显示错误
- 修复插件导入失败时，依然存在于已导入插件列表中
- 移除 `state` 依赖注入所需的默认值 `State()`
- 增加 `fastapi` 配置项：是否将适配器路由包含在 schema 中
- 修改 `load_builtin_plugins` 函数，使其能够支持加载多个内置插件
- 新增 `load_builtin_plugin` 函数，用于加载单个内置插件
- 修改 `Message` 和 `MessageSegment` 类，完善 typing，转移 Mapping 构建支持至 pydantic validate
- 调整项目结构，分离内部定义与用户接口
- 新增 Bot 连接事件钩子 (如 `driver.on_bot_connect` ) 的依赖注入
## v2.0.0b1
- 新增 `MessageTemplate` 对于 `str` 普通模板的支持

4
website/src/pages/store.mdx
View File

@ -13,6 +13,10 @@ import Bot from "../components/Bot";
# 商店
:::warning 警告
商店未带有绿色官方标记的任何适配器、插件均由社区贡献，官方无法对其质量、安全性、可用性负责。
:::
<div className="w-full border rounded shadow">
<Tabs defaultValue="plugin" className="justify-center font-light">
<TabItem value="driver" label="驱动器">

4
website/static/adapters.json
View File

@ -5,7 +5,7 @@
"name": "OneBot V11",
"desc": "OneBot V11 协议",
"author": "yanyongyu",
"homepage": "https://github.com/nonebot/adapter-onebot",
"homepage": "https://onebot.adapters.nonebot.dev/",
"tags": [],
"is_official": true
},
@ -69,4 +69,4 @@
"tags": [],
"is_official": false
}
]
]

1
website/static/img/setup.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 177 KiB

2
website/static/plugins.json
View File

@ -1303,4 +1303,4 @@
],
"is_official": false
}
]
]

17
website/static/unregister-sw.js
View File

@ -1 +1,16 @@
navigator.serviceWorker.getRegistrations().then(function(e){for(var r,i=e,t=Array.isArray(i),a=0,i=t?i:i[Symbol.iterator]();;){if(t){if(a>=i.length)break;r=i[a++]}else{if((a=i.next()).done)break;r=a.value}r.unregister()}});
navigator.serviceWorker.getRegistrations().then(function (e) {
for (
var r, i = e, t = Array.isArray(i), a = 0, i = t ? i : i[Symbol.iterator]();
;
) {
if (t) {
if (a >= i.length) break;
r = i[a++];
} else {
if ((a = i.next()).done) break;
r = a.value;
}
r.unregister();
}
});

49
website/versioned_docs/version-2.0.0-beta.1/README.md
View File

@ -1,49 +0,0 @@
---
sidebar_position: 0
id: index
slug: /
---
# 概览
NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架，它基于 Python 的类型注解和异步特性，能够为你的需求实现提供便捷灵活的支持。
需要注意的是，NoneBot 仅支持 **Python 3.7.3 以上版本**
## 特色
### 异步优先
NoneBot2 基于 Python [asyncio](https://docs.python.org/3/library/asyncio.html) 编写，并在异步机制的基础上进行了一定程度的同步函数兼容。
### 完整的类型注解
NoneBot2 参考 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 等 PEP 完整实现了类型注解，通过 `pyright`/`pylance` 检查。配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](./start/editor-support))。
### 开箱即用
NoneBot2 提供了使用便捷、具有交互式功能的命令行工具 -- `nb-cli`，使得初次接触 NoneBot 时更容易上手。详细使用方法请参考各文档章节以及 [使用脚手架](./start/nb-cli)。
### 插件系统
插件系统是 NoneBot 的核心，通过它可以实现机器人的模块化以及功能扩展，便于维护和管理。
### 依赖注入系统
NoneBot2 采用了一套自行定义的依赖注入系统，可以让事件的处理过程更加的简洁、清晰，增加代码的可读性，减少代码冗余。
#### 什么是依赖注入
[**"依赖注入"**](https://zh.m.wikipedia.org/wiki/%E6%8E%A7%E5%88%B6%E5%8F%8D%E8%BD%AC)意思是，在编程中，有一种方法可以让你的代码声明它工作和使用所需要的东西, 即"**依赖**"。
系统 (在这里是指 `NoneBot` ) 将负责做任何需要的事情，为你的代码提供这些必要依赖 (即"**注入**"依赖性)
这在你有以下情形的需求时非常有用:
- 这部分代码拥有共享的逻辑(同样的代码逻辑多次重复)
- 共享数据库以及网络请求连接会话
- 比如 `httpx.AsyncClient`, `aiohttp.ClientSession` 和 `sqlalchemy.Session`
- 用户权限检查以及认证
- 还有更多...
它在完成上述工作的同时，还能尽量减少代码的耦合和重复

192
website/versioned_docs/version-2.0.0-beta.1/advanced/README.md
View File

@ -1,192 +0,0 @@
---
id: index
slug: /advanced
options:
menu:
weight: 10
category: advanced
---
# 深入
:::danger 警告
进阶部分尚未更新完成
:::
## 它如何工作？
如同[概览](../README.md)所言:
> NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的事件进行解析和处理，并以插件化的形式，按优先级分发给事件所对应的事件响应器，来完成具体的功能。
`Nonebot2` 是一个可以对机器人上报的事件进行处理并完成具体功能的机器人框架，在这里，我们将简要讲述它的工作内容。
**便捷起见，以下内容对 `Nonebot2` 会被称为 `nonebot`，与 `Nonebot2` 交互的机器人实现会被称为 `协议端`**。
在实际应用中，`nonebot` 会充当一个高性能，轻量级的 Python 微服务框架。协议端可以通过 `http`, `websocket` 等方式与之通信，这个通信往往是双向的：一方面，协议端可以上报数据给 `nonebot`，`nonebot` 会处理数据并返回响应给协议端；另一方面，`nonebot` 可以主动推送数据给协议端。而 `nonebot` 便是围绕双向通信进行工作的。
在开始工作之前，`nonebot` 需要进行准备工作：
1. **运行 `nonebot.init` 初始化函数**，它会读取配置文件，并初始化 `nonebot` 和后端驱动 `driver` 对象。
2. **注册协议适配器 `adapter`** 。
3. **加载插件**。
准备工作完成后，`nonebot` 会利用 `uvicorn` 启动，并运行 `on_startup` 钩子函数。
随后，倘若一个协议端与 `nonebot` 进行了连接，`nonebot` 的后端驱动 `driver` 就会将 `adapter` 实例化为 `bot`，`nonebot` 便会利用 `bot` 开始工作，它的工作内容分为两个方面：
1. **事件处理**，`bot` 会将协议端上报的数据转化为 `事件`(`Event`)，之后 `nonebot` 会根据一套既定流程来处理 `事件`。
2. **调用 `API`**, 在**事件处理**的过程中，`nonebot` 可以通过 `bot` 调用协议端指定的 `API` 来获取更多数据，或者反馈响应给协议端; `nonebot` 也可以通过调用 `API` 向协议端主动请求数据或者主动推送数据。
在**指南**模块， 我们已经叙述了[如何配置 nonebot](../tutorial/configuration.md), [如何注册协议适配器](../tutorial/register-adapter.md)，[如何加载插件](../tutorial/plugin/load-plugin.md), 在这里便不再赘述。
下面，我们将对**事件处理**， **调用 API**进行说明。
## 事件处理
我们可以先看事件处理的流程图：
![handle-event](./images/Handle-Event.png)
在流程图里，我们可以看到，`nonebot` 会有三个阶段来处理事件：
1. **driver 处理上报数据**
2. **adapter 处理原始数据**
3. **nonebot 处理 Event**
我们将顺序说明这三个阶段。其中，会将第三个阶段拆分成**概念解释**，**处理 Event**，**特殊异常处理**三个部分来说明。
### driver 处理上报数据
1. 协议端会通过 `websocket` 或者 `http` 等方式与 `nonebot` 的后端驱动 `driver` 连接，`driver` 会根据之前注册的 `adapter` 和配置文件的内容来进行鉴权，从而获得这个连接的唯一识别 id `self-id`，随后 `adapter` 就会利用 `self-id` 实例化为 `bot` 对象。
::: tip
需要注意的是，如果协议端通过 `websocket` 与 `nonebot` 连接，这个步骤只会在建立连接时进行，并在之后运行 `on_bot_connect` 钩子函数；通过 `http` 方式连接时，会在协议端每次上报数据时都进行这个步骤。
:::
::: warning
连接之前必须要注册 `adapter`
:::
::: warning
`self-id` 是帐号的唯一识别 ID，这意味着不能出现相同的 `self-id`。
:::
2. `driver` 会将接收到的数据转交给 `bot` 对象进一步处理。
### adapter 处理原始数据
1. `bot` 会利用事先定义好的 `Event Model` 对上报的数据进行分析处理，将数据转化为 `nonebot` 可以处理的 `Event` 对象。
::: tip
`adapter` 在转换数据格式的同时可以进行一系列的特殊操作，例如 `CQHTTP` 会对 `reply` 信息进行提取。
:::
2. `Event` 会传入 `nonebot` 做进一步处理。
### nonebot 处理 Event
在讲述这个阶段之前，我们需要先对几个概念进行解释。
#### 概念解释
1. **hook**，或者说**钩子函数**，它们可以在 `nonebot` 处理 `Event` 的不同时刻进行拦截，修改或者扩展，在 `nonebot` 中，钩子函数分为 `事件预处理hook`，`运行预处理hook`，`运行后处理hook` 和 `事件后处理hook`。
::: tip
关于`hook`的更多信息，可以查阅[这里](./runtime-hook.md)
:::
2. **Matcher**与**matcher**，在**指南**中，我们讲述了[如何注册事件响应器](../tutorial/plugin/create-matcher.md)，这里的事件响应器或者说 `Matcher` 并不是一个具体的实例 `instance`，而是一个具有特定属性的类 `class`。只有当 `Matcher` **响应事件**时，才会实例化为具体的 `instance`，也就是 `matcher`。`matcher` 可以认为是 `nonebot` 处理 `Event` 的基本单位，运行 `matcher` 是`nonebot`工作的主要内容。
3. **handler**，或者说**事件处理函数**, 它们可以认为是 `nonebot` 处理 `Event` 的最小单位。在不考虑 `hook` 的情况下，**运行 matcher 就是顺序运行 matcher.handlers**，这句话换种表达方式就是，`handler` 只有添加到 `matcher.handlers` 时，才可以参与到 `nonebot` 的工作中来。
::: tip
如何让 `handler` 添加到 `matcher.handlers`？
一方面，我们可以参照[这里](../tutorial/plugin/create-handler.md)利用装饰器来添加；另一方面，我们在用 `on()` 或者 `on_*()` 注册事件响应器时，可以添加 `handlers=[handler1, handler2, ...]` 这样的关键词参数来添加。
:::
#### 处理 Event
1. **执行事件预处理 hook**， `nonebot` 接收到 `Event` 后，会传入到 `事件预处理hook` 中进行处理。
::: warning
需要注意的是，执行多个 `事件预处理hook` 时并无顺序可言，它们是**并行运行**的。这个原则同样适用于其他的 `hook`。
:::
2. **按优先级升序选出同一优先级的 Matcher**，`nonebot` 提供了一个全局字典 `matchers`，这个字典的 `key` 是优先级 `priority`，`value` 是一个 `list`，里面存放着同一优先级的 `Matcher`。在注册 `Matcher` 时，它和优先级 `priority` 会添加到里面。
在执行 `事件预处理hook` 后，`nonebot` 会对 `matchers` 的 `key` 升序排序并选择出当前最小优先级的 `Matcher`。
3. **根据 Matcher 定义的 Rule, Permission 判断是否运行**，在选出 `Matcher` 后，`nonebot` 会将 `bot`，`Event` 传入到 `Matcher.check_rule` 和 `Matcher.check_perm` 两个函数中，两个函数分别对 Matcher 定义的 Rule, Permission 进行 check，当 check 通过后，这个 `Matcher` 就会响应事件。但是当同一个优先级的所有 `Matcher` 均没有响应时，`nonebot` 会返回到上一个步骤，选择出下一优先级的 `Matcher`。
4. **实例化 matcher 并执行运行预处理 hook**，当 `Matcher` 响应事件后，它便会实例化为 `matcher`，并执行 `运行预处理hook`。
5. **顺序运行 matcher 的所有 handlers**，`运行预处理hook` 执行完毕后，便会运行 `matcher`，也就是**顺序运行**它的 `handlers`。
::: tip
`matcher` 运行 `handlers` 的顺序是: 先运行该 `matcher` 的类 `Matcher` 注册时添加的 `handlers`(如果有的话)，再按照装饰器装饰顺序运行装饰的 `handlers`。
:::
6. **执行运行后处理 hook**，`matcher` 的 `handlers` 运行完毕后，会执行 `运行后处理hook`。
7. **判断是否停止事件传播**，`nonebot` 会根据当前优先级所有 `matcher` 的 `block` 参数或者 `StopPropagation` 异常判断是否停止传播 `Event`，如果事件没有停止传播，`nonebot` 便会返回到第 2 步， 选择出下一优先级的 `Matcher`。
8. **执行事件后处理 hook**，在 `Event` 停止传播或执行完所有响应的 `Matcher` 后，`nonebot` 会执行 `事件后处理hook`。
当 `事件后处理hook` 执行完毕后，当前`Event`的处理周期就顺利结束了。
#### 特殊异常处理
在这个阶段，`nonebot` 规定了几个特殊的异常，当 `nonebot` 捕获到它们时，会用特定的行为来处理它们。
1. **IgnoredException**
这个异常可以在 `事件预处理hook` 和 `运行预处理hook` 抛出。
当 `事件预处理hook` 抛出它时，`nonebot` 会忽略当前的 `Event`，不进行处理。
当 `运行预处理hook` 抛出它时，`nonebot` 会忽略当前的 `matcher`，结束当前 `matcher` 的运行。
::: warning
当 `hook` 需要抛出这个异常时，要写明原因。
:::
2. **PausedException**
这个异常可以在 `handler` 中由 `Matcher.pause` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将后续的 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行后续的 handlers。
3. **RejectedException**
这个异常可以在 `handler` 中由 `Matcher.reject` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行，并将当前 handler 和后续 `handler` 交给一个临时 `Matcher` 来响应当前交互用户的下一个消息事件，当临时 `Matcher` 响应时，临时 `Matcher` 会运行当前 `handler` 和后续的 `handler`。
4. **FinishedException**
这个异常可以在 `handler` 中由 `Matcher.finish` 抛出。
当 `nonebot` 捕获到它时，会停止运行当前 `handler` 并结束当前 `matcher` 的运行。
5. **StopPropagation**
这个异常一般会在执行 `运行后处理hook` 后抛出。
当 `nonebot` 捕获到它时， 会停止传播当前 `Event`，不再寻找下一优先级的 `Matcher`，直接执行 `事件后处理hook`。
## 调用 API
`nonebot` 可以通过 `bot` 来调用 `API` ，`API` 可以向协议端发送数据，也可以向协议端请求更多的数据。
::: tip
不同 `adapter` 规定了不同的 API，对应的 API 列表请参照协议规范。
:::
一般来说，我们可以用 `bot.*` 来调用 `API`(\*是 `API` 的 `action` 或者 `endpoint`)。
对于发送消息而言，一方面可以调用既有的 API；另一方面 `nonebot` 实现了两个便捷方法，`bot.send(event, message, **kwargs)` 方法和可以在 `handler` 中使用的 `Matcher.send(message, **kwargs)` 方法，来向事件主体发送消息。

3
website/versioned_docs/version-2.0.0-beta.1/advanced/di/_category_.json
View File

@ -1,3 +0,0 @@
{
"label": "依赖注入"
}

109
website/versioned_docs/version-2.0.0-beta.1/advanced/di/dependency-injection.md
View File

@ -1,109 +0,0 @@
---
sidebar_position: 1
description: 依赖注入简介
options:
menu:
weight: 60
category: advanced
---
# 简介
受 [`FastApi`](https://fastapi.tiangolo.com/tutorial/dependencies/) 启发，NoneBot 同样编写了一个简易的依赖注入模块，使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。
## 什么是依赖注入？
~~交给 mix 了~~
## 使用依赖注入
以下通过一个简单的例子来说明依赖注入的使用方法：
### 编写依赖函数
这里我们编写了一个简单的函数 `depend` 作为依赖函数
```python {7-9}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
```
它和普通的事件处理函数并无区别，同样可以接受 `bot`, `event` 等参数，你可以把它当作一个普通的事件处理函数但是去除了装饰器（并没有使用 `matcher.handle()` 等来进行装饰），并且它可以返回任何类型的值。
在这个例子中，依赖函数接受一个参数：
- `state: dict`：当前事件处理状态字典。
并且返回了一个 `state` 的复制以及一个附加的键值 `depend` 。
### Import `Depends`
```python {2}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
```
### 在事件处理函数里声明依赖函数
与 FastAPI 类似，你可以在函数中添加一个新的参数，并且使用 `Depends` 来声明它的依赖。
```python {12}
from nonebot.log import logger
from nonebot.params import Depends
from nonebot import on_command, on_message
test = on_command("123")
def depend(state: dict):
# do something with state
return {**state, "depend": "depend"}
@test.handle()
async def _(x: dict = Depends(depend)):
print(x)
```
你需要给 `Depends` 指定一个依赖函数，这个依赖函数的返回值会被作为 `x` 的值。
`Depends` 的首个参数即是依赖函数，或者其他 `Callable` 对象，在之后会对更多形式的依赖对象进行介绍。
:::tip
参数 `x` 的类型标注并不会影响事件处理函数的运行，类型检查并不会对依赖函数的返回值以及类型标注进行检查。
:::
当接收到事件时，NoneBot 会进行以下处理：
1. 查询缓存，如果缓存中有相应的值，则直接返回。
2. 准备依赖函数所需要的参数。
3. 调用依赖函数并获得返回值。
4. 将返回值存入缓存。
5. 将返回值作为事件处理函数中的参数值传入。
## 依赖缓存
## Class 作为依赖
## Generator 作为依赖

74
website/versioned_docs/version-2.0.0-beta.1/advanced/di/overload.md
View File

@ -1,74 +0,0 @@
---
sidebar_position: 3
description: 重载事件处理函数
options:
menu:
weight: 62
category: advanced
---
# 事件处理函数重载
当我们在编写 `nonebot2` 应用时，常常会遇到这样一个问题：该怎么让同一类型的不同事件执行不同的响应逻辑？又或者如何让不同的 `adapter` 针对同一类型的事件作出不同响应？
针对这个问题， `nonebot2` 提供一个便捷而高效的解决方案：事件处理函数重载机制。简单地说，`handler` (事件处理函数) 会根据其参数的 `type hints` ([PEP484 类型标注](https://www.python.org/dev/peps/pep-0484/)) 来对相对应的 `adapter` 和 `Event` 进行响应，并且会忽略不符合其参数类型标注的情况。
<!-- 必须要注意的是，该机制利用了 `inspect` 标准库获取到了事件处理函数的 `singnature` (签名) ，进一步获取到参数名称和类型标注。故而，我们在编写 `handler` 时，参数的名称和类型标注必须要符合 `T_Handler` 规定，详情可以参看 **指南** 中的[事件处理](../../guide/creating-a-handler)。 -->
:::tip 提示
如果想了解更多关于 `inspect` 标准库的信息，可以查看[官方文档](https://docs.python.org/zh-cn/3.9/library/inspect.html)。
:::
下面，我们会以 `CQHTTP` 中的 `群聊消息事件` 和 `私聊消息事件` 为例，对该机制的应用进行简单的介绍。
## 一个例子
首先，我们需要导入需要的方法、类型。
```python
from nonebot import on_command
from nonebot.adapters.cqhttp import Bot, GroupMessageEvent, PrivateMessageEvent
```
之后，我们可以注册一个 `Matcher` 来响应 `消息事件` 。
```python
matcher = on_command("testoverload")
```
最后, 我们编写不同的 `handler` 并编写不同的类型标注来实现事件处理函数重载：
```python
@matcher.handle()
async def _(bot: Bot, event: GroupMessageEvent):
await matcher.send("群聊消息事件响应成功！")
@matcher.handle()
async def _(bot: Bot, event: PrivateMessageEvent):
await matcher.send("私聊消息事件响应成功！")
```
此时，我们可以在群聊或私聊中对我们的机器人发送 `testoverload` ，它会在不同的场景做出不同的应答。
这样一个简单的事件处理函数重载就完成了。
## 进阶
事件处理函数重载机制同样支持被 `matcher.got` 等装饰器装饰的函数。 例如：
```python
@matcher.got("key1", prompt="群事件提问")
async def _(bot: Bot, event: GroupMessageEvent):
await matcher.send("群聊消息事件响应成功！")
@matcher.got("key2", prompt="私聊事件提问")
async def _(bot: Bot, event: PrivateMessageEvent):
await matcher.send("私聊消息事件响应成功！")
```
只有触发事件符合的函数才会触发装饰器。

11
website/versioned_docs/version-2.0.0-beta.1/advanced/di/sync-support.md
View File

@ -1,11 +0,0 @@
---
sidebar_position: 2
description: 同步函数作为依赖
options:
menu:
weight: 61
category: advanced
---
# 同步支持

124
website/versioned_docs/version-2.0.0-beta.1/advanced/export-and-require.md
View File

@ -1,124 +0,0 @@
---
options:
menu:
weight: 50
category: advanced
---
# 跨插件访问
由于 `nonebot2` 独特的插件加载机制，在使用 python 原有的 import 机制来进行插件之间的访问时，很可能会有奇怪的或者意料以外的情况发生。为了避免这种情况的发生，您可以有两种方法来实现跨插件访问：
1. 将插件间的要使用的公共代码剥离出来，作为公共文件或者文件夹，提供给插件加以调用。
2. 使用 `nonebot2` 提供的 `export` 和 `require` 机制，来实现插件间的互相调用。
第一种方法比较容易理解和实现，这里不再赘述，但需要注意的是，请不要将公共文件或者公共文件夹作为**插件**被 `nonebot2` 加载。
下面将介绍第二种方法—— `export` 和 `require` 机制：
## 使用 export 和 require
现在，假定有两个插件 `pluginA` 和 `pluginB`，需要在 `pluginB` 中调用 `pluginA` 中的一个变量 `varA` 和一个函数 `funcA`。
在上面的条件中涉及到了两种操作：一种是在 `pluginA` 的 `导出对象` 操作；而另一种是在 `pluginB` 的 `导入对象` 操作。在 `nonebot2` 中，`导出对象` 的操作用 `export` 机制来实现，`导入对象` 的操作用 `require` 机制来实现。下面，我们将逐一进行介绍。
:::warning 警告
使用这个方法进行跨插件访问时，**需要先加载`导出对象`的插件，再加载`导入对象`的插件。**
:::
### 使用 export
在 `pluginA` 中，我们调用 `export` 机制 `导出对象`。
在 `export` 机制调用前，我们需要保证导出的对象已经被定义，比如：
```python
varA = "varA"
def funcA():
return "funcA"
```
在确保定义之后，我们可以从 `nonebot.plugin` 导入 `export()` 方法, `export()` 方法会返回一个特殊的字典 `export`：
```python
from nonebot.plugin import export
export=export()
```
这个字典可以用来装载导出的对象，它的 key 是对象导出后的命名，value 是对象本身，我们可以直接创建新的 `key` - `value` 对导出对象：
```python
export.vA = varA
export.fA = funcA
```
除此之外，也支持 `嵌套` 导出对象：
```python
export.sub.vA = varA
export.sub.fA = funcA
```
特别地，对于 `函数对象` 而言，`export` 支持用 `装饰器` 的方法来导出，因此，我们可以这样定义 `funcA`：
```python
@export.sub
def funcA():
return "funcA"
```
或者:
```python
@export
def funcA():
return "funcA"
```
通过 `装饰器` 的方法导出函数时，命名固定为函数的命名，也就是说，上面的两个例子等同于：
```python
export.sub.funcA = funcA
export.funcA = funcA
```
这样，我们就成功导出 `varA` 和 `funcA` 对象了。
下面我们将介绍如何在 `pluginB` 中导入这些对象。
### 使用 require
在 `pluginB` 中，我们调用 `require` 机制 `导入对象`。
:::warning 警告
在导入来自其他插件的对象时, 请确保导出该对象的插件在引用该对象的插件之前加载。如果该插件并未被加载，则会尝试加载，加载失败则会返回 `None`。
:::
我们可以从 `nonebot.plugin` 中导入 `require()` 方法：
```python
from nonebot.plugin import require
```
`require()` 方法的参数是插件名, 它会返回在指定插件中，用 `export()` 方法创建的字典。
```python
require_A = require('pluginA')
```
在之前，这个字典已经存入了 `'vA'` - `varA`, `'fA'` - `funcA` 或 `'funcA'` - `funcA` 这样的 `key` - `value` 对。因此在这里我们直接用 `属性` 的方法来获取导入对象:
```python
varA = require_A.vA
funcA = require_A.fA or require_A.funcA
```
这样，我们就在 `pluginB` 中成功导入了 `varA` 和 `funcA` 对象了。

BIN
website/versioned_docs/version-2.0.0-beta.1/advanced/images/Handle-Event.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 127 KiB

BIN
website/versioned_docs/version-2.0.0-beta.1/advanced/images/plugin_store_publish.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 103 KiB

BIN
website/versioned_docs/version-2.0.0-beta.1/advanced/images/plugin_store_publish_2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 128 KiB

97
website/versioned_docs/version-2.0.0-beta.1/advanced/permission.md
View File

@ -1,97 +0,0 @@
---
options:
menu:
weight: 30
category: advanced
---
# 权限控制
**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot` 提供了十分完善且灵活的权限控制机制—— `Permission` 机制。接下来我们将对这个机制进行简单的说明。
## 应用
如同 `Rule` 一样, `Permission` 可以在[注册事件响应器](../tutorial/plugin/create-matcher.md)时添加 `permission` 参数来加以应用，这样 `Nonebot` 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例，对该机制的应用做一下介绍。
```python
from nonebot.permission import SUPERUSER
from nonebot.adapters import Bot
from nonebot import on_command
matcher = on_command("测试超管", permission=SUPERUSER)
@matcher.handle()
async def _(bot: Bot):
await matcher.send("超管命令测试成功")
@matcher.got("key1", "超管提问")
async def _(bot: Bot, event: Event):
await matcher.send("超管命令got成功")
```
在这段代码中，我们事件响应器指定了 `SUPERUSER` 这样一个权限，那么机器人只会响应超级管理员的 `测试超管` 命令，并且会响应该超级管理员的连续对话。
::: tip 提示
在这里需要强调的是，`Permission` 与 `Rule` 的表现并不相同， `Rule` 只会在初次响应时生效，在余下的对话中并没有限制事件；但是 `Permission` 会持续生效，在连续对话中会一直对事件主体加以限制。
:::
## 进阶
`Permission` 除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数 `handler` 时主动调用，我们可以利用这个特性在一个 `handler` 里对不同权限的事件主体进行区别响应，下面我们以 `CQHTTP` 中的 `GROUP_ADMIN` (普通管理员非群主)和 `GROUP_OWNER` 为例，说明下怎么进行主动调用。
```python
from nonebot import on_command
from nonebot.adapters.cqhttp import Bot
from nonebot.adapters.cqhttp import GroupMessageEvent
from nonebot.adapters.cqhttp import GROUP_ADMIN, GROUP_OWNER
matcher = on_command("测试权限")
@matcher.handle()
async def _(bot: Bot, event: GroupMessageEvent):
if await GROUP_ADMIN(bot, event):
await matcher.send("管理员测试成功")
elif await GROUP_OWNER(bot, event):
await matcher.send("群主测试成功")
else:
await matcher.send("群员测试成功")
```
在这段代码里，我们并没有对命令的权限指定，这个命令会响应所有在群聊中的 `测试权限` 命令，但是在 `handler` 里，我们对两个 `Permission` 进行主动调用，从而可以对不同的角色进行不同的响应。
## 自定义
如同 `Rule` 一样, `Permission` 也是由非负数个 `PermissionChecker` 组成的，但只需其中一个返回 `True` 时就会匹配成功。下面则是 `PermissionChecker` 和 `Permission` 示例：
```python
from nonebot.adapters import Bot, Event
from nonebot.permission import Permission
async def async_checker(bot: Bot, event: Event) -> bool:
return True
def sync_checker(bot: Bot, event: Event) -> bool:
return True
def check(arg1, arg2):
async def _checker(bot: Bot, event: Event) -> bool:
return bool(arg1 + arg2)
return Permission(_checker)
```
`Permission` 和 `PermissionChecker` 之间可以使用 `或 |` 互相组合：
```python
from nonebot.permission import Permission
Permission(async_checker1) | sync_checker | async_checker2
```
同样地，如果想用 `Permission(*checkers)` 包裹构造 `Permission` ，函数必须是异步的；但是在利用 `或 |` 符号连接构造时， `Nonebot` 会自动包裹同步函数为异步函数。

69
website/versioned_docs/version-2.0.0-beta.1/advanced/publish-plugin.md
View File

@ -1,69 +0,0 @@
---
options:
menu:
weight: 70
category: advanced
---
# 发布插件
## 前注
本章节仅包含插件发布流程指导，插件开发请查阅 **[创建插件](../tutorial/plugin/config-plugin.md)** 章节与 **[Plugin API 文档](../api/plugin.md)** 。
## 插件发布流程
### 发布到 PyPI
您可以选择任意自己喜欢的方式将您的插件发布到 **[PyPI](https://pypi.org/)** ，如使用 **[setuptools](https://pypi.org/project/setuptools/)** 或 **[poetry](https://pypi.org/project/poetry/)** 进行 PyPI 发布。
发布时，请您为自己的插件取一个清晰易懂的名字。通常而言，一款 NoneBot2 插件名称使用 `nonebot-plugin-` 作为前缀(如`nonebot-plugin-foo`)，以 `nonebot_plugin_` 作为导入名的前缀(如`nonebot_plugin_foo`)，这并非是强制规范, 而是为了防止与其他 PyPI 包产生冲突, 所以我们推荐您在没有特殊需求的情况下这样做。
发布后，请确保您的插件已能公开的从 PyPI 访问到，请检查您的插件在 PyPI 的地址：`https://pypi.org/project/<您的Nonebot2插件项目名>`
### 托管您的插件源代码
将插件源代码及相关构建文件（如`pyproject.toml`或`setup.py`等与 PyPI 包构建相关的文件）托管在公开代码仓。
请确保您的代码仓地址能够被正确的访问，检查您的插件在代码仓的地址，如 `https://github.com/<您的Github用户名>/<您的插件Github项目名>` 。
### 申请发布到 Nonebot2 插件商店
完成在 PyPI 的插件发布流程与源代码托管流程后，请您前往 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** 页面，切换到 **插件** 页签，点击 **发布插件** 按钮。
![插件发布界面](./images/plugin_store_publish.png)
如图所示，在弹出的插件信息提交表单内，填入您所要发布的相应插件信息：
```text
插件名称： 您的Nonebot2插件名称
插件介绍： 为您的插件提供的简短介绍信息
PyPI项目名： 您的插件所在的PyPI Project名，如 nonebot-plugin-xxxx
import包名： 您的插件通过Python导入时使用的包名，如 nonebot_plugin_xxxx
仓库/主页： 您的插件托管地址，如 https://github.com/<您的Github用户名>/nonebot-plugin-xxxx
标签： 一个或多个可选颜色的TAG，每填写一个点击添加标签，若要删除，点击标签即可；标签长度不超过10字符，标签个数不超过3个
特定标签内容Adapter：点击Type的Adapter，将创建一个 a: 开头的标签，填入内容以指定您插件使用的adapter
特定标签内容Topic：点击Type的Topic，将创建一个 t: 开头的标签，填入内容以指定您插件的主题
```
![插件信息填写](./images/plugin_store_publish_2.png)
完成填写后，请点击 **发布** 按钮，这将自动在 **[NoneBot2](https://github.com/nonebot/nonebot2)** 代码仓内创建发布您的插件的对应 Issue。
### 等待插件发布处理
您的插件发布 Issue 创建后，将会经过*Nonebot2 Publish Bot*的检查，以确保插件信息正确无误。
若您的插件发布 Issue 未通过检查，您可以 **直接修改** Issue 内容以更新发布请求。*Nonebot2 Publish Bot*在您修改 Issue 内容后将会自动重新执行检查。您无需关闭、重新提交发布申请。
之后，NoneBot2 的维护者们将会对插件进行进一步的检查，以确保用户能够正常安装并使用该插件。
完成这些步骤后，您的插件将会被合并到 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** ，而您也将成为 **[NoneBot2 贡献者](https://github.com/nonebot/nonebot2/graphs/contributors)** 的一员。
## 完成
恭喜您，经过上述的发布流程，您的插件已经成功发布到 Nonebot2 商店了。
此时，您可以在 **[NoneBot2 商店](https://v2.nonebot.dev/store.html)** 的插件页签查找到您的插件。同时，欢迎您成为 **[NoneBot2 贡献者](https://github.com/nonebot/nonebot2/graphs/contributors)** ！
**Congratulations!**

170
website/versioned_docs/version-2.0.0-beta.1/advanced/runtime-hook.md
View File

@ -1,170 +0,0 @@
---
options:
menu:
weight: 40
category: advanced
---
# 钩子函数
[`钩子编程`](https://zh.wikipedia.org/wiki/%E9%92%A9%E5%AD%90%E7%BC%96%E7%A8%8B)
> 钩子编程（hooking），也称作“挂钩”，是计算机程序设计术语，指通过拦截软件模块间的函数调用、消息传递、事件传递来修改或扩展操作系统、应用程序或其他软件组件的行为的各种技术。处理被拦截的函数调用、事件、消息的代码，被称为钩子（hook）。
在 `nonebot2` 中有一系列预定义的钩子函数，分为两类：`全局钩子函数` 和 `事件钩子函数` ，这些钩子函数可以用装饰器的形式来使用。
## 全局钩子函数
全局钩子函数是指 `nonebot2` 针对其本身运行过程的钩子函数。
这些钩子函数是由其后端驱动 `driver`来运行的，故需要先获得全局 `driver` 对象：
```python
from nonebot import get_driver
driver=get_driver()
```
共分为六种函数：
### 启动准备
这个钩子函数会在 `nonebot2` 启动时运行。
```python
@driver.on_startup
async def do_something():
pass
```
### 终止处理
这个钩子函数会在 `nonebot2` 终止时运行。
```python
@driver.on_shutdown
async def do_something():
pass
```
### bot 连接处理
这个钩子函数会在 `bot` 通过 `websocket` 连接到 `nonebot2` 时运行。
```python
@driver.on_bot_connect
async def do_something(bot: Bot):
pass
```
### bot 断开处理
这个钩子函数会在 `bot` 断开与 `nonebot2` 的 `websocket` 连接时运行。
```python
@driver.on_bot_disconnect
async def do_something(bot: Bot):
pass
```
### bot api 调用钩子
这个钩子函数会在 `Bot` 调用 API 时运行。
```python
from nonebot.adapters import Bot
@Bot.on_calling_api
async def handle_api_call(bot: Bot, api: str, data: Dict[str, Any]):
pass
```
### bot api 调用后钩子
这个钩子函数会在 `Bot` 调用 API 后运行。
```python
from nonebot.adapters import Bot
@Bot.on_called_api
async def handle_api_result(bot: Bot, exception: Optional[Exception], api: str, data: Dict[str, Any], result: Any):
pass
```
## 事件处理钩子
这些钩子函数指的是影响 `nonebot2` 进行 `事件处理` 的函数。
:::tip 提示
关于 `事件处理` 的流程，可以在[这里](./README.md)查阅。
:::
:::warning 注意
1.在事件处理钩子函数中，与 `matcher` 运行状态相关的函数将不可用，如 `matcher.finish()`
2.如果需要在事件处理钩子函数中打断整个对话的执行，请参考以下范例：
```python
from nonebot.exception import IgnoredException
@event_preprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
raise IgnoredException("reason")
```
:::
共分为四种函数：
### 事件预处理
这个钩子函数会在 `Event` 上报到 `nonebot2` 时运行
```python
from nonebot.message import event_preprocessor
@event_preprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
pass
```
### 事件后处理
这个钩子函数会在 `nonebot2` 处理 `Event` 后运行
```python
from nonebot.message import event_postprocessor
@event_postprocessor
async def do_something(bot: Bot, event: Event, state: T_State):
pass
```
### 运行预处理
这个钩子函数会在 `nonebot2`运行 `matcher` 前运行。
```python
from nonebot.message import run_preprocessor
@run_preprocessor
async def do_something(matcher: Matcher, bot: Bot, event: Event, state: T_State):
pass
```
### 运行后处理
这个钩子函数会在 `nonebot2`运行 `matcher` 后运行。
```python
from nonebot.message import run_postprocessor
@run_postprocessor
async def do_something(matcher: Matcher, exception: Optional[Exception], bot: Bot, event: Event, state: T_State):
pass
```

142
website/versioned_docs/version-2.0.0-beta.1/advanced/scheduler.md
View File

@ -1,142 +0,0 @@
---
options:
menu:
weight: 20
category: advanced
---
# 定时任务
[`APScheduler`](https://apscheduler.readthedocs.io/en/3.x/) —— Advanced Python Scheduler
> Advanced Python Scheduler (APScheduler) is a Python library that lets you schedule your Python code to be executed later, either just once or periodically. You can add new jobs or remove old ones on the fly as you please. If you store your jobs in a database, they will also survive scheduler restarts and maintain their state. When the scheduler is restarted, it will then run all the jobs it should have run while it was offline.
## 从 NoneBot v1 迁移
`APScheduler` 作为 `nonebot` v1 的可选依赖，为众多 bot 提供了方便的定时任务功能。`nonebot2` 已将 `APScheduler` 独立为 `nonebot_plugin_apscheduler` 插件，你可以在 [商店](https://v2.nonebot.dev/store.html) 中找到它。
相比于 `nonebot` v1，`nonebot` v2 只需要安装插件并修改 `scheduler` 的导入方式即可完成迁移。
## 安装插件
### 通过 nb-cli
如正在使用 `nb-cli` 构建项目，你可以从插件市场复制安装命令或手动输入以下命令以添加 `nonebot_plugin_apscheduler`。
```bash
nb plugin install nonebot_plugin_apscheduler
```
:::tip 提示
`nb-cli` 默认通过 `pypi` 安装，你可以添加命令参数 `-i [mirror]` 或 `--index [mirror]` 以使用镜像源安装。
:::
### 通过 poetry
执行以下命令以添加 `nonebot_plugin_apscheduler`
```bash
poetry add nonebot-plugin-apscheduler
```
:::tip 提示
由于稍后我们将使用 `nonebot.require()` 方法进行导入，所以无需额外的 `nonebot.load_plugin()`
:::
## 快速上手
1. 在需要设置定时任务的插件中，通过 `nonebot.require` 从 `nonebot_plugin_apscheduler` 导入 `scheduler` 对象
2. 在该对象的基础上，根据 `APScheduler` 的使用方法进一步配置定时任务
将上述步骤归纳为最小实现的代码如下：
```python
from nonebot import require
scheduler = require("nonebot_plugin_apscheduler").scheduler
@scheduler.scheduled_job("cron", hour="*/2", id="xxx", args=[1], kwargs={"arg2": 2})
async def run_every_2_hour(arg1, arg2):
pass
scheduler.add_job(run_every_day_from_program_start, "interval", days=1, id="xxx")
```
## 分步进行
### 导入 scheduler 对象
为了使插件能够实现定时任务，需要先将 `scheduler` 对象导入插件。
`nonebot2` 提供了 `nonebot.require` 方法来实现导入其他插件的内容，此处我们使用这个方法来导入 `scheduler` 对象。
`nonebot` 使用的 `scheduler` 对象为 `AsyncScheduler` 。
> 使用该方法传入的插件本身也需要有对应实现，关于该方法的更多介绍可以参阅 [这里](./export-and-require.md)
```python
from nonebot import require
scheduler = require("nonebot_plugin_apscheduler").scheduler
```
### 编写定时任务
由于本部分为标准的通过 `APScheduler` 配置定时任务，有关指南请参阅 [APScheduler 官方文档](https://apscheduler.readthedocs.io/en/3.x/userguide.html#adding-jobs)。
### 配置插件选项
根据项目的 `.env` 文件设置，向 `.env.*` 或 `bot.py` 文件添加 `nonebot_plugin_apscheduler` 的可选配置项
:::warning 注意
`.env.*` 文件的编写应遵循 nonebot2 对 `.env.*` 文件的编写要求
:::
#### `apscheduler_autostart`
类型：`bool`
默认值：`True`
是否自动启动 `APScheduler`。
对于大多数情况，我们需要在 `nonebot2` 项目被启动时启动定时任务，则此处设为 `true`
##### 在 `.env` 中添加
```bash
APSCHEDULER_AUTOSTART=true
```
##### 在 `bot.py` 中添加
```python
nonebot.init(apscheduler_autostart=True)
```
#### `apscheduler_config`
类型：`dict`
默认值：`{"apscheduler.timezone": "Asia/Shanghai"}`
`APScheduler` 相关配置。修改/增加其中配置项需要确保 `prefix: apscheduler`。
对于 `APScheduler` 的相关配置，请参阅 [scheduler-config](https://apscheduler.readthedocs.io/en/3.x/userguide.html#scheduler-config) 和 [BaseScheduler](https://apscheduler.readthedocs.io/en/3.x/modules/schedulers/base.html#apscheduler.schedulers.base.BaseScheduler)
> 官方文档在绝大多数时候能提供最准确和最具时效性的指南
##### 在 `.env` 中添加
```bash
APSCHEDULER_CONFIG={"apscheduler.timezone": "Asia/Shanghai"}
```
##### 在 `bot.py` 中添加
```python
nonebot.init(apscheduler_config={
"apscheduler.timezone": "Asia/Shanghai"
})
```

10
website/versioned_docs/version-2.0.0-beta.1/advanced/unittest.md
View File

@ -1,10 +0,0 @@
---
description: 编写单元测试
options:
menu:
weight: 80
category: advanced
---
# 单元测试

0
website/versioned_docs/version-2.0.0-beta.1/api/.gitkeep
View File

213
website/versioned_docs/version-2.0.0-beta.1/api/README.md
View File

@ -1,213 +0,0 @@
---
sidebar_position: 1
id: index
slug: /api
---
# NoneBot 模块
## 快捷导入
为方便使用，`nonebot` 模块从子模块导入了部分内容
- `on_message` => `nonebot.plugin.on_message`
- `on_notice` => `nonebot.plugin.on_notice`
- `on_request` => `nonebot.plugin.on_request`
- `on_metaevent` => `nonebot.plugin.on_metaevent`
- `on_startswith` => `nonebot.plugin.on_startswith`
- `on_endswith` => `nonebot.plugin.on_endswith`
- `on_keyword` => `nonebot.plugin.on_keyword`
- `on_command` => `nonebot.plugin.on_command`
- `on_shell_command` => `nonebot.plugin.on_shell_command`
- `on_regex` => `nonebot.plugin.on_regex`
- `CommandGroup` => `nonebot.plugin.CommandGroup`
- `Matchergroup` => `nonebot.plugin.MatcherGroup`
- `load_plugin` => `nonebot.plugin.load_plugin`
- `load_plugins` => `nonebot.plugin.load_plugins`
- `load_all_plugins` => `nonebot.plugin.load_all_plugins`
- `load_from_json` => `nonebot.plugin.load_from_json`
- `load_from_toml` => `nonebot.plugin.load_from_toml`
- `load_builtin_plugins` => `nonebot.plugin.load_builtin_plugins`
- `get_plugin` => `nonebot.plugin.get_plugin`
- `get_loaded_plugins` => `nonebot.plugin.get_loaded_plugins`
- `export` => `nonebot.plugin.export`
- `require` => `nonebot.plugin.require`
## `get_driver()`
- **说明**
获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。
- **返回**
- `Driver`: 全局 Driver 对象
- **异常**
- `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**
```python
driver = nonebot.get_driver()
```
## `get_app()`
- **说明**
获取全局 Driver 对应 Server App 对象。
- **返回**
- `Any`: Server App 对象
- **异常**
- `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**
```python
app = nonebot.get_app()
```
## `get_asgi()`
- **说明**
获取全局 Driver 对应 Asgi 对象。
- **返回**
- `Any`: Asgi 对象
- **异常**
- `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**
```python
asgi = nonebot.get_asgi()
```
## `get_bot(self_id=None)`
- **说明**
当提供 self_id 时，此函数是 get_bots()[self_id] 的简写；当不提供时，返回一个 Bot。
- **参数**
- `self_id: Optional[str]`: 用来识别 Bot 的 ID
- **返回**
- `Bot`: Bot 对象
- **异常**
- `KeyError`: 对应 ID 的 Bot 不存在
- `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- `ValueError`: 没有传入 ID 且没有 Bot 可用
- **用法**
```python
assert nonebot.get_bot('12345') == nonebot.get_bots()['12345']
another_unspecified_bot = nonebot.get_bot()
```
## `get_bots()`
- **说明**
获取所有通过 ws 连接 NoneBot 的 Bot 对象。
- **返回**
- `Dict[str, Bot]`: 一个以字符串 ID 为键，Bot 对象为值的字典
- **异常**
- `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
- **用法**
```python
bots = nonebot.get_bots()
```
## `init(*, _env_file=None, **kwargs)`
- **说明**
初始化 NoneBot 以及 全局 Driver 对象。
NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。
你也可以传入自定义的 \_env_file 来指定 NoneBot 从该文件读取配置。
- **参数**
- `_env_file: Optional[str]`: 配置文件名，默认从 .env.{env_name} 中读取配置
- `**kwargs`: 任意变量，将会存储到 Config 对象里
- **返回**
- `None`
- **用法**
```python
nonebot.init(database=Database(...))
```
## `run(*args, **kwargs)`
- **说明**
启动 NoneBot，即运行全局 Driver 对象。
- **参数**
- `*args`: 传入 Driver.run 的位置参数
- `**kwargs`: 传入 Driver.run 的命名参数
- **返回**
- `None`
- **用法**
```python
nonebot.run(host="127.0.0.1", port=8080)
```

327
website/versioned_docs/version-2.0.0-beta.1/api/adapters/README.md
View File

@ -1,327 +0,0 @@
---
id: index
slug: /api/adapters/
---
# NoneBot.adapters 模块
## 协议适配基类
各协议请继承以下基类，并使用 `driver.register_adapter` 注册适配器
## _class_ `Bot`
基类：`abc.ABC`
Bot 基类。用于处理上报消息，并提供 API 调用接口。
### `_calling_api_hook`
- **类型**
`Set[T_CallingAPIHook]`
- **说明**
call_api 时执行的函数
### `_called_api_hook`
- **类型**
`Set[T_CalledAPIHook]`
- **说明**
call_api 后执行的函数
### `__init__(adapter, self_id)`
- **参数**
- `self_id: str`: 机器人 ID
- `request: HTTPConnection`: request 连接对象
### `self_id`
机器人 ID
### _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)`
- **说明**
根据模板和参数生成消息对象

3
website/versioned_docs/version-2.0.0-beta.1/api/adapters/_category_.json
View File

@ -1,3 +0,0 @@
{
"position": 14
}

163
website/versioned_docs/version-2.0.0-beta.1/api/config.md
View File

@ -1,163 +0,0 @@
---
sidebar_position: 2
---
# NoneBot.config 模块
## 配置
NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 以及 [python-dotenv](https://saurabh-kumar.com/python-dotenv/) 来读取配置。
配置项需符合特殊格式或 json 序列化格式。详情见 [pydantic Field Type](https://pydantic-docs.helpmanual.io/usage/types/) 文档。
## _class_ `Env`
基类：`nonebot.config.BaseConfig`
运行环境配置。大小写不敏感。
将会从 `nonebot.init 参数` > `环境变量` > `.env 环境配置文件` 的优先级读取配置。
### `environment`
- **类型**: `str`
- **默认值**: `"prod"`
- **说明**
当前环境名。 NoneBot 将从 `.env.{environment}` 文件中加载配置。
## _class_ `Config`
基类：`nonebot.config.BaseConfig`
NoneBot 主要配置。大小写不敏感。
除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。
这些配置将会在 json 反序列化后一起带入 `Config` 类中。
### `driver`
- **类型**: `str`
- **默认值**: `"~fastapi"`
- **说明**
NoneBot 运行所使用的 `Driver` 。继承自 `nonebot.drivers.Driver` 。
配置格式为 `<module>[:<Driver>][+<module>[:<Mixin>]]*`。
`~` 为 `nonebot.drivers.` 的缩写。
### `host`
- **类型**: `IPvAnyAddress`
- **默认值**: `127.0.0.1`
- **说明**
NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。
### `port`
- **类型**: `int`
- **默认值**: `8080`
- **说明**
NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
### `log_level`
- **类型**: `Union[int, str]`
- **默认值**: `INFO`
- **说明**
配置 NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称，参考 [loguru 日志等级](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
- **示例**
```default
LOG_LEVEL=25
LOG_LEVEL=INFO
```
### `api_timeout`
- **类型**: `Optional[float]`
- **默认值**: `30.`
- **说明**
API 请求超时时间，单位: 秒。
### `superusers`
- **类型**: `Set[str]`
- **默认值**: `set()`
- **说明**
机器人超级用户。
- **示例**
```default
SUPERUSERS=["12345789"]
```
### `nickname`
- **类型**: `Set[str]`
- **默认值**: `set()`
- **说明**
机器人昵称。
### `command_start`
- **类型**: `Set[str]`
- **默认值**: `{"/"}`
- **说明**
命令的起始标记，用于判断一条消息是不是命令。
### `command_sep`
- **类型**: `Set[str]`
- **默认值**: `{"."}`
- **说明**
命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
### `session_expire_timeout`
- **类型**: `timedelta`
- **默认值**: `timedelta(minutes=2)`
- **说明**
等待用户回复的超时时间。
- **示例**
```default
SESSION_EXPIRE_TIMEOUT=120 # 单位: 秒
SESSION_EXPIRE_TIMEOUT=[DD ][HH:MM]SS[.ffffff]
SESSION_EXPIRE_TIMEOUT=P[DD]DT[HH]H[MM]M[SS]S # ISO 8601
```

9
website/versioned_docs/version-2.0.0-beta.1/api/dependencies.md
View File

@ -1,9 +0,0 @@
---
sidebar_position: 8
---
# NoneBot.dependencies 模块
## 依赖注入处理模块
该模块实现了依赖注入的定义与处理。

192
website/versioned_docs/version-2.0.0-beta.1/api/drivers/README.md
View File

@ -1,192 +0,0 @@
---
id: index
slug: /api/drivers/
---
# NoneBot.drivers 模块
## 后端驱动适配基类
各驱动请继承以下基类
## _class_ `Driver`
基类：`abc.ABC`
Driver 基类。
### `_adapters`
- **类型**
`Dict[str, Adapter]`
- **说明**
已注册的适配器列表
### `_bot_connection_hook`
- **类型**
`Set[T_BotConnectionHook]`
- **说明**
Bot 连接建立时执行的函数
### `_bot_disconnection_hook`
- **类型**
`Set[T_BotDisconnectionHook]`
- **说明**
Bot 连接断开时执行的函数
### `__init__(env, config)`
- **参数**
- `env: Env`: 包含环境信息的 Env 对象
- `config: Config`: 包含配置信息的 Config 对象
### `env`
- **类型**
`str`
- **说明**
环境名称
### `config`
- **类型**
`Config`
- **说明**
配置对象
### `_clients`
- **类型**
`Dict[str, Bot]`
- **说明**
已连接的 Bot
### _property_ `bots`
- **类型**
`Dict[str, Bot]`
- **说明**
获取当前所有已连接的 Bot
### `register_adapter(adapter, **kwargs)`
- **说明**
注册一个协议适配器
- **参数**
- `name: str`: 适配器名称，用于在连接时进行识别
- `adapter: Type[Bot]`: 适配器 Class
- `**kwargs`: 其他传递给适配器的参数
### _abstract property_ `type`
驱动类型名称
### _abstract property_ `logger`
驱动专属 logger 日志记录器
### _abstract_ `run(*args, **kwargs)`
- **说明**
启动驱动框架
- **参数**
- `*args`
- `**kwargs`
### _abstract_ `on_startup(func)`
注册一个在驱动启动时运行的函数
### _abstract_ `on_shutdown(func)`
注册一个在驱动停止时运行的函数
### `on_bot_connect(func)`
- **说明**
装饰一个函数使他在 bot 通过 WebSocket 连接成功时执行。
- **函数参数**
- `bot: Bot`: 当前连接上的 Bot 对象
### `on_bot_disconnect(func)`
- **说明**
装饰一个函数使他在 bot 通过 WebSocket 连接断开时执行。
- **函数参数**
- `bot: Bot`: 当前连接上的 Bot 对象
### `_bot_connect(bot)`
在 WebSocket 连接成功后，调用该函数来注册 bot 对象
### `_bot_disconnect(bot)`
在 WebSocket 连接断开后，调用该函数来注销 bot 对象
## _class_ `ForwardDriver`
基类：`nonebot.drivers.Driver`, `nonebot.drivers.ForwardMixin`
Forward Driver 基类。将客户端框架封装，以满足适配器使用。
## _class_ `ReverseDriver`
基类：`nonebot.drivers.Driver`
Reverse Driver 基类。将后端框架封装，以满足适配器使用。
### _abstract property_ `server_app`
驱动 APP 对象
### _abstract property_ `asgi`
驱动 ASGI 对象
## _class_ `HTTPServerSetup`
基类：`object`
## _class_ `WebSocketServerSetup`
基类：`object`

5
website/versioned_docs/version-2.0.0-beta.1/api/drivers/aiohttp.md
View File

@ -1,5 +0,0 @@
# NoneBot.drivers.aiohttp 模块
## AIOHTTP 驱动适配
本驱动仅支持客户端连接

127
website/versioned_docs/version-2.0.0-beta.1/api/drivers/fastapi.md
View File

@ -1,127 +0,0 @@
# NoneBot.drivers.fastapi 模块
## FastAPI 驱动适配
本驱动同时支持服务端以及客户端连接
后端使用方法请参考: [FastAPI 文档](https://fastapi.tiangolo.com/)
## _class_ `Config`
基类：`pydantic.env_settings.BaseSettings`
FastAPI 驱动框架设置，详情参考 FastAPI 文档
### `fastapi_openapi_url`
- **类型**
`Optional[str]`
- **说明**
`openapi.json` 地址，默认为 `None` 即关闭
### `fastapi_docs_url`
- **类型**
`Optional[str]`
- **说明**
`swagger` 地址，默认为 `None` 即关闭
### `fastapi_redoc_url`
- **类型**
`Optional[str]`
- **说明**
`redoc` 地址，默认为 `None` 即关闭
### `fastapi_reload`
- **类型**
`bool`
- **说明**
开启/关闭冷重载
### `fastapi_reload_dirs`
- **类型**
`Optional[List[str]]`
- **说明**
重载监控文件夹列表，默认为 uvicorn 默认值
### `fastapi_reload_delay`
- **类型**
`Optional[float]`
- **说明**
重载延迟，默认为 uvicorn 默认值
### `fastapi_reload_includes`
- **类型**
`Optional[List[str]]`
- **说明**
要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
### `fastapi_reload_excludes`
- **类型**
`Optional[List[str]]`
- **说明**
不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
## _class_ `Driver`
基类：[`nonebot.drivers.ReverseDriver`](README.md#nonebot.drivers.ReverseDriver)
FastAPI 驱动框架。包含反向 Server 功能。
### _property_ `type`
驱动名称: `fastapi`
### _property_ `server_app`
`FastAPI APP` 对象
### _property_ `asgi`
`FastAPI APP` 对象
### _property_ `logger`
fastapi 使用的 logger
### `on_startup(func)`
参考文档: [Events](https://fastapi.tiangolo.com/advanced/events/#startup-event)
### `on_shutdown(func)`
参考文档: [Events](https://fastapi.tiangolo.com/advanced/events/#startup-event)
### `run(host=None, port=None, *, app=None, **kwargs)`
使用 `uvicorn` 启动 FastAPI

1
website/versioned_docs/version-2.0.0-beta.1/api/drivers/httpx.md
View File

@ -1 +0,0 @@
# NoneBot.drivers.httpx 模块

95
website/versioned_docs/version-2.0.0-beta.1/api/drivers/quart.md
View File

@ -1,95 +0,0 @@
# NoneBot.drivers.quart 模块
## Quart 驱动适配
后端使用方法请参考: [Quart 文档](https://pgjones.gitlab.io/quart/index.html)
## _class_ `Config`
基类：`pydantic.env_settings.BaseSettings`
Quart 驱动框架设置
### `quart_reload`
- **类型**
`bool`
- **说明**
开启/关闭冷重载
### `quart_reload_dirs`
- **类型**
`Optional[List[str]]`
- **说明**
重载监控文件夹列表，默认为 uvicorn 默认值
### `quart_reload_delay`
- **类型**
`Optional[float]`
- **说明**
重载延迟，默认为 uvicorn 默认值
### `quart_reload_includes`
- **类型**
`Optional[List[str]]`
- **说明**
要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
### `quart_reload_excludes`
- **类型**
`Optional[List[str]]`
- **说明**
不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
## _class_ `Driver`
基类：[`nonebot.drivers.ReverseDriver`](README.md#nonebot.drivers.ReverseDriver)
Quart 驱动框架
### _property_ `type`
驱动名称: `quart`
### _property_ `server_app`
`Quart` 对象
### _property_ `asgi`
`Quart` 对象
### _property_ `logger`
Quart 使用的 logger
### `on_startup(func)`
参考文档: [Startup and Shutdown](https://pgjones.gitlab.io/quart/how_to_guides/startup_shutdown.html)
### `on_shutdown(func)`
参考文档: [Startup and Shutdown](https://pgjones.gitlab.io/quart/how_to_guides/startup_shutdown.html)
### `run(host=None, port=None, *, app=None, **kwargs)`
使用 `uvicorn` 启动 Quart

1
website/versioned_docs/version-2.0.0-beta.1/api/drivers/websockets.md
View File

@ -1 +0,0 @@
# NoneBot.drivers.websockets 模块

203
website/versioned_docs/version-2.0.0-beta.1/api/exception.md
View File

@ -1,203 +0,0 @@
---
sidebar_position: 12
---
# NoneBot.exception 模块
## 异常
下列文档中的异常是所有 NoneBot 运行时可能会抛出的。
这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。
## _exception_ `NoneBotException`
基类：`Exception`
- **说明**
所有 NoneBot 发生的异常基类。
## _exception_ `ParserExit`
基类：`nonebot.exception.NoneBotException`
- **说明**
`shell command` 处理消息失败时返回的异常
- **参数**
- `status`
- `message`
## _exception_ `ProcessException`
基类：`nonebot.exception.NoneBotException`
- **说明**
事件处理过程中发生的异常基类。
## _exception_ `IgnoredException`
基类：`nonebot.exception.ProcessException`
- **说明**
指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。
- **参数**
- `reason`: 忽略事件的原因
## _exception_ `MockApiException`
基类：`nonebot.exception.ProcessException`
- **说明**
指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。可由 api hook 抛出。
- **参数**
- `result`: 返回的内容
## _exception_ `StopPropagation`
基类：`nonebot.exception.ProcessException`
- **说明**
指示 NoneBot 终止事件向下层传播。
- **用法**
在 `Matcher.block == True` 时抛出。
## _exception_ `MatcherException`
基类：`nonebot.exception.NoneBotException`
- **说明**
所有 Matcher 发生的异常基类。
## _exception_ `SkippedException`
基类：`nonebot.exception.MatcherException`
- **说明**
指示 NoneBot 立即结束当前 `Handler` 的处理，继续处理下一个 `Handler`。
- **用法**
可以在 `Handler` 中通过 `Matcher.skip()` 抛出。
## _exception_ `TypeMisMatch`
基类：`nonebot.exception.SkippedException`
- **说明**
当前 `Handler` 的参数类型不匹配。
## _exception_ `PausedException`
基类：`nonebot.exception.MatcherException`
- **说明**
指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。
可用于用户输入新信息。
- **用法**
可以在 `Handler` 中通过 `Matcher.pause()` 抛出。
## _exception_ `RejectedException`
基类：`nonebot.exception.MatcherException`
- **说明**
指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。
可用于用户重新输入。
- **用法**
可以在 `Handler` 中通过 `Matcher.reject()` 抛出。
## _exception_ `FinishedException`
基类：`nonebot.exception.MatcherException`
- **说明**
指示 NoneBot 结束当前 `Handler` 且后续 `Handler` 不再被运行。
可用于结束用户会话。
- **用法**
可以在 `Handler` 中通过 `Matcher.finish()` 抛出。
## _exception_ `AdapterException`
基类：`nonebot.exception.NoneBotException`
- **说明**
代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception`
- **参数**
- `adapter_name: str`: 标识 adapter
## _exception_ `NoLogException`
基类：`nonebot.exception.AdapterException`
- **说明**
指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息，可在 `get_log_string` 时抛出
## _exception_ `ApiNotAvailable`
基类：`nonebot.exception.AdapterException`
- **说明**
在 API 连接不可用时抛出。
## _exception_ `NetworkError`
基类：`nonebot.exception.AdapterException`
- **说明**
在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
## _exception_ `ActionFailed`
基类：`nonebot.exception.AdapterException`
- **说明**
API 请求成功返回数据，但 API 操作失败。
## _exception_ `DriverException`
基类：`nonebot.exception.NoneBotException`
- **说明**
`Driver` 抛出的异常基类
## _exception_ `WebSocketClosed`
基类：`nonebot.exception.DriverException`
- **说明**
WebSocket 连接已关闭

31
website/versioned_docs/version-2.0.0-beta.1/api/log.md
View File

@ -1,31 +0,0 @@
---
sidebar_position: 9
---
# NoneBot.log 模块
## 日志
NoneBot 使用 [loguru](https://github.com/Delgan/loguru) 来记录日志信息。
自定义 logger 请参考 [loguru](https://github.com/Delgan/loguru) 文档。
## `logger`
- **说明**
NoneBot 日志记录器对象。
- **默认信息**
- 格式: `[%(asctime)s %(name)s] %(levelname)s: %(message)s`
- 等级: `INFO` ，根据 `config.log_level` 配置改变
- 输出: 输出至 stdout
- **用法**
```python
from nonebot.log import logger
```

390
website/versioned_docs/version-2.0.0-beta.1/api/matcher.md
View File

@ -1,390 +0,0 @@
---
sidebar_position: 5
---
# NoneBot.matcher 模块
## 事件响应器
该模块实现事件响应器的创建与运行，并提供一些快捷方法来帮助用户更好的与机器人进行对话 。
## `matchers`
- **类型**
`Dict[int, List[Type[Matcher]]]`
- **说明**
用于存储当前所有的事件响应器
## _class_ `Matcher`
基类：`object`
事件响应器类
### `plugin`
- **类型**
`Optional[Plugin]`
- **说明**
事件响应器所在插件
### `module`
- **类型**
`Optional[ModuleType]`
- **说明**
事件响应器所在插件模块
### `plugin_name`
- **类型**
`Optional[str]`
- **说明**
事件响应器所在插件名
### `module_name`
- **类型**
`Optional[str]`
- **说明**
事件响应器所在点分割插件模块路径
### `type`
- **类型**
`str`
- **说明**
事件响应器类型
### `rule`
- **类型**
`Rule`
- **说明**
事件响应器匹配规则
### `permission`
- **类型**
`Permission`
- **说明**
事件响应器触发权限
### `priority`
- **类型**
`int`
- **说明**
事件响应器优先级
### `block`
- **类型**
`bool`
- **说明**
事件响应器是否阻止事件传播
### `temp`
- **类型**
`bool`
- **说明**
事件响应器是否为临时
### `expire_time`
- **类型**
`Optional[datetime]`
- **说明**
事件响应器过期时间点
### `_default_state`
- **类型**
`T_State`
- **说明**
事件响应器默认状态
### `_default_type_updater`
- **类型**
`Optional[Dependent]`
- **说明**
事件响应器类型更新函数
### `_default_permission_updater`
- **类型**
`Optional[Dependent]`
- **说明**
事件响应器权限更新函数
### `__init__()`
实例化 Matcher 以便运行
### `handlers`
- **类型**
`List[Handler]`
- **说明**
事件响应器拥有的事件处理函数列表
### _classmethod_ `new(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, plugin=None, module=None, expire_time=None, default_state=None, default_type_updater=None, default_permission_updater=None)`
- **说明**
创建一个新的事件响应器，并存储至 [matchers](#matchers)
- **参数**
- `type_: str`: 事件响应器类型，与 `event.get_type()` 一致时触发，空字符串表示任意
- `rule: Optional[Rule]`: 匹配规则
- `permission: Optional[Permission]`: 权限
- `handlers: Optional[List[T_Handler]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器，即触发一次后删除
- `priority: int`: 响应优先级
- `block: bool`: 是否阻止事件向更低优先级的响应器传播
- `plugin: Optional[Plugin]`: 事件响应器所在插件
- `module: Optional[ModuleType]`: 事件响应器所在模块
- `default_state: Optional[T_State]`: 默认状态 `state`
- `expire_time: Optional[datetime]`: 事件响应器最终有效时间点，过时即被删除
- **返回**
- `Type[Matcher]`: 新的事件响应器类
### _async classmethod_ `check_perm(bot, event, stack=None, dependency_cache=None)`
- **说明**
检查是否满足触发权限
- **参数**
- `bot: Bot`: Bot 对象
- `event: Event`: 上报事件
- **返回**
- `bool`: 是否满足权限
### _async classmethod_ `check_rule(bot, event, state, stack=None, dependency_cache=None)`
- **说明**
检查是否满足匹配规则
- **参数**
- `bot: Bot`: Bot 对象
- `event: Event`: 上报事件
- `state: T_State`: 当前状态
- **返回**
- `bool`: 是否满足匹配规则
### _classmethod_ `type_updater(func)`
- **说明**
装饰一个函数来更改当前事件响应器的默认响应事件类型更新函数
- **参数**
- `func: T_TypeUpdater`: 响应事件类型更新函数
### _classmethod_ `permission_updater(func)`
- **说明**
装饰一个函数来更改当前事件响应器的默认会话权限更新函数
- **参数**
- `func: T_PermissionUpdater`: 会话权限更新函数
### _classmethod_ `handle(parameterless=None)`
- **说明**
装饰一个函数来向事件响应器直接添加一个处理函数
- **参数**
- `parameterless: Optional[List[Any]]`: 非参数类型依赖列表
### _classmethod_ `receive(id='', parameterless=None)`
- **说明**
装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
- **参数**
- `id: str`: 消息 ID
- `parameterless: Optional[List[Any]]`: 非参数类型依赖列表
### _classmethod_ `got(key, prompt=None, parameterless=None)`
- **说明**
装饰一个函数来指示 NoneBot 当要获取的 `key` 不存在时接收用户新的一条消息并经过 `ArgsParser` 处理后再运行该函数，如果 `key` 已存在则直接继续运行
- **参数**
- `key: str`: 参数名
- `prompt: Optional[Union[str, Message, MessageSegment, MessageFormatter]]`: 在参数不存在时向用户发送的消息
- `args_parser: Optional[T_ArgsParser]`: 可选参数解析函数，空则使用默认解析函数
- `parameterless: Optional[List[Any]]`: 非参数类型依赖列表
### _async classmethod_ `send(message, **kwargs)`
- **说明**
发送一条消息给当前交互用户
- **参数**
- `message: Union[str, Message, MessageSegment]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### _async classmethod_ `finish(message=None, **kwargs)`
- **说明**
发送一条消息给当前交互用户并结束当前事件响应器
- **参数**
- `message: Union[str, Message, MessageSegment, MessageTemplate]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### _async classmethod_ `pause(prompt=None, **kwargs)`
- **说明**
发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
- **参数**
- `prompt: Union[str, Message, MessageSegment, MessageTemplate]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### _async classmethod_ `reject(prompt=None, **kwargs)`
- **说明**
最近使用 `got` / `receive` 接收的消息不符合预期，发送一条消息给当前交互用户并暂停事件响应器，
在接收用户新的一条消息后继续当前处理函数
- **参数**
- `prompt: Union[str, Message, MessageSegment, MessageTemplate]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### _async classmethod_ `reject_arg(key, prompt=None, **kwargs)`
- **说明**
最近使用 `got` 接收的消息不符合预期，发送一条消息给当前交互用户并暂停事件响应器，
在接收用户新的一条消息后继续当前处理函数
- **参数**
- `key: str`: 参数名
- `prompt: Union[str, Message, MessageSegment, MessageTemplate]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### _async classmethod_ `reject_receive(id='', prompt=None, **kwargs)`
- **说明**
最近使用 `got` 接收的消息不符合预期，发送一条消息给当前交互用户并暂停事件响应器，
在接收用户新的一条消息后继续当前处理函数
- **参数**
- `id: str`: 消息 id
- `prompt: Union[str, Message, MessageSegment, MessageTemplate]`: 消息内容
- `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
### `stop_propagation()`
- **说明**
阻止事件传播

52
website/versioned_docs/version-2.0.0-beta.1/api/message.md
View File

@ -1,52 +0,0 @@
---
sidebar_position: 4
---
# NoneBot.message 模块
## 事件处理
NoneBot 内部处理并按优先级分发事件给所有事件响应器，提供了多个插槽以进行事件的预处理等。
## `event_preprocessor(func)`
- **说明**
事件预处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。
## `event_postprocessor(func)`
- **说明**
事件后处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。
## `run_preprocessor(func)`
- **说明**
运行预处理。装饰一个函数，使它在每次事件响应器运行前执行。
## `run_postprocessor(func)`
- **说明**
运行后处理。装饰一个函数，使它在每次事件响应器运行后执行。
## _async_ `handle_event(bot, event)`
- **说明**
处理一个事件。调用该函数以实现分发事件。
- **参数**
- `bot: Bot`: Bot 对象
- `event: Event`: Event 对象
- **示例**
```python
import asyncio
asyncio.create_task(handle_event(bot, event))
```

98
website/versioned_docs/version-2.0.0-beta.1/api/permission.md
View File

@ -1,98 +0,0 @@
---
sidebar_position: 7
---
# NoneBot.permission 模块
## 权限
每个 `Matcher` 拥有一个 `Permission` ，其中是 `PermissionChecker` 的集合，只要有一个 `PermissionChecker` 检查结果为 `True` 时就会继续运行。
:::tip 提示
`PermissionChecker` 既可以是 async function 也可以是 sync function
:::
## _class_ `Permission`
基类：`object`
- **说明**
`Matcher` 规则类，当事件传递时，在 `Matcher` 运行前进行检查。
- **示例**
```python
Permission(async_function) | sync_function
# 等价于
from nonebot.utils import run_sync
Permission(async_function, run_sync(sync_function))
```
### `__init__(*checkers)`
- **参数**
- `*checkers: Union[T_PermissionChecker, Dependent[bool]`: PermissionChecker
### `checkers`
- **说明**
存储 `PermissionChecker`
- **类型**
- `Set[Dependent[bool]]`
### _async_ `__call__(bot, event, stack=None, dependency_cache=None)`
- **说明**
检查是否满足某个权限
- **参数**
- `bot: Bot`: Bot 对象
- `event: Event`: Event 对象
- `stack: Optional[AsyncExitStack]`: 异步上下文栈
- `dependency_cache: Optional[CacheDict[T_Handler, Any]]`: 依赖缓存
- **返回**
- `bool`
## `MESSAGE`
- **说明**: 匹配任意 `message` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 message type 的 Matcher。
## `NOTICE`
- **说明**: 匹配任意 `notice` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 notice type 的 Matcher。
## `REQUEST`
- **说明**: 匹配任意 `request` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 request type 的 Matcher。
## `METAEVENT`
- **说明**: 匹配任意 `meta_event` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 meta_event type 的 Matcher。
## `USER(*users, perm=None)`
- **说明**
`event` 的 `session_id` 在白名单内且满足 perm
- **参数**
- `*user: str`: 白名单
- `perm: Optional[Permission]`: 需要同时满足的权限
## `SUPERUSER`
- **说明**: 匹配任意超级用户消息类型事件

953
website/versioned_docs/version-2.0.0-beta.1/api/plugin.md
View File

@ -1,953 +0,0 @@
---
sidebar_position: 3
---
# NoneBot.plugin 模块
## 插件
为 NoneBot 插件开发提供便携的定义函数。
## `plugins`
- **类型**
`Dict[str, Plugin]`
- **说明**
已加载的插件
## _class_ `Plugin`
基类：`object`
存储插件信息
### `name`
- **类型**: `str`
- **说明**: 插件名称，使用 文件/文件夹 名称作为插件名
### `module`
- **类型**: `ModuleType`
- **说明**: 插件模块对象
### `module_name`
- **类型**: `str`
- **说明**: 点分割模块路径
### `manager`
- **类型**: `PluginManager`
- **说明**: 导入该插件的插件管理器
### `export`
- **类型**: `Export`
- **说明**: 插件内定义的导出内容
### `matcher`
- **类型**: `Set[Type[Matcher]]`
- **说明**: 插件内定义的 `Matcher`
### `parent_plugin`
- **类型**: `Optional[Plugin]`
- **说明**: 父插件
### `sub_plugins`
- **类型**: `Set[Plugin]`
- **说明**: 子插件集合
## `get_plugin(name)`
- **说明**
获取当前导入的某个插件。
- **参数**
- `name: str`: 插件名，与 `load_plugin` 参数一致。如果为 `load_plugins` 导入的插件，则为文件(夹)名。
- **返回**
- `Optional[Plugin]`
## `get_loaded_plugins()`
- **说明**
获取当前已导入的所有插件。
- **返回**
- `Set[Plugin]`
## `on(type='', rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=False, state=None, _depth=0)`
- **说明**
注册一个基础事件响应器，可自定义类型。
- **参数**
- `type: str`: 事件响应器类型
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_metaevent(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, _depth=0)`
- **说明**
注册一个元事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_message(rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=True, state=None, _depth=0)`
- **说明**
注册一个消息事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_notice(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, _depth=0)`
- **说明**
注册一个通知事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_request(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, _depth=0)`
- **说明**
注册一个请求事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_startswith(msg, rule=None, ignorecase=False, _depth=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容开头时响应。
- **参数**
- `msg: Union[str, Tuple[str, ...]]`: 指定消息开头内容
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `ignorecase: bool`: 是否忽略大小写
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_endswith(msg, rule=None, ignorecase=False, _depth=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容结尾时响应。
- **参数**
- `msg: Union[str, Tuple[str, ...]]`: 指定消息结尾内容
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `ignorecase: bool`: 是否忽略大小写
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_keyword(keywords, rule=None, _depth=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。
- **参数**
- `keywords: Set[str]`: 关键词列表
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_command(cmd, rule=None, aliases=None, _depth=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息以指定命令开头时响应。
命令匹配规则参考: [命令形式匹配](rule.md#command-command)
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_shell_command(cmd, rule=None, aliases=None, parser=None, _depth=0, **kwargs)`
- **说明**
注册一个支持 `shell_like` 解析参数的命令消息事件响应器。
与普通的 `on_command` 不同的是，在添加 `parser` 参数时, 响应器会自动处理消息。
并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名
- `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `on_regex(pattern, flags=0, rule=None, _depth=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息匹配正则表达式时响应。
命令匹配规则参考: [正则匹配](rule.md#regex-regex-flags-0)
- **参数**
- `pattern: str`: 正则表达式
- `flags: Union[int, re.RegexFlag]`: 正则匹配标志
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## _class_ `CommandGroup`
基类：`object`
命令组，用于声明一组有相同名称前缀的命令。
### `__init__(cmd, **kwargs)`
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 命令前缀
- `**kwargs`: 其他传递给 `on_command` 的参数默认值，参考 [on_command](#on-command-cmd-rule-none-aliases-none-kwargs)
### `basecmd`
- **类型**: `Tuple[str, ...]`
- **说明**: 命令前缀
### `base_kwargs`
- **类型**: `Dict[str, Any]`
- **说明**: 其他传递给 `on_command` 的参数默认值
### `command(cmd, **kwargs)`
- **说明**
注册一个新的命令。
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 命令前缀
- `**kwargs`: 其他传递给 `on_command` 的参数，将会覆盖命令组默认值
- **返回**
- `Type[Matcher]`
### `shell_command(cmd, **kwargs)`
- **说明**
注册一个新的命令。
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 命令前缀
- `**kwargs`: 其他传递给 `on_shell_command` 的参数，将会覆盖命令组默认值
- **返回**
- `Type[Matcher]`
## _class_ `MatcherGroup`
基类：`object`
事件响应器组合，统一管理。为 `Matcher` 创建提供默认属性。
### `__init__(**kwargs)`
- **说明**
创建一个事件响应器组合，参数为默认值，与 `on` 一致
### `matchers`
- **类型**
`List[Type[Matcher]]`
- **说明**
组内事件响应器列表
### `base_kwargs`
- **类型**: `Dict[str, Any]`
- **说明**: 其他传递给 `on` 的参数默认值
### `on(**kwargs)`
- **说明**
注册一个基础事件响应器，可自定义类型。
- **参数**
- `type: str`: 事件响应器类型
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_metaevent(**kwargs)`
- **说明**
注册一个元事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_message(**kwargs)`
- **说明**
注册一个消息事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_notice(**kwargs)`
- **说明**
注册一个通知事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_request(**kwargs)`
- **说明**
注册一个请求事件响应器。
- **参数**
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_startswith(msg, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容开头时响应。
- **参数**
- `msg: Union[str, Tuple[str, ...]]`: 指定消息开头内容
- `ignorecase: bool`: 是否忽略大小写
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_endswith(msg, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容结尾时响应。
- **参数**
- `msg: Union[str, Tuple[str, ...]]`: 指定消息结尾内容
- `ignorecase: bool`: 是否忽略大小写
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_keyword(keywords, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。
- **参数**
- `keywords: Set[str]`: 关键词列表
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_command(cmd, aliases=None, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息以指定命令开头时响应。
命令匹配规则参考: [命令形式匹配](rule.md#command-command)
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容
- `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_shell_command(cmd, aliases=None, parser=None, **kwargs)`
- **说明**
注册一个支持 `shell_like` 解析参数的命令消息事件响应器。
与普通的 `on_command` 不同的是，在添加 `parser` 参数时, 响应器会自动处理消息。
并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中
- **参数**
- `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容
- `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名
- `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
### `on_regex(pattern, flags=0, **kwargs)`
- **说明**
注册一个消息事件响应器，并且当消息匹配正则表达式时响应。
命令匹配规则参考: [正则匹配](rule.md#regex-regex-flags-0)
- **参数**
- `pattern: str`: 正则表达式
- `flags: Union[int, re.RegexFlag]`: 正则匹配标志
- `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则
- `permission: Optional[Union[Permission, T_PermissionChecker]] =]]`: 事件响应权限
- `handlers: Optional[List[Union[T_Handler, Dependent]]]`: 事件处理函数列表
- `temp: bool`: 是否为临时事件响应器（仅执行一次）
- `priority: int`: 事件响应器优先级
- `block: bool`: 是否阻止事件向更低优先级传递
- `state: Optional[T_State]`: 默认 state
- **返回**
- `Type[Matcher]`
## `load_plugin(module_path)`
- **说明**
使用 `PluginManager` 加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
- **参数**
- `module_path: str`: 插件名称 `path.to.your.plugin`
- **返回**
- `Optional[Plugin]`
## `load_plugins(*plugin_dir)`
- **说明**
导入目录下多个插件，以 `_` 开头的插件不会被导入！
- **参数**
- `*plugin_dir: str`: 插件路径
- **返回**
- `Set[Plugin]`
## `load_all_plugins(module_path, plugin_dir)`
- **说明**
导入指定列表中的插件以及指定目录下多个插件，以 `_` 开头的插件不会被导入！
- **参数**
- `module_path: Iterable[str]`: 指定插件集合
- `plugin_dir: Iterable[str]`: 指定插件路径集合
- **返回**
- `Set[Plugin]`
## `load_from_json(file_path, encoding='utf-8')`
- **说明**
导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入！
- **参数**
- `file_path: str`: 指定 json 文件路径
- `encoding: str`: 指定 json 文件编码
- **返回**
- `Set[Plugin]`
## `load_from_toml(file_path, encoding='utf-8')`
- **说明**
导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，
以 `_` 开头的插件不会被导入！
- **参数**
- `file_path: str`: 指定 toml 文件路径
- `encoding: str`: 指定 toml 文件编码
- **返回**
- `Set[Plugin]`
## `load_builtin_plugins(name)`
- **说明**
导入 NoneBot 内置插件
- **返回**
- `Plugin`
## `require(name)`
- **说明**
获取一个插件的导出内容
- **参数**
- `name: str`: 插件名，与 `load_plugin` 参数一致。如果为 `load_plugins` 导入的插件，则为文件(夹)名。
- **返回**
- `Export`
- **异常**
- `RuntimeError`: 插件无法加载
## _class_ `Export`
基类：`dict`
- **说明**
插件导出内容以使得其他插件可以获得。
- **示例**
```python
nonebot.export().default = "bar"
@nonebot.export()
def some_function():
pass
# this doesn't work before python 3.9
# use
# export = nonebot.export(); @export.sub
# instead
# See also PEP-614: https://www.python.org/dev/peps/pep-0614/
@nonebot.export().sub
def something_else():
pass
```
## `export()`
- **说明**
获取插件的导出内容对象
- **返回**
- `Export`

193
website/versioned_docs/version-2.0.0-beta.1/api/rule.md
View File

@ -1,193 +0,0 @@
---
sidebar_position: 6
---
# NoneBot.rule 模块
## 规则
每个事件响应器 `Matcher` 拥有一个匹配规则 `Rule` ，其中是 `RuleChecker` 的集合，只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
:::tip 提示
`RuleChecker` 既可以是 async function 也可以是 sync function
:::
## _class_ `Rule`
基类：`object`
- **说明**
`Matcher` 规则类，当事件传递时，在 `Matcher` 运行前进行检查。
- **示例**
```python
Rule(async_function) & sync_function
# 等价于
from nonebot.utils import run_sync
Rule(async_function, run_sync(sync_function))
```
### `__init__(*checkers)`
- **参数**
- `*checkers: Union[T_RuleChecker, Dependent[bool]]`: RuleChecker
### `checkers`
- **说明**
存储 `RuleChecker`
- **类型**
- `Set[Dependent[bool]]`
### _async_ `__call__(bot, event, state, stack=None, dependency_cache=None)`
- **说明**
检查是否符合所有规则
- **参数**
- `bot: Bot`: Bot 对象
- `event: Event`: Event 对象
- `state: T_State`: 当前 State
- `stack: Optional[AsyncExitStack]`: 异步上下文栈
- `dependency_cache: Optional[CacheDict[T_Handler, Any]]`: 依赖缓存
- **返回**
- `bool`
## `startswith(msg, ignorecase=False)`
- **说明**
匹配消息开头
- **参数**
- `msg: str`: 消息开头字符串
## `endswith(msg, ignorecase=False)`
- **说明**
匹配消息结尾
- **参数**
- `msg: str`: 消息结尾字符串
## `keyword(*keywords)`
- **说明**
匹配消息关键词
- **参数**
- `*keywords: str`: 关键词
## `command(*cmds)`
- **说明**
命令形式匹配，根据配置里提供的 `command_start`, `command_sep` 判断消息是否为命令。
可以通过 `state["_prefix"]["command"]` 获取匹配成功的命令（例：`("test",)`），通过 `state["_prefix"]["raw_command"]` 获取匹配成功的原始命令文本（例：`"/test"`）。
- **参数**
- `*cmds: Union[str, Tuple[str, ...]]`: 命令内容
- **示例**
使用默认 `command_start`, `command_sep` 配置
命令 `("test",)` 可以匹配：`/test` 开头的消息
命令 `("test", "sub")` 可以匹配”`/test.sub` 开头的消息
:::tip 提示
命令内容与后续消息间无需空格！
:::
## _class_ `ArgumentParser`
基类：`argparse.ArgumentParser`
- **说明**
`shell_like` 命令参数解析器，解析出错时不会退出程序。
## `shell_command(*cmds, parser=None)`
- **说明**
支持 `shell_like` 解析参数的命令形式匹配，根据配置里提供的 `command_start`, `command_sep` 判断消息是否为命令。
可以通过 `state["_prefix"]["command"]` 获取匹配成功的命令（例：`("test",)`），通过 `state["_prefix"]["raw_command"]` 获取匹配成功的原始命令文本（例：`"/test"`）。
可以通过 `state["argv"]` 获取用户输入的原始参数列表
添加 `parser` 参数后, 可以自动处理消息并将结果保存在 `state["args"]` 中。
- **参数**
- `*cmds: Union[str, Tuple[str, ...]]`: 命令内容
- `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象
- **示例**
使用默认 `command_start`, `command_sep` 配置，更多示例参考 `argparse` 标准库文档。
```python
from nonebot.rule import ArgumentParser
parser = ArgumentParser()
parser.add_argument("-a", action="store_true")
rule = shell_command("ls", parser=parser)
```
:::tip 提示
命令内容与后续消息间无需空格！
:::
## `regex(regex, flags=0)`
- **说明**
根据正则表达式进行匹配。
可以通过 `state["_matched"]` `state["_matched_groups"]` `state["_matched_dict"]`
获取正则表达式匹配成功的文本。
- **参数**
- `regex: str`: 正则表达式
- `flags: Union[int, re.RegexFlag]`: 正则标志
:::tip 提示
正则表达式匹配使用 search 而非 match，如需从头匹配请使用 `r"^xxx"` 来确保匹配开头
:::
## `to_me()`
- **说明**
通过 `event.is_tome()` 判断事件是否与机器人有关
- **参数**
- 无

267
website/versioned_docs/version-2.0.0-beta.1/api/typing.md
View File

@ -1,267 +0,0 @@
---
sidebar_position: 11
---
# NoneBot.typing 模块
## 类型
下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，见 [PEP 484](https://www.python.org/dev/peps/pep-0484/)、[PEP 526](https://www.python.org/dev/peps/pep-0526/) 和 [typing](https://docs.python.org/3/library/typing.html)。
除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。
以下类型均可从 nonebot.typing 模块导入。
## `T_State`
- **类型**
`Dict[Any, Any]`
- **说明**
事件处理状态 State 类型
## `T_BotConnectionHook`
- **类型**
`Callable[[Bot], Awaitable[None]]`
- **说明**
Bot 连接建立时执行的函数
## `T_BotDisconnectionHook`
- **类型**
`Callable[[Bot], Awaitable[None]]`
- **说明**
Bot 连接断开时执行的函数
## `T_CallingAPIHook`
- **类型**
`Callable[[Bot, str, Dict[str, Any]], Awaitable[None]]`
- **说明**
`bot.call_api` 时执行的函数
## `T_CalledAPIHook`
- **类型**
`Callable[[Bot, Optional[Exception], str, Dict[str, Any], Any], Awaitable[None]]`
- **说明**
`bot.call_api` 后执行的函数，参数分别为 bot, exception, api, data, result
## `T_EventPreProcessor`
- **类型**
`Callable[..., Union[None, Awaitable[None]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
事件预处理函数 EventPreProcessor 类型
## `T_EventPostProcessor`
- **类型**
`Callable[..., Union[None, Awaitable[None]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
事件预处理函数 EventPostProcessor 类型
## `T_RunPreProcessor`
- **类型**
`Callable[..., Union[None, Awaitable[None]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `MatcherParam`: Matcher 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
事件响应器运行前预处理函数 RunPreProcessor 类型
## `T_RunPostProcessor`
- **类型**
`Callable[..., Union[None, Awaitable[None]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `MatcherParam`: Matcher 对象
- `ExceptionParam`: 异常对象（可能为 None）
- `DefaultParam`: 带有默认值的参数
- **说明**
事件响应器运行前预处理函数 RunPostProcessor 类型，第二个参数为运行时产生的错误（如果存在）
## `T_RuleChecker`
- **类型**
`Callable[..., Union[bool, Awaitable[bool]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
RuleChecker 即判断是否响应事件的处理函数。
## `T_PermissionChecker`
- **类型**
`Callable[..., Union[bool, Awaitable[bool]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
RuleChecker 即判断是否响应消息的处理函数。
## `T_Handler`
- **类型**
`Callable[..., Any]`
- **说明**
Handler 处理函数。
## `T_TypeUpdater`
- **类型**
`Callable[..., Union[None, Awaitable[None]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `MatcherParam`: Matcher 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应的事件类型。默认会更新为 `message`。
## `T_PermissionUpdater`
- **类型**
`Callable[..., Union[Permission, Awaitable[Permission]]]`
- **依赖参数**
- `DependParam`: 子依赖参数
- `BotParam`: Bot 对象
- `EventParam`: Event 对象
- `StateParam`: State 对象
- `MatcherParam`: Matcher 对象
- `DefaultParam`: 带有默认值的参数
- **说明**
PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新会话对象权限。默认会更新为当前事件的触发对象。
## `T_DependencyCache`
- **类型**
`Dict[Callable[..., Any], Task[Any]]`
- **说明**
依赖缓存, 用于存储依赖函数的返回值

55
website/versioned_docs/version-2.0.0-beta.1/api/utils.md
View File

@ -1,55 +0,0 @@
---
sidebar_position: 10
---
# NoneBot.utils 模块
## `escape_tag(s)`
- **说明**
用于记录带颜色日志时转义 `<tag>` 类型特殊标签
- **参数**
- `s: str`: 需要转义的字符串
- **返回**
- `str`
## `run_sync(call)`
- **说明**
一个用于包装 sync function 为 async function 的装饰器
- **参数**
- `call: Callable[P, R]`: 被装饰的同步函数
- **返回**
- `Callable[P, Awaitable[R]]`
## _class_ `DataclassEncoder`
基类：`json.encoder.JSONEncoder`
- **说明**
在 JSON 序列化 `Message` (List[Dataclass]) 时使用的 `JSONEncoder`
## `logger_wrapper(logger_name)`
- **说明**
用于打印 adapter 的日志。
- **Log 参数**
- `level: Literal["CRITICAL", "WARNING", "INFO", "DEBUG", "TRACE"]`: 日志等级
- `message: str`: 日志信息
- `exception: Optional[Exception]`: 异常信息

33
website/versioned_docs/version-2.0.0-beta.1/start/editor-support.md
View File

@ -1,33 +0,0 @@
---
sidebar_position: 80
description: 编辑器支持
---
# 编辑器支持
框架基于 [PEP484](https://www.python.org/dev/peps/pep-0484/), [PEP 561](https://www.python.org/dev/peps/pep-0517/), [PEP8](https://www.python.org/dev/peps/pep-0008/) 等规范进行开发并且是 **Fully Typed**。框架使用 `pyright` (`pylance`) 工具进行类型检查，确保代码可以被编辑器正确解析。
## 编辑器推荐配置
### Visual Studio Code
在 Visual Studio Code 中，可以使用 `pylance` Language Server 并启用 `Type Checking` 以达到最佳开发体验。
向 `.vscode` 文件夹中对应文件添加以下配置并在 VSCode 插件面板安装推荐插件：
```json title=extensions.json
{
"recommendations": ["ms-python.python", "ms-python.vscode-pylance"]
}
```
```json title=settings.json
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "basic"
}
```
### 其他
欢迎提交 Pull Request 添加其他编辑器配置推荐。点击左下角 `Edit this page` 前往编辑。

40
website/versioned_docs/version-2.0.0-beta.1/start/install-adapter.md
View File

@ -1,40 +0,0 @@
---
sidebar_position: 2
description: 通过脚手架, pip 安装适配器
---
# 安装协议适配器
## 查看
前往 [商店](/store) 即可查看所有协议适配器。
或者使用 `nb-cli` 命令行查看：
```bash
nb adapter list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb adapter install <adapter-name>
```
或者使用交互模式安装：
```bash
nb adapter install
```
也可以使用 `pip` 安装
```bash
pip install <adapter-name>
```
<!-- TODO: asciinema for install adapter -->

42
website/versioned_docs/version-2.0.0-beta.1/start/install-driver.md
View File

@ -1,42 +0,0 @@
---
sidebar_position: 1
description: 通过脚手架, pip 安装驱动器
---
# 安装驱动器
NoneBot 在默认安装情况下内置了 `fastapi` 服务端驱动器，其他驱动器如 `httpx`, `aiohttp` 则需要额外安装。
## 查看
前往 [商店](/store) 即可查看所有驱动器。
或者使用 `nb-cli` 命令行查看：
```bash
nb driver list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb driver install <driver-name>
```
或者使用交互模式安装：
```bash
nb driver install
```
也可以使用 `pip` 安装
```bash
pip install <driver-name>
```
<!-- TODO: asciinema for install driver -->

40
website/versioned_docs/version-2.0.0-beta.1/start/install-plugin.md
View File

@ -1,40 +0,0 @@
---
sidebar_position: 3
description: 通过脚手架, pip 安装插件
---
# 安装第三方插件
## 查看
前往 [商店](/store) 即可查看所有发布的插件。
或者使用 `nb-cli` 命令行查看：
```bash
nb plugin list
```
## 安装
前往 [商店](/store) 点击复制 `nb-cli` 安装命令至命令行执行即可安装。
或者自行输入命令安装：
```bash
nb plugin install <plugin-name>
```
或者使用交互模式安装：
```bash
nb plugin install
```
也可以使用 `pip` 安装
```bash
pip install <plugin-name>
```
<!-- TODO: asciinema for install plugin -->

75
website/versioned_docs/version-2.0.0-beta.1/start/installation.md
View File

@ -1,75 +0,0 @@
---
sidebar_position: 0
description: 通过脚手架, PyPI, GitHub 安装 NoneBot
options:
menu:
weight: 10
category: guide
---
# 安装 NoneBot
:::warning 注意
请确保你的 Python 版本 >= 3.7.3。
:::
:::warning 注意
请在安装 NoneBot v2 之前卸载 NoneBot v1
```bash
pip uninstall nonebot
```
:::
## 通过脚手架安装 (推荐)
1. (可选) 使用你喜欢的 Python 环境管理工具 (如 `poetry`, `venv`, `conda` 等) 创建新的虚拟环境
2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装
```bash
pip install nb-cli
```
<!-- TODO: asciinema for installation -->
:::important 提示
`nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md)
:::
## 不使用脚手架 (纯净安装)
如果你不想使用脚手架，可以直接安装 `nonebot2`，并自行完成开发配置。
```bash
pip install nonebot2
# 也可以通过 poetry 安装
poetry add nonebot2
```
## 从 GitHub 安装
如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
:::warning 注意
直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
在任何情况下请不要将其应用于生产环境!
:::
```bash title="Install From Github"
# master分支
poetry add git+https://github.com/nonebot/nonebot2.git#master
# dev分支
poetry add git+https://github.com/nonebot/nonebot2.git#dev
```
或者在克隆 Git 仓库后手动安装：
```bash
git clone https://github.com/nonebot/nonebot2.git
cd nonebot2
poetry install --no-dev # 推荐
pip install . # 不推荐
```

13
website/versioned_docs/version-2.0.0-beta.1/start/nb-cli.md
View File

@ -1,13 +0,0 @@
---
sidebar_position: 90
description: 使用 nb-cli 帮助开发
options:
menu:
weight: 11
category: guide
---
# 使用脚手架
<!-- TODO: nb-cli docs -->

28
website/versioned_docs/version-2.0.0-beta.1/start/question.md
View File

@ -1,28 +0,0 @@
---
sidebar-position: 100
description: 如何获取帮助
---
# 遇到问题
如果在安装或者开发过程中遇到了任何问题，可以通过以下方式解决：
1. 点击下方链接前往 GitHub ~~点击 star~~ ，前往 Issues 页面，在 `New Issue` Template 中选择 `Question`
NoneBot2: [![nonebot2](https://img.shields.io/github/stars/nonebot/nonebot2?style=social)](https://github.com/nonebot/nonebot2)
2. 通过 QQ 群 (点击下方链接直达)
[![QQ Chat](https://img.shields.io/badge/QQ%E7%BE%A4-768887710-orange?style=social)](https://jq.qq.com/?_wv=1027&k=5OFifDh)
3. 通过 QQ 频道
前往 QQ 频道搜索 `NoneBot` 点击加入
4. 通过 Telegram 群 (点击下方链接直达)
[![Telegram Chat](https://img.shields.io/badge/telegram-cqhttp-blue?style=social)](https://t.me/cqhttp)
5. 通过 Discord 服务器 (点击下方链接直达)
[![Discord Server](https://discordapp.com/api/guilds/847819937858584596/widget.png?style=shield)](https://discord.gg/VKtE6Gdc4h)

Some files were not shown because too many files have changed in this diff Show More