This is unreleased documentation for NoneBot Next version.

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

Version: Next

nonebot.matcher

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

class `Matcher()`

说明: 事件响应器类
参数
empty

instance-var `handlers`

类型: list[Dependent[Any]]
说明: 事件响应器拥有的事件处理函数列表

class-var `plugin`

类型: Plugin | None
说明: 事件响应器所在插件

class-var `module`

类型: ModuleType | None
说明: 事件响应器所在插件模块

class-var `plugin_name`

类型: str | None
说明: 事件响应器所在插件名

class-var `module_name`

类型: str | None
说明: 事件响应器所在点分割插件模块路径

class-var `type`

类型: str
说明: 事件响应器类型

class-var `rule`

类型: Rule
说明: 事件响应器匹配规则

class-var `permission`

类型: Permission
说明: 事件响应器触发权限

class-var `priority`

类型: int
说明: 事件响应器优先级

class-var `block`

类型: bool
说明: 事件响应器是否阻止事件传播

class-var `temp`

类型: bool
说明: 事件响应器是否为临时

class-var `expire_time`

类型: datetime | None
说明: 事件响应器过期时间点

classmethod `new(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 (Rule | None): 匹配规则
- permission (Permission | None): 权限
- handlers (list[T_Handler | Dependent[Any]] | None): 事件处理函数列表
- temp (bool): 是否为临时事件响应器，即触发一次后删除
- priority (int): 响应优先级
- block (bool): 是否阻止事件向更低优先级的响应器传播
- plugin (Plugin | None): 事件响应器所在插件
- module (ModuleType | 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. (self, id) -> Event | None
- 参数
  - self
  - id (str)
- 返回
  - Event | None
2. (self, id, default) -> Event | T
- 参数
  - self
  - 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. (self) -> Event | None
- 参数
  - self
- 返回
  - Event | None
2. (self, default) -> Event | T
- 参数
  - self
  - default (T)
- 返回
  - Event | T

method `get_arg(key, default=None)`

说明
获取一个 got 消息
如果没有找到对应的消息，返回 default 值
重载
1. (self, key) -> Message | None
- 参数
  - self
  - key (str)
- 返回
  - Message | None
2. (self, key, default) -> Message | T
- 参数
  - self
  - 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. (self) -> str | None
- 参数
  - self
- 返回
  - str | None
2. (self, default) -> str | T
- 参数
  - self
  - default (T)
- 返回
  - str | T

method `stop_propagation()`

说明: 阻止事件传播
参数
empty
返回
- untyped

async method `update_type(bot, event)`

参数
- bot (Bot)
- event (Event)
返回
- str

async method `update_permission(bot, event)`

参数
- bot (Bot)
- event (Event)
返回
- 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`

类型:

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. (self, key) -> list[type[Matcher]] | None
- 参数
  - self
  - key (int)
- 返回
  - list[type[Matcher]] | None
2. (self, key, default) -> list[type[Matcher]] | T
- 参数
  - self
  - 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`

类型:
说明: 默认存储器类型

class Matcher()#

instance-var handlers#

class-var plugin#

class-var module#

class-var plugin_name#

class-var module_name#

class-var type#

class-var rule#

class-var permission#

class-var priority#

class-var block#

class-var temp#

class-var expire_time#

classmethod new(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)#

classmethod destroy()#

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

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

classmethod type_updater(func)#

classmethod permission_updater(func)#

classmethod append_handler(handler, parameterless=None)#

classmethod handle(parameterless=None)#

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

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

classmethod send(message, **kwargs)#

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

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

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

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

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

classmethod skip()#

method get_receive(id, default=None)#

method set_receive(id, event)#

method get_last_receive(default=None)#

method get_arg(key, default=None)#

method set_arg(key, message)#

method set_target(target, cache=True)#

method get_target(default=None)#

method stop_propagation()#

async method update_type(bot, event)#

async method update_permission(bot, event)#

async method resolve_reject()#

method ensure_context(bot, event)#

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

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

var matchers#

class MatcherManager()#

method keys()#

method values()#

method items()#

method get(key, default=None)#

method pop(key)#

method popitem()#

method clear()#

method update(__m)#

method setdefault(key, default)#

method set_provider(provider_class)#

abstract class MatcherProvider(matchers)#

var DEFAULT_PROVIDER_CLASS#

class `Matcher()`

instance-var `handlers`

class-var `plugin`

class-var `module`

class-var `plugin_name`

class-var `module_name`

class-var `type`

class-var `rule`

class-var `permission`

class-var `priority`

class-var `block`

class-var `temp`

class-var `expire_time`

classmethod `new(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)`

classmethod `destroy()`

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

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

classmethod `type_updater(func)`

classmethod `permission_updater(func)`

classmethod `append_handler(handler, parameterless=None)`

classmethod `handle(parameterless=None)`

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

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

classmethod `send(message, **kwargs)`

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

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

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

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

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

classmethod `skip()`

method `get_receive(id, default=None)`

method `set_receive(id, event)`

method `get_last_receive(default=None)`

method `get_arg(key, default=None)`

method `set_arg(key, message)`

method `set_target(target, cache=True)`

method `get_target(default=None)`

method `stop_propagation()`

async method `update_type(bot, event)`

async method `update_permission(bot, event)`

async method `resolve_reject()`

method `ensure_context(bot, event)`

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

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

var `matchers`

class `MatcherManager()`

method `keys()`

method `values()`

method `items()`

method `get(key, default=None)`

method `pop(key)`

method `popitem()`

method `clear()`

method `update(__m)`

method `setdefault(key, default)`

method `set_provider(provider_class)`

abstract class `MatcherProvider(matchers)`

var `DEFAULT_PROVIDER_CLASS`