nonebot2/website/versioned_docs/version-2.4.0/api/rule.md

mdx	sidebar_position	description
format md	5	nonebot.rule 模块

nonebot.rule

本模块是 Matcher.rule 的类型定义。

每个事件响应器拥有一个 Rule，其中是 RuleChecker 的集合。 只有当所有 RuleChecker 检查结果为 True 时继续运行。

class Rule(*checkers)

• 说明

  规则类。

  当事件传递时，在 Matcher 运行前进行检查。

• 参数

  • *checkers (T_RuleChecker | Dependent[bool]): RuleChecker

• 用法

  Rule(async_function) & sync_function
  # 等价于
  Rule(async_function, sync_function)
  

instance-var checkers

• 类型: set[Dependent[bool]]

• 说明: 存储 RuleChecker

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

• 说明: 检查是否符合所有规则

• 参数

  • bot (Bot): Bot 对象

  • event (Event): Event 对象

  • state (T_State): 当前 State

  • stack (AsyncExitStack | None): 异步上下文栈

  • dependency_cache (T_DependencyCache | None): 依赖缓存

• 返回

  • bool

class CMD_RESULT(<auto>)

• 参数

  auto

class TRIE_VALUE(<auto>)

• 说明: TRIE_VALUE(command_start, command)

• 参数

  auto

class StartswithRule(msg, ignorecase=False)

• 说明: 检查消息纯文本是否以指定字符串开头。

• 参数

  • msg (tuple[str, ...]): 指定消息开头字符串元组

  • ignorecase (bool): 是否忽略大小写

def startswith(msg, ignorecase=False)

• 说明: 匹配消息纯文本开头。

• 参数

  • msg (str | tuple[str, ...]): 指定消息开头字符串元组

  • ignorecase (bool): 是否忽略大小写

• 返回

  • Rule

class EndswithRule(msg, ignorecase=False)

• 说明: 检查消息纯文本是否以指定字符串结尾。

• 参数

  • msg (tuple[str, ...]): 指定消息结尾字符串元组

  • ignorecase (bool): 是否忽略大小写

def endswith(msg, ignorecase=False)

• 说明: 匹配消息纯文本结尾。

• 参数

  • msg (str | tuple[str, ...]): 指定消息开头字符串元组

  • ignorecase (bool): 是否忽略大小写

• 返回

  • Rule

class FullmatchRule(msg, ignorecase=False)

• 说明: 检查消息纯文本是否与指定字符串全匹配。

• 参数

  • msg (tuple[str, ...]): 指定消息全匹配字符串元组

  • ignorecase (bool): 是否忽略大小写

def fullmatch(msg, ignorecase=False)

• 说明: 完全匹配消息。

• 参数

  • msg (str | tuple[str, ...]): 指定消息全匹配字符串元组

  • ignorecase (bool): 是否忽略大小写

• 返回

  • Rule

class KeywordsRule(*keywords)

• 说明: 检查消息纯文本是否包含指定关键字。

• 参数

  • *keywords (str): 指定关键字元组

def keyword(*keywords)

• 说明: 匹配消息纯文本关键词。

• 参数

  • *keywords (str): 指定关键字元组

• 返回

  • Rule

class CommandRule(cmds, force_whitespace=None)

• 说明: 检查消息是否为指定命令。

• 参数

  • cmds (list[tuple[str, ...]]): 指定命令元组列表

  • force_whitespace (str | bool | None): 是否强制命令后必须有指定空白符

def command(*cmds, force_whitespace=None)

• 说明

  匹配消息命令。

  根据配置里提供的 command_start, command_sep 判断消息是否为命令。

  可以通过 Command 获取匹配成功的命令（例: ("test",)）， 通过 RawCommand 获取匹配成功的原始命令文本（例: "/test"）， 通过 CommandArg 获取匹配成功的命令参数。

• 参数

  • *cmds (str | tuple[str, ...]): 命令文本或命令元组

  • force_whitespace (str | bool | None): 是否强制命令后必须有指定空白符

• 返回

  • Rule

• 用法

  使用默认 command_start, command_sep 配置情况下：

  命令 ("test",) 可以匹配: /test 开头的消息 命令 ("test", "sub") 可以匹配: /test.sub 开头的消息

:::tip 提示 命令内容与后续消息间无需空格! :::

class ArgumentParser(<auto>)

• 说明

  shell_like 命令参数解析器，解析出错时不会退出程序。

  支持 Message 富文本解析。

• 参数

  auto

• 用法

  用法与 argparse.ArgumentParser 相同， 参考文档: argparse

method parse_known_args(args=None, namespace=None)

• 重载

  1. (args=None, namespace=None) -> tuple[Namespace, list[str | MessageSegment]]

  • 参数

    • args (Sequence[str | MessageSegment] | None)

    • namespace (None)

  • 返回

    • tuple[Namespace, list[str | MessageSegment]]

  2. (args, namespace) -> tuple[T, list[str | MessageSegment]]

  • 参数

    • args (Sequence[str | MessageSegment] | None)

    • namespace (T)

  • 返回

    • tuple[T, list[str | MessageSegment]]

  3. (*, namespace) -> tuple[T, list[str | MessageSegment]]

  • 参数

    • namespace (T)

  • 返回

    • tuple[T, list[str | MessageSegment]]

class ShellCommandRule(cmds, parser)

• 说明: 检查消息是否为指定 shell 命令。

• 参数

  • cmds (list[tuple[str, ...]]): 指定命令元组列表

  • parser (ArgumentParser | None): 可选参数解析器

def shell_command(*cmds, parser=None)

• 说明

  匹配 shell_like 形式的消息命令。

  根据配置里提供的 command_start, command_sep 判断消息是否为命令。

  可以通过 Command 获取匹配成功的命令 （例: ("test",)）， 通过 RawCommand 获取匹配成功的原始命令文本 （例: "/test"）， 通过 ShellCommandArgv 获取解析前的参数列表 （例: ["arg", "-h"]）， 通过 ShellCommandArgs 获取解析后的参数字典 （例: {"arg": "arg", "h": True}）。

  :::caution 警告 如果参数解析失败，则通过 ShellCommandArgs 获取的将是 ParserExit 异常。 :::

• 参数

  • *cmds (str | tuple[str, ...]): 命令文本或命令元组

  • parser (ArgumentParser | None): ArgumentParser 对象

• 返回

  • Rule

• 用法

  使用默认 command_start, command_sep 配置，更多示例参考 argparse 标准库文档。

  from nonebot.rule import ArgumentParser
  
  parser = ArgumentParser()
  parser.add_argument("-a", action="store_true")
  
  rule = shell_command("ls", parser=parser)
  

:::tip 提示 命令内容与后续消息间无需空格! :::

class RegexRule(regex, flags=0)

• 说明: 检查消息字符串是否符合指定正则表达式。

• 参数

  • regex (str): 正则表达式

  • flags (int): 正则表达式标记

def regex(regex, flags=0)

• 说明

  匹配符合正则表达式的消息字符串。

  可以通过 RegexStr 获取匹配成功的字符串， 通过 RegexGroup 获取匹配成功的 group 元组， 通过 RegexDict 获取匹配成功的 group 字典。

• 参数

  • regex (str): 正则表达式

  • flags (int | re.RegexFlag): 正则表达式标记

• 返回

  • Rule

:::tip 提示 正则表达式匹配使用 search 而非 match，如需从头匹配请使用 r"^xxx" 来确保匹配开头 ::: :::tip 提示 正则表达式匹配使用 EventMessage 的 str 字符串， 而非 EventMessage 的 PlainText 纯文本字符串 :::

class ToMeRule(<auto>)

• 说明: 检查事件是否与机器人有关。

• 参数

  auto

def to_me()

• 说明: 匹配与机器人有关的事件。

• 参数

  empty

• 返回

  • Rule

class IsTypeRule(*types)

• 说明: 检查事件类型是否为指定类型。

• 参数

  • *types (type[Event])

def is_type(*types)

• 说明: 匹配事件类型。

• 参数

  • *types (type[Event]): 事件类型

• 返回

  • Rule