# NoneBot.plugin 模块

# 插件

为 NoneBot 插件开发提供便携的定义函数。

# plugins

• 类型

  Dict[str, Plugin]

• 说明

  已加载的插件

# class Plugin

基类：object

存储插件信息

# name

• 类型: str

• 说明: 插件名称，使用 文件/文件夹 名称作为插件名

# module

• 类型: ModuleType

• 说明: 插件模块对象

# export

• 类型: Export

• 说明: 插件内定义的导出内容

# property matcher

• 类型: Set[Type[Matcher]]

• 说明: 插件内定义的 Matcher

# on(type='', rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=False, state=None, state_factory=None)

• 说明

  注册一个基础事件响应器，可自定义类型。

• 参数

  • type: str: 事件响应器类型

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_metaevent(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, state_factory=None)

• 说明

  注册一个元事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_message(rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=True, state=None, state_factory=None)

• 说明

  注册一个消息事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_notice(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, state_factory=None)

• 说明

  注册一个通知事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_request(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None, state_factory=None)

• 说明

  注册一个请求事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_startswith(msg, rule=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息的**文本部分**以指定内容开头时响应。

• 参数

  • msg: str: 指定消息开头内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_endswith(msg, rule=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息的**文本部分**以指定内容结尾时响应。

• 参数

  • msg: str: 指定消息结尾内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_keyword(keywords, rule=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。

• 参数

  • keywords: Set[str]: 关键词列表

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_command(cmd, rule=None, aliases=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息以指定命令开头时响应。

  命令匹配规则参考: 命令形式匹配

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 指定命令内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • aliases: Optional[Set[Union[str, Tuple[str, ...]]]]: 命令别名

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_shell_command(cmd, rule=None, aliases=None, parser=None, **kwargs)

• 说明

  注册一个支持 shell_like 解析参数的命令消息事件响应器。

  与普通的 on_command 不同的是，在添加 parser 参数时, 响应器会自动处理消息。

  并将用户输入的原始参数列表保存在 state["argv"], parser 处理的参数保存在 state["args"] 中

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 指定命令内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • aliases: Optional[Set[Union[str, Tuple[str, ...]]]]: 命令别名

  • parser: Optional[ArgumentParser]: nonebot.rule.ArgumentParser 对象

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_regex(pattern, flags=0, rule=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息匹配正则表达式时响应。

  命令匹配规则参考: 正则匹配

• 参数

  • pattern: str: 正则表达式

  • flags: Union[int, re.RegexFlag]: 正则匹配标志

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# class CommandGroup

基类：object

命令组，用于声明一组有相同名称前缀的命令。

# __init__(cmd, **kwargs)

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 命令前缀

  • **kwargs: 其他传递给 on_command 的参数默认值，参考 on_command

# basecmd

• 类型: Tuple[str, ...]

• 说明: 命令前缀

# base_kwargs

• 类型: Dict[str, Any]

• 说明: 其他传递给 on_command 的参数默认值

# command(cmd, **kwargs)

• 说明

  注册一个新的命令。

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 命令前缀

  • **kwargs: 其他传递给 on_command 的参数，将会覆盖命令组默认值

• 返回

  • Type[Matcher]

# shell_command(cmd, **kwargs)

• 说明

  注册一个新的命令。

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 命令前缀

  • **kwargs: 其他传递给 on_command 的参数，将会覆盖命令组默认值

• 返回

  • Type[Matcher]

# class MatcherGroup

基类：object

事件响应器组合，统一管理。为 Matcher 创建提供默认属性。

# __init__(**kwargs)

• 说明

  创建一个事件响应器组合，参数为默认值，与 on 一致

# matchers

• 类型

  List[Type[Matcher]]

• 说明

  组内事件响应器列表

# base_kwargs

• 类型: Dict[str, Any]

• 说明: 其他传递给 on 的参数默认值

# on(**kwargs)

• 说明

  注册一个基础事件响应器，可自定义类型。

• 参数

  • type: str: 事件响应器类型

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_metaevent(**kwargs)

• 说明

  注册一个元事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_message(**kwargs)

• 说明

  注册一个消息事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_notice(**kwargs)

• 说明

  注册一个通知事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_request(**kwargs)

• 说明

  注册一个请求事件响应器。

• 参数

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_startswith(msg, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息的**文本部分**以指定内容开头时响应。

• 参数

  • msg: str: 指定消息开头内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_endswith(msg, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息的**文本部分**以指定内容结尾时响应。

• 参数

  • msg: str: 指定消息结尾内容

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_keyword(keywords, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。

• 参数

  • keywords: Set[str]: 关键词列表

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_command(cmd, aliases=None, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息以指定命令开头时响应。

  命令匹配规则参考: 命令形式匹配

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 指定命令内容

  • aliases: Optional[Set[Union[str, Tuple[str, ...]]]]: 命令别名

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_shell_command(cmd, aliases=None, parser=None, **kwargs)

• 说明

  注册一个支持 shell_like 解析参数的命令消息事件响应器。

  与普通的 on_command 不同的是，在添加 parser 参数时, 响应器会自动处理消息。

  并将用户输入的原始参数列表保存在 state["argv"], parser 处理的参数保存在 state["args"] 中

• 参数

  • cmd: Union[str, Tuple[str, ...]]: 指定命令内容

  • aliases: Optional[Set[Union[str, Tuple[str, ...]]]]: 命令别名

  • parser: Optional[ArgumentParser]: nonebot.rule.ArgumentParser 对象

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# on_regex(pattern, flags=0, **kwargs)

• 说明

  注册一个消息事件响应器，并且当消息匹配正则表达式时响应。

  命令匹配规则参考: 正则匹配

• 参数

  • pattern: str: 正则表达式

  • flags: Union[int, re.RegexFlag]: 正则匹配标志

  • rule: Optional[Union[Rule, T_RuleChecker]]: 事件响应规则

  • permission: Optional[Permission]: 事件响应权限

  • handlers: Optional[List[Union[T_Handler, Handler]]]: 事件处理函数列表

  • temp: bool: 是否为临时事件响应器（仅执行一次）

  • priority: int: 事件响应器优先级

  • block: bool: 是否阻止事件向更低优先级传递

  • state: Optional[T_State]: 默认 state

  • state_factory: Optional[T_StateFactory]: 默认 state 的工厂函数

• 返回

  • Type[Matcher]

# load_plugin(module_path)

• 说明

  使用 PluginManager 加载单个插件，可以是本地插件或是通过 pip 安装的插件。

• 参数

  • module_path: str: 插件名称 path.to.your.plugin

• 返回

  • Optional[Plugin]

# load_plugins(*plugin_dir)

• 说明

  导入目录下多个插件，以 _ 开头的插件不会被导入！

• 参数

  • *plugin_dir: str: 插件路径

• 返回

  • Set[Plugin]

# load_all_plugins(module_path, plugin_dir)

• 说明

  导入指定列表中的插件以及指定目录下多个插件，以 _ 开头的插件不会被导入！

• 参数

  • module_path: Set[str]: 指定插件集合

  • plugin_dir: Set[str]: 指定插件路径集合

• 返回

  • Set[Plugin]

# load_from_json(file_path, encoding='utf-8')

• 说明

  导入指定 json 文件中的 plugins 以及 plugin_dirs 下多个插件，以 _ 开头的插件不会被导入！

• 参数

  • file_path: str: 指定 json 文件路径

  • encoding: str: 指定 json 文件编码

• 返回

  • Set[Plugin]

# load_from_toml(file_path, encoding='utf-8')

• 说明

  导入指定 toml 文件 [nonebot.plugins] 中的 plugins 以及 plugin_dirs 下多个插件， 以 _ 开头的插件不会被导入！

• 参数

  • file_path: str: 指定 toml 文件路径

  • encoding: str: 指定 toml 文件编码

• 返回

  • Set[Plugin]

# load_builtin_plugins(name='echo')

• 说明

  导入 NoneBot 内置插件

• 返回

  • Plugin

# get_plugin(name)

• 说明

  获取当前导入的某个插件。

• 参数

  • name: str: 插件名，与 load_plugin 参数一致。如果为 load_plugins 导入的插件，则为文件(夹)名。

• 返回

  • Optional[Plugin]

# get_loaded_plugins()

• 说明

  获取当前已导入的所有插件。

• 返回

  • Set[Plugin]

# require(name)

• 说明

  获取一个插件的导出内容

• 参数

  • name: str: 插件名，与 load_plugin 参数一致。如果为 load_plugins 导入的插件，则为文件(夹)名。

• 返回

  • Optional[Export]

# class Export

基类：dict

• 说明

  插件导出内容以使得其他插件可以获得。

• 示例

nonebot.export().default = "bar"

@nonebot.export()
def some_function():
    pass

# this doesn't work before python 3.9
# use
# export = nonebot.export(); @export.sub
# instead
# See also PEP-614: https://www.python.org/dev/peps/pep-0614/
@nonebot.export().sub
def something_else():
    pass

# export()

• 说明

  获取插件的导出内容对象

• 返回

  • Export