v11.utils

v11 检查（验证）器

class melobot.protocols.onebot.v11.utils.abc.Checker

基类：BetterABC, Cloneable

检查器基类

abstract async check(event: Event) → bool

检查器检查方法

任何检查器应该实现此抽象方法。

参数:

event (Event) -- 给定的事件

返回:

检查是否通过

返回类型:

bool

static new(func: Callable[[Event], bool]) → Checker

参数:

func (Callable[[Event], bool])

返回类型:

Checker

class melobot.protocols.onebot.v11.utils.abc.WrappedChecker

基类：Checker

合并检查器

在两个 Checker 对象间使用 | & ^ ~ 运算符即可返回合并检查器。

set_fail_cb(fail_cb: AsyncCallable[(), None] | None) → None

参数:

fail_cb (AsyncCallable[(), None] | None)

返回类型:

None

class melobot.protocols.onebot.v11.utils.LevelRole

基类：int, Enum

用户权限等级枚举

OWNER = 16

SU = 8

WHITE = 4

NORMAL = 2

BLACK = 1

class melobot.protocols.onebot.v11.utils.GroupRole

基类：int, Enum

群权限等级枚举

OWNER = 4

ADMIN = 2

MEMBER = 1

class melobot.protocols.onebot.v11.utils.MsgChecker

基类：Checker

消息事件分级权限检查器

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

__init__(role: LevelRole | GroupRole, owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, fail_cb: AsyncCallable[(), None] | None = None) → None

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

参数:

• role (LevelRole | GroupRole) -- 允许的等级（>= 此等级才能通过校验）

• owner (int | None) -- 主人的 qq 号

• super_users (list[int] | None) -- 超级用户 qq 号列表

• white_users (list[int] | None) -- 白名单用户 qq 号列表

• black_users (list[int] | None) -- 黑名单用户 qq 号列表

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回类型:

None

async check(event: Event) → bool

检查器检查方法

任何检查器应该实现此抽象方法。

参数:

event (Event) -- 给定的事件

返回:

检查是否通过

返回类型:

bool

class melobot.protocols.onebot.v11.utils.GroupMsgChecker

基类：MsgChecker

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

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

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

__init__(role: LevelRole | GroupRole, 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, fail_cb: AsyncCallable[(), None] | None = None) → None

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

参数:

• role (LevelRole | GroupRole) -- 允许的等级（>= 此等级才能通过校验）

• owner (int | None) -- 主人的 qq 号

• super_users (list[int] | None) -- 超级用户 qq 号列表

• white_users (list[int] | None) -- 白名单用户 qq 号列表

• black_users (list[int] | None) -- 黑名单用户 qq 号列表

• white_groups (list[int] | None) -- 白名单群号列表（不在其中的群不通过校验）

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回类型:

None

class melobot.protocols.onebot.v11.utils.PrivateMsgChecker

基类：MsgChecker

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

基本功能与 MsgChecker 一致。

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

__init__(role: LevelRole, owner: int | None = None, super_users: list[int] | None = None, white_users: list[int] | None = None, black_users: list[int] | None = None, fail_cb: AsyncCallable[(), None] | None = None) → None

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

参数:

• role (LevelRole) -- 允许的等级（>= 此等级才能通过校验）

• owner (int | None) -- 主人的 qq 号

• super_users (list[int] | None) -- 超级用户 qq 号列表

• white_users (list[int] | None) -- 白名单用户 qq 号列表

• black_users (list[int] | None) -- 黑名单用户 qq 号列表

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回类型:

None

class melobot.protocols.onebot.v11.utils.MsgCheckerFactory

基类：object

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

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

__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, fail_cb: AsyncCallable[(), None] | None = None) → None

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

参数:

• owner (int | None) -- 主人的 qq 号

• super_users (list[int] | None) -- 超级用户 qq 号列表

• white_users (list[int] | None) -- 白名单用户 qq 号列表

• black_users (list[int] | None) -- 黑名单用户 qq 号列表

• white_groups (list[int] | None) -- 白名单群号列表（不在其中的群不通过校验）

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调（这将自动附加到生成的检查器上）

返回类型:

None

get_base(role: LevelRole | GroupRole, fail_cb: AsyncCallable[(), None] | None = None) → MsgChecker

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

参数:

• role (LevelRole | GroupRole) -- 允许的等级（>= 此等级才能通过校验）

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回:

消息事件分级权限检查器

返回类型:

MsgChecker

get_group(role: LevelRole | GroupRole, fail_cb: AsyncCallable[(), None] | None = None) → GroupMsgChecker

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

参数:

• role (LevelRole | GroupRole) -- 允许的等级（>= 此等级才能通过校验）

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回:

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

返回类型:

GroupMsgChecker

get_private(role: LevelRole, fail_cb: AsyncCallable[(), None] | None = None) → PrivateMsgChecker

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

参数:

• role (LevelRole) -- 允许的等级（>= 此等级才能通过校验）

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回:

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

返回类型:

PrivateMsgChecker

class melobot.protocols.onebot.v11.utils.AtMsgChecker

基类：Checker

艾特消息事件检查器

__init__(qid: int | Literal['all'] | None = None, fail_cb: AsyncCallable[(), None] | None = None) → None

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

参数:

• qid (int | Literal['all'] | None) -- 被艾特的 qq 号。为空则接受所有艾特消息事件；不为空则只接受指定 qid 被艾特的艾特消息事件

• fail_cb (AsyncCallable[(), None] | None) -- 检查不通过的回调

返回类型:

None

async check(event: Event) → bool

检查器检查方法

任何检查器应该实现此抽象方法。

参数:

event (Event) -- 给定的事件

返回:

检查是否通过

返回类型:

bool

v11 匹配器

class melobot.protocols.onebot.v11.utils.abc.Matcher

基类：BetterABC, Cloneable

匹配器基类

abstract async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

class melobot.protocols.onebot.v11.utils.abc.WrappedMatcher

基类：Matcher

合并匹配器

在两个 Matcher 对象间使用 | & ^ ~ 运算符即可返回合并匹配器

class melobot.protocols.onebot.v11.utils.StartMatcher

基类：Matcher

字符串起始匹配器

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

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

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

参数:

• target (str | list[str]) -- 匹配目标

• mode (LogicMode) -- 匹配模式

返回类型:

None

async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

class melobot.protocols.onebot.v11.utils.ContainMatcher

基类：Matcher

字符串包含匹配器

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

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

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

参数:

• target (str | list[str]) -- 匹配目标

• mode (LogicMode) -- 匹配模式

返回类型:

None

async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

class melobot.protocols.onebot.v11.utils.EndMatcher

基类：Matcher

字符串结尾匹配器

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

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

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

参数:

• target (str | list[str]) -- 匹配目标

• mode (LogicMode) -- 匹配模式

返回类型:

None

async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

class melobot.protocols.onebot.v11.utils.FullMatcher

基类：Matcher

字符串全匹配器

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

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

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

参数:

• target (str | list[str]) -- 匹配目标

• mode (LogicMode) -- 匹配模式

返回类型:

None

async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

class melobot.protocols.onebot.v11.utils.RegexMatcher

基类：Matcher

字符串正则匹配器

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

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

参数:

• regex_pattern (str) -- 正则 pattern

• regex_flags (Any) -- 正则 flag，默认不使用

返回类型:

None

async match(text: str) → bool

匹配器匹配方法

任何匹配器应该实现此抽象方法。

参数:

text (str) -- 消息事件的文本内容

返回:

是否匹配

返回类型:

bool

v11 解析器

class melobot.protocols.onebot.v11.utils.abc.Parser

基类：BetterABC

解析器基类

解析器一般用作从消息文本中按规则批量提取参数

abstract async parse(text: str) → ParseArgs | None

解析方法

任何解析器应该实现此抽象方法

参数:

text (str) -- 消息文本内容

返回:

解析结果

返回类型:

ParseArgs | None

class melobot.protocols.onebot.v11.utils.abc.ParseArgs

基类：object

解析参数

name: str

vals: list[Any]

class melobot.protocols.onebot.v11.utils.CmdParser

基类：Parser

命令解析器

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

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

初始化一个命令解析器

注意

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

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

参数:

• cmd_start (str | list[str]) -- 命令起始符（可以是字符串或字符串列表）

• cmd_sep (str | list[str]) -- 命令间隔符（可以是字符串或字符串列表）

• targets (str | list[str]) -- 匹配的命令名

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

• fmtters (list[CmdArgFormatter | None] | None)

返回类型:

None

async parse(text: str) → ParseArgs | None

解析方法

任何解析器应该实现此抽象方法

参数:

text (str) -- 消息文本内容

返回:

解析结果

返回类型:

ParseArgs | None

class melobot.protocols.onebot.v11.utils.CmdArgFormatter

基类：object

命令参数格式化器

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

__init__(convert: ~typing.Callable[[str], ~typing_extensions.Any] | None = None, validate: ~typing.Callable[[~typing_extensions.Any], bool] | None = None, src_desc: str | None = None, src_expect: str | None = None, default: ~typing_extensions.Any = VoidType.VOID, default_replace_flag: str | None = None, convert_fail: ~melobot.typ.AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None = None, validate_fail: ~melobot.typ.AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None = None, arg_lack: ~melobot.typ.AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None = None) → None

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

参数:

• convert (Callable[[str], Any] | None) -- 类型转换方法，为空则不进行类型转换

• validate (Callable[[Any], bool] | None) -- 值验证方法，为空则不对值进行验证

• src_desc (str | None) -- 命令参数值的功能描述

• src_expect (str | None) -- 命令参数值的值期待描述

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

• default_replace_flag (str | None) -- 命令参数使用默认值的标志

• convert_fail (AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None) -- 类型转换失败的回调，为空则使用默认回调

• validate_fail (AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None) -- 值验证失败的回调，为空则使用默认回调

• arg_lack (AsyncCallable[(<class 'melobot.protocols.onebot.v11.utils.parse.FormatInfo'>,), None] | None) -- 参数缺失的回调，为空则执行默认规则

返回类型:

None

async format(group_id: str, args: ParseArgs, idx: int) → bool

参数:

• group_id (str)

• args (ParseArgs)

• idx (int)

返回类型:

bool

class melobot.protocols.onebot.v11.utils.FormatInfo

基类：object

命令参数格式化信息对象

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

name: str

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

src: str | VoidType

命令参数格式化前的原值，参数缺失时是 VoidType.VOID

src_desc: str | None

命令参数值的功能描述

src_expect: str | None

命令参数值的值期待描述

idx: int

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

exc: Exception

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

exc_tb: TracebackType | None

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

class melobot.protocols.onebot.v11.utils.CmdParserFactory

基类：object

命令解析器的工厂

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

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

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

注意

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

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

参数:

• cmd_start (str | list[str]) -- 命令起始符（可以是字符串或字符串列表）

• cmd_sep (str | list[str]) -- 命令间隔符（可以是字符串或字符串列表）

返回类型:

None

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

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

参数:

• targets (str | list[str]) -- 匹配的命令名

• formatters (list[CmdArgFormatter | None] | None) -- 格式化器列表（列表可以包含空值，即此位置的参数无格式化选项）

返回类型:

CmdParser