mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-09-07 12:36:47 +00:00
Ju4tCode
GitHub
@ -15,17 +15,17 @@ options:
|
||||
:::
|
||||
|
||||
:::tip 提示
|
||||
如何**安装**驱动器请参考 [安装驱动器](../start/install-driver.mdx)
|
||||
如何**安装**驱动器请参考[安装驱动器](../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,33 +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`。
|
||||
类型：`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()
|
||||
@ -101,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
|
||||
@ -143,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()
|
||||
@ -154,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 请求。
|
||||
@ -186,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
|
||||
@ -200,7 +200,7 @@ DRIVER=~httpx
|
||||
|
||||
### websockets
|
||||
|
||||
类型: `ForwardDriver`
|
||||
类型：`ForwardDriver`
|
||||
|
||||
:::warning 注意
|
||||
本驱动器仅支持 WebSocket 请求，不支持 HTTP 请求。
|
||||
@ -208,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
|
||||
@ -222,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
|
||||
|
||||
@ -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,14 +140,14 @@ DRIVER=~fastapi+~httpx+~websockets
|
||||
DRIVER=~fastapi+~aiohttp
|
||||
```
|
||||
|
||||
各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。
|
||||
各驱动器的功能与区别请参考[选择驱动器](./choose-driver.md)。
|
||||
|
||||
### Host
|
||||
|
||||
- **类型**: `IPvAnyAddress`
|
||||
- **默认值**: `127.0.0.1`
|
||||
|
||||
使用 `ReversedDriver` 时，NoneBot 监听的 IP/主机名。
|
||||
使用 `ReversedDriver` 时，NoneBot2 监听的 IP/主机名。
|
||||
|
||||
```env
|
||||
HOST=127.0.0.1
|
||||
@ -158,7 +158,7 @@ HOST=127.0.0.1
|
||||
- **类型**: `int`
|
||||
- **默认值**: `8080`
|
||||
|
||||
使用 `ReversedDriver` 时，NoneBot 监听的端口。
|
||||
使用 `ReversedDriver` 时，NoneBot2 监听的端口。
|
||||
|
||||
```env
|
||||
PORT=8080
|
||||
@ -169,7 +169,7 @@ PORT=8080
|
||||
- **类型**: `int | str`
|
||||
- **默认值**: `INFO`
|
||||
|
||||
NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称
|
||||
NoneBot2 日志输出等级，可以为 `int` 类型等级或等级名称
|
||||
|
||||
参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
|
||||
|
||||
@ -233,7 +233,7 @@ COMMAND_SEP={".", "/"}
|
||||
- **类型**: `timedelta`
|
||||
- **默认值**: `timedelta(minutes=2)`
|
||||
|
||||
用户会话超时时间，配置格式参考 [`Pydantic Field`](https://pydantic-docs.helpmanual.io/usage/types/#datetime-types) 。
|
||||
用户会话超时时间，配置格式参考 [Datetime Types](https://pydantic-docs.helpmanual.io/usage/types/#datetime-types)。
|
||||
|
||||
```env
|
||||
SESSION_EXPIRE_TIMEOUT=120
|
||||
|
||||
@ -41,10 +41,10 @@ nb create
|
||||
```
|
||||
|
||||
- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
|
||||
- `.env`, `.env.dev`, `.env.prod`: 各环境配置文件
|
||||
- `.env`、`.env.dev`、`.env.prod`: 各环境配置文件
|
||||
- `bot.py`: bot 入口文件
|
||||
- `pyproject.toml`: 项目插件配置文件
|
||||
- `Dockerfile`, `docker-compose.yml`: Docker 镜像配置文件
|
||||
- `Dockerfile`、`docker-compose.yml`: Docker 镜像配置文件
|
||||
|
||||
## 启动 Bot
|
||||
|
||||
@ -55,7 +55,7 @@ nb create
|
||||
|
||||
:::
|
||||
|
||||
1. 通过 `nb-cli`
|
||||
1. 通过 nb-cli
|
||||
|
||||
```bash
|
||||
nb run [--file=bot.py] [--app=app]
|
||||
@ -68,12 +68,12 @@ nb create
|
||||
options={{ theme: "monokai", startAt: 15.3, poster: "npt:20.3" }}
|
||||
/>
|
||||
|
||||
2. 直接通过 `python` 启动
|
||||
2. 直接通过 Python 启动
|
||||
|
||||
```bash
|
||||
python bot.py
|
||||
```
|
||||
|
||||
:::tip 提示
|
||||
如果在 bot 入口文件内定义了 asgi server， `nb-cli` 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot 实例）
|
||||
如果在 bot 入口文件内定义了 asgi server，nb-cli 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot2 实例）
|
||||
:::
|
||||
|
||||
@ -5,7 +5,7 @@ description: 修改日志级别与输出
|
||||
|
||||
# 自定义日志
|
||||
|
||||
NoneBot 使用 [loguru](https://loguru.readthedocs.io/) 进行日志记录，并提供了一些内置的格式和过滤器等。
|
||||
NoneBot 使用 [Loguru](https://loguru.readthedocs.io/) 进行日志记录，并提供了一些内置的格式和过滤器等。
|
||||
|
||||
## 默认日志
|
||||
|
||||
@ -40,7 +40,7 @@ from nonebot.log import LoguruHandler
|
||||
|
||||
## 自定义日志记录
|
||||
|
||||
如果需要移除 NoneBot 的默认日志 handler，可以在 `nonebot.init` 之前进行如下操作:
|
||||
如果需要移除 NoneBot 的默认日志 handler，可以在 `nonebot.init` 之前进行如下操作：
|
||||
|
||||
```python
|
||||
from nonebot.log import logger, logger_id
|
||||
@ -50,7 +50,7 @@ logger.remove(logger_id)
|
||||
|
||||
如果需要添加自定义的日志 handler，可以在 `nonebot.init` 之前添加 handler，参考 [loguru 文档](https://loguru.readthedocs.io/)。
|
||||
|
||||
示例:
|
||||
示例：
|
||||
|
||||
```python
|
||||
from nonebot.log import logger, default_format
|
||||
|
||||
@ -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/) 文档。
|
||||
:::
|
||||
|
||||
## 读取配置
|
||||
|
||||
@ -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,7 +113,7 @@ matcher = on_message(
|
||||
|
||||
## 事件处理流程
|
||||
|
||||
在一个事件响应器中，事件被添加的处理依赖依次执行，直到所有处理依赖都执行完毕，或者遇到了某个处理依赖需要更多的事件来进行下一步的处理。在下一个事件到来并符合响应要求时，继续执行。更多有关 NoneBot 事件分发与处理流程的详细信息，请参考 [进阶 - 深入](../../advanced/README.md)。
|
||||
在一个事件响应器中，事件被添加的处理依赖依次执行，直到所有处理依赖都执行完毕，或者遇到了某个处理依赖需要更多的事件来进行下一步的处理。在下一个事件到来并符合响应要求时，继续执行。更多有关 NoneBot 事件分发与处理流程的详细信息，请参考[进阶 - 深入](../../advanced/README.md)。
|
||||
|
||||
## 获取上下文信息
|
||||
|
||||
|
||||
@ -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` 导入即可。
|
||||
|
||||
辅助函数有以下几种：
|
||||
|
||||
|
||||
@ -9,13 +9,13 @@ description: 插件入门
|
||||
|
||||
在编写插件之前，首先我们需要了解一下插件的概念。
|
||||
|
||||
在 NoneBot 中，插件可以是 Python 的一个模块 `module` ，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
|
||||
在 NoneBot 中，插件可以是 Python 的一个模块 `module`，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
|
||||
|
||||
下面详细介绍两种插件的结构：
|
||||
|
||||
### 模块插件（单文件形式）
|
||||
|
||||
在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../create-project.mdx) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
|
||||
在合适的路径创建一个 `.py` 文件即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
|
||||
|
||||
```tree title=Project {4}
|
||||
📦 AweSome-Bot
|
||||
@ -37,7 +37,7 @@ description: 插件入门
|
||||
|
||||
### 包插件（文件夹形式）
|
||||
|
||||
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../create-project.mdx) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
|
||||
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
|
||||
|
||||
```tree title=Project {4,5}
|
||||
📦 AweSome-Bot
|
||||
@ -64,7 +64,7 @@ description: 插件入门
|
||||
请注意，插件名称不能存在重复，即所有模块插件的文件名和所有包插件的文件夹名不能存在相同。
|
||||
:::
|
||||
|
||||
除了通过手动创建的方式以外，还可以通过 `nb-cli` 来创建插件，`nb-cli` 会为你在合适的位置创建一个模板包插件。
|
||||
除了通过手动创建的方式以外，还可以通过 nb-cli 来创建插件，nb-cli 会为你在合适的位置创建一个模板包插件。
|
||||
|
||||
```bash
|
||||
nb plugin create
|
||||
|
||||
@ -11,10 +11,10 @@ options:
|
||||
# 加载插件
|
||||
|
||||
:::danger 警告
|
||||
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot 无法将其转换为插件而损失部分功能。
|
||||
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot2 无法将其转换为插件而损失部分功能。
|
||||
:::
|
||||
|
||||
加载插件通常在机器人的入口文件进行，例如在 [创建项目](../create-project.mdx) 中创建的项目中的 `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"])
|
||||
|
||||
@ -16,7 +16,7 @@ options:
|
||||
|
||||
向用户回复一条消息。回复的方式或途径由协议适配器自行实现。
|
||||
|
||||
可以是 `str`, [`Message`](../../api/adapters/index.md#Message), [`MessageSegment`](../../api/adapters/index.md#MessageSegment) 或 [`MessageTemplate`](../../api/adapters/index.md#MessageTemplate)。
|
||||
可以是 `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`。
|
||||
|
||||
|
||||
@ -11,20 +11,20 @@ options:
|
||||
# 使用适配器
|
||||
|
||||
:::tip 提示
|
||||
如何**安装**协议适配器请参考 [安装协议适配器](../start/install-adapter.mdx)
|
||||
如何**安装**协议适配器请参考[安装协议适配器](../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
|
||||
|
||||
Reference in New Issue
Block a user