📝 update handler doc

nonebot/matcher.py

@@ -46,7 +46,6 @@ from nonebot.typing import (
     Any,
     T_State,
     T_Handler,
-    T_ArgsParser,
     T_TypeUpdater,
     T_DependencyCache,
     T_PermissionUpdater,
@@ -223,7 +222,6 @@ class Matcher(metaclass=MatcherMeta):
         module: Optional[ModuleType] = None,
         expire_time: Optional[datetime] = None,
         default_state: Optional[T_State] = None,
-        default_parser: Optional[T_ArgsParser] = None,
         default_type_updater: Optional[T_TypeUpdater] = None,
         default_permission_updater: Optional[T_PermissionUpdater] = None,
     ) -> Type["Matcher"]:
@@ -276,7 +274,6 @@ class Matcher(metaclass=MatcherMeta):
                 "priority": priority,
                 "block": block,
                 "_default_state": default_state or {},
-                "_default_parser": default_parser,
                 "_default_type_updater": default_type_updater,
                 "_default_permission_updater": default_permission_updater,
             },
@@ -344,22 +341,6 @@ class Matcher(metaclass=MatcherMeta):
             bot, event, state, stack, dependency_cache
         )
 
-    @classmethod
-    def args_parser(cls, func: T_ArgsParser) -> T_ArgsParser:
-        """
-        :说明:
-
-          装饰一个函数来更改当前事件响应器的默认参数解析函数
-
-        :参数:
-
-          * ``func: T_ArgsParser``: 参数解析函数
-        """
-        cls._default_parser = Dependent[None].parse(
-            call=func, allow_types=cls.HANDLER_PARAM_TYPES
-        )
-        return func
-
     @classmethod
     def type_updater(cls, func: T_TypeUpdater) -> T_TypeUpdater:
         """
@@ -777,7 +758,6 @@ class Matcher(metaclass=MatcherMeta):
                 module=self.module,
                 expire_time=datetime.now() + bot.config.session_expire_timeout,
                 default_state=self.state,
-                default_parser=self.__class__._default_parser,
                 default_type_updater=self.__class__._default_type_updater,
                 default_permission_updater=self.__class__._default_permission_updater,
             )
@@ -797,7 +777,6 @@ class Matcher(metaclass=MatcherMeta):
                 module=self.module,
                 expire_time=datetime.now() + bot.config.session_expire_timeout,
                 default_state=self.state,
-                default_parser=self.__class__._default_parser,
                 default_type_updater=self.__class__._default_type_updater,
                 default_permission_updater=self.__class__._default_permission_updater,
             )

nonebot/typing.py

@@ -197,23 +197,6 @@ T_Handler = Callable[..., Any]
 
   Handler 处理函数。
 """
-T_ArgsParser = Callable[..., Union[None, Awaitable[None]]]
-"""
-:类型: ``Callable[..., Union[None, Awaitable[None]]]``
-
-:依赖参数:
-
-  * ``DependParam``: 子依赖参数
-  * ``BotParam``: Bot 对象
-  * ``EventParam``: Event 对象
-  * ``StateParam``: State 对象
-  * ``MatcherParam``: Matcher 对象
-  * ``DefaultParam``: 带有默认值的参数
-
-:说明:
-
-  ArgsParser 即消息参数解析函数，在 Matcher.got 获取参数时被运行。
-"""
 T_TypeUpdater = Callable[..., Union[str, Awaitable[str]]]
 """
 :类型: ``Callable[..., Union[None, Awaitable[None]]]``

website/docs/advanced/di/dependency-injection.md

@@ -1,13 +1,14 @@
 ---
-sidebar_position: 3
+sidebar_position: 1
+description: 依赖注入简介
 
 options:
   menu:
-    weight: 62
+    weight: 60
     category: advanced
 ---
 
-# 依赖注入
+# 简介
 
 受 [`FastApi`](https://fastapi.tiangolo.com/tutorial/dependencies/) 启发，NoneBot 同样编写了一个简易的依赖注入模块，使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。
 

website/docs/advanced/di/overload.md

@@ -1,9 +1,10 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
+description: 重载事件处理函数
 
 options:
   menu:
-    weight: 61
+    weight: 62
     category: advanced
 ---
 

website/docs/advanced/di/sync-support.md

@@ -1,9 +1,10 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
+description: 同步函数作为依赖
 
 options:
   menu:
-    weight: 60
+    weight: 61
     category: advanced
 ---
 

website/docs/advanced/unittest.md

@@ -0,0 +1,10 @@
+---
+description: 编写单元测试
+
+options:
+  menu:
+    weight: 80
+    category: advanced
+---
+
+# 单元测试

website/docs/tutorial/plugin/create-handler.md

@@ -14,8 +14,107 @@ options:
 
 ## 添加一个处理依赖
 
+在事件响应器中，事件处理流程由一个或多个处理依赖组成，每个处理依赖都是一个 `Dependent`，详情可以参考 [进阶 - 依赖注入](../../advanced/di/dependency-injection.md)。下面介绍如何添加一个处理依赖。
+
+### 使用 `handle` 装饰器
+
+```python {3-5}
+matcher = on_message()
+
+@matcher.handle()
+async def handle_func():
+    # do something here
+```
+
+如上方示例所示，我们使用 `matcher` 响应器的 `handle` 装饰器装饰了一个函数 `handle_func` 。`handle_func` 函数会被自动转换为 `Dependent` 对象，并被添加到 `matcher` 的事件处理流程中。
+
+在 `handle_func` 函数中，我们可以编写任何事件响应逻辑，如：操作数据库，发送消息等。上下文信息可以通过依赖注入的方式获取，参考：[获取上下文信息](#获取上下文信息)。发送消息可以通过 [事件响应器操作](./matcher-operation.md) 或者直接调用 Bot 的方法（ API 等，由协议适配器决定）。
+
+:::warning 注意
+`handle_func` 函数虽然会被装饰器自动转换为 `Dependent` 对象，但 `handle_func` 仍然为原本的函数，因此 `handle_func` 函数可以进行复用。如：
+
+```python
+matcher1 = on_message()
+matcher2 = on_message()
+
+@matcher1.handle()
+@matcher2.handle()
+async def handle_func():
+    # do something here
+```
+
+:::
+
+### 使用 `receive` 装饰器
+
+```python {3-5}
+matcher = on_message()
+
+@matcher.receive("id")
+async def handle_func(e: Event = Received("id")):
+    # do something here
+```
+
+`receive` 装饰器与 `handle` 装饰器一样，可以装饰一个函数添加到事件响应器的事件处理流程中。但与 `handle` 装饰器不同的是，`receive` 装饰器会中断当前事件处理流程，等待接收一个新的事件，就像是会话状态等待用户一个新的事件。可以接收的新的事件类型取决于事件响应器的 [`type`](./create-matcher.md#事件响应器类型-type) 更新值以及 [`permission`](./create-matcher.md#事件触发权限-permission) 更新值，可以通过自定义更新方法来控制会话响应（如进行非消息交互、多人会话、跨群会话等）。
+
+`receive` 装饰器接受一个可选参数 `id` ，用于标识当前需要接收的事件，如果不指定，则默认为空 `""`。
+
+在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的事件，参考：[`Received`](#received), [`LastReceived`](#lastreceived)。
+
+:::important 提示
+`receive` 装饰器可以和自身与 `got` 装饰器嵌套使用
+:::
+
+:::warning 注意
+如果存在多个 `receive` 装饰器，则必须指定不相同的多个 `id`；否则相同的 `id` 将会被跳过接收。
+
+```python
+matcher = on_message()
+
+@matcher.receive("id1")
+@matcher.receive("id2")
+async def handle_func():
+    # do something here
+```
+
+:::
+
+### 使用 `got` 装饰器
+
+```python {3-5}
+matcher = on_message()
+
+@matcher.got("key")
+async def handle_func(key: Message = Arg()):
+    # do something here
+```
+
+`got` 装饰器与 `receive` 装饰器一样，会中断当前事件处理流程，等待接收一个新的事件。但与 `receive` 装饰器不同的是，`got` 装饰器用于接收一条消息，并且可以控制是否向用户发送询问 `prompt` 等，更贴近于对话形式会话。
+
+`got` 装饰器接受一个参数 `key` 和一个可选参数 `prompt`，当 `key` 不存在时，会向用户发送 `prompt` 消息，并等待用户回复。
+
+在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的消息，参考：[`Arg`](#arg), [`ArgStr`](#argstr), [`ArgPlainText`](#argplaintext)。
+
+:::important 提示
+`got` 装饰器可以和自身与 `receive` 装饰器嵌套使用
+:::
+
+### 直接添加
+
+```python {2}
+matcher = on_message(
+    handlers=[handle_func, or_dependent]
+)
+```
+
+:::warning 注意
+通过该方法添加的处理依赖将会处于整个事件处理流程的最前，因此，如果再使用 `handle` 等装饰器，则会在其之后。
+:::
+
 ## 事件处理流程
 
+<!-- TODO -->
+
 ## 获取上下文信息
 
 ### Bot

website/docs/tutorial/plugin/create-matcher.md

@@ -20,6 +20,8 @@ options:
 
 NoneBot 内置了四种主要类型：`meta_event`, `message`, `notice`, `request`。通常情况下，协议适配器会将事件合理的分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
 
+<!-- TODO: move session updater to advanced -->
+
 :::warning 注意
 当会话状态更新时，会执行 `type_updater` 以更新 `type` 属性，以便会话收到新事件时能够正确匹配。
 

website/docs/tutorial/plugin/matcher-operation.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 5
+description: 使用事件响应器操作，改变事件处理流程
+
+options:
+  menu:
+    weight: 28
+    category: guide
+---
+
+# 事件响应器操作
+
+## send
+
+## finish
+
+## pause
+
+## reject
+
+## reject_arg
+
+## reject_receive
+
+## skip
+
+## get_receive
+
+## set_receive
+
+## get_last_receive
+
+## get_arg
+
+## set_arg
+
+## stop_propagation