🎨 format docstring

nonebot/adapters/__init__.py

@@ -29,6 +29,7 @@ class BaseBot(abc.ABC):
                  websocket: Optional[WebSocket] = None):
         """
         :参数:
+
           * ``driver: Driver``: Driver 对象
           * ``connection_type: str``: http 或者 websocket
           * ``config: Config``: Config 对象
@@ -62,15 +63,22 @@ class BaseBot(abc.ABC):
                                body: Optional[dict]) -> Union[str, NoReturn]:
         """
         :说明:
+
           检查连接请求是否合法的函数，如果合法则返回当前连接 ``唯一标识符``，通常为机器人 ID；如果不合法则抛出 ``RequestDenied`` 异常。
+
         :参数:
+
           * ``driver: Driver``: Driver 对象
           * ``connection_type: str``: 连接类型
           * ``headers: dict``: 请求头
           * ``body: Optional[dict]``: 请求数据，WebSocket 连接该部分为空
+
         :返回:
+
           - ``str``: 连接唯一标识符
+
         :异常:
+
           - ``RequestDenied``: 请求非法
         """
         raise NotImplementedError
@@ -79,8 +87,11 @@ class BaseBot(abc.ABC):
     async def handle_message(self, message: dict):
         """
         :说明:
+
           处理上报消息的函数，转换为 ``Event`` 事件后调用 ``nonebot.message.handle_event`` 进一步处理事件。
+
         :参数:
+
           * ``message: dict``: 收到的上报消息
         """
         raise NotImplementedError
@@ -89,10 +100,14 @@ class BaseBot(abc.ABC):
     async def call_api(self, api: str, **data):
         """
         :说明:
+
           调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用
+
         :参数:
+
           * ``api: str``: API 名称
           * ``**data``: API 数据
+
         :示例:
 
         .. code-block:: python
@@ -108,8 +123,11 @@ class BaseBot(abc.ABC):
                                   "BaseMessageSegment"], **kwargs):
         """
         :说明:
+
           调用机器人基础发送消息接口
+
         :参数:
+
           * ``event: Event``: 上报事件
           * ``message: Union[str, Message, MessageSegment]``: 要发送的消息
           * ``**kwargs``
@@ -125,6 +143,7 @@ class BaseEvent(abc.ABC):
     def __init__(self, raw_event: dict):
         """
         :参数:
+
           * ``raw_event: dict``: 原始上报消息
         """
         self._raw_event = raw_event
@@ -325,6 +344,7 @@ class BaseMessage(list, abc.ABC):
                  **kwargs):
         """
         :参数:
+
           * ``message: Union[str, dict, list, MessageSegment, Message]``: 消息内容
         """
         super().__init__(*args, **kwargs)
@@ -362,8 +382,11 @@ class BaseMessage(list, abc.ABC):
     def append(self, obj: Union[str, BaseMessageSegment]) -> "BaseMessage":
         """
         :说明:
+
           添加一个消息段到消息数组末尾
+
         :参数:
+
           * ``obj: Union[str, MessageSegment]``: 要添加的消息段
         """
         if isinstance(obj, BaseMessageSegment):
@@ -382,8 +405,11 @@ class BaseMessage(list, abc.ABC):
                          Iterable[BaseMessageSegment]]) -> "BaseMessage":
         """
         :说明:
+
           拼接一个消息数组或多个消息段到消息数组末尾
+
         :参数:
+
           * ``obj: Union[Message, Iterable[MessageSegment]]``: 要添加的消息数组
         """
         for segment in obj:
@@ -393,6 +419,7 @@ class BaseMessage(list, abc.ABC):
     def reduce(self) -> None:
         """
         :说明:
+
           缩减消息数组，即拼接相邻纯文本消息段
         """
         index = 0
@@ -407,6 +434,7 @@ class BaseMessage(list, abc.ABC):
     def extract_plain_text(self) -> str:
         """
         :说明:
+
           提取消息内纯文本消息
         """
 

nonebot/adapters/cqhttp/__init__.py

@@ -303,6 +303,7 @@ class Bot(BaseBot):
                                body: Optional[dict]) -> Union[str, NoReturn]:
         """
         :说明:
+
           CQHTTP (OneBot) 协议鉴权。参考 `鉴权 <https://github.com/howmanybots/onebot/blob/master/v11/specs/communication/authorization.md>`_
         """
         x_self_id = headers.get("x-self-id")

nonebot/config.py

@@ -125,6 +125,7 @@ class Config(BaseConfig):
     - 类型: ``str``
     - 默认值: ``"nonebot.drivers.fastapi"``
     - 说明:
+
       NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。
     """
     host: IPvAnyAddress = IPv4Address("127.0.0.1")  # type: ignore
@@ -132,6 +133,7 @@ class Config(BaseConfig):
     - 类型: ``IPvAnyAddress``
     - 默认值: ``127.0.0.1``
     - 说明:
+
       NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。
     """
     port: int = 8080
@@ -139,6 +141,7 @@ class Config(BaseConfig):
     - 类型: ``int``
     - 默认值: ``8080``
     - 说明:
+
       NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
     """
     debug: bool = False
@@ -146,6 +149,7 @@ class Config(BaseConfig):
     - 类型: ``bool``
     - 默认值: ``False``
     - 说明:
+
       是否以调试模式运行 NoneBot。
     """
 
@@ -155,7 +159,9 @@ class Config(BaseConfig):
     - 类型: ``Dict[str, str]``
     - 默认值: ``{}``
     - 说明:
+
       以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。
+
     - 示例:
 
     .. code-block:: default
@@ -167,6 +173,7 @@ class Config(BaseConfig):
     - 类型: ``Optional[float]``
     - 默认值: ``30.``
     - 说明:
+
       API 请求超时时间，单位: 秒。
     """
     access_token: Optional[str] = None
@@ -174,7 +181,9 @@ class Config(BaseConfig):
     - 类型: ``Optional[str]``
     - 默认值: ``None``
     - 说明:
+
       API 请求以及上报所需密钥，在请求头中携带。
+
     - 示例:
 
     .. code-block:: http
@@ -187,7 +196,9 @@ class Config(BaseConfig):
     - 类型: ``Optional[str]``
     - 默认值: ``None``
     - 说明:
+
       HTTP POST 形式上报所需签名，在请求头中携带。
+
     - 示例:
 
     .. code-block:: http
@@ -202,7 +213,9 @@ class Config(BaseConfig):
     - 类型: ``Set[int]``
     - 默认值: ``set()``
     - 说明:
+
       机器人超级用户。
+
     - 示例:
 
     .. code-block:: default
@@ -214,6 +227,7 @@ class Config(BaseConfig):
     - 类型: ``Set[str]``
     - 默认值: ``set()``
     - 说明:
+
       机器人昵称。
     """
     command_start: Set[str] = {"/"}
@@ -221,6 +235,7 @@ class Config(BaseConfig):
     - 类型: ``Set[str]``
     - 默认值: ``{"/"}``
     - 说明:
+
       命令的起始标记，用于判断一条消息是不是命令。
     """
     command_sep: Set[str] = {"."}
@@ -228,6 +243,7 @@ class Config(BaseConfig):
     - 类型: ``Set[str]``
     - 默认值: ``{"."}``
     - 说明:
+
       命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
     """
     session_expire_timeout: timedelta = timedelta(minutes=2)
@@ -235,7 +251,9 @@ class Config(BaseConfig):
     - 类型: ``timedelta``
     - 默认值: ``timedelta(minutes=2)``
     - 说明:
+
       等待用户回复的超时时间。
+
     - 示例:
 
     .. code-block:: default
@@ -249,6 +267,7 @@ class Config(BaseConfig):
     - 类型: ``dict``
     - 默认值: ``{"apscheduler.timezone": "Asia/Shanghai"}``
     - 说明:
+
       APScheduler 的配置对象，见 `Configuring the Scheduler`_
 
     .. _Configuring the Scheduler:

nonebot/drivers/__init__.py

@@ -51,8 +51,11 @@ class BaseDriver(abc.ABC):
     def register_adapter(cls, name: str, adapter: Type[Bot]):
         """
         :说明:
+
           注册一个协议适配器
+
         :参数:
+
           * ``name: str``: 适配器名称，用于在连接时进行识别
           * ``adapter: Type[Bot]``: 适配器 Class
         """
@@ -110,8 +113,11 @@ class BaseDriver(abc.ABC):
             **kwargs):
         """
         :说明:
+
           启动驱动框架
+
         :参数:
+
           * ``host: Optional[str]``: 驱动绑定 IP
           * ``post: Optional[int]``: 驱动绑定端口
           * ``*args``

nonebot/exception.py

@@ -18,7 +18,6 @@ class IgnoredException(Exception):
     :参数:
 
       * ``reason``: 忽略事件的原因
-
     """
 
     def __init__(self, reason):

nonebot/matcher.py

@@ -101,8 +101,7 @@ class Matcher(metaclass=MatcherMeta):
     """
 
     def __init__(self):
-        """实例化 Matcher 以便运行
+        """实例化 Matcher 以便运行"""
-        """
         self.handlers = self.handlers.copy()
         self.state = self._default_state.copy()
 
@@ -128,8 +127,11 @@ class Matcher(metaclass=MatcherMeta):
             expire_time: Optional[datetime] = None) -> Type["Matcher"]:
         """
         :说明:
+
           创建一个新的事件响应器，并存储至 `matchers <#matchers>`_
+
         :参数:
+
           * ``type_: str``: 事件响应器类型，与 ``event.type`` 一致时触发，空字符串表示任意
           * ``rule: Optional[Rule]``: 匹配规则
           * ``permission: Optional[Permission]``: 权限
@@ -140,7 +142,9 @@ class Matcher(metaclass=MatcherMeta):
           * ``module: Optional[str]``: 事件响应器所在模块名称
           * ``default_state: Optional[dict]``: 默认状态 ``state``
           * ``expire_time: Optional[datetime]``: 事件响应器最终有效时间点，过时即被删除
+
         :返回:
+
           - ``Type[Matcher]``: 新的事件响应器类
         """
 
@@ -166,11 +170,16 @@ class Matcher(metaclass=MatcherMeta):
     async def check_perm(cls, bot: Bot, event: Event) -> bool:
         """
         :说明:
+
           检查是否满足触发权限
+
         :参数:
+
           * ``bot: Bot``: Bot 对象
           * ``event: Event``: 上报事件
+
         :返回:
+
           - ``bool``: 是否满足权限
         """
         return await cls.permission(bot, event)
@@ -179,12 +188,17 @@ class Matcher(metaclass=MatcherMeta):
     async def check_rule(cls, bot: Bot, event: Event, state: dict) -> bool:
         """
         :说明:
+
           检查是否满足匹配规则
+
         :参数:
+
           * ``bot: Bot``: Bot 对象
           * ``event: Event``: 上报事件
           * ``state: dict``: 当前状态
+
         :返回:
+
           - ``bool``: 是否满足匹配规则
         """
         return (event.type == (cls.type or event.type) and
@@ -194,8 +208,11 @@ class Matcher(metaclass=MatcherMeta):
     def args_parser(cls, func: ArgsParser) -> ArgsParser:
         """
         :说明:
+
           装饰一个函数来更改当前事件响应器的默认参数解析函数
+
         :参数:
+
           * ``func: ArgsParser``: 参数解析函数
         """
         cls._default_parser = func
@@ -205,8 +222,11 @@ class Matcher(metaclass=MatcherMeta):
     def handle(cls) -> Callable[[Handler], Handler]:
         """
         :说明:
+
           装饰一个函数来向事件响应器直接添加一个处理函数
+
         :参数:
+
           * 无
         """
 
@@ -220,8 +240,11 @@ class Matcher(metaclass=MatcherMeta):
     def receive(cls) -> Callable[[Handler], Handler]:
         """
         :说明:
+
           装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
+
         :参数:
+
           * 无
         """
 
@@ -249,8 +272,11 @@ class Matcher(metaclass=MatcherMeta):
     ) -> Callable[[Handler], Handler]:
         """
         :说明:
+
           装饰一个函数来指示 NoneBot 当要获取的 ``key`` 不存在时接收用户新的一条消息并经过 ``ArgsParser`` 处理后再运行该函数，如果 ``key`` 已存在则直接继续运行
+
         :参数:
+
           * ``key: str``: 参数名
           * ``prompt: Optional[Union[str, Message, MessageSegment]]``: 在参数不存在时向用户发送的消息
           * ``args_parser: Optional[ArgsParser]``: 可选参数解析函数，空则使用默认解析函数
@@ -300,8 +326,11 @@ class Matcher(metaclass=MatcherMeta):
     async def send(cls, message: Union[str, Message, MessageSegment], **kwargs):
         """
         :说明:
+
           发送一条消息给当前交互用户
+
         :参数:
+
           * ``message: Union[str, Message, MessageSegment]``: 消息内容
           * ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
         """
@@ -316,8 +345,11 @@ class Matcher(metaclass=MatcherMeta):
                      **kwargs) -> NoReturn:
         """
         :说明:
+
           发送一条消息给当前交互用户并结束当前事件响应器
+
         :参数:
+
           * ``message: Union[str, Message, MessageSegment]``: 消息内容
           * ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
         """
@@ -334,8 +366,11 @@ class Matcher(metaclass=MatcherMeta):
                     **kwargs) -> NoReturn:
         """
         :说明:
+
           发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
+
         :参数:
+
           * ``prompt: Union[str, Message, MessageSegment]``: 消息内容
           * ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
         """
@@ -352,8 +387,11 @@ class Matcher(metaclass=MatcherMeta):
                      **kwargs) -> NoReturn:
         """
         :说明:
+
           发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后重新运行当前处理函数
+
         :参数:
+
           * ``prompt: Union[str, Message, MessageSegment]``: 消息内容
           * ``**kwargs``: 其他传递给 ``bot.send`` 的参数，请参考对应 adapter 的 bot 对象 api
         """
@@ -430,6 +468,7 @@ class MatcherGroup:
                  expire_time: Optional[datetime] = None):
         """
         :说明:
+
           创建一个事件响应器组合，参数为默认值，与 ``Matcher.new`` 一致
         """
         self.matchers: List[Type[Matcher]] = []
@@ -474,6 +513,7 @@ class MatcherGroup:
             expire_time: Optional[datetime] = None) -> Type[Matcher]:
         """
         :说明:
+
           在组中创建一个新的事件响应器，参数留空则使用组合默认值
 
         \:\:\:danger 警告

nonebot/message.py

@@ -25,8 +25,11 @@ _run_postprocessors: Set[RunPostProcessor] = set()
 def event_preprocessor(func: EventPreProcessor) -> EventPreProcessor:
     """
     :说明:
+
       事件预处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。
+
     :参数:
+
       事件预处理函数接收三个参数。
 
       * ``bot: Bot``: Bot 对象
@@ -40,8 +43,11 @@ def event_preprocessor(func: EventPreProcessor) -> EventPreProcessor:
 def event_postprocessor(func: EventPostProcessor) -> EventPostProcessor:
     """
     :说明:
+
       事件后处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。
+
     :参数:
+
       事件后处理函数接收三个参数。
 
       * ``bot: Bot``: Bot 对象
@@ -55,8 +61,11 @@ def event_postprocessor(func: EventPostProcessor) -> EventPostProcessor:
 def run_preprocessor(func: RunPreProcessor) -> RunPreProcessor:
     """
     :说明:
+
       运行预处理。装饰一个函数，使它在每次事件响应器运行前执行。
+
     :参数:
+
       运行预处理函数接收四个参数。
 
       * ``matcher: Matcher``: 当前要运行的事件响应器
@@ -71,8 +80,11 @@ def run_preprocessor(func: RunPreProcessor) -> RunPreProcessor:
 def run_postprocessor(func: RunPostProcessor) -> RunPostProcessor:
     """
     :说明:
+
       运行后处理。装饰一个函数，使它在每次事件响应器运行后执行。
+
     :参数:
+
       运行后处理函数接收五个参数。
 
       * ``matcher: Matcher``: 运行完毕的事件响应器
@@ -176,10 +188,14 @@ async def _run_matcher(Matcher: Type[Matcher], bot: Bot, event: Event,
 async def handle_event(bot: Bot, event: Event):
     """
     :说明:
+
        处理一个事件。调用该函数以实现分发事件。
+
     :参数:
+
       * ``bot: Bot``: Bot 对象
       * ``event: Event``: Event 对象
+
     :示例:
 
     .. code-block:: python

nonebot/permission.py

@@ -22,24 +22,33 @@ class Permission:
                                            Awaitable[bool]]) -> None:
         """
         :参数:
+
           * ``*checkers: Callable[[Bot, Event], Awaitable[bool]]``: **异步** PermissionChecker
         """
         self.checkers = set(checkers)
         """
         :说明:
+
           存储 ``PermissionChecker``
+
         :类型:
+
           * ``Set[Callable[[Bot, Event], Awaitable[bool]]]``
         """
 
     async def __call__(self, bot: Bot, event: Event) -> bool:
         """
         :说明:
+
           检查是否满足某个权限
+
         :参数:
+
           * ``bot: Bot``: Bot 对象
           * ``event: Event``: Event 对象
+
         :返回:
+
           - ``bool``
         """
         if not self.checkers:
@@ -103,8 +112,11 @@ METAEVENT = Permission(_metaevent)
 def USER(*user: int, perm: Permission = Permission()):
     """
     :说明:
+
       在白名单内且满足 perm
+
     :参数:
+
       * ``*user: int``: 白名单
       * ``perm: Permission``: 需要同时满足的权限
     """

nonebot/plugin.py

@@ -33,7 +33,9 @@ _export: ContextVar["Export"] = ContextVar("_export")
 class Export(dict):
     """
     :说明:
+
       插件导出内容以使得其他插件可以获得。
+
     :示例:
 
     .. code-block:: python
@@ -107,8 +109,11 @@ def on(type: str = "",
        state: Optional[dict] = None) -> Type[Matcher]:
     """
     :说明:
+
       注册一个基础事件响应器，可自定义类型。
+
     :参数:
+
       * ``type: str``: 事件响应器类型
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``permission: Optional[Permission]``: 事件响应权限
@@ -117,7 +122,9 @@ def on(type: str = "",
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     matcher = Matcher.new(type,
@@ -141,15 +148,20 @@ def on_metaevent(rule: Optional[Union[Rule, RuleChecker]] = None,
                  state: Optional[dict] = None) -> Type[Matcher]:
     """
     :说明:
+
       注册一个元事件响应器。
+
     :参数:
+
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``handlers: Optional[List[Handler]]``: 事件处理函数列表
       * ``temp: bool``: 是否为临时事件响应器（仅执行一次）
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     matcher = Matcher.new("meta_event",
@@ -174,8 +186,11 @@ def on_message(rule: Optional[Union[Rule, RuleChecker]] = None,
                state: Optional[dict] = None) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器。
+
     :参数:
+
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``permission: Optional[Permission]``: 事件响应权限
       * ``handlers: Optional[List[Handler]]``: 事件处理函数列表
@@ -183,7 +198,9 @@ def on_message(rule: Optional[Union[Rule, RuleChecker]] = None,
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     matcher = Matcher.new("message",
@@ -207,15 +224,20 @@ def on_notice(rule: Optional[Union[Rule, RuleChecker]] = None,
               state: Optional[dict] = None) -> Type[Matcher]:
     """
     :说明:
+
       注册一个通知事件响应器。
+
     :参数:
+
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``handlers: Optional[List[Handler]]``: 事件处理函数列表
       * ``temp: bool``: 是否为临时事件响应器（仅执行一次）
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     matcher = Matcher.new("notice",
@@ -239,15 +261,20 @@ def on_request(rule: Optional[Union[Rule, RuleChecker]] = None,
                state: Optional[dict] = None) -> Type[Matcher]:
     """
     :说明:
+
       注册一个请求事件响应器。
+
     :参数:
+
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``handlers: Optional[List[Handler]]``: 事件处理函数列表
       * ``temp: bool``: 是否为临时事件响应器（仅执行一次）
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     matcher = Matcher.new("request",
@@ -267,8 +294,11 @@ def on_startswith(msg: str,
                   **kwargs) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器，并且当消息的**文本部分**以指定内容开头时响应。
+
     :参数:
+
       * ``msg: str``: 指定消息开头内容
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``permission: Optional[Permission]``: 事件响应权限
@@ -277,7 +307,9 @@ def on_startswith(msg: str,
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     return on_message(startswith(msg) & rule, **kwargs)
@@ -288,8 +320,11 @@ def on_endswith(msg: str,
                 **kwargs) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器，并且当消息的**文本部分**以指定内容结尾时响应。
+
     :参数:
+
       * ``msg: str``: 指定消息结尾内容
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``permission: Optional[Permission]``: 事件响应权限
@@ -298,7 +333,9 @@ def on_endswith(msg: str,
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     return on_message(endswith(msg) & rule, **kwargs)
@@ -309,8 +346,11 @@ def on_keyword(keywords: Set[str],
                **kwargs) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。
+
     :参数:
+
       * ``keywords: Set[str]``: 关键词列表
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``permission: Optional[Permission]``: 事件响应权限
@@ -319,7 +359,9 @@ def on_keyword(keywords: Set[str],
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     return on_message(keyword(*keywords) & rule, **kwargs)
@@ -331,10 +373,13 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
                **kwargs) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器，并且当消息以指定命令开头时响应。
 
       命令匹配规则参考: `命令形式匹配 <rule.html#command-command>`_
+
     :参数:
+
       * ``cmd: Union[str, Tuple[str, ...]]``: 指定命令内容
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
       * ``aliases: Optional[Set[Union[str, Tuple[str, ...]]]]``: 命令别名
@@ -344,7 +389,9 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
 
@@ -366,10 +413,13 @@ def on_regex(pattern: str,
              **kwargs) -> Type[Matcher]:
     """
     :说明:
+
       注册一个消息事件响应器，并且当消息匹配正则表达式时响应。
 
       命令匹配规则参考: `正则匹配 <rule.html#regex-regex-flags-0>`_
+
     :参数:
+
       * ``pattern: str``: 正则表达式
       * ``flags: Union[int, re.RegexFlag]``: 正则匹配标志
       * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则
@@ -379,7 +429,9 @@ def on_regex(pattern: str,
       * ``priority: int``: 事件响应器优先级
       * ``block: bool``: 是否阻止事件向更低优先级传递
       * ``state: Optional[dict]``: 默认的 state
+
     :返回:
+
       - ``Type[Matcher]``
     """
     return on_message(regex(pattern, flags) & rule, **kwargs)
@@ -391,6 +443,7 @@ class CommandGroup:
     def __init__(self, cmd: Union[str, Tuple[str, ...]], **kwargs):
         """
         :参数:
+
           * ``cmd: Union[str, Tuple[str, ...]]``: 命令前缀
           * ``**kwargs``: 其他传递给 ``on_command`` 的参数默认值，参考 `on_command <#on-command-cmd-rule-none-aliases-none-kwargs>`_
         """
@@ -411,11 +464,16 @@ class CommandGroup:
                 **kwargs) -> Type[Matcher]:
         """
         :说明:
+
           注册一个新的命令。
+
         :参数:
+
           * ``cmd: Union[str, Tuple[str, ...]]``: 命令前缀
           * ``**kwargs``: 其他传递给 ``on_command`` 的参数，将会覆盖命令组默认值
+
         :返回:
+
           - ``Type[Matcher]``
         """
         sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
@@ -429,10 +487,15 @@ class CommandGroup:
 def load_plugin(module_path: str) -> Optional[Plugin]:
     """
     :说明:
+
       使用 ``importlib`` 加载单个插件，可以是本地插件或是通过 ``pip`` 安装的插件。
+
     :参数:
+
       * ``module_path: str``: 插件名称 ``path.to.your.plugin``
+
     :返回:
+
       - ``Optional[Plugin]``
     """
 
@@ -469,10 +532,15 @@ def load_plugin(module_path: str) -> Optional[Plugin]:
 def load_plugins(*plugin_dir: str) -> Set[Plugin]:
     """
     :说明:
+
       导入目录下多个插件，以 ``_`` 开头的插件不会被导入！
+
     :参数:
+
       - ``*plugin_dir: str``: 插件路径
+
     :返回:
+
       - ``Set[Plugin]``
     """
 
@@ -517,8 +585,11 @@ def load_plugins(*plugin_dir: str) -> Set[Plugin]:
 def load_builtin_plugins() -> Optional[Plugin]:
     """
     :说明:
+
       导入 NoneBot 内置插件
+
     :返回:
+
       - ``Plugin``
     """
     return load_plugin("nonebot.plugins.base")
@@ -527,10 +598,15 @@ def load_builtin_plugins() -> Optional[Plugin]:
 def get_plugin(name: str) -> Optional[Plugin]:
     """
     :说明:
+
       获取当前导入的某个插件。
+
     :参数:
+
       * ``name: str``: 插件名，与 ``load_plugin`` 参数一致。如果为 ``load_plugins`` 导入的插件，则为文件(夹)名。
+
     :返回:
+
       - ``Optional[Plugin]``
     """
     return plugins.get(name)
@@ -539,8 +615,11 @@ def get_plugin(name: str) -> Optional[Plugin]:
 def get_loaded_plugins() -> Set[Plugin]:
     """
     :说明:
+
       获取当前已导入的所有插件。
+
     :返回:
+
       - ``Set[Plugin]``
     """
     return set(plugins.values())
@@ -549,8 +628,11 @@ def get_loaded_plugins() -> Set[Plugin]:
 def export() -> Export:
     """
     :说明:
+
       获取插件的导出内容对象
+
     :返回:
+
       - ``Export``
     """
     return _export.get()
@@ -559,10 +641,15 @@ def export() -> Export:
 def require(name: str) -> Optional[Export]:
     """
     :说明:
+
       获取一个插件的导出内容
+
     :参数:
+
       * ``name: str``: 插件名，与 ``load_plugin`` 参数一致。如果为 ``load_plugins`` 导入的插件，则为文件(夹)名。
+
     :返回:
+
       - ``Optional[Export]``
     """
     plugin = get_plugin(name)

nonebot/rule.py

@@ -24,7 +24,9 @@ from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, Option
 class Rule:
     """
     :说明:
+
       ``Matcher`` 规则类，当事件传递时，在 ``Matcher`` 运行前进行检查。
+
     :示例:
 
     .. code-block:: python
@@ -41,25 +43,35 @@ class Rule:
                                       Awaitable[bool]]) -> None:
         """
         :参数:
+
           * ``*checkers: Callable[[Bot, Event, dict], Awaitable[bool]]``: **异步** RuleChecker
+
         """
         self.checkers = set(checkers)
         """
         :说明:
+
           存储 ``RuleChecker``
+
         :类型:
+
           * ``Set[Callable[[Bot, Event, dict], Awaitable[bool]]]``
         """
 
     async def __call__(self, bot: Bot, event: Event, state: dict) -> bool:
         """
         :说明:
+
           检查是否符合所有规则
+
         :参数:
+
           * ``bot: Bot``: Bot 对象
           * ``event: Event``: Event 对象
           * ``state: dict``: 当前 State
+
         :返回:
+
           - ``bool``
         """
         results = await asyncio.gather(
@@ -157,8 +169,11 @@ class TrieRule:
 def startswith(msg: str) -> Rule:
     """
     :说明:
+
       匹配消息开头
+
     :参数:
+
       * ``msg: str``: 消息开头字符串
     """
 
@@ -171,8 +186,11 @@ def startswith(msg: str) -> Rule:
 def endswith(msg: str) -> Rule:
     """
     :说明:
+
       匹配消息结尾
+
     :参数:
+
       * ``msg: str``: 消息结尾字符串
     """
 
@@ -185,8 +203,11 @@ def endswith(msg: str) -> Rule:
 def keyword(*keywords: str) -> Rule:
     """
     :说明:
+
       匹配消息关键词
+
     :参数:
+
       * ``*keywords: str``: 关键词
     """
 
@@ -200,12 +221,17 @@ def keyword(*keywords: str) -> Rule:
 def command(*cmds: Union[str, Tuple[str, ...]]) -> Rule:
     """
     :说明:
+
       命令形式匹配，根据配置里提供的 ``command_start``, ``command_sep`` 判断消息是否为命令。
 
       可以通过 ``state["_prefix"]["command"]`` 获取匹配成功的命令（例：``("test",)``），通过 ``state["_prefix"]["raw_command"]`` 获取匹配成功的原始命令文本（例：``"/test"``）。
+
     :参数:
+
       * ``*cmds: Union[str, Tuple[str, ...]]``: 命令内容
+
     :示例:
+
       使用默认 ``command_start``, ``command_sep`` 配置
 
       命令 ``("test",)`` 可以匹配：``/test`` 开头的消息
@@ -240,10 +266,13 @@ def command(*cmds: Union[str, Tuple[str, ...]]) -> Rule:
 def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
     """
     :说明:
+
       根据正则表达式进行匹配。
 
       可以通过 ``state["_matched"]`` 获取正则表达式匹配成功的文本。
+
     :参数:
+
       * ``regex: str``: 正则表达式
       * ``flags: Union[int, re.RegexFlag]``: 正则标志
 
@@ -269,8 +298,11 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
 def to_me() -> Rule:
     """
     :说明:
+
       通过 ``event.to_me`` 判断消息是否是发送给机器人
+
     :参数:
+
       * 无
     """
 

nonebot/sched.py

@@ -19,8 +19,11 @@ if AsyncIOScheduler:
     scheduler = AsyncIOScheduler()
     """
     :类型:
+
       ``Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]``
+
     :说明:
+
       当可选依赖 ``APScheduler`` 未安装时，``scheduler`` 为 None
 
       使用 ``pip install nonebot[scheduler]`` 安装可选依赖

nonebot/utils.py

@@ -10,10 +10,15 @@ from nonebot.typing import Any, Callable, Awaitable, overrides
 def escape_tag(s: str) -> str:
     """
     :说明:
+
       用于记录带颜色日志时转义 ``<tag>`` 类型特殊标签
+
     :参数:
+
       * ``s: str``: 需要转义的字符串
+
     :返回:
+
       - ``str``
     """
     return re.sub(r"</?((?:[fb]g\s)?[^<>\s]*)>", r"\\\g<0>", s)
@@ -22,10 +27,15 @@ def escape_tag(s: str) -> str:
 def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     """
     :说明:
+
       一个用于包装 sync function 为 async function 的装饰器
+
     :参数:
+
       * ``func: Callable[..., Any]``: 被装饰的同步函数
+
     :返回:
+
       - ``Callable[..., Awaitable[Any]]``
     """
 
@@ -42,6 +52,7 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
 class DataclassEncoder(json.JSONEncoder):
     """
     :说明:
+
       在JSON序列化 ``Message`` (List[Dataclass]) 时使用的 ``JSONEncoder``
     """