This is unreleased documentation for NoneBot Next version.

For up-to-date documentation, see the latest version (2.0.0-beta.5).

Version: Next

nonebot.matcher

本模块实现事件响应器的创建与运行，并提供一些快捷方法来帮助用户更好的与机器人进行对话。

class `Matcher()`

说明
事件响应器类

classmethod `append_handler(cls, handler, parameterless=None)`

参数
- handler ((Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any])
- parameterless (list[Any] | None)
返回
- Dependent[typing.Any]

async classmethod `check_perm(cls, bot, event, stack=None, dependency_cache=None)`

说明
检查是否满足触发权限
参数
- bot (nonebot.internal.adapter.bot.Bot): Bot 对象
- event (nonebot.internal.adapter.event.Event): 上报事件
- stack (contextlib.AsyncExitStack | None): 异步上下文栈
- dependency_cache (dict[(Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any], Task[Any]] | None): 依赖缓存
返回
- bool: 是否满足权限

async classmethod `check_rule(cls, bot, event, state, stack=None, dependency_cache=None)`

说明
检查是否满足匹配规则
参数
- bot (nonebot.internal.adapter.bot.Bot): Bot 对象
- event (nonebot.internal.adapter.event.Event): 上报事件
- state (dict[Any, Any]): 当前状态
- stack (contextlib.AsyncExitStack | None): 异步上下文栈
- dependency_cache (dict[(Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any], Task[Any]] | None): 依赖缓存
返回
- bool: 是否满足匹配规则

async classmethod `finish(cls, message=None, **kwargs)`

说明
发送一条消息给当前交互用户并结束当前事件响应器
参数
- message (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 消息内容
- **kwargs: Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- NoReturn

method `get_arg(self, key, default=None)`

说明
获取一个 got 消息
如果没有找到对应的消息，返回 default 值
参数
- key (str)
- default ((~ T) | None)
返回
- nonebot.internal.adapter.message.Message | (~ T) | NoneType

method `get_last_receive(self, default=None)`

说明
获取最近一次 receive 事件
如果没有事件，返回 default 值
参数
- default ((~ T) | None)
返回
- nonebot.internal.adapter.event.Event | (~ T) | NoneType

method `get_receive(self, id, default=None)`

说明
获取一个 receive 事件
如果没有找到对应的事件，返回 default 值
参数
- id (str)
- default ((~ T) | None)
返回
- nonebot.internal.adapter.event.Event | (~ T) | NoneType

method `get_target(self, default=None)`

参数
- default ((~ T) | None)
返回
- str | (~ T) | NoneType

classmethod `got(cls, key, prompt=None, parameterless=None)`

说明
装饰一个函数来指示 NoneBot 获取一个参数 key
当要获取的 key 不存在时接收用户新的一条消息再运行该函数，如果 key 已存在则直接继续运行
参数
- key (str): 参数名
- prompt (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 在参数不存在时向用户发送的消息
- parameterless (list[Any] | None): 非参数类型依赖列表
返回
- ((*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]) -> (*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]

classmethod `handle(cls, parameterless=None)`

说明
装饰一个函数来向事件响应器直接添加一个处理函数
参数
- parameterless (list[Any] | None): 非参数类型依赖列表
返回
- ((*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]) -> (*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]

classmethod `new(cls, type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, plugin=None, module=None, expire_time=None, default_state=None, default_type_updater=None, default_permission_updater=None)`

说明
创建一个新的事件响应器，并存储至 matchers <#matchers>_
参数
- type_ (str): 事件响应器类型，与 event.get_type() 一致时触发，空字符串表示任意
- rule (nonebot.internal.rule.Rule | None): 匹配规则
- permission (nonebot.internal.permission.Permission | None): 权限
- handlers (list[(Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any] | Dependent[Any]] | None): 事件处理函数列表
- temp (bool): 是否为临时事件响应器，即触发一次后删除
- priority (int): 响应优先级
- block (bool): 是否阻止事件向更低优先级的响应器传播
- plugin (Plugin | None): 事件响应器所在插件
- module (module | None): 事件响应器所在模块
- expire_time (datetime.datetime | datetime.timedelta | NoneType): 事件响应器最终有效时间点，过时即被删除
- default_state (dict[Any, Any] | None): 默认状态 state
- default_type_updater ((Any, **Any) -> str | (Any, **Any) -> Awaitable[str] | Dependent[str] | NoneType)
- default_permission_updater ((Any, **Any) -> Permission | (Any, **Any) -> Awaitable[Permission] | Dependent[nonebot.internal.permission.Permission] | NoneType)
返回
- Type[Matcher]: 新的事件响应器类

async classmethod `pause(cls, prompt=None, **kwargs)`

说明
发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
参数
- prompt (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 消息内容
- **kwargs: Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- NoReturn

classmethod `permission_updater(cls, func)`

说明
装饰一个函数来更改当前事件响应器的默认会话权限更新函数
参数
- func ((Any, **Any) -> Permission | (Any, **Any) -> Awaitable[Permission]): 会话权限更新函数
返回
- (*Any, **Any) -> Permission | (*Any, **Any) -> Awaitable[Permission]

classmethod `receive(cls, id='', parameterless=None)`

说明
装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
参数
- id (str): 消息 ID
- parameterless (list[Any] | None): 非参数类型依赖列表
返回
- ((*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]) -> (*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]

async classmethod `reject(cls, prompt=None, **kwargs)`

说明
最近使用 got / receive 接收的消息不符合预期，发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
参数
- prompt (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 消息内容
- **kwargs: Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- NoReturn

async classmethod `reject_arg(cls, key, prompt=None, **kwargs)`

说明
最近使用 got 接收的消息不符合预期，发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一条消息后从头开始执行当前处理函数
参数
- key (str): 参数名
- prompt (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 消息内容
- **kwargs: Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- NoReturn

async classmethod `reject_receive(cls, id='', prompt=None, **kwargs)`

说明
最近使用 receive 接收的消息不符合预期，发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
参数
- id (str): 消息 id
- prompt (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate | NoneType): 消息内容
- **kwargs: Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- NoReturn

async method `resolve_reject(self)`

返回
- Unknown

async method `run(self, bot, event, state, stack=None, dependency_cache=None)`

参数
- bot (nonebot.internal.adapter.bot.Bot)
- event (nonebot.internal.adapter.event.Event)
- state (dict[Any, Any])
- stack (contextlib.AsyncExitStack | None)
- dependency_cache (dict[(Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any], Task[Any]] | None)
返回
- Unknown

async classmethod `send(cls, message, **kwargs)`

说明
发送一条消息给当前交互用户
参数
- message (str | nonebot.internal.adapter.message.Message | nonebot.internal.adapter.message.MessageSegment | nonebot.internal.adapter.template.MessageTemplate): 消息内容
- **kwargs (Any): Bot.send 的参数，请参考对应 adapter 的 bot 对象 api
返回
- Any

method `set_arg(self, key, message)`

说明
设置一个 got 消息
参数
- key (str)
- message (nonebot.internal.adapter.message.Message)
返回
- None

method `set_receive(self, id, event)`

说明
设置一个 receive 事件
参数
- id (str)
- event (nonebot.internal.adapter.event.Event)
返回
- None

method `set_target(self, target, cache=True)`

参数
- target (str)
- cache (bool)
返回
- None

async method `simple_run(self, bot, event, state, stack=None, dependency_cache=None)`

参数
- bot (nonebot.internal.adapter.bot.Bot)
- event (nonebot.internal.adapter.event.Event)
- state (dict[Any, Any])
- stack (contextlib.AsyncExitStack | None)
- dependency_cache (dict[(Any, **Any) -> Any | (Any, **Any) -> Awaitable[Any], Task[Any]] | None)
返回
- Unknown

classmethod `skip(cls)`

说明
跳过当前事件处理函数，继续下一个处理函数
通常在事件处理函数的依赖中使用。
返回
- NoReturn

method `stop_propagation(self)`

说明
阻止事件传播
返回
- Unknown

classmethod `type_updater(cls, func)`

说明
装饰一个函数来更改当前事件响应器的默认响应事件类型更新函数
参数
- func ((Any, **Any) -> str | (Any, **Any) -> Awaitable[str]): 响应事件类型更新函数
返回
- (*Any, **Any) -> str | (*Any, **Any) -> Awaitable[str]

async method `update_permission(self, bot, event)`

参数
- bot (nonebot.internal.adapter.bot.Bot)
- event (nonebot.internal.adapter.event.Event)
返回
- nonebot.internal.permission.Permission

async method `update_type(self, bot, event)`

参数
- bot (nonebot.internal.adapter.bot.Bot)
- event (nonebot.internal.adapter.event.Event)
返回
- str

class Matcher()#

classmethod append_handler(cls, handler, parameterless=None)#

async classmethod check_perm(cls, bot, event, stack=None, dependency_cache=None)#

async classmethod check_rule(cls, bot, event, state, stack=None, dependency_cache=None)#

async classmethod finish(cls, message=None, **kwargs)#

method get_arg(self, key, default=None)#

method get_last_receive(self, default=None)#

method get_receive(self, id, default=None)#

method get_target(self, default=None)#

classmethod got(cls, key, prompt=None, parameterless=None)#

classmethod handle(cls, parameterless=None)#

classmethod new(cls, type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, plugin=None, module=None, expire_time=None, default_state=None, default_type_updater=None, default_permission_updater=None)#

async classmethod pause(cls, prompt=None, **kwargs)#

classmethod permission_updater(cls, func)#

classmethod receive(cls, id='', parameterless=None)#

async classmethod reject(cls, prompt=None, **kwargs)#

async classmethod reject_arg(cls, key, prompt=None, **kwargs)#

async classmethod reject_receive(cls, id='', prompt=None, **kwargs)#

async method resolve_reject(self)#

async method run(self, bot, event, state, stack=None, dependency_cache=None)#

async classmethod send(cls, message, **kwargs)#

method set_arg(self, key, message)#

method set_receive(self, id, event)#

method set_target(self, target, cache=True)#

async method simple_run(self, bot, event, state, stack=None, dependency_cache=None)#

classmethod skip(cls)#

method stop_propagation(self)#

classmethod type_updater(cls, func)#

async method update_permission(self, bot, event)#

async method update_type(self, bot, event)#

class `Matcher()`

classmethod `append_handler(cls, handler, parameterless=None)`

async classmethod `check_perm(cls, bot, event, stack=None, dependency_cache=None)`

async classmethod `check_rule(cls, bot, event, state, stack=None, dependency_cache=None)`

async classmethod `finish(cls, message=None, **kwargs)`

method `get_arg(self, key, default=None)`

method `get_last_receive(self, default=None)`

method `get_receive(self, id, default=None)`

method `get_target(self, default=None)`

classmethod `got(cls, key, prompt=None, parameterless=None)`

classmethod `handle(cls, parameterless=None)`

classmethod `new(cls, type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, plugin=None, module=None, expire_time=None, default_state=None, default_type_updater=None, default_permission_updater=None)`

async classmethod `pause(cls, prompt=None, **kwargs)`

classmethod `permission_updater(cls, func)`

classmethod `receive(cls, id='', parameterless=None)`

async classmethod `reject(cls, prompt=None, **kwargs)`

async classmethod `reject_arg(cls, key, prompt=None, **kwargs)`

async classmethod `reject_receive(cls, id='', prompt=None, **kwargs)`

async method `resolve_reject(self)`

async method `run(self, bot, event, state, stack=None, dependency_cache=None)`

async classmethod `send(cls, message, **kwargs)`

method `set_arg(self, key, message)`

method `set_receive(self, id, event)`

method `set_target(self, target, cache=True)`

async method `simple_run(self, bot, event, state, stack=None, dependency_cache=None)`

classmethod `skip(cls)`

method `stop_propagation(self)`

classmethod `type_updater(cls, func)`

async method `update_permission(self, bot, event)`

async method `update_type(self, bot, event)`