mirror of
https://github.com/nonebot/nonebot2.git
synced 2024-09-20 21:02:36 +00:00
📝 update handler doc
This commit is contained in:
yanyongyu
parent
381e5e4a76
commit
89ae275793
@ -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,
|
||||
)
|
||||
|
||||
@ -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]]]``
|
||||
|
||||
@ -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 同样编写了一个简易的依赖注入模块，使得开发者可以通过事件处理函数参数的类型标注来自动注入依赖。
|
||||
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
sidebar_position: 3
|
||||
description: 重载事件处理函数
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 61
|
||||
weight: 62
|
||||
category: advanced
|
||||
---
|
||||
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
sidebar_position: 2
|
||||
description: 同步函数作为依赖
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 60
|
||||
weight: 61
|
||||
category: advanced
|
||||
---
|
||||
|
||||
|
||||
10
website/docs/advanced/unittest.md
Normal file
10
website/docs/advanced/unittest.md
Normal file
@ -0,0 +1,10 @@
|
||||
---
|
||||
description: 编写单元测试
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 80
|
||||
category: advanced
|
||||
---
|
||||
|
||||
# 单元测试
|
||||
@ -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
|
||||
|
||||
@ -20,6 +20,8 @@ options:
|
||||
|
||||
NoneBot 内置了四种主要类型：`meta_event`, `message`, `notice`, `request`。通常情况下，协议适配器会将事件合理的分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
|
||||
|
||||
<!-- TODO: move session updater to advanced -->
|
||||
|
||||
:::warning 注意
|
||||
当会话状态更新时，会执行 `type_updater` 以更新 `type` 属性，以便会话收到新事件时能够正确匹配。
|
||||
|
||||
|
||||
37
website/docs/tutorial/plugin/matcher-operation.md
Normal file
37
website/docs/tutorial/plugin/matcher-operation.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user