From 27b1ded9a16f780f1fc95545197ebdbcf2a67811 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Tue, 18 Jan 2022 12:31:08 +0800 Subject: [PATCH] :bulb: add config docstring --- nonebot/__init__.py | 58 +++++++++++++++++------------------ nonebot/config.py | 75 +++++++++++++++++++++++++-------------------- poetry.lock | 2 +- 3 files changed, 72 insertions(+), 63 deletions(-) diff --git a/nonebot/__init__.py b/nonebot/__init__.py index e23cd234..c0e8323b 100644 --- a/nonebot/__init__.py +++ b/nonebot/__init__.py @@ -3,30 +3,30 @@ 为方便使用，`nonebot` 模块从子模块导入了部分内容，以下内容可以直接通过 `nonebot` 模块导入: -- `on` => {ref}`nonebot.plugin.on.on` -- `on_metaevent` => {ref}`nonebot.plugin.on.on_metaevent` -- `on_message` => {ref}`nonebot.plugin.on.on_message` -- `on_notice` => {ref}`nonebot.plugin.on.on_notice` -- `on_request` => {ref}`nonebot.plugin.on.on_request` -- `on_startswith` => {ref}`nonebot.plugin.on.on_startswith` -- `on_endswith` => {ref}`nonebot.plugin.on.on_endswith` -- `on_keyword` => {ref}`nonebot.plugin.on.on_keyword` -- `on_command` => {ref}`nonebot.plugin.on.on_command` -- `on_shell_command` => {ref}`nonebot.plugin.on.on_shell_command` -- `on_regex` => {ref}`nonebot.plugin.on.on_regex` -- `CommandGroup` => {ref}`nonebot.plugin.on.CommandGroup` -- `Matchergroup` => {ref}`nonebot.plugin.on.MatcherGroup` -- `load_plugin` => {ref}`nonebot.plugin.load.load_plugin` -- `load_plugins` => {ref}`nonebot.plugin.load.load_plugins` -- `load_all_plugins` => {ref}`nonebot.plugin.load.load_all_plugins` -- `load_from_json` => {ref}`nonebot.plugin.load.load_from_json` -- `load_from_toml` => {ref}`nonebot.plugin.load.load_from_toml` -- `load_builtin_plugin` => {ref}`nonebot.plugin.load.load_builtin_plugin` -- `load_builtin_plugins` => {ref}`nonebot.plugin.load.load_builtin_plugins` -- `get_plugin` => {ref}`nonebot.plugin.plugin.get_plugin` -- `get_loaded_plugins` => {ref}`nonebot.plugin.plugin.get_loaded_plugins` -- `export` => {ref}`nonebot.plugin.export.export` -- `require` => {ref}`nonebot.plugin.load.require` +- `on` => {ref}``on` ` +- `on_metaevent` => {ref}``on_metaevent` ` +- `on_message` => {ref}``on_message` ` +- `on_notice` => {ref}``on_notice` ` +- `on_request` => {ref}``on_request` ` +- `on_startswith` => {ref}``on_startswith` ` +- `on_endswith` => {ref}``on_endswith` ` +- `on_keyword` => {ref}``on_keyword` ` +- `on_command` => {ref}``on_command` ` +- `on_shell_command` => {ref}``on_shell_command` ` +- `on_regex` => {ref}``on_regex` ` +- `CommandGroup` => {ref}``CommandGroup` ` +- `Matchergroup` => {ref}``MatcherGroup` ` +- `load_plugin` => {ref}``load_plugin` ` +- `load_plugins` => {ref}``load_plugins` ` +- `load_all_plugins` => {ref}``load_all_plugins` ` +- `load_from_json` => {ref}``load_from_json` ` +- `load_from_toml` => {ref}``load_from_toml` ` +- `load_builtin_plugin` => {ref}``load_builtin_plugin` ` +- `load_builtin_plugins` => {ref}``load_builtin_plugins` ` +- `get_plugin` => {ref}``get_plugin` ` +- `get_loaded_plugins` => {ref}``get_loaded_plugins` ` +- `export` => {ref}``export` ` +- `require` => {ref}``require` ` FrontMatter: sidebar_position: 0 @@ -64,7 +64,7 @@ def get_driver() -> Driver: 全局 {ref}`nonebot.drivers.Driver` 对象 异常: - ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用) + ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init ` 尚未调用) 用法: ```python @@ -84,7 +84,7 @@ def get_app() -> Any: 异常: AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型 - ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用) + ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init ` 尚未调用) 用法: ```python @@ -106,7 +106,7 @@ def get_asgi() -> Any: 异常: AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型 - ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用) + ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init ` 尚未调用) 用法: ```python @@ -135,7 +135,7 @@ def get_bot(self_id: Optional[str] = None) -> Bot: 异常: KeyError: 对应 self_id 的 Bot 不存在 ValueError: 没有传入 self_id 且没有 Bot 可用 - ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用) + ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init ` 尚未调用) 用法: ```python @@ -161,7 +161,7 @@ def get_bots() -> Dict[str, Bot]: 一个以 {ref}`nonebot.adapters._bot.Bot.self_id` 为键，{ref}`nonebot.adapters._bot.Bot` 对象为值的字典 异常: - ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init` 尚未调用) + ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init ` 尚未调用) 用法: ```python diff --git a/nonebot/config.py b/nonebot/config.py index f2e1d0a0..d9d61994 100644 --- a/nonebot/config.py +++ b/nonebot/config.py @@ -15,7 +15,7 @@ from datetime import timedelta from ipaddress import IPv4Address from typing import Any, Set, Dict, Tuple, Union, Mapping, Optional -from pydantic import BaseSettings, IPvAnyAddress +from pydantic import BaseSettings, IPvAnyAddress, validator from pydantic.env_settings import ( SettingsError, EnvSettingsSource, @@ -125,15 +125,15 @@ class BaseConfig(BaseSettings): class Env(BaseConfig): - """ - 运行环境配置。大小写不敏感。 + """运行环境配置。大小写不敏感。 - 将会从 `nonebot.init 参数` > `环境变量` > `.env 环境配置文件` 的优先级读取配置。 + 将会从 `环境变量` > `.env 环境配置文件` 的优先级读取环境信息。 """ environment: str = "prod" - """ - 当前环境名。 NoneBot 将从 `.env.{environment}` 文件中加载配置。 + """当前环境名。 + + NoneBot 将从 `.env.{environment}` 文件中加载配置。 """ class Config: @@ -142,36 +142,37 @@ class Env(BaseConfig): class Config(BaseConfig): - """ - NoneBot 主要配置。大小写不敏感。 + """NoneBot 主要配置。大小写不敏感。 除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。 这些配置将会在 json 反序列化后一起带入 `Config` 类中。 + + 配置方法参考: [配置](https://v2.nonebot.dev/docs/tutorial/configuration) """ - _common_config: dict _env_file: str + _common_config: Dict[str, Any] # nonebot configs driver: str = "~fastapi" - """ - NoneBot 运行所使用的 `Driver` 。继承自 `nonebot.drivers.Driver` 。 + """NoneBot 运行所使用的 `Driver` 。继承自 {ref}`nonebot.drivers.Driver` 。 配置格式为 `[:][+[:]]*`。 `~` 为 `nonebot.drivers.` 的缩写。 """ host: IPvAnyAddress = IPv4Address("127.0.0.1") # type: ignore - """ - NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。 - """ + """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的 IP/主机名。""" port: int = 8080 - """ - NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。 - """ + """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的端口。""" log_level: Union[int, str] = "INFO" - """ - 配置 NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称，参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。 + """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称 + + 参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。 + + :::tip 提示 + 日志等级名称应为大写，如 `INFO`。 + ::: 用法: ```conf @@ -182,14 +183,11 @@ class Config(BaseConfig): # bot connection configs api_timeout: Optional[float] = 30.0 - """ - API 请求超时时间，单位: 秒。 - """ + """API 请求超时时间，单位: 秒。""" # bot runtime configs superusers: Set[str] = set() - """ - 机器人超级用户。 + """机器人超级用户。 用法: ```conf @@ -197,20 +195,25 @@ class Config(BaseConfig): ``` """ nickname: Set[str] = set() - """ - 机器人昵称。 - """ + """机器人昵称。""" command_start: Set[str] = {"/"} - """ - 命令的起始标记，用于判断一条消息是不是命令。 + """命令的起始标记，用于判断一条消息是不是命令。 + + 用法: + ```conf + COMMAND_START=["/", ""] + ``` """ command_sep: Set[str] = {"."} - """ - 命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。 + """命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。 + + 用法: + ```conf + COMMAND_SEP=["."] + ``` """ session_expire_timeout: timedelta = timedelta(minutes=2) - """ - 等待用户回复的超时时间。 + """等待用户回复的超时时间。 用法: ```conf @@ -230,3 +233,9 @@ class Config(BaseConfig): class Config: extra = "allow" env_file = ".env.prod" + + +__autodoc__ = { + "CustomEnvSettings": False, + "BaseConfig": False, +} diff --git a/poetry.lock b/poetry.lock index a1dc72b6..abb00720 100644 --- a/poetry.lock +++ b/poetry.lock @@ -561,7 +561,7 @@ six = ">=1.6.1" type = "git" url = "https://github.com/nonebot/nb-autodoc.git" reference = "master" -resolved_reference = "19f4b1c3e215ca98f6d1e48ba9be7825596fec8a" +resolved_reference = "56f34218ab931dd568d7a41f2922d2657be7f638" [[package]] name = "nodeenv"