From 9b9941e6c5a3d9432c149b06c629e13490c0b629 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Sat, 25 Dec 2021 14:57:29 +0800 Subject: [PATCH] :bulb: write config docs --- nonebot/config.py | 57 +------- website/docs/guide/basic-configuration.md | 95 ------------ website/docs/guide/start/install-adapter.md | 2 +- website/docs/guide/start/install-driver.md | 2 +- website/docs/guide/start/install-plugin.md | 2 +- website/docs/guide/start/installation.md | 2 +- website/docs/guide/start/nb-cli.md | 2 +- website/docs/guide/tutorial/choose-driver.md | 11 ++ website/docs/guide/tutorial/configuration.md | 144 +++++++++++++++++++ website/docs/guide/tutorial/custom-logger.md | 0 10 files changed, 166 insertions(+), 151 deletions(-) delete mode 100644 website/docs/guide/basic-configuration.md create mode 100644 website/docs/guide/tutorial/choose-driver.md create mode 100644 website/docs/guide/tutorial/configuration.md create mode 100644 website/docs/guide/tutorial/custom-logger.md diff --git a/nonebot/config.py b/nonebot/config.py index 99507fa7..c8d2cc19 100644 --- a/nonebot/config.py +++ b/nonebot/config.py @@ -153,16 +153,18 @@ class Config(BaseConfig): """ # nonebot configs - driver: str = "nonebot.drivers.fastapi" + driver: str = "~fastapi" """ - **类型**: ``str`` - - **默认值**: ``"nonebot.drivers.fastapi"`` + - **默认值**: ``"~fastapi"`` :说明: - NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。 + NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.drivers.Driver`` 。 - 配置格式为 ``[:]``，默认类名为 ``Driver``。 + 配置格式为 ``[:][+[:]]*``。 + + ``~`` 为 ``nonebot.drivers.`` 的缩写。 """ host: IPvAnyAddress = IPv4Address("127.0.0.1") # type: ignore """ @@ -212,21 +214,6 @@ class Config(BaseConfig): """ # bot connection configs - api_root: Dict[str, str] = {} - """ - - **类型**: ``Dict[str, str]`` - - **默认值**: ``{}`` - - :说明: - - 以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。 - - :示例: - - .. code-block:: default - - API_ROOT={"123456": "http://127.0.0.1:5700"} - """ api_timeout: Optional[float] = 30.0 """ - **类型**: ``Optional[float]`` @@ -236,38 +223,6 @@ class Config(BaseConfig): API 请求超时时间，单位: 秒。 """ - access_token: Optional[str] = None - """ - - **类型**: ``Optional[str]`` - - **默认值**: ``None`` - - :说明: - - API 请求以及上报所需密钥，在请求头中携带。 - - :示例: - - .. code-block:: http - - POST /cqhttp/ HTTP/1.1 - Authorization: Bearer kSLuTF2GC2Q4q4ugm3 - """ - secret: Optional[str] = None - """ - - **类型**: ``Optional[str]`` - - **默认值**: ``None`` - - :说明: - - HTTP POST 形式上报所需签名，在请求头中携带。 - - :示例: - - .. code-block:: http - - POST /cqhttp/ HTTP/1.1 - X-Signature: sha1=f9ddd4863ace61e64f462d41ca311e3d2c1176e2 - """ # bot runtime configs superusers: Set[str] = set() diff --git a/website/docs/guide/basic-configuration.md b/website/docs/guide/basic-configuration.md deleted file mode 100644 index 9a7cc59c..00000000 --- a/website/docs/guide/basic-configuration.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_position: 5 - -options: - menu: - weight: 50 - category: guide ---- - -# 基本配置 - -到目前为止我们还在使用 NoneBot 的默认行为，在开始编写自己的插件之前，我们先尝试在配置文件上动动手脚，让 NoneBot 表现出不同的行为。 - -在上一章节中，我们创建了默认的项目结构，其中 `.env` 和 `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式。 - -:::danger 警告 -请勿将敏感信息写入配置文件并提交至开源仓库！ -::: - -## .env 文件 - -NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。 -这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。 - -`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。 - -现在，我们在 `.env` 文件中写入当前环境信息： - -```bash -# .env -ENVIRONMENT=dev -CUSTOM_CONFIG=common config # 这个配置项在任何环境中都会被加载 -``` - -如你所想，之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。 - -## .env.\* 文件 - -NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置管理，会从 `.env.{ENVIRONMENT}` 文件中获悉环境配置。 - -可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。 - -:::warning 提示 -由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如： - -```bash -list=["123456789", "987654321", 1] -test={"hello": "world"} -``` - -如果配置项值解析失败将作为字符串处理。 -::: - -示例及说明： - -```bash -HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名 -PORT=8080 # 配置 NoneBot 监听的端口 -DEBUG=true # 开启 debug 模式 **请勿在生产环境开启** -SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户 -NICKNAME=["awesome", "bot"] # 配置机器人的昵称 -COMMAND_START=["/", ""] # 配置命令起始字符 -COMMAND_SEP=["."] # 配置命令分割字符 - -# Custom Configs -CUSTOM_CONFIG1="config in env file" -CUSTOM_CONFIG2= # 留空则从系统环境变量读取，如不存在则为空字符串 -``` - -详细的配置项参考 [Config Reference](../api/config.md) 。 - -## 系统环境变量 - -如果在系统环境变量中定义了配置，则一样会被读取。 - -## bot.py 文件 - -配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。 - -示例： - -```python -# bot.py -import nonebot - -nonebot.init(custom_config3="config on init") - -config = nonebot.get_driver().config -config.custom_config3 = "changed after init" -config.custom_config4 = "new config after init" -``` - -## 优先级 - -`bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env` `.env.*` 文件 diff --git a/website/docs/guide/start/install-adapter.md b/website/docs/guide/start/install-adapter.md index 4906a0e1..1959c619 100644 --- a/website/docs/guide/start/install-adapter.md +++ b/website/docs/guide/start/install-adapter.md @@ -37,4 +37,4 @@ nb adapter install pip install ``` - + diff --git a/website/docs/guide/start/install-driver.md b/website/docs/guide/start/install-driver.md index 4707cb00..8845821f 100644 --- a/website/docs/guide/start/install-driver.md +++ b/website/docs/guide/start/install-driver.md @@ -39,4 +39,4 @@ nb driver install pip install ``` - + diff --git a/website/docs/guide/start/install-plugin.md b/website/docs/guide/start/install-plugin.md index 7d459141..a2acd1e1 100644 --- a/website/docs/guide/start/install-plugin.md +++ b/website/docs/guide/start/install-plugin.md @@ -37,4 +37,4 @@ nb plugin install pip install ``` - + diff --git a/website/docs/guide/start/installation.md b/website/docs/guide/start/installation.md index 5ff6463d..4f430cce 100644 --- a/website/docs/guide/start/installation.md +++ b/website/docs/guide/start/installation.md @@ -32,7 +32,7 @@ pip uninstall nonebot pip install nb-cli ``` - + :::important 提示 `nb-cli` 的使用方法详见 [使用脚手架](./nb-cli.md) diff --git a/website/docs/guide/start/nb-cli.md b/website/docs/guide/start/nb-cli.md index 5ff94380..6472d4e7 100644 --- a/website/docs/guide/start/nb-cli.md +++ b/website/docs/guide/start/nb-cli.md @@ -10,4 +10,4 @@ options: # 使用脚手架 - + diff --git a/website/docs/guide/tutorial/choose-driver.md b/website/docs/guide/tutorial/choose-driver.md new file mode 100644 index 00000000..1e518223 --- /dev/null +++ b/website/docs/guide/tutorial/choose-driver.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 5 +description: 各驱动器的功能与区别 + +options: + menu: + weight: 25 + category: guide +--- + +# 选择驱动器 diff --git a/website/docs/guide/tutorial/configuration.md b/website/docs/guide/tutorial/configuration.md new file mode 100644 index 00000000..653a3af7 --- /dev/null +++ b/website/docs/guide/tutorial/configuration.md @@ -0,0 +1,144 @@ +--- +sidebar_position: 1 +description: 项目配置方式与配置项 + +options: + menu: + weight: 21 + category: guide +--- + +# 配置 + +在上一章节中，我们创建了默认的项目结构，其中 `.env` 和 `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式以及配置项。 + +:::danger 警告 +请勿将敏感信息写入配置文件并提交至开源仓库！ +::: + +## 配置方式 + +### .env 文件 + +NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。 +这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。 + +`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。 + +NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置处理，并对 `pydantic` 的行为做出了更改，详见下方说明。 + +现在，我们在 `.env` 文件中写入当前环境信息： + +```bash +# .env +ENVIRONMENT=dev +CUSTOM_CONFIG=common config # 这个配置项在任何环境中都会被加载 +``` + +如你所想，之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。 + +:::important 参考文档 +`.env` 相关文件的加载使用 `dotenv` 语法，请参考 [`dotenv` 文档](https://saurabh-kumar.com/python-dotenv/) +::: + +:::warning 提示 +由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如： + +```bash +list=["123456789", "987654321", 1] +test={"hello": "world"} +``` + +如果配置项值解析失败将作为 **字符串** 处理。 + +特别的，如果配置项 **为空** ，则会从 **系统环境变量** 中获取值，如果不存在则为空字符串。 +::: + +### .env.\* 文件 + +NoneBot 默认会从 `.env.{ENVIRONMENT}` 文件加载配置，但是可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。 + +配置语法与 `.env` 文件相同。 + +示例及说明： + +```bash +HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名 +PORT=8080 # 配置 NoneBot 监听的端口 +DEBUG=true # 开启 debug 模式 **请勿在生产环境开启** +SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户 +NICKNAME=["awesome", "bot"] # 配置机器人的昵称 +COMMAND_START=["/", ""] # 配置命令起始字符 +COMMAND_SEP=["."] # 配置命令分割字符 + +# Custom Configs +CUSTOM_CONFIG1="config in env file" +CUSTOM_CONFIG2= # 留空则从系统环境变量读取，如不存在则为空字符串 +``` + +详细的配置项可以参考 [配置项](#详细配置项) 。 + +### 系统环境变量 + +如果在系统环境变量中定义了配置，则一样会被读取。 + +### bot.py 文件 + +配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。 + +示例： + +```python +# bot.py +import nonebot + +nonebot.init(custom_config3="config on init") + +config = nonebot.get_driver().config +config.custom_config3 = "changed after init" +config.custom_config4 = "new config after init" +``` + +## 配置优先级 + +`bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env`, `.env.*` 文件 + +## 读取配置项 + +配置项可以通过三种类型的对象获取：`driver`, `adapter`, `bot`。 + +```python +import nonebot +# driver +nonebot.get_driver().config.custom_config +# bot +nonebot.get_bot().config.custom_config +# adapter +nonebot.get_driver()._adapters["adapter_name"].config.custom_config +``` + +## 详细配置项 + +配置项的 API 文档可以前往 [Class Config](../../api/config.md#class-config) 查看。 + +### Driver + +- **类型**: `str` +- **默认值**: `"~fastapi"` + +NoneBot 运行所使用的驱动器。主要分为 `ForwardDriver`, `ReverseDriver` 即客户端和服务端两类。 + +配置格式采用特殊语法：`[:][+[:]]*` + +其中 `` 为驱动器模块名，可以使用 `~` 作为 `nonebot.drivers.` 的简写；`` 为驱动器类名，默认为 `Driver`；`` 为驱动器混入的类名，默认为 `Mixin`。 + +NoneBot 内置了几个常用驱动器，包括了各类常用功能，常见驱动器配置如下： + +- `~fastapi` +- `~httpx+~websockets` +- `~fastapi+~httpx+~websockets` +- `~fastapi+~aiohttp` + +各驱动器的功能与区别请参考 [选择驱动器](./choose-driver.md) 。 + + diff --git a/website/docs/guide/tutorial/custom-logger.md b/website/docs/guide/tutorial/custom-logger.md new file mode 100644 index 00000000..e69de29b