nonebot2/website/versioned_docs/version-2.1.1/api/matcher.md

sidebar_position	description
3	nonebot.matcher 模块

nonebot.matcher

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

class Matcher()

• 说明: 事件响应器类

• 参数

  empty

instance-var handlers

• 类型: list[Dependent[Any]]

• 说明: 事件响应器拥有的事件处理函数列表

class-var type

• 类型: ClassVar[str]

• 说明: 事件响应器类型

class-var rule

• 类型: ClassVar[Rule]

• 说明: 事件响应器匹配规则

class-var permission

• 类型: ClassVar[Permission]

• 说明: 事件响应器触发权限

class-var priority

• 类型: ClassVar[int]

• 说明: 事件响应器优先级

class-var block

• 类型: bool

• 说明: 事件响应器是否阻止事件传播

class-var temp

• 类型: ClassVar[bool]

• 说明: 事件响应器是否为临时

class-var expire_time

• 类型: ClassVar[datetime | None]

• 说明: 事件响应器过期时间点

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

• 说明: 创建一个新的事件响应器，并存储至 matchers <#matchers>_

• 参数

  • type_ (str): 事件响应器类型，与 event.get_type() 一致时触发，空字符串表示任意

  • rule (Rule | None): 匹配规则

  • permission (Permission | None): 权限

  • handlers (list[T_Handler | Dependent[Any]] | None): 事件处理函数列表

  • temp (bool): 是否为临时事件响应器，即触发一次后删除

  • priority (int): 响应优先级

  • block (bool): 是否阻止事件向更低优先级的响应器传播

  • plugin (Plugin | None): Deprecated. 事件响应器所在插件

  • module (ModuleType | None): Deprecated. 事件响应器所在模块

  • source (MatcherSource | None): 事件响应器源代码上下文信息

  • expire_time (datetime | timedelta | None): 事件响应器最终有效时间点，过时即被删除

  • default_state (T_State | None): 默认状态 state

  • default_type_updater (T_TypeUpdater | Dependent[str] | None): 默认事件类型更新函数

  • default_permission_updater (T_PermissionUpdater | Dependent[Permission] | None): 默认会话权限更新函数

• 返回

  • type[Matcher]: 新的事件响应器类

classmethod destroy()

• 说明: 销毁当前的事件响应器

• 参数

  empty

• 返回

  • None

classmethod check_perm(bot, event, stack=None, dependency_cache=None)

• 说明: 检查是否满足触发权限

• 参数

  • bot (Bot): Bot 对象

  • event (Event): 上报事件

  • stack (AsyncExitStack | None): 异步上下文栈

  • dependency_cache (T_DependencyCache | None): 依赖缓存

• 返回

  • bool: 是否满足权限

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

• 说明: 检查是否满足匹配规则

• 参数

  • bot (Bot): Bot 对象

  • event (Event): 上报事件

  • state (T_State): 当前状态

  • stack (AsyncExitStack | None): 异步上下文栈

  • dependency_cache (T_DependencyCache | None): 依赖缓存

• 返回

  • bool: 是否满足匹配规则

classmethod type_updater(func)

• 说明: 装饰一个函数来更改当前事件响应器的默认响应事件类型更新函数

• 参数

  • func (T_TypeUpdater): 响应事件类型更新函数

• 返回

  • T_TypeUpdater

classmethod permission_updater(func)

• 说明: 装饰一个函数来更改当前事件响应器的默认会话权限更新函数

• 参数

  • func (T_PermissionUpdater): 会话权限更新函数

• 返回

  • T_PermissionUpdater

classmethod append_handler(handler, parameterless=None)

• 参数

  • handler (T_Handler)

  • parameterless (Iterable[Any] | None)

• 返回

  • Dependent[Any]

classmethod handle(parameterless=None)

• 说明: 装饰一个函数来向事件响应器直接添加一个处理函数

• 参数

  • parameterless (Iterable[Any] | None): 非参数类型依赖列表

• 返回

  • (T_Handler) -> T_Handler

classmethod receive(id="", parameterless=None)

• 说明: 装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数

• 参数

  • id (str): 消息 ID

  • parameterless (Iterable[Any] | None): 非参数类型依赖列表

• 返回

  • (T_Handler) -> T_Handler

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

• 说明

  装饰一个函数来指示 NoneBot 获取一个参数 key

  当要获取的 key 不存在时接收用户新的一条消息再运行该函数， 如果 key 已存在则直接继续运行

• 参数

  • key (str): 参数名

  • prompt (str | Message | MessageSegment | MessageTemplate | None): 在参数不存在时向用户发送的消息

  • parameterless (Iterable[Any] | None): 非参数类型依赖列表

• 返回

  • (T_Handler) -> T_Handler

classmethod send(message, **kwargs)

• 说明: 发送一条消息给当前交互用户

• 参数

  • message (str | Message | MessageSegment | MessageTemplate): 消息内容

  • **kwargs (Any): Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • Any

classmethod finish(message=None, **kwargs)

• 说明: 发送一条消息给当前交互用户并结束当前事件响应器

• 参数

  • message (str | Message | MessageSegment | MessageTemplate | None): 消息内容

  • **kwargs: Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • NoReturn

classmethod pause(prompt=None, **kwargs)

• 说明: 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数

• 参数

  • prompt (str | Message | MessageSegment | MessageTemplate | None): 消息内容

  • **kwargs: Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • NoReturn

classmethod reject(prompt=None, **kwargs)

• 说明: 最近使用 got / receive 接收的消息不符合预期， 发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数

• 参数

  • prompt (str | Message | MessageSegment | MessageTemplate | None): 消息内容

  • **kwargs: Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • NoReturn

classmethod reject_arg(key, prompt=None, **kwargs)

• 说明: 最近使用 got 接收的消息不符合预期， 发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一条消息后从头开始执行当前处理函数

• 参数

  • key (str): 参数名

  • prompt (str | Message | MessageSegment | MessageTemplate | None): 消息内容

  • **kwargs: Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • NoReturn

classmethod reject_receive(id="", prompt=None, **kwargs)

• 说明: 最近使用 receive 接收的消息不符合预期， 发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数

• 参数

  • id (str): 消息 id

  • prompt (str | Message | MessageSegment | MessageTemplate | None): 消息内容

  • **kwargs: Bot.send 的参数， 请参考对应 adapter 的 bot 对象 api

• 返回

  • NoReturn

classmethod skip()

• 说明

  跳过当前事件处理函数，继续下一个处理函数

  通常在事件处理函数的依赖中使用。

• 参数

  empty

• 返回

  • NoReturn

method get_receive(id, default=None)

• 说明

  获取一个 receive 事件

  如果没有找到对应的事件，返回 default 值

• 重载

  1. (id) -> Event | None

  • 参数

    • id (str)

  • 返回

    • Event | None

  2. (id, default) -> Event | T

  • 参数

    • id (str)

    • default (T)

  • 返回

    • Event | T

method set_receive(id, event)

• 说明: 设置一个 receive 事件

• 参数

  • id (str)

  • event (Event)

• 返回

  • None

method get_last_receive(default=None)

• 说明

  获取最近一次 receive 事件

  如果没有事件，返回 default 值

• 重载

  1. () -> Event | None

  • 参数

    empty

  • 返回

    • Event | None

  2. (default) -> Event | T

  • 参数

    • default (T)

  • 返回

    • Event | T

method get_arg(key, default=None)

• 说明

  获取一个 got 消息

  如果没有找到对应的消息，返回 default 值

• 重载

  1. (key) -> Message | None

  • 参数

    • key (str)

  • 返回

    • Message | None

  2. (key, default) -> Message | T

  • 参数

    • key (str)

    • default (T)

  • 返回

    • Message | T

method set_arg(key, message)

• 说明: 设置一个 got 消息

• 参数

  • key (str)

  • message (Message)

• 返回

  • None

method set_target(target, cache=True)

• 参数

  • target (str)

  • cache (bool)

• 返回

  • None

method get_target(default=None)

• 重载

  1. () -> str | None

  • 参数

    empty

  • 返回

    • str | None

  2. (default) -> str | T

  • 参数

    • default (T)

  • 返回

    • str | T

method stop_propagation()

• 说明: 阻止事件传播

• 参数

  empty

• 返回

  • untyped

async method update_type(bot, event, stack=None, dependency_cache=None)

• 参数

  • bot (Bot)

  • event (Event)

  • stack (AsyncExitStack | None)

  • dependency_cache (T_DependencyCache | None)

• 返回

  • str

async method update_permission(bot, event, stack=None, dependency_cache=None)

• 参数

  • bot (Bot)

  • event (Event)

  • stack (AsyncExitStack | None)

  • dependency_cache (T_DependencyCache | None)

• 返回

  • Permission

async method resolve_reject()

• 参数

  empty

• 返回

  • untyped

method ensure_context(bot, event)

• 参数

  • bot (Bot)

  • event (Event)

• 返回

  • untyped

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

• 参数

  • bot (Bot)

  • event (Event)

  • state (T_State)

  • stack (AsyncExitStack | None)

  • dependency_cache (T_DependencyCache | None)

• 返回

  • untyped

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

• 参数

  • bot (Bot)

  • event (Event)

  • state (T_State)

  • stack (AsyncExitStack | None)

  • dependency_cache (T_DependencyCache | None)

• 返回

  • untyped

var matchers

• 类型: untyped

class MatcherManager()

• 说明

  事件响应器管理器

  实现了常用字典操作，用于管理事件响应器。

• 参数

  empty

method keys()

• 参数

  empty

• 返回

  • KeysView[int]

method values()

• 参数

  empty

• 返回

  • ValuesView[list[type[Matcher]]]

method items()

• 参数

  empty

• 返回

  • ItemsView[int, list[type[Matcher]]]

method get(key, default=None)

• 重载

  1. (key) -> list[type[Matcher]] | None

  • 参数

    • key (int)

  • 返回

    • list[type[Matcher]] | None

  2. (key, default) -> list[type[Matcher]] | T

  • 参数

    • key (int)

    • default (T)

  • 返回

    • list[type[Matcher]] | T

method pop(key)

• 参数

  • key (int)

• 返回

  • list[type[Matcher]]

method popitem()

• 参数

  empty

• 返回

  • tuple[int, list[type[Matcher]]]

method clear()

• 参数

  empty

• 返回

  • None

method update(__m)

• 参数

  • __m (MutableMapping[int, list[type[Matcher]]])

• 返回

  • None

method setdefault(key, default)

• 参数

  • key (int)

  • default (list[type[Matcher]])

• 返回

  • list[type[Matcher]]

method set_provider(provider_class)

• 说明: 设置事件响应器存储器

• 参数

  • provider_class (type[MatcherProvider]): 事件响应器存储器类

• 返回

  • None

abstract class MatcherProvider(matchers)

• 说明: 事件响应器存储器基类

• 参数

  • matchers (Mapping[int, list[type[Matcher]]]): 当前存储器中已有的事件响应器

var DEFAULT_PROVIDER_CLASS

• 类型: untyped

• 说明: 默认存储器类型