nonebot2/website/versioned_docs/version-2.0.0rc2/api/matcher.md

sidebar_position	description
3	nonebot.matcher 模块

nonebot.matcher

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

class Matcher()

• 说明

  事件响应器类

classmethod append_handler(cls, handler, parameterless=None)

• 参数

  • handler ((*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any])

  • parameterless (Iterable[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: 是否满足匹配规则

method ensure_context(self, bot, event)

• 参数

  • bot (nonebot.internal.adapter.bot.Bot)

  • event (nonebot.internal.adapter.event.Event)

• 返回

  • Unknown

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 (Iterable[Any] | None): 非参数类型依赖列表

• 返回

  • ((*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]) -> (*Any, **Any) -> Any | (*Any, **Any) -> Awaitable[Any]

classmethod handle(cls, parameterless=None)

• 说明

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

• 参数

  • parameterless (Iterable[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 (Iterable[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 MatcherManager()

• 说明

  事件响应器管理器

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

method clear(self)

• 返回

  • None

method get(self, key, default=None)

• 参数

  • key (int)

  • default ((~ T) | None)

• 返回

  • list[Type[Matcher]] | (~ T) | NoneType

method items(self)

• 返回

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

method keys(self)

• 返回

  • KeysView[int]

method pop(self, key)

• 参数

  • key (int)

• 返回

  • list[Type[Matcher]]

method popitem(self)

• 返回

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

method set_provider(self, provider_class)

• 说明

  设置事件响应器存储器

• 参数

  • provider_class (Type[nonebot.internal.matcher.provider.MatcherProvider]): 事件响应器存储器类

• 返回

  • None

method setdefault(self, key, default)

• 参数

  • key (int)

  • default (list[Type[Matcher]])

• 返回

  • list[Type[Matcher]]

method update(self, _MatcherManager__m)

• 参数

  • _MatcherManager__m (MutableMapping[int, list[Type[Matcher]]])

• 返回

  • None

method values(self)

• 返回

  • ValuesView[list[Type[Matcher]]]

abstract class MatcherProvider(matchers)

• 说明

  事件响应器存储器基类

• 参数

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

class DEFAULT_PROVIDER_CLASS(matchers)

• 参数

  • matchers (Mapping[int, list[Type[Matcher]]])