From 608cf859c837c5ba455729ee11845f03127c5f42 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Tue, 18 Jan 2022 16:12:12 +0800 Subject: [PATCH] :bulb: add log, exception, consts docstring --- nonebot/consts.py | 14 ++++ nonebot/exception.py | 154 ++++++++++++++++++++++++------------------- nonebot/log.py | 14 ++-- 3 files changed, 110 insertions(+), 72 deletions(-) diff --git a/nonebot/consts.py b/nonebot/consts.py index 0d332e6d..c455f416 100644 --- a/nonebot/consts.py +++ b/nonebot/consts.py @@ -7,21 +7,35 @@ from typing_extensions import Literal # used by Matcher RECEIVE_KEY: Literal["_receive_{id}"] = "_receive_{id}" +"""`receive` 存储 key""" LAST_RECEIVE_KEY: Literal["_last_receive"] = "_last_receive" +"""`last_receive` 存储 key""" ARG_KEY: Literal["{key}"] = "{key}" +"""`arg` 存储 key""" REJECT_TARGET: Literal["_current_target"] = "_current_target" +"""当前 `reject` 目标存储 key""" REJECT_CACHE_TARGET: Literal["_next_target"] = "_next_target" +"""下一个 `reject` 目标存储 key""" # used by Rule PREFIX_KEY: Literal["_prefix"] = "_prefix" +"""命令前缀存储 key""" CMD_KEY: Literal["command"] = "command" +"""命令元组存储 key""" RAW_CMD_KEY: Literal["raw_command"] = "raw_command" +"""命令文本存储 key""" CMD_ARG_KEY: Literal["command_arg"] = "command_arg" +"""命令参数存储 key""" SHELL_ARGS: Literal["_args"] = "_args" +"""shell 命令 parse 后参数字典存储 key""" SHELL_ARGV: Literal["_argv"] = "_argv" +"""shell 命令原始参数列表存储 key""" REGEX_MATCHED: Literal["_matched"] = "_matched" +"""正则匹配结果存储 key""" REGEX_GROUP: Literal["_matched_groups"] = "_matched_groups" +"""正则匹配 group 元组存储 key""" REGEX_DICT: Literal["_matched_dict"] = "_matched_dict" +"""正则匹配 group 字典存储 key""" diff --git a/nonebot/exception.py b/nonebot/exception.py index 79b9d5b2..24aadb0c 100644 --- a/nonebot/exception.py +++ b/nonebot/exception.py @@ -4,6 +4,28 @@ 下列文档中的异常是所有 NoneBot 运行时可能会抛出的。 这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。 +```bash +NoneBotException +├── ParserExit +├── ProcessException +| ├── IgnoredException +| ├── MockApiException +| └── StopPropagation +├── MatcherException +| ├── SkippedException +| | └── TypeMisMatch +| ├── PausedException +| ├── RejectedException +| └── FinishedException +├── AdapterException +| ├── NoLogException +| ├── ApiNotAvailable +| ├── NetworkError +| └── ActionFailed +└── DriverException + └── WebSocketClosed +``` + FrontMatter: sidebar_position: 10 description: nonebot.exception 模块 @@ -15,16 +37,12 @@ from pydantic.fields import ModelField class NoneBotException(Exception): - """ - 所有 NoneBot 发生的异常基类。 - """ + """所有 NoneBot 发生的异常基类。""" # Rule Exception class ParserExit(NoneBotException): - """ - `shell command` 处理消息失败时返回的异常 - """ + """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常""" def __init__(self, status: int = 0, message: Optional[str] = None): self.status = status @@ -39,21 +57,18 @@ class ParserExit(NoneBotException): # Processor Exception class ProcessException(NoneBotException): - """ - 事件处理过程中发生的异常基类。 - """ + """事件处理过程中发生的异常基类。""" class IgnoredException(ProcessException): - """ - 指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。 + """指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。 参数: reason: 忽略事件的原因 """ - def __init__(self, reason): - self.reason = reason + def __init__(self, reason: Any): + self.reason: Any = reason def __repr__(self): return f"" @@ -63,8 +78,7 @@ class IgnoredException(ProcessException): class MockApiException(ProcessException): - """ - 指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。可由 api hook 抛出。 + """指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。可由 api hook 抛出。 参数: result: 返回的内容 @@ -81,34 +95,46 @@ class MockApiException(ProcessException): class StopPropagation(ProcessException): - """ - 指示 NoneBot 终止事件向下层传播。 + """指示 NoneBot 终止事件向下层传播。 + + 在 {ref}`nonebot.matcher.Matcher.block` 为 `True` + 或使用 {ref}`nonebot.matcher.Matcher.stop_propagation` 方法时抛出。 用法: - 在 `Matcher.block == True` 时抛出。 + ```python + matcher = on_notice(block=True) + # 或者 + @matcher.handle() + async def handler(matcher: Matcher): + matcher.stop_propagation() + ``` """ # Matcher Exceptions class MatcherException(NoneBotException): - """ - 所有 Matcher 发生的异常基类。 - """ + """所有 Matcher 发生的异常基类。""" class SkippedException(MatcherException): - """ - 指示 NoneBot 立即结束当前 `Handler` 的处理，继续处理下一个 `Handler`。 + """指示 NoneBot 立即结束当前 `Handler` 的处理，继续处理下一个 `Handler`。 + + 可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.skip` 抛出。 用法: - 可以在 `Handler` 中通过 `Matcher.skip()` 抛出。 + ```python + def always_skip(): + Matcher.skip() + + @matcher.handle() + async def handler(dependency = Depends(always_skip)): + ... + ``` """ class TypeMisMatch(SkippedException): - """ - 当前 `Handler` 的参数类型不匹配。 - """ + """当前 `Handler` 的参数类型不匹配。""" def __init__(self, param: ModelField, value: Any): self.param: ModelField = param @@ -122,91 +148,85 @@ class TypeMisMatch(SkippedException): class PausedException(MatcherException): - """ - 指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。 - 可用于用户输入新信息。 + """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。可用于用户输入新信息。 + + 可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.pause` 抛出。 用法: - 可以在 `Handler` 中通过 `Matcher.pause()` 抛出。 + ```python + @matcher.handle() + async def handler(): + await matcher.pause("some message") + ``` """ class RejectedException(MatcherException): - """ - 指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。 - 可用于用户重新输入。 + """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。可用于用户重新输入。 + + 可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.reject` 抛出。 用法: - 可以在 `Handler` 中通过 `Matcher.reject()` 抛出。 + ```python + @matcher.handle() + async def handler(): + await matcher.reject("some message") + ``` """ class FinishedException(MatcherException): - """ - 指示 NoneBot 结束当前 `Handler` 且后续 `Handler` 不再被运行。 - 可用于结束用户会话。 + """指示 NoneBot 结束当前 `Handler` 且后续 `Handler` 不再被运行。可用于结束用户会话。 + + 可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.finish` 抛出。 用法: - 可以在 `Handler` 中通过 `Matcher.finish()` 抛出。 + ```python + @matcher.handle() + async def handler(): + await matcher.finish("some message") + ``` """ # Adapter Exceptions class AdapterException(NoneBotException): - """ - 代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception` + """代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception` 参数: adapter_name: 标识 adapter """ def __init__(self, adapter_name: str) -> None: - self.adapter_name = adapter_name + self.adapter_name: str = adapter_name class NoLogException(AdapterException): - """ - 指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息，可在 `get_log_string` 时抛出 - """ + """指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息。 - pass + 可在 {ref}`nonebot.adapters._event.Event.get_log_string` 时抛出 + """ class ApiNotAvailable(AdapterException): - """ - 在 API 连接不可用时抛出。 - """ - - pass + """在 API 连接不可用时抛出。""" class NetworkError(AdapterException): - """ - 在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。 - """ - - pass + """在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。""" class ActionFailed(AdapterException): - """ - API 请求成功返回数据，但 API 操作失败。 - """ - - pass + """API 请求成功返回数据，但 API 操作失败。""" # Driver Exceptions class DriverException(NoneBotException): - """ - `Driver` 抛出的异常基类 - """ + """`Driver` 抛出的异常基类""" class WebSocketClosed(DriverException): - """ - WebSocket 连接已关闭 - """ + """WebSocket 连接已关闭""" def __init__(self, code: int, reason: Optional[str] = None): self.code = code diff --git a/nonebot/log.py b/nonebot/log.py index 959f05f7..b98c516b 100644 --- a/nonebot/log.py +++ b/nonebot/log.py @@ -3,7 +3,8 @@ NoneBot 使用 [`loguru`][loguru] 来记录日志信息。 -自定义 logger 请参考 [`loguru`][loguru] 文档。 +自定义 logger 请参考 [自定义日志](https://v2.nonebot.dev/docs/tutorial/custom-logger) +以及 [`loguru`][loguru] 文档。 [loguru]: https://github.com/Delgan/loguru @@ -27,8 +28,7 @@ if TYPE_CHECKING: # logger = logging.getLogger("nonebot") logger: "Logger" = loguru.logger -""" -NoneBot 日志记录器对象。 +"""NoneBot 日志记录器对象。 默认信息: @@ -84,14 +84,16 @@ class LoguruHandler(logging.Handler): # pragma: no cover logger.remove() -default_filter = Filter() -default_format = ( +default_filter: Filter = Filter() +"""默认日志等级过滤器""" +default_format: str = ( "{time:MM-DD HH:mm:ss} " "[{level}] " "{name} | " # "{function}:{line}| " "{message}" ) +"""默认日志格式""" logger_id = logger.add( sys.stdout, level=0, @@ -100,3 +102,5 @@ logger_id = logger.add( filter=default_filter, format=default_format, ) + +__autodoc__ = {"Filter": False, "LoguruHandler": False}