melobot.plugin

插件

实例化 BotPlugin 类即可创建一个插件。插件是 melobot 的重要组件之一。

class melobot.plugin.BotPlugin[源代码]

插件类，使用该类实例化一个插件

__init__(id: str, version: str, desc: str = '', doc: str = '', keywords: list[str] | None = None, url: str = '', multi_use: bool = False) → None[源代码]

初始化一个插件

参数:

  • id – 插件的 id

  • version – 插件的版本

  • desc – 插件功能描述

  • doc – 插件简单的文档说明

  • keywords – 关键词列表

  • url – 插件项目地址

  • multi_use – 是否支持同时被多个 bot 实例加载

ID

本实例属性与初始化参数一一对应

VER

本实例属性与初始化参数一一对应

DESC

本实例属性与初始化参数一一对应

KEYWORDS

本实例属性与初始化参数一一对应

URL

本实例属性与初始化参数一一对应

DOC

本实例属性与初始化参数一一对应

MULTI_USE

本实例属性与初始化参数一一对应

on_event(checker: BotChecker | None | Callable[[BotEvent], bool] = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption | None = None)[源代码]

绑定一个任意事件处理方法

参数:

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_message(matcher: BotMatcher | None = None, parser: BotParser | None = None, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个消息事件处理方法

参数:

  • matcher – 使用的匹配器（和解析器二选一）

  • parser – 使用的解析器（和匹配器二选一）

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_at_qq(qid: int | None = None, matcher: BotMatcher | None = None, parser: BotParser | None = None, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个艾特消息事件处理方法

消息必须是艾特消息，且匹配成功才能被进一步处理。

参数:

  • qid – 被艾特的 qq 号。为空则接受所有艾特消息;不为空则只接受指定 qid 被艾特的艾特消息

  • matcher – 使用的匹配器（和解析器二选一）

  • parser – 使用的解析器（和匹配器二选一）

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_command(cmd_start: str | list[str], cmd_sep: str | list[str], targets: str | list[str], formatters: list[CmdArgFormatter | None] | None = None, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个消息事件处理方法

注意

  • 命令起始符和命令间隔符不允许包含：引号，各种括号，反斜杠，数字，英文，控制字符及各类空白字符。

  • 命令起始符不能是命令间隔符的子序列，反之亦然。

参数:

  • cmd_start – 命令起始符（可以是字符串或字符串列表）

  • cmd_sep – 命令间隔符（可以是字符串或字符串列表）

  • targets – 匹配的命令名

  • formatters – 格式化器列表（列表可以包含空值，即此位置的参数无格式化）

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_start_match(target: str | list[str], logic_mode: LogicMode = LogicMode.OR, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个字符串起始匹配的消息事件处理方法

target 为字符串时，只进行一次起始匹配，即判断是否匹配成功。 target 为字符串列表时，所有字符串都进行起始匹配，再将所有结果使用给定 logic_mode 计算是否匹配成功。

消息必须匹配成功才能被进一步处理。

参数:

  • target – 匹配目标

  • logic_mode – target 为 list[str] 时的计算模式

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_contain_match(target: str | list[str], logic_mode: LogicMode = LogicMode.OR, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个字符串包含匹配的消息事件处理方法

target 为字符串时，只进行一次包含匹配，即判断是否匹配成功。 target 为字符串列表时，所有字符串都进行包含匹配，再将所有结果使用给定 logic_mode 计算是否匹配成功。

消息必须匹配成功才能被进一步处理。

参数:

  • target – 匹配目标

  • logic_mode – target 为 list[str] 时的计算模式

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_full_match(target: str | list[str], logic_mode: LogicMode = LogicMode.OR, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个字符串全匹配的消息事件处理方法

target 为字符串时，只进行一次全匹配，即判断是否匹配成功。 target 为字符串列表时，所有字符串都进行全匹配，再将所有结果使用给定 logic_mode 计算是否匹配成功。

消息必须匹配成功才能被进一步处理。

参数:

  • target – 匹配目标

  • logic_mode – target 为 list[str] 时的计算模式

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_end_match(target: str | list[str], logic_mode: LogicMode = LogicMode.OR, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个字符串结尾匹配的消息事件处理方法

target 为字符串时，只进行一次结尾匹配，即判断是否匹配成功。 target 为字符串列表时，所有字符串都进行结尾匹配，再将所有结果使用给定 logic_mode 计算是否匹配成功。

消息必须匹配成功才能被进一步处理。

参数:

  • target – 匹配目标

  • logic_mode – target 为 list[str] 时的计算模式

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_regex_match(target: str, checker: BotChecker[MessageEvent] | Callable[[MessageEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MessageEvent] | None = None)[源代码]

绑定一个字符串正则匹配的消息事件处理方法

消息必须匹配成功才能被进一步处理。

参数:

  • target – 匹配目标的正则表达式，在匹配时，它应该可以使 re.findall() 不返回空列表

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_request(checker: BotChecker[RequestEvent] | Callable[[RequestEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[RequestEvent] | None = None)[源代码]

绑定一个请求事件处理方法

参数:

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_notice(checker: BotChecker[NoticeEvent] | Callable[[NoticeEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[NoticeEvent] | None = None)[源代码]

绑定一个通知事件处理方法

参数:

  • type – 通知的类型，为 “ALL” 时接受所有通知

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_meta_event(checker: BotChecker[MetaEvent] | Callable[[MetaEvent], bool] | None = None, priority: PriorLevel = PriorLevel.MEAN, block: bool = False, temp: bool = False, option: SessionOption[MetaEvent] | None = None)[源代码]

绑定一个元事件处理方法

参数:

  • checker – 使用的检查器，为空则默认通过检查

  • priority – 优先级

  • block – 是否进行优先级阻断

  • temp – 是否是一次性的

  • option – 会话选项（用于指定会话的工作方式）

on_signal(signal: str, namespace: str | None = None)[源代码]

绑定一个信号处理方法

namespace 为空时，自动设置它为当前插件的 ID

本方法作为异步函数的装饰器使用，此时可绑定一个函数为信号处理方法。

# 假设存在一个名为 plugin 的变量，是 BotPlugin 实例
# 为在命名空间 BaseUtils 中，名为 txt2img 的信号绑定处理方法：
@plugin.on_signal("txt2img", "BaseUtils")
async def get_img_of_txt(text: str, format: Any) -> bytes:
    # melobot 对被装饰函数的参数类型和返回值没有限制
    # 接下来是具体逻辑
    ...
# 在这个示例中，具体的功能是为其他插件提供转换大段文本为图片的能力，因为大段文本不便于发送

注意

在一个 bot 实例的范围内，同命名空间同名称的信号，只能绑定一个处理方法。

参数:

  • namespace – 信号的命名空间

  • signal – 信号的名称

on_share(id: str, namespace: str | None = None, reflector: Callable[[P], Any] | None = None)[源代码]

注册一个共享对象，同时绑定它的值获取方法

namespace 为空时，自动设置它为当前插件的 ID

本方法可作为异步函数的装饰器使用，此时被装饰函数就是共享对象的值获取方法：

# 假设存在一个名为 plugin 的变量，是 BotPlugin 实例
# 在命名空间 HelpUtils 中，注册一个名为 all_helps 的共享对象，且绑定值获取方法：
@plugin.on_share("all_helps", "HelpUtils")
async def get_all_helps() -> str:
    # melobot 对被装饰函数的要求：无参数，但必须有返回值
    return ALL_HELPS_INFO_STR
# 在这个示例中，具体的功能是在插件间共享 “所有插件的帮助文本” 这一数据

当然，值获取方法较为简单时，直接传参即可：

# 最后一个参数不能给定具体的值，必须为一个同步函数
plugin.on_share("all_helps", "HelpUtils", lambda: ALL_HELPS_INFO_STR)

注意

在一个 bot 实例的范围内，同命名空间同名称的共享对象，只能注册一个。

参数:

  • namespace – 共享对象的命名空间

  • id – 共享对象的 id 标识

  • reflector – 本方法当作异步函数的装饰器使用时，本参数为空；直接使用本方法时，参数为共享对象值获取的同步函数

on_share_affected(id: str, namespace: str | None = None)[源代码]

为一个共享对象绑定回调方法

namespace 为空时，自动设置它为当前插件的 ID

本方法作为异步函数的装饰器使用，此时可为一个共享对象绑定回调方法。

# 假设存在一个名为 plugin 的变量，是 BotPlugin 实例
# 为在命名空间 HelpUtils 中，名为 all_helps 的共享对象绑定回调方法：
@plugin.on_share_affected("all_helps", "HelpUtils")
async def add_a_help(text: str) -> bool:
    # melobot 对被装饰函数的参数类型和返回值没有限制
    # 接下来是具体逻辑
    ...
# 此回调用于被其他插件触发，为它们提供“影响”共享对象的能力，
# 在这个示例中，具体的功能是让其他插件可以添加一条自己的帮助信息，但是有所校验

注意

在一个 bot 实例的范围内，同命名空间同名称的共享对象，只能绑定一个回调方法。 而且这个共享对象必须在本插件通过 on_share() 注册（共享对象注册、共享对象回调绑定先后顺序不重要）

参数:

  • namespace – 共享对象的命名空间

  • id – 共享对象的 id 标识

on_bot_life(*types: BotLife)[源代码]

绑定 bot 在某个/某些生命周期的 hook 方法

本方法作为异步函数的装饰器使用，此时可绑定一个函数为 bot 生命周期 hook 方法。

# 假设存在一个名为 plugin 的变量，是 BotPlugin 实例
# 我们希望这个插件，在 bot 连接器建立连接后给某人发一条消息
@plugin.on_bot_life(BotLife.CONNECTED)
async def say_hi() -> None:
    # melobot 对被装饰函数的要求：无参数，返回空值
    await send_custom("Hello~", isPrivate=True, userId=xxxxx)
# 在这个示例中，bot 登录上号后，便会向 xxxxx 发送一条 Hello~ 消息
参数:

types – bot 生命周期类型枚举值，可传入多个

property on_bot_loaded

绑定 bot 在 BotLife.LOADED 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_first_connected

绑定 bot 在 BotLife.FIRST_CONNECTED 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_reconnected

绑定 bot 在 BotLife.RECONNECTED 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_connected

绑定 bot 在 BotLife.FIRST_CONNECTED 和 BotLife.RECONNECTED 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_before_close

绑定 bot 在 BotLife.BEFORE_CLOSE 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_before_stop

绑定 bot 在 BotLife.BEFORE_STOP 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_event_built

绑定 bot 在 BotLife.EVENT_BUILT 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

property on_action_presend

绑定 bot 在 BotLife.ACTION_PRESEND 生命周期的 hook 方法

本方法作为异步函数的装饰器使用。用法与 on_bot_life 类似。

class melobot.plugin.PluginProxy[源代码]

Bot 插件代理类

通过 bot 实例获取插件时，将获取此对象的列表

提示

一般无需手动实例化该类，多数情况会直接使用本类对象，或将本类用作类型注解。

id: str

插件的 id

version: str

插件的版本

desc: str

插件的简短描述

doc: str

插件的长篇描述

keywords: list[str]

插件的关键词

url: str

插件的项目地址

multi_use

是否支持同时被多个 bot 实例加载

shares: list[tuple[str, str]]

插件的共享对象标识：[(命名空间，id), …]

share_cbs: list[tuple[str, str]]

插件的共享对象回调标识：[(命名空间，id), …]

signal_methods: list[tuple[str, str]]

插件的信号处理方法标识：[(命名空间, 信号名), …]