diff --git a/nonebot/matcher.py b/nonebot/matcher.py index 18ef9fcd..f9d7f8c5 100644 --- a/nonebot/matcher.py +++ b/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, ) diff --git a/nonebot/typing.py b/nonebot/typing.py index d4ff66b4..55774ca1 100644 --- a/nonebot/typing.py +++ b/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]]]`` diff --git a/website/docs/advanced/di/dependency-injection.md b/website/docs/advanced/di/dependency-injection.md index a19baadb..67ce8b60 100644 --- a/website/docs/advanced/di/dependency-injection.md +++ b/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 同样编写了一个简易的依赖注入模块,使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。 diff --git a/website/docs/advanced/di/overload.md b/website/docs/advanced/di/overload.md index 444e72cd..b1ab1650 100644 --- a/website/docs/advanced/di/overload.md +++ b/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 --- diff --git a/website/docs/advanced/di/sync-support.md b/website/docs/advanced/di/sync-support.md index 54d81b6c..47d6f4df 100644 --- a/website/docs/advanced/di/sync-support.md +++ b/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 --- diff --git a/website/docs/advanced/test/unittest.md b/website/docs/advanced/test/unittest.md deleted file mode 100644 index e69de29b..00000000 diff --git a/website/docs/advanced/unittest.md b/website/docs/advanced/unittest.md new file mode 100644 index 00000000..f480a2d7 --- /dev/null +++ b/website/docs/advanced/unittest.md @@ -0,0 +1,10 @@ +--- +description: 编写单元测试 + +options: + menu: + weight: 80 + category: advanced +--- + +# 单元测试 diff --git a/website/docs/tutorial/plugin/create-handler.md b/website/docs/tutorial/plugin/create-handler.md index 95b29b20..eaf7c707 100644 --- a/website/docs/tutorial/plugin/create-handler.md +++ b/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` 等装饰器,则会在其之后。 +::: + ## 事件处理流程 + + ## 获取上下文信息 ### Bot diff --git a/website/docs/tutorial/plugin/create-matcher.md b/website/docs/tutorial/plugin/create-matcher.md index 50a8a180..6aba5738 100644 --- a/website/docs/tutorial/plugin/create-matcher.md +++ b/website/docs/tutorial/plugin/create-matcher.md @@ -20,6 +20,8 @@ options: NoneBot 内置了四种主要类型:`meta_event`, `message`, `notice`, `request`。通常情况下,协议适配器会将事件合理的分类至这四种类型中。如果有其他类型的事件需要响应,可以自行定义新的类型。 + + :::warning 注意 当会话状态更新时,会执行 `type_updater` 以更新 `type` 属性,以便会话收到新事件时能够正确匹配。 diff --git a/website/docs/tutorial/plugin/matcher-operation.md b/website/docs/tutorial/plugin/matcher-operation.md new file mode 100644 index 00000000..0d8d6551 --- /dev/null +++ b/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