melobot.utils

日志器

日志器可使用内置的 BotLogger，也可以使用标准库或第三方的日志器。

运行时通过 thisbot.logger 获取当前 bot 实例的日志器。

class melobot.utils.BotLogger

melobot 内置日志器类

__init__(name: str, level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO', to_console: bool = True, to_dir: str | None = None, no_tag: bool = False) → None

初始化一个日志器实例

参数:

• name – 日志器的名称（唯一）

• level – 日志等级

• to_console – 是否输出到 console

• to_dir – 保存日志文件的目录，为空则不保存文件

• no_tag – 记录日志时是否不标识日志器名称

setLevel(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']) → None

设置日志等级

日志等级自动应用于包含的所有 handler

参数:

level – 日志等级字面量

exc(prefix: str = '出现异常：', e: BaseException | None = None, locals: dict[str, Any] | None = None) → None

更好的用于记录异常的方法

参数:

• prefix – 记录时的前缀信息

• e – 异常对象

• locals – 需要记录的局部变量，为空则不记录

obj(obj: Any, prefix: str, prefix_fmt: str = '%s：\n', level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'DEBUG') → None

在日志时记录指定的对象

参数:

• obj – 对象

• prefix – 记录时的前缀信息

• prefix_fmt – 前缀信息的格式化字符串

• level – 记录的日志等级，默认为 DEBUG

melobot.utils.logger_patch(logger: Any, log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO') → None

修复任何非 BotLogger 类型的日志器，使其可以被用于 bot 实例初始化

注意

非 BotLogger 类型的日志器，不使用该方法打补丁，无法被用于 bot 实例。但如果不用于 bot 实例，可以不打补丁。

如果日志器的日志等级是可变的，请在更新后再次使用该方法修补

参数:

• logger – 任意日志器对象（支持 debug, info, warning, error, critical 方法即可）

• log_level – 日志器此时可以输出的最小日志等级（”DEBUG” 一端为小，”CRITICAL” 一端为大）

匹配器

匹配器被用于消息事件预处理的文本匹配过程。

相关知识

对于消息事件来说，预处理过程主要分为两步：匹配或解析、检查。

但对于其他事件来说，预处理过程只有一步：检查。

class melobot.utils.StartMatcher

基类：BotMatcher

字符串起始匹配器

__init__(target: str | list[str], mode: LogicMode = LogicMode.OR) → None

初始化一个字符串起始匹配器

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

参数:

• target – 匹配目标

• mode – 匹配模式

class melobot.utils.ContainMatcher

基类：BotMatcher

字符串包含匹配器

__init__(target: str | list[str], mode: LogicMode = LogicMode.OR) → None

初始化一个字符串包含匹配器

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

参数:

• target – 匹配目标

• mode – 匹配模式

class melobot.utils.EndMatcher

基类：BotMatcher

字符串结尾匹配器

__init__(target: str | list[str], mode: LogicMode = LogicMode.OR) → None

初始化一个字符串结尾匹配器

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

参数:

• target – 匹配目标

• mode – 匹配模式

class melobot.utils.FullMatcher

基类：BotMatcher

字符串全匹配器

__init__(target: str | list[str], mode: LogicMode = LogicMode.OR) → None

初始化一个字符串全匹配器

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

参数:

• target – 匹配目标

• mode – 匹配模式

class melobot.utils.RegexMatcher

基类：BotMatcher

字符串正则匹配器

__init__(regex_pattern: str, regex_flags: Any = 0) → None

初始化一个字符串正则匹配器

参数:

• regex_pattern – 正则 pattern

• regex_flags – 正则 flag，默认不使用

检查器

检查器被用于所有事件预处理的事件检查过程。

相关知识

对于消息事件来说，预处理过程主要分为两步：匹配或解析、检查。

但对于其他事件来说，预处理过程只有一步：检查。

class melobot.utils.MsgLvlChecker

基类：BotChecker[MessageEvent]

消息事件分级权限检查器

主要分 主人、超级用户、白名单用户、普通用户、黑名单用户 五级

__init__(level: User, owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → None

初始化一个消息事件分级权限检查器

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• owner – 主人的 qq 号

• super_users – 超级用户 qq 号列表

• white_users – 白名单用户 qq 号列表

• black_users – 黑名单用户 qq 号列表

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

class melobot.utils.GroupMsgLvlChecker

基类：MsgLvlChecker

群聊消息事件分级权限检查器

基本功能与 MsgLvlChecker 一致。但增加了白名单机制， 不提供 white_groups 参数默认拒绝所有群聊消息事件。

对所有私聊消息事件校验不通过。

__init__(level: User, owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, white_groups: list[int] | None = None, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → None

初始化一个群聊消息事件分级权限检查器

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• owner – 主人的 qq 号

• super_users – 超级用户 qq 号列表

• white_users – 白名单用户 qq 号列表

• black_users – 黑名单用户 qq 号列表

• white_groups – 白名单群号列表（不在其中的群不通过校验）

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

class melobot.utils.PrivateMsgLvlChecker

基类：MsgLvlChecker

私聊消息事件分级权限检查器

基本功能与 MsgLvlChecker 一致。

对所有群聊消息事件校验不通过。

__init__(level: User, owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → None

初始化一个私聊消息事件分级权限检查器

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• owner – 主人的 qq 号

• super_users – 超级用户 qq 号列表

• white_users – 白名单用户 qq 号列表

• black_users – 黑名单用户 qq 号列表

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

class melobot.utils.MsgCheckerFactory

消息事件分级权限检查器的工厂

预先存储检查依据（各等级数据），指定检查等级后，可返回一个 MsgLvlChecker 类的对象

__init__(owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, white_groups: list[int] | None = None, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → None

初始化一个消息事件分级权限检查器的工厂

参数:

• owner – 主人的 qq 号

• super_users – 超级用户 qq 号列表

• white_users – 白名单用户 qq 号列表

• black_users – 黑名单用户 qq 号列表

• white_groups – 白名单群号列表（不在其中的群不通过校验）

• ok_cb – 检查通过的回调（这将自动附加到生成的检查器上）

• fail_cb – 检查不通过的回调（这将自动附加到生成的检查器上）

get_base(level: User = User.USER, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → MsgLvlChecker

根据内部依据和给定等级，生成一个 MsgLvlChecker 对象

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

返回:

消息事件分级权限检查器

get_group(level: User = User.USER, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → GroupMsgLvlChecker

根据内部依据和给定等级，生成一个 GroupMsgLvlChecker 对象

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

返回:

群聊消息事件分级权限检查器

get_private(level: User = User.USER, ok_cb: Callable[[], Awaitable[None]] | None = None, fail_cb: Callable[[], Awaitable[None]] | None = None) → PrivateMsgLvlChecker

根据内部依据和给定等级，生成一个 PrivateMsgLvlChecker 对象

参数:

• level – 允许的等级（>= 此等级才能通过校验）

• ok_cb – 检查通过的回调

• fail_cb – 检查不通过的回调

返回:

私聊消息事件分级权限检查器

class melobot.utils.AtMsgChecker

基类：BotChecker[MessageEvent]

艾特消息事件检查器

__init__(qid: int | None = None) → None

初始化一个艾特消息事件检查器

参数:

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

解析器

解析器被用于消息事件预处理的参数解析。

相关知识

对于消息事件来说，预处理过程主要分为两步：匹配或解析、检查。

但对于其他事件来说，预处理过程只有一步：检查。

class melobot.utils.CmdParser

基类：BotParser

命令解析器

通过解析命令名和命令参数的形式，解析字符串。

__init__(cmd_start: str | list[str], cmd_sep: str | list[str], targets: str | list[str], formatters: list[CmdArgFormatter | None] | None = None) → None

初始化一个命令解析器

注意

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

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

参数:

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

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

• targets – 匹配的命令名

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

class melobot.utils.CmdParserFactory

命令解析器的工厂

预先存储命令起始符和命令间隔符，指定匹配的命令名后返回一个命令解析器。

__init__(cmd_start: str | list[str], cmd_sep: str | list[str]) → None

初始化一个命令解析器的工厂

注意

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

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

参数:

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

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

get(targets: str | list[str], formatters: list[CmdArgFormatter | None] | None = None) → CmdParser

生成匹配指定命令名的命令解析器

参数:

• targets – 匹配的命令名

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

class melobot.utils.CmdArgFormatter

命令参数格式化器

用于格式化命令解析器解析出的命令参数。搭配命令解析器 CmdParser 使用

__init__(convert: Callable[[str], Any] | None = None, verify: Callable[[Any], bool] | None = None, src_desc: str | None = None, src_expect: str | None = None, default: Any = Void, default_replace_flag: str | None = None, convert_fail: Callable[[FormatInfo], Awaitable[None]] | None = None, verify_fail: Callable[[FormatInfo], Awaitable[None]] | None = None, arg_lack: Callable[[FormatInfo], Awaitable[None]] | None = None) → None

初始化一个命令参数格式化器

参数:

• convert – 类型转换方法，为空则不进行类型转换

• verify – 值验证方法，为空则不对值进行验证

• src_desc – 命令参数值的功能描述

• src_expect – 命令参数值的值期待描述

• default – 命令参数值的默认值（默认值 Void 表示无值，而不是 None 表达的空值）

• default_replace_flag – 命令参数使用默认值的标志

• convert_fail – 类型转换失败的回调，为空则使用默认回调

• verify_fail – 值验证失败的回调，为空则使用默认回调

• arg_lack – 参数缺失的回调，为空则使用默认回调

class melobot.utils.FormatInfo

命令参数格式化信息对象

用于在命令参数格式化异常时传递信息。

提示

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

src

命令参数格式化前的原值

src_desc

命令参数值的功能描述

src_expect

命令参数值的值期待描述

idx

命令参数值的顺序（从 0 开始索引）

exc

命令参数格式化异常时的异常对象

exc_tb

命令参数格式化异常时的调用栈信息

group_id

命令参数所属命令的命令名