💡 add log, exception, consts docstring

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"""

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):
-    """
+    """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常"""
-    `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):
+    def __init__(self, reason: Any):
-        self.reason = reason
+        self.reason: Any = reason
 
     def __repr__(self):
         return f"<IgnoredException, reason={self.reason}>"
@@ -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 信息。
-    指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息，可在 `get_log_string` 时抛出
-    """
 
-    pass
+    可在 {ref}`nonebot.adapters._event.Event.get_log_string` 时抛出
+    """
 
 
 class ApiNotAvailable(AdapterException):
-    """
+    """在 API 连接不可用时抛出。"""
-    在 API 连接不可用时抛出。
-    """
-
-    pass
 
 
 class NetworkError(AdapterException):
-    """
+    """在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。"""
-    在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
-    """
-
-    pass
 
 
 class ActionFailed(AdapterException):
-    """
+    """API 请求成功返回数据，但 API 操作失败。"""
-    API 请求成功返回数据，但 API 操作失败。
-    """
-
-    pass
 
 
 # Driver Exceptions
 class DriverException(NoneBotException):
-    """
+    """`Driver` 抛出的异常基类"""
-    `Driver` 抛出的异常基类
-    """
 
 
 class WebSocketClosed(DriverException):
-    """
+    """WebSocket 连接已关闭"""
-    WebSocket 连接已关闭
-    """
 
     def __init__(self, code: int, reason: Optional[str] = None):
         self.code = code

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_filter: Filter = Filter()
-default_format = (
+"""默认日志等级过滤器"""
+default_format: str = (
     "<g>{time:MM-DD HH:mm:ss}</g> "
     "[<lvl>{level}</lvl>] "
     "<c><u>{name}</u></c> | "
     # "<c>{function}:{line}</c>| "
     "{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}