add log and config docs

nonebot/config.py

@@ -9,7 +9,7 @@ from ipaddress import IPv4Address
 from pydantic import BaseSettings, IPvAnyAddress
 from pydantic.env_settings import SettingsError, env_file_sentinel, read_env_file
 
-from nonebot.typing import Set, Dict, Union, Mapping, Optional
+from nonebot.typing import Any, Set, Dict, Union, Mapping, Optional
 
 
 class BaseConfig(BaseSettings):
@@ -73,9 +73,24 @@ class BaseConfig(BaseSettings):
 
         return d
 
+    def __getattr__(self, name: str) -> Any:
+        return self.__dict__.get(name)
+
 
 class Env(BaseSettings):
+    """
+    运行环境配置。大小写不敏感。
+
+    将会从 ``nonebot.init 参数`` > ``环境变量`` > ``.env 环境配置文件`` 的优先级读取配置。
+    """
+
     environment: str = "prod"
+    """
+    - 类型: ``str``
+    - 默认值: ``"prod"``
+    - 说明:
+      当前环境名。 NoneBot 将从 ``.env.{environment}`` 文件中加载配置。
+    """
 
     class Config:
         env_file = ".env"
@@ -83,23 +98,52 @@ class Env(BaseSettings):
 
 class Config(BaseConfig):
     """
-    NoneBot Config Object
+    NoneBot 主要配置。大小写不敏感。
 
-    configs:
-
-    ### `driver`
-
-    - 类型: `str`
-    - 默认值: `"nonebot.drivers.fastapi"`
-    - 说明:
-      nonebot 运行使用后端框架封装 Driver 。继承自 nonebot.driver.BaseDriver 。
+    除了 NoneBot 的配置项外，还可以自行添加配置项到 ``.env.{environment}`` 文件中。这些配置将会一起带入 ``Config`` 类中。
     """
     # nonebot configs
     driver: str = "nonebot.drivers.fastapi"
+    """
+    - 类型: ``str``
+    - 默认值: ``"nonebot.drivers.fastapi"``
+    - 说明:
+      NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。
+    """
     host: IPvAnyAddress = IPv4Address("127.0.0.1")  # type: ignore
+    """
+    - 类型: ``IPvAnyAddress``
+    - 默认值: ``127.0.0.1``
+    - 说明:
+      NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP／主机名。
+    """
     port: int = 8080
+    """
+    - 类型: ``int``
+    - 默认值: ``8080``
+    - 说明:
+      NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
+    """
     secret: Optional[str] = None
+    """
+    - 类型: ``Optional[str]``
+    - 默认值: ``None``
+    - 说明:
+      上报连接 NoneBot 所需的密钥。
+    - 示例:
+
+    .. code-block:: http
+
+        POST /cqhttp/ HTTP/1.1
+        Authorization: Bearer kSLuTF2GC2Q4q4ugm3
+    """
     debug: bool = False
+    """
+    - 类型: ``bool``
+    - 默认值: ``False``
+    - 说明:
+      是否以调试模式运行 NoneBot。
+    """
 
     # bot connection configs
     api_root: Dict[str, str] = {}

nonebot/exception.py

@@ -1,49 +1,108 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+异常
+====
+
+下列文档中的异常是所有 NoneBot 运行时可能会抛出的。
+这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。
+"""
 
 from nonebot.typing import Optional
 
 
 class IgnoredException(Exception):
     """
-    Raised by event_preprocessor indicating that
-    the bot should ignore the event
+    :说明:
+
+      指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。
+
+    :参数:
+
+      * ``reason``: 忽略事件的原因
+
     """
 
     def __init__(self, reason):
-        """
-        :param reason: reason to ignore the event
-        """
         self.reason = reason
 
+    def __repr__(self):
+        return f"<IgnoredException, reason={self.reason}>"
+
+    def __str__(self):
+        return self.__repr__()
+
 
 class PausedException(Exception):
-    """Block a message from further handling and try to receive a new message"""
+    """
+    :说明:
+
+      指示 NoneBot 结束当前 Handler 并等待下一条消息后继续下一个 Handler。
+      可用于用户输入新信息。
+
+    :用法:
+
+      可以在 Handler 中通过 Matcher.pause() 抛出。
+    """
     pass
 
 
 class RejectedException(Exception):
-    """Reject a message and return current handler back"""
+    """
+    :说明:
+
+      指示 NoneBot 结束当前 Handler 并等待下一条消息后重新运行当前 Handler。
+      可用于用户重新输入。
+
+    :用法:
+
+      可以在 Handler 中通过 Matcher.reject() 抛出。
+    """
     pass
 
 
 class FinishedException(Exception):
-    """Finish handling a message"""
+    """
+    :说明:
+
+      指示 NoneBot 结束当前 Handler 且后续 Handler 不再被运行。
+      可用于结束用户会话。
+
+    :用法:
+
+      可以在 Handler 中通过 Matcher.finish() 抛出。
+    """
     pass
 
 
 class ApiNotAvailable(Exception):
-    """Api is not available"""
+    """
+    :说明:
+
+      在 API 连接不可用时抛出。
+    """
     pass
 
 
 class NetworkError(Exception):
-    """There is something error with the network"""
+    """
+    :说明:
+
+      在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
+    """
     pass
 
 
 class ActionFailed(Exception):
-    """The action call returned a failed response"""
+    """
+    :说明:
+
+      API 请求成功返回数据，但 API 操作失败。
+
+    :参数:
+
+      * ``retcode``: 错误代码
+    """
 
     def __init__(self, retcode: Optional[int]):
         self.retcode = retcode

nonebot/log.py

@@ -1,11 +1,42 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+日志
+====
+
+NoneBot 使用标准库 `logging`_ 来记录日志信息。
+
+自定义 logger 请参考 `logging`_ 文档。
+
+.. _logging:
+    https://docs.python.org/3/library/logging.html
+"""
 
 import sys
 import logging
 
 logger = logging.getLogger("nonebot")
-"""nonebot logger"""
+"""
+:说明:
+
+  NoneBot 日志记录器对象。
+
+:默认信息:
+
+  * 格式: ``[%(asctime)s %(name)s] %(levelname)s: %(message)s``
+  * 等级: ``DEBUG`` / ``INFO`` ，根据 config 配置改变
+  * 输出: 输出至 stdout
+
+:用法:
+
+.. code-block:: python
+
+    from nonebot.log import logger
+
+    # 也可以这样
+    import logging
+    logger = logging.getLogger("nonebot")
+"""
 
 default_handler = logging.StreamHandler(sys.stdout)
 default_handler.setFormatter(