ProjectHentai/nonebot2
6
0
Fork 0
mirror of https://github.com/nonebot/nonebot2.git synced 2024-11-28 08:12:14 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
ad8a998a8c
nonebot2/docs/api.md
yanyongyu ad8a998a8c bump version to 1.6.0 and update docs
2020-04-24 15:54:52 +08:00

66 KiB
Raw Blame History

sidebar
auto

API

类型

下面的 API 文档中，「类型」部分使用 Python 的 Type Hint 语法，见 PEP 484、PEP 526 和 typing。

除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。

以下类型均可从 nonebot.typing 模块导入。

Context_T

  • 类型: Dict[str, Any]

  • 说明:

    CQHTTP 上报的事件数据对象的类型。

Message_T

  • 类型: Union[str, Dict[str, Any], List[Dict[str, Any]]]

  • 说明:

    消息对象的类型，通常表示 NoneBot 提供的消息相关接口所支持的类型，nonebot.message.Message 也是一个合法的 Message_T。

Expression_T

  • 类型: Union[str, Sequence[str], Callable]

  • 说明:

    Expression 对象的类型。

CommandName_T

  • 类型: Tuple[str]

  • 说明:

    命令名称的类型。

CommandArgs_T

  • 类型: Dict[str, Any]

  • 说明:

    命令参数的类型。

CommandHandler_T

  • 类型: Callable[[CommandSession], Any]

  • 说明:

    命令处理函数

State_T

  • 类型: Dict[str, Any]

  • 说明:

    命令会话的状态（state 属性）的类型。

Filter_T

  • 类型: Callable[[Any], Union[Any, Awaitable[Any]]]

  • 说明:

    过滤器的类型。

    例如：

    async def validate(value):
    if value > 100:
        raise ValidateError('数值必须小于 100')
    return value

配置

API_ROOT

  • 类型: str

  • 默认值: ''

  • 说明:

    CQHTTP 插件的 HTTP 接口地址，如果不使用 HTTP 通信，则无需设置。

  • 用法:

    API_ROOT = 'http://127.0.0.1:5700'

    告诉 NoneBot CQHTTP 插件的 HTTP 服务运行在 http://127.0.0.1:5700。

ACCESS_TOKEN

  • 类型: str

  • 默认值: ''

  • 说明:

    需要和 CQHTTP 插件的配置中的 access_token 相同。

SECRET

  • 类型: str

  • 默认值: ''

  • 说明:

    需要和 CQHTTP 插件的配置中的 secret 相同。

HOST

  • 类型: str

  • 默认值: '127.0.0.1'

  • 说明:

    NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP／主机名。

  • 用法:

    HOST = '0.0.0.0'

    监听服务器的所有 IP。

PORT

  • 类型: int

  • 默认值: 8080

  • 说明:

    NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。

  • 用法:

    PORT = 9876

    监听 9876 端口。

DEBUG

  • 类型: bool

  • 默认值: True

  • 说明:

    是否以调试模式运行，生产环境需要设置为 False 以提高性能。

  • 用法:

    DEBUG = False

    不使用调试模式运行。

SUPERUSERS

  • 类型: Container[int]

  • 默认值: set()

  • 说明:

    超级用户的 QQ 号，用于命令的权限检查。

  • 用法:

    SUPERUSERS = {12345678, 87654321}

    设置 12345678 和 87654321 为超级用户。

NICKNAME

  • 类型: Union[str, Iterable[str]]

  • 默认值: ''

  • 说明:

    机器人的昵称，用于辨别用户是否在和机器人说话（目前仅用于自然语言处理器，命令仍需 @）。

  • 用法:

    NICKNAME = {'奶茶', '小奶茶'}

    用户可以通过「奶茶」或「小奶茶」来呼唤机器人。

COMMAND_START

  • 类型: Iterable[Union[str, Pattern]]

  • 默认值: {'/', '!', '／', '！'}

  • 说明:

    命令的起始标记，用于判断一条消息是不是命令。

  • 用法:

    COMMAND_START = {'', '/', '!'}

    允许使用 /、! 作为命令起始符，或不用发送起始符。

COMMAND_SEP

  • 类型: Iterable[Union[str, Pattern]]

  • 默认值: {'/', '.'}

  • 说明:

    命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。

  • 用法:

    COMMAND_SEP = {'.'}

    将 note.add 这样的命令解析为 ('note', 'add')。

SESSION_EXPIRE_TIMEOUT

  • 类型: Optional[datetime.timedelta]

  • 默认值: datetime.timedelta(minutes=5)

  • 说明:

    命令会话的过期超时时长，超时后会话将被移除。None 表示不超时。

  • 用法:

    from datetime import timedelta
SESSION_EXPIRE_TIMEOUT = timedelta(minutes=2)

    设置过期超时为 2 分钟，即用户 2 分钟不发消息后，会话将被关闭。

SESSION_RUN_TIMEOUT

  • 类型: Optional[datetime.timedelta]

  • 默认值: None

  • 说明:

    命令会话的运行超时时长，超时后会话将被移除，命令处理函数会被异常所中断。此时用户可以调用新的命令，开启新的会话。None 表示不超时。

  • 用法:

    from datetime import timedelta
SESSION_RUN_TIMEOUT = timedelta(seconds=10)

    设置运行超时为 10 秒，即命令会话运行达到 10 秒，NoneBot 将认为它已经结束。

SESSION_RUNNING_EXPRESSION

  • 类型: Expression_T

  • 默认值: '您有命令正在执行，请稍后再试'

  • 说明:

    当有命令会话正在运行时，给用户新消息的回复。

  • 用法:

    SESSION_RUNNING_EXPRESSION = ''

    设置为空，表示当有命令会话正在运行时，不回复用户的新消息。

SHORT_MESSAGE_MAX_LENGTH

  • 类型: int

  • 默认值: 50

  • 说明:

    短消息的最大长度。默认情况下（only_short_message 为 True），自然语言处理器只会响应消息中纯文本部分的长度总和小于等于此值的消息。

  • 用法:

    SHORT_MESSAGE_MAX_LENGTH = 100

    设置最大长度为 100。

DEFAULT_VALIDATION_FAILURE_EXPRESSION

  • 类型: Expression_T

  • 默认值: '您的输入不符合要求，请重新输入'

  • 说明:

    命令参数验证失败（验证器抛出 ValidateError 异常）、且验证器没有指定错误信息时，默认向用户发送的错误提示。

  • 用法:

    DEFAULT_VALIDATION_FAILURE_EXPRESSION = '你发送的内容格式不太对呢，请检查一下再发送哦～'

    设置更亲切的默认错误提示。

MAX_VALIDATION_FAILURES

  • 类型: int

  • 默认值: 3

  • 说明:

    命令参数验证允许的最大失败次数，用户输入错误达到这个次数之后，将会提示用户输入错误太多次，并结束命令会话。

    设置为 0 将不会检查验证失败次数。

TOO_MANY_VALIDATION_FAILURES_EXPRESSION

  • 类型: Expression_T

  • 默认值: '您输入错误太多次啦，如需重试，请重新触发本功能'

  • 说明:

    命令参数验证失败达到 MAX_VALIDATION_FAILURES 次之后，向用户发送的提示。

  • 用法:

    TOO_MANY_VALIDATION_FAILURES_EXPRESSION = (
    '你输错太多次啦，需要的时候再叫我吧',
    '你输错太多次了，建议先看看使用帮助哦～',
)

SESSION_CANCEL_EXPRESSION

  • 类型: Expression_T

  • 默认值: '好的'

  • 说明:

    nonebot.command.argfilter.controllers.handle_cancellation() 控制器在用户发送了 算了、取消 等取消指令后，结束当前命令会话时，向用户发送的提示。

  • 用法:

    SESSION_CANCEL_EXPRESSION = (
    '好的',
    '好的吧',
    '好吧，那奶茶就不打扰啦',
    '那奶茶先不打扰小主人啦',
)

APSCHEDULER_CONFIG

  • 类型: Dict[str, Any]

  • 默认值: {'apscheduler.timezone': 'Asia/Shanghai'}

  • 说明:

    APScheduler 的配置对象，见 Configuring the scheduler。

nonebot 模块

快捷导入

为方便使用，nonebot 模块从子模块导入了部分内容：

  • CQHttpError -> nonebot.exceptions.CQHttpError
  • load_plugin -> nonebot.plugin.load_plugin
  • load_plugins -> nonebot.plugin.load_plugins
  • load_builtin_plugins -> nonebot.plugin.load_builtin_plugins
  • get_loaded_plugins -> nonebot.plugin.get_loaded_plugins
  • on_command -> nonebot.plugin.on_command
  • on_natural_language -> nonebot.plugin.on_natural_language
  • on_notice -> nonebot.plugin.on_notice
  • on_request -> nonebot.plugin.on_request
  • message_preprocessor -> nonebot.message.message_preprocessor
  • Message -> nonebot.message.Message
  • MessageSegment -> nonebot.message.MessageSegment
  • CommandSession -> nonebot.command.CommandSession
  • CommandGroup -> nonebot.command.CommandGroup
  • NLPSession -> nonebot.natural_language.NLPSession
  • NLPResult -> nonebot.natural_language.NLPResult
  • NoticeSession -> nonebot.notice_request.NoticeSession
  • RequestSession -> nonebot.notice_request.RequestSession
  • context_id -> nonebot.helpers.context_id

scheduler

  • 类型: Scheduler

  • 说明:

    全局的计划任务对象，只有当 Python 环境中安装了 APScheduler 时才有效，否则为 None。

class NoneBot

继承自 aiocqhttp.CQHttp。

config

  • 类型: Any

  • 说明:

    配置对象。

asgi

  • 类型: Quart

  • 说明:

    ASGI 对象，继承自 aiocqhttp.CQHttp，目前等价于 server_app。

server_app

  • 类型: Quart

  • 说明:

    内部的 Quart 对象，继承自 aiocqhttp.CQHttp。

__init__(config_object=None)

  • 说明:

    初始化 NoneBot 对象。配置对象会被保存到 config 属性，并且被传入父类的初始化函数。

    不建议手动创建 NoneBot 对象，而应该使用全局的 init() 函数。

  • 参数:

    • config_object: Optional[Any]: 配置对象，类型不限，只要能够通过 __getattr__ 和 __dict__ 分别访问到单个和所有配置项即可，若没有传入，则使用默认配置

__getattr__(item)

  • 说明:

    获取用于 API 调用的 Callable 对象。

    对返回结果进行函数调用会调用 CQHTTP 的相应 API，请注意捕获 CQHttpError 异常，具体请参考 aiocqhttp 的 API 调用。

  • 参数:

    • item: str: 要调用的 API 动作名，请参考 CQHTTP 插件文档的 API 列表

  • 返回:

    • Callable: 用于 API 调用的 Callable 对象

  • 用法:

    bot = nonebot.get_bot()
try:
    info = await bot.get_group_member_info(group_id=1234567, user_id=12345678)
except CQHttpError as e:
    logger.exception(e)

run(host=None, port=None, *args, **kwargs)

  • 说明:

    运行 NoneBot。

    不建议直接运行 NoneBot 对象，而应该使用全局的 run() 函数。

  • 参数:

    • host: Optional[str]: 主机名／IP
    • port: Optional[int]: 端口
    • *args: Any: 其它传入 CQHttp.run() 的位置参数
    • **kwargs: Any: 其它传入 CQHttp.run() 的命名参数

decorator on_message(*events)

  • 说明:

    将函数装饰为消息事件的处理函数，继承自 aiocqhttp.CQHttp。

    监听所有消息事件时，可以不加括号。

  • 参数:

    • *events: str: 消息事件名，例如 private、group、private.friend，不传入表示监听所有消息事件

  • 用法:

    bot = nonebot.get_bot()

@bot.on_message('group')
async def handle_group_message(event: aiocqhttp.Event)
    pass

    注册群消息事件处理函数。

decorator on_notice(*events)

  • 说明:

    将函数装饰为通知事件的处理函数，继承自 aiocqhttp.CQHttp。

    监听所有通知事件时，可以不加括号。

  • 参数:

    • *events: str: 消息事件名，例如 group_increase、group_decrease.leave、friend_add，不传入表示监听所有通知事件

  • 用法:

    bot = nonebot.get_bot()

@bot.on_notice('group_increase')
async def handle_group_increase(event: aiocqhttp.Event)
    pass

    注册群成员增加事件处理函数。

decorator on_request(*events)

  • 说明:

    将函数装饰为请求事件的处理函数，继承自 aiocqhttp.CQHttp。

    监听所有请求事件时，可以不加括号。

  • 参数:

    • *events: str: 消息事件名，例如 friend、group、group.add，不传入表示监听所有请求事件

  • 用法:

    bot = nonebot.get_bot()

@bot.on_request('friend', 'group.invite')
async def handle_request(event: aiocqhttp.Event)
    pass

    注册加好友和邀请入群请求事件处理函数。

decorator on_meta_event(*events)

  • 说明:

    将函数装饰为元事件的处理函数，继承自 aiocqhttp.CQHttp。

    监听所有元事件时，可以不加括号。

  • 参数:

    • *events: str: 消息事件名，例如 heartbeat，不传入表示监听所有元事件

  • 用法:

    bot = nonebot.get_bot()

@bot.on_meta_event('heartbeat')
async def handle_heartbeat(event: aiocqhttp.Event)
    pass

    注册心跳元事件处理函数。

init(config_object=None)

  • 说明:

    初始化全局 NoneBot 对象。

  • 参数:

    • config_object: Optional[Any]: 配置对象，类型不限，只要能够通过 __getattr__ 和 __dict__ 分别访问到单个和所有配置项即可，若没有传入，则使用默认配置

  • 返回:

    • None

  • 用法:

    import config
nonebot.init(config)

    导入 config 模块并初始化全局 NoneBot 对象。

get_bot()

  • 说明:

    获取全局 NoneBot 对象。可用于在计划任务的回调中获取当前 NoneBot 对象。

  • 返回:

    • NoneBot: 全局 NoneBot 对象

  • 异常:

    • ValueError: 全局 NoneBot 对象尚未初始化

  • 用法:

    bot = nonebot.get_bot()

run(host=None, port=None, *args, **kwargs)

  • 说明:

    运行全局 NoneBot 对象。

  • 参数:

    • host: Optional[str]: 主机名／IP，若不传入则使用配置文件中指定的值
    • port: Optional[int]: 端口，若不传入则使用配置文件中指定的值
    • *args: Any: 其它传入 CQHttp.run() 的位置参数
    • **kwargs: Any: 其它传入 CQHttp.run() 的命名参数

  • 返回:

    • None

  • 用法:

    nonebot.run(host='127.0.0.1', port=8080)

    在 127.0.0.1:8080 运行全局 NoneBot 对象。

decorator on_startup

  • 说明:

    将函数装饰为 NoneBot 启动时的回调函数。

  • 用法:

    @on_startup
async def startup()
    await db.init()

    注册启动时回调，初始化数据库。

decorator on_websocket_connect

  • 说明:

    将函数装饰为 CQHTTP 反向 WebSocket 连接建立时的回调函数。

    该装饰器等价于 @bot.on_meta_event('lifecycle.connect')，只在 CQHTTP v4.14+ 有用。

  • 用法:

    @on_websocket_connect
async def connect(event: aiocqhttp.Event):
    bot = nonebot.get_bot()
    groups = await bot.get_group_list()

    注册 WebSocket 连接时回调，获取群列表。

nonebot.exceptions 模块

class CQHttpError

等价于 aiocqhttp.Error。

nonebot.plugin 模块

class Plugin

用于包装已加载的插件模块的类。

module

  • 类型: ModuleType

  • 说明:

    已加载的插件模块（importlib 导入的 Python 模块）。

name

  • 类型: Optional[str]

  • 说明:

    插件名称，从插件模块的 __plugin_name__ 特殊变量获得，如果没有此变量，则为 None。

usage

  • 类型: Optional[Any]

  • 说明:

    插件使用方法，从插件模块的 __plugin_usage__ 特殊变量获得，如果没有此变量，则为 None。

commands

  • 类型: Set[Command]

  • 说明:

    插件包含的命令，通过 on_command 装饰器注册。

nl_processors

  • 类型: Set[NLProcessor]

  • 说明:

    插件包含的自然语言处理器，通过 on_natural_language 装饰器注册。

event_handlers

  • 类型: Set[EventHandler]

  • 说明:

    插件包含的事件处理器（包含通知、请求），通过 on_notice 以及 on_request 装饰器注册。

class PluginManager

插件管理器：用于管理插件的加载以及插件中命令、自然语言处理器、事件处理器的开关

cmd_manager

  • 类型: CommandManager

  • 说明:

    命令管理器实例

nlp_manager

  • 类型: NLPManager

  • 说明:

    自然语言管理器实例

class method add_plugin(cls, module_path, plugin)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method get_plugin(cls, module_path)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method remove_plugin(cls, module_path)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method switch_plugin_global(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method switch_command_global(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method switch_nlprocessor_global(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

class method switch_eventhandler_global(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

switch_plugin(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

switch_command(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

switch_nlprocessor(cls, module_path, state=None)

  • 说明:

  • 参数:

  • 返回:

  • 用法:

load_plugin(module_name)

  • 说明:

    加载插件（等价于导入模块）。

  • 参数:

    • module_path: str: 模块路径

  • 返回:

    • Optional[Plugin]: 加载后生成的 Plugin 对象

  • 用法:

    nonebot.plugin.load_plugin('nonebot_tuling')

    加载 nonebot_tuling 插件。

reload_plugin(module_name)

  • 说明:

    :::danger 该函数为强制重载，可能导致不可预测的错误！ :::

    重载插件（等价于）。

  • 参数:

    • module_path: str: 模块路径

  • 返回:

    • Optional[Plugin]: 重载后生成的 Plugin 对象

  • 用法:

    nonebot.plugin.reload_plugin('nonebot_tuling')

    重载 nonebot_tuling 插件。

load_plugins(plugin_dir, module_prefix)

  • 说明:

    查找指定路径（相对或绝对）中的非隐藏模块（隐藏模块名字以 _ 开头）并通过指定的模块前缀导入。

  • 参数:

    • plugin_dir: str: 插件目录
    • module_prefix: str: 模块前缀

  • 返回:

    • Set[Plugin]: 加载成功的插件 Plugin 对象

  • 用法:

    nonebot.plugin.load_plugins(path.join(path.dirname(__file__), 'plugins'), 'plugins')

    加载 plugins 目录下的插件。

load_builtin_plugins()

  • 说明:

    加载内置插件。

  • 返回:

    • int: 加载成功的插件数量

  • 用法:

    nonebot.plugin.load_builtin_plugins()

get_loaded_plugins()

  • 说明:

    获取已经加载的插件集合。

  • 返回:

    • Set[Plugin]: 已加载的插件集合

  • 用法:

    plugins = nonebot.plugin.get_loaded_plugins()
await session.send('我现在支持以下功能：\n\n' +
                   '\n'.join(map(lambda p: p.name, filter(lambda p: p.name, plugins))))

decorator on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False, shell_like=False)

  • 说明:

    将函数装饰为命令处理器。

    被装饰的函数将会获得一个 args_parser 属性，是一个装饰器，下面会有详细说明。

  • 参数:

    • name: Union[str, CommandName_T]: 命令名，如果传入的是字符串则会自动转为元组
    • aliases: Union[Iterable[str], str]: 命令别名
    • permission: int: 命令所需要的权限，不满足权限的用户将无法触发该命令
    • only_to_me: bool: 是否只响应确定是在和「我」（机器人）说话的命令（在开头或结尾 @ 了机器人，或在开头称呼了机器人昵称）
    • privileged: bool: 是否特权命令，若是，则无论当前是否有命令会话正在运行，都会运行该命令，但运行不会覆盖已有会话，也不会保留新创建的会话
    • shell_like: bool: 是否使用类 shell 语法，若是，则会自动使用 shlex 模块进行分割（无需手动编写参数解析器），分割后的参数列表放入 session.args['argv']

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 CommandSession，即形如：

    async def func(session: CommandSession):
    pass

  • 用法:

    @on_command('echo', aliases=('复读',))
async def _(session: CommandSession):
    await session.send(session.current_arg)

    一个简单的复读命令。

decorator on_natural_language(keywords=None, *, permission=EVERYBODY, only_to_me=True, only_short_message=True, allow_empty_message=False)

  • 说明:

    将函数装饰为自然语言处理器。

  • 参数:

    • keywords: Optional[Union[Iterable, str]]: 要响应的关键词，若传入 None，则响应所有消息
    • permission: int: 自然语言处理器所需要的权限，不满足权限的用户将无法触发该处理器
    • only_to_me: bool: 是否只响应确定是在和「我」（机器人）说话的消息（在开头或结尾 @ 了机器人，或在开头称呼了机器人昵称）
    • only_short_message: bool: 是否只响应短消息
    • allow_empty_message: bool: 是否响应内容为空的消息（只有 @ 或机器人昵称）

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 NLPSession，即形如：

    async def func(session: NLPSession):
    pass

  • 用法:

    @on_natural_language({'天气'}, only_to_me=False)
async def _(session: NLPSession):
    return NLPResult(100.0, ('weather',), None)

    响应所有带有「天气」关键词的消息，当做 weather 命令处理。

decorator on_notice(*events)

  • 说明:

    将函数装饰为通知处理器。

  • 参数:

    • *events: str: 要处理的通知类型（notice_type），若不传入，则处理所有通知

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 NoticeSession，即形如：

    async def func(session: NoticeSession):
    pass

  • 用法:

    @on_notice
async def _(session: NoticeSession):
    logger.info('有新的通知事件：%s', session.event)

@on_notice('group_increase')
async def _(session: NoticeSession):
    await session.send('欢迎新朋友～')

    收到所有通知时打日志，收到新成员进群通知时除了打日志还发送欢迎信息。

decorator on_request(*events)

  • 说明:

    将函数装饰为请求处理器。

  • 参数:

    • *events: str: 要处理的请求类型（request_type），若不传入，则处理所有请求

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 RequestSession，即形如：

    async def func(session: RequestSession):
    pass

  • 用法:

    @on_request
async def _(session: RequestSession):
    logger.info('有新的请求事件：%s', session.event)

@on_request('group')
async def _(session: RequestSession):
    await session.approve()

    收到所有请求时打日志，收到群请求时除了打日志还同意请求。

nonebot.message 模块

decorator message_preprocessor

  • 说明:

    将函数装饰为消息预处理器。

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收两个位置参数，类型分别为 NoneBot 和 aiocqhttp.Event，即形如：

    async def func(bot: NoneBot, event: aiocqhttp.Event):
    pass

  • 用法:

    @message_preprocessor
async def _(bot: NoneBot, event: aiocqhttp.Event):
    event['preprocessed'] = True

    在所有消息处理之前，向消息事件对象中加入 preprocessed 字段。

class MessageSegment

从 aiocqhttp.message 模块导入，继承自 dict，用于表示一个消息段。该类型是合法的 Message_T。

更多关于消息段的内容，见 消息格式。

type

  • 类型: str

  • 说明:

    消息段类型。

data

  • 类型: Dict[str, Any]

  • 说明:

    消息段数据。

__init__(d=None, *, type_=None, data=None)

  • 说明:

    初始化消息段对象。

  • 参数:

    • d: Dict[str, Any]: 当有此参数且此参数中有 type 字段时，由此参数构造消息段
    • type_: str: 当没有传入 d 参数或 d 参数无法识别时，此参数必填，对应消息段的 type 字段
    • data: Dict[str, str]: 对应消息段的 data 字段，若不传入则初始化为 {}

  • 异常:

    • ValueError: 没有正确传入 type 参数

  • 用法:

    seg1 = MessageSegment({'type': 'face', 'data': {'id': '123'}})
seg2 = MessageSegment(type_='face', data={'id': '123'})

__str__()

  • 说明:

    将消息段转换成字符串格式。

  • 返回:

    • str: 字符串格式的消息段

  • 用法:

    str(MessageSegment.face(123))

__eq__(other)

  • 说明:

    判断两个消息段是否相同。

  • 参数:

    • other: Any: 要比较的对象

  • 返回:

    • bool: 两个消息段相同

  • 用法:

    MessageSegment.face(123) == MessageSegment(type='face', data={'id': '123'})

staticmethod text(text)

  • 说明:

    构造纯文本消息段。

  • 参数:

    • text: str: 文本内容

  • 返回:

    • MessageSegment: 消息段对象

staticmethod emoji(id_)

  • 说明:

    构造 emoji 消息段。

  • 参数:

    • id_: int: Emoji ID（Unicode 代码点）

  • 返回:

    • MessageSegment: 消息段对象

staticmethod face(id_)

  • 说明:

    构造 QQ 表情消息段。

  • 参数:

    • id_: int: QQ 表情 ID

  • 返回:

    • MessageSegment: 消息段对象

staticmethod image(file)

  • 说明:

    构造图片消息段。

  • 参数:

    • file: str: 图片文件名、路径、URL、或 Base64 编码

  • 返回:

    • MessageSegment: 消息段对象

staticmethod record(file, magic=False)

  • 说明:

    构造语音消息段。

  • 参数:

    • file: str: 语音文件名、路径、URL、或 Base64 编码
    • magic: bool: 是否使用变声

  • 返回:

    • MessageSegment: 消息段对象

staticmethod at(user_id)

  • 说明:

    构造 @ 消息段。

  • 参数:

    • user_id: int: 要 @ 用户 QQ 号

  • 返回:

    • MessageSegment: 消息段对象

staticmethod rps()

  • 说明:

    构造猜拳消息段。

  • 返回:

    • MessageSegment: 消息段对象

staticmethod dice()

  • 说明:

    构造掷骰子消息段。

  • 返回:

    • MessageSegment: 消息段对象

staticmethod shake()

  • 说明:

    构造窗口抖动消息段。

  • 返回:

    • MessageSegment: 消息段对象

staticmethod anonymous(ignore_failure=False)

  • 说明:

    构造匿名消息段。

  • 参数:

    • ignore_failure: bool: 是否忽略匿名失败，如果忽略，则匿名失败时仍使用真实身份发送消息

  • 返回:

    • MessageSegment: 消息段对象

staticmethod share(url, title, content='', image_url='')

  • 说明:

    构造链接分享消息段。

  • 参数:

    • url: str: 链接 URL
    • title: str: 卡片标题
    • content: str: 卡片内容
    • image_url: str: 图片 URL

  • 返回:

    • MessageSegment: 消息段对象

staticmethod contact_user(id_)

  • 说明:

    构造好友分享消息段。

  • 参数:

    • id_: int: 好友 QQ 号

  • 返回:

    • MessageSegment: 消息段对象

staticmethod contact_group(id_)

  • 说明:

    构造群组分享消息段。

  • 参数:

    • id_: int: 群号

  • 返回:

    • MessageSegment: 消息段对象

staticmethod location(latitude, longitude, title='', content='')

  • 说明:

    构造位置分享消息段。

  • 参数:

    • latitude: float: 纬度
    • longitude: float: 经度
    • title: str: 卡片标题
    • content: str: 卡片内容

  • 返回:

    • MessageSegment: 消息段对象

staticmethod music(type_, id_)

  • 说明:

    构造音乐分享消息段。

  • 参数:

    • type_: str: 分享类型
    • id_: int: 音乐 ID

  • 返回:

    • MessageSegment: 消息段对象

staticmethod music_custom(url, audio_url, title, content='', image_url='')

  • 说明:

    构造自定义音乐分享消息段。

  • 参数:

    • url: str: 链接 URL
    • audio_url: str: 音频 URL
    • title: str: 卡片标题
    • content: str: 卡片内容
    • image_url: str: 图片 URL

  • 返回:

    • MessageSegment: 消息段对象

class Message

从 aiocqhttp.message 模块导入，继承自 list，用于表示一个消息。该类型是合法的 Message_T。

__init__(msg=None)

  • 说明:

    初始化消息对象。

  • 参数:

    • msg: Optional[Message_T]: 消息内容，若不传入则构造空消息

  • 异常:

    • ValueError: msg 参数不是一个合法的 Message_T

  • 用法:

    msg = Message('你好')

__str__()

  • 说明:

    将消息转换成字符串格式。

  • 返回:

    • str: 字符串格式的消息

  • 用法:

    str(event.message)

__add__(other)

  • 说明:

    将两个消息对象拼接。

  • 参数:

    • other: Message_T: 任何符合 Message_T 类型的对象

  • 返回:

    • Message: 两个消息拼接的结果

  • 异常:

    • ValueError: other 参数不是一个合法的 Message_T

  • 用法:

    msg = Message('你好') + '，世界！'

append(obj)

  • 说明:

    将一个消息段拼接到当前消息的尾部。

  • 参数:

    • obj: Any: MessageSegment 对象，或任何可以传入 MessageSegment 构造函数的对象

  • 返回:

    • None

  • 异常:

    • ValueError: obj 参数不是一个能够被识别的消息段

  • 用法:

    msg = Message('你好')
msg.append(MessageSegment.face(14))

extend(msg)

  • 说明:

    将一个消息拼接到当前消息的尾部。

  • 参数:

    • msg: Any: 字符串，或任何元素能够传入 append() 的 Iterable

  • 返回:

    • None

  • 异常:

    • ValueError: msg 参数不是一个能够被识别的消息

  • 用法:

    msg = Message('你好')
msg.extend('[CQ:face,id=14]')

extract_plain_text(reduce=False)

  • 说明:

    从消息中提取类型为 text 的消息段，使用空格拼接。

  • 参数:

    • reduce: bool: 是否先化简消息段列表（合并相邻的 text 段），对于从 酷 Q 收到的消息，通常不需要开启

  • 返回:

    • str: 消息文本字符串

  • 用法:

    text = session.event.message.extract_plain_text()

    提取事件上报的原始消息中的纯文本部分。

escape(s, *, escape_comma=True)

  • 说明:

    从 aiocqhttp.message 模块导入，对字符串进行转义。

  • 参数:

    • s: str: 要转义的字符串
    • escape_comma: bool: 是否转义英文逗号 ,

  • 返回:

    • str: 转义后的字符串

unescape(s)

  • 说明:

    从 aiocqhttp.message 模块导入，对字符串进行去转义。

  • 参数:

    • s: str: 要去转义的字符串

  • 返回:

    • str: 去转义后的字符串

nonebot.command 模块

decorator on_command(name, *, aliases=(), permission=perm.EVERYBODY, only_to_me=True, privileged=False, shell_like=False)

  • 说明:

    将函数装饰为命令处理器。

    被装饰的函数将会获得一个 args_parser 属性，是一个装饰器，下面会有详细说明。

  • 参数:

    • name: Union[str, CommandName_T]: 命令名，如果传入的是字符串则会自动转为元组
    • aliases: Union[Iterable[str], str]: 命令别名
    • permission: int: 命令所需要的权限，不满足权限的用户将无法触发该命令
    • only_to_me: bool: 是否只响应确定是在和「我」（机器人）说话的命令（在开头或结尾 @ 了机器人，或在开头称呼了机器人昵称）
    • privileged: bool: 是否特权命令，若是，则无论当前是否有命令会话正在运行，都会运行该命令，但运行不会覆盖已有会话，也不会保留新创建的会话
    • shell_like: bool: 是否使用类 shell 语法，若是，则会自动使用 shlex 模块进行分割（无需手动编写参数解析器），分割后的参数列表放入 session.args['argv']

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 CommandSession，即形如：

    async def func(session: CommandSession):
    pass

  • 用法:

    @on_command('echo', aliases=('复读',))
async def _(session: CommandSession):
    await session.send(session.current_arg)

    一个简单的复读命令。

decorator command_func.args_parser

  • 说明:

    将函数装饰为命令层面的参数解析器，将在命令实际处理函数之前被运行。

    如果已经在 on_command 装饰器中使用了 shell_like=True，则无需手动使用编写参数解析器。

    如果使用 CommandSession#get() 方法获取参数，并且传入了 arg_filters（相当于单个参数层面的参数解析器），则不会再运行此装饰器注册的命令层面的参数解析器；相反，如果没有传入 arg_filters，则会运行。

  • 要求:

    对被装饰函数的要求同 on_command 装饰器。

  • 用法:

    @my_cmd.args_parser
async def _(session: CommandSession):
    stripped_text = session.current_arg_text.strip()
    if not session.current_key and stripped_text:
        session.current_key = 'initial_arg'
    session.state[session.current_key] = stripped_text  # 若使用 1.1.0 及以下版本，请使用 session.args

    一个典型的命令参数解析器。

class CommandGroup

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

basename

  • 类型: CommandName_T

  • 说明:

    命令名前缀。

permission

  • 类型: Optional[int]

  • 说明:

    命令组内命令的默认 permission 属性。

only_to_me

  • 类型: Optional[bool]

  • 说明:

    命令组内命令的默认 only_to_me 属性。

privileged

  • 类型: Optional[bool]

  • 说明:

    命令组内命令的默认 privileged 属性。

shell_like

  • 类型: Optional[bool]

  • 说明:

    命令组内命令的默认 shell_like 属性。

__init__(name, permission=None, *, only_to_me=None, privileged=None, shell_like=None)

  • 说明:

    初始化命令组，参数即为上面的三个属性。

  • 参数:

    • name: Union[str, CommandName_T]: 命令名前缀，若传入字符串，则会自动转换成元组
    • permission: Optional[int]: 对应 permission 属性
    • only_to_me: Optional[bool]: 对应 only_to_me 属性
    • privileged: Optional[bool]: 对应 privileged 属性
    • shell_like: Optional[bool]: 对应 shell_like 属性

decorator command(name, *, aliases=None, permission=None, only_to_me=None, privileged=None, shell_like=None)

  • 说明:

    将函数装饰为命令组中的命令处理器。使用方法和 on_command 装饰器完全相同。

  • 参数:

    • name: Union[str, CommandName_T]: 命令名，注册命令处理器时会加上命令组的前缀
    • aliases: Optional[Iterable[str]]: 和 on_command 装饰器含义相同，若不传入则使用命令组默认值，若命令组没有默认值，则使用 on_command 装饰器的默认值
    • permission: Optional[int]: 同上
    • only_to_me: Optional[bool]: 同上
    • privileged: Optional[bool]: 同上
    • shell_like: Optional[bool]: 同上

  • 用法:

    sched = CommandGroup('scheduler')

@sched.command('add', permission=PRIVATE)
async def _(session: CommandSession)
    pass

    注册 ('scheduler', 'add') 命令。

class CommandSession

继承自 BaseSession 类，表示命令 Session。

readonly property state

  • 类型: State_T

  • 说明:

    命令会话的状态数据（包括已获得的所有参数）。

    属性本身只读，但属性中的内容可读写。

  • 用法:

    if not session.state.get('initialized'):
    # ... 初始化工作
    session.state['initialized'] = True

    在命令处理函数的开头进行每次命令调用只应该执行一次的初始化操作。

readonly property args

  • 类型: CommandArgs_T

  • 说明:

    命令会话已获得的所有参数。

readonly property is_first_run

  • 类型: bool

  • 说明:

    命令会话是否第一次运行。

current_key

  • 类型: Optional[str]

  • 说明:

    命令会话当前正在询问用户的参数的键（或称参数的名字）。第一次运行会话时，该属性为 None。

current_arg

  • 类型: str

  • 说明:

    命令会话当前参数。实际上是 酷 Q 收到的消息去掉命令名的剩下部分，因此可能存在 CQ 码。

readonly property current_arg_text

  • 类型: str

  • 说明:

    current_arg 属性的纯文本部分（不包含 CQ 码），各部分使用空格连接。

readonly property current_arg_images

  • 类型: List[str]

  • 说明:

    current_arg 属性中所有图片的 URL 的列表，如果参数中没有图片，则为 []。

readonly property argv

  • 类型: List[str]

  • 说明:

    命令参数列表，类似于 sys.argv，本质上是 session.state.get('argv', [])，需要搭配 on_command(..., shell_like=True) 使用。

  • 用法:

    @on_command('some_cmd', shell_like=True)
async def _(session: CommandSession):
    argv = session.argv

get(key, *, prompt=None, arg_filters=None, **kwargs)

  • 说明:

    从 state 属性获取参数，如果参数不存在，则暂停当前会话，向用户发送提示，并等待用户的新一轮交互。

    如果需要暂停当前会话，则命令处理器中，此函数调用之后的语句将不会被执行（除非捕获了此函数抛出的特殊异常）。

    注意，一旦传入 arg_filters 参数（参数过滤器），则等用户再次输入时，command_func.args_parser 所注册的参数解析函数将不会被运行，而会在对 current_arg 依次运行过滤器之后直接将其放入 state 属性中。

  • 参数:

    • key: Any: 参数的键
    • prompt: Optional[Message_T]: 提示的消息内容
    • arg_filters: Optional[List[Filter_T]] : 用于处理和验证用户输入的参数的过滤器
    • **kwargs: Any: 其它传入 BaseSession.send() 的命名参数

  • 返回:

    • Any: 参数的值

  • 用法:

    location = session.get('location', prompt='请输入要查询的地区')

    获取位置信息，如果当前还不知道，则询问用户。

    from nonebot.command.argfilter import extractors, validators

time = session.get(
    'time', prompt='你需要我在什么时间提醒你呢？',
    arg_filters=[
        extractors.extract_text,  # 取纯文本部分
        controllers.handle_cancellation(session),  # 处理用户可能的取消指令
        str.strip,  # 去掉两边空白字符
        # 正则匹配输入格式
        validators.match_regex(r'^\d{4}-\d{2}-\d{2}$', '格式不对啦，请重新输入')
    ]
)

    获取时间信息，如果当前还不知道，则询问用户，等待用户输入之后，会依次运行 arg_filters 参数中的过滤器，以确保参数内容和格式符合要求。

get_optional(key, default=None)

  • 说明:

    从 args 属性获取参数，如果参数不存在，则返回默认值。等价于 args.get(key, default)。

  • 参数:

    • key: Any: 参数的键
    • default: Optional[Any]: 默认值

  • 返回:

    • Any: 参数的值，或 default 参数给出的默认值

  • 用法:

    time = session.get_optional('time')

    获取可选的时间参数。

pause(message=None, **kwargs)

  • 说明:

    暂停当前命令会话，并发送消息。此函数调用之后的语句将不会被执行（除非捕获了此函数抛出的特殊异常）。

  • 参数:

    • message: Optional[Message_T]: 要发送的消息，若不传入则不发送
    • **kwargs: Any: 其它传入 BaseSession.send() 的命名参数

  • 用法:

    session.pause('请继续发送要处理的图片，发送 done 结束')

    需要连续接收用户输入，并且过程中不需要改变 current_key 时，使用此函数暂停会话。

finish(message=None, **kwargs)

  • 说明:

    结束当前命令会话，并发送消息。此函数调用之后的语句将不会被执行（除非捕获了此函数抛出的特殊异常）。

    调用此函数后，命令将被视为已经完成，当前命令会话将被移除。

  • 参数:

    • message: Optional[Message_T]: 要发送的消息，若不传入则不发送
    • **kwargs: Any: 其它传入 BaseSession.send() 的命名参数

  • 用法:

    session.finish('感谢您的使用～')

switch(new_message)

  • 说明:

    结束当前会话，改变当前消息事件中的消息内容，然后重新处理消息事件。

    此函数可用于从一个命令中跳出，将用户输入的剩余部分作为新的消息来处理，例如可实现以下对话：

    用户：帮我查下天气
Bot：你要查询哪里的天气呢？
用户：算了，帮我查下今天下午南京到上海的火车票吧
Bot：今天下午南京到上海的火车票有如下班次：blahblahblah

    这里进行到第三行时，命令期待的是一个地点，但实际发现消息的开头是「算了」，于是调用 switch('帮我查下今天下午南京到上海的火车票吧')，结束天气命令，将剩下来的内容作为新的消息来处理（触发火车票插件的自然语言处理器，进而调用火车票查询命令）。

  • 参数:

    • new_message: Message_T: 要覆盖消息事件的新消息内容

  • 用法:

    @my_cmd.args_parser
async def _(session: CommandSession)
    if not session.is_first_run and session.current_arg.startswith('算了，'):
        session.switch(session.current_arg[len('算了，'):])

    使用「算了」来取消当前命令，转而进入新的消息处理流程。这个例子比较简单，实际应用中可以使用更复杂的 NLP 技术来判断。

coroutine call_command(bot, event, name, *, current_arg='', args=None, check_perm=True, disable_interaction=False)

  • 说明:

    从内部直接调用命令。可用于在一个插件中直接调用另一个插件的命令。

  • 参数:

    • bot: NoneBot: NoneBot 对象
    • event: aiocqhttp.Event: 事件对象
    • name: Union[str, CommandName_T]: 要调用的命令名
    • current_arg: str: 命令会话的当前输入参数
    • args: Optional[CommandArgs_T]: 命令会话的（初始）参数（将会被并入命令会话的 state 属性）
    • check_perm: bool: 是否检查命令的权限，若否，则即使当前事件上下文并没有权限调用这里指定的命令，也仍然会调用成功
    • disable_interaction: bool: 是否禁用交互功能，若是，则该命令的会话不会覆盖任何当前已存在的命令会话，新创建的会话也不会保留

  • 返回:

    • bool: 命令是否调用成功

  • 用法:

    await call_command(bot, event, 'say', current_arg='[CQ:face,id=14]', check_perm=False)

    从内部调用 say 命令，且不检查权限。

kill_current_session(event)

  • 说明:

    强行移除当前已存在的任何命令会话，即使它正在运行。该函数可用于强制移除执行时间超过预期的命令，以保证新的消息不会被拒绝服务。

  • 参数:

    • event: aiocqhttp.Event: 事件对象

  • 返回:

    • None

  • 用法:

    @on_command('kill', privileged=True)
async def _(session: CommandSession):
    kill_current_session(session.event)

    在特权命令 kill 中强行移除当前正在运行的会话。

nonebot.command.argfilter 模块

本模块主要用于命令参数过滤相关的功能。

命令参数过滤器主要有下面几种：

  • 提取器，从用户输入的原始参数内容中提取需要的内容，extractors 子模块中提供了一些常用提取器
  • 修剪器，将用户输入的原始参数内容进行适当修建，例如 str.strip 可以去掉两遍的空白字符
  • 验证器，验证参数的格式、长度等是否符合要求，validators 子模块中提供了一些常用验证器
  • 转换器，将参数进行类型或格式上的转换，例如 int 可以将字符串转换成整数，converters 子模块中提供了一些常用转换器
  • 控制器，根据用户输入或当前会话状态对会话进行相关控制，例如当用户发送 算了 时停止当前会话，controllers 子模块中提供了一些常用控制器

class ValidateError

用于表示验证失败的异常类。

message

  • 类型: Optional[Message_T]

  • 说明:

    验证失败时要发送的错误提示消息。如果为 None，则使用配置中的 DEFAULT_VALIDATION_FAILURE_EXPRESSION。

nonebot.command.argfilter.extractors 模块

提供几种常用的提取器。

extract_text

  • 说明:

    提取消息中的纯文本部分（使用空格合并纯文本消息段）。

  • 输入类型: Message_T

  • 输出类型: str

extract_image_urls

  • 说明:

    提取消息中的图片 URL 列表。

  • 输入类型: Message_T

  • 输出类型: List[str]

extract_numbers

  • 说明:

    提取消息中的所有数字（浮点数）。

  • 输入类型: Message_T

  • 输出类型: List[float]

nonebot.command.argfilter.validators 模块

提供几种常用的验证器。

这些验证器的工厂函数全都接受可选参数 message: Optional[Message_T]，用于在验证失败时向用户发送错误提示。使用这些的验证器时，必须先调用验证器的工厂函数，其返回结果才是真正的验证器，例如：

session.get('arg1', prompt='请输入 arg1：',
            arg_filters=[extract_text， not_empty('输入不能为空')])

注意 extract_text 和 not_empty 使用上的区别。

not_empty(message=None)

  • 说明:

    验证输入不为空。

  • 输入类型: Any

  • 输出类型: Any

fit_size(min_length=0, max_length=None, message=None)

  • 说明:

    验证输入的长度（大小）在 min_length 到 max_length 之间（包括两者）。

  • 参数:

    • min_length: int: 最小长度
    • max_length: Optional[int]: 最大长度

  • 输入类型: Sized

  • 输出类型: Sized

match_regex(pattern, message=None, *, flags=0, fullmatch=False)

  • 说明:

    验证输入是否匹配正则表达式。

  • 参数:

    • pattern: str: 正则表达式
    • flags: 传入 re.compile() 的标志
    • fullmatch: bool: 是否使用完全匹配（re.fullmatch()）

  • 输入类型: str

  • 输出类型: str

ensure_true(bool_func, message=None)

  • 说明:

    验证输入是否能使给定布尔函数返回 True。

  • 参数:

    • bool_func: Callable[[Any], bool]: 接受输入、返回布尔值的函数

  • 输入类型: Any

  • 输出类型: Any

between_inclusive(start=None, end=None, message=None)

  • 说明:

    验证输入是否在 start 到 end 之间（包括两者）。

  • 参数:

    • start: 范围开始
    • end: 范围结束

  • 输入类型: Comparable

  • 输出类型: Comparable

nonebot.command.argfilter.converters 模块

提供几种常用的转换器。

simple_chinese_to_bool

  • 说明:

    将中文（好、不行 等）转换成布尔值。

  • 输入类型: str

  • 输出类型: Optional[bool]

split_nonempty_lines

  • 说明:

    按行切割文本，并忽略所有空行。

  • 输入类型: str

  • 输出类型: List[str]

split_nonempty_stripped_lines

  • 说明:

    按行切割文本，并对每一行进行 str.strip，再忽略所有空行。

  • 输入类型: str

  • 输出类型: List[str]

nonebot.command.argfilter.controllers 模块

提供几种常用的控制器。

这些验证器通常需要提供一些参数进行一次调用，返回的结果才是真正的验证器，其中的技巧在于通过闭包使要控制的对象能够被内部函数访问。

handle_cancellation(session)

  • 说明:

    在用户发送 算了、不用了、取消吧、停 之类的话的时候，结束当前传入的命令会话（调用 session.finish()），并发送配置项 SESSION_CANCEL_EXPRESSION 所填的内容。

    如果不是上述取消指令，则将输入原样输出。

  • 参数:

    • session: CommandSession: 要控制的命令会话

  • 输入类型: Any

  • 输出类型: Any

nonebot.natural_language 模块

decorator on_natural_language(keywords=None, *, permission=EVERYBODY, only_to_me=True, only_short_message=True, allow_empty_message=False)

  • 说明:

    将函数装饰为自然语言处理器。

  • 参数:

    • keywords: Optional[Union[Iterable, str]]: 要响应的关键词，若传入 None，则响应所有消息
    • permission: int: 自然语言处理器所需要的权限，不满足权限的用户将无法触发该处理器
    • only_to_me: bool: 是否只响应确定是在和「我」（机器人）说话的消息（在开头或结尾 @ 了机器人，或在开头称呼了机器人昵称）
    • only_short_message: bool: 是否只响应短消息
    • allow_empty_message: bool: 是否响应内容为空的消息（只有 @ 或机器人昵称）

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 NLPSession，即形如：

    async def func(session: NLPSession):
    pass

  • 用法:

    @on_natural_language({'天气'}, only_to_me=False)
async def _(session: NLPSession):
    return NLPResult(100.0, ('weather',), None)

    响应所有带有「天气」关键词的消息，当做 weather 命令处理。

class NLPSession

继承自 BaseSession 类，表示自然语言处理 Session。

msg

  • 类型: str

  • 说明:

    以字符串形式表示的消息内容，已去除开头的 @ 和机器人称呼，可能存在 CQ 码。

msg_text

  • 类型: str

  • 说明:

    消息内容的纯文本部分，已去除所有 CQ 码／非 text 类型的消息段。各纯文本消息段之间使用空格连接。

msg_images

  • 类型: List[str]

  • 说明:

    消息内容中所有图片的 URL 的列表，如果消息中没有图片，则为 []。

class IntentCommand

用于表示自然语言处理之后得到的意图命令，是一个 namedtuple，由自然语言处理器返回。

confidence

  • 类型: float

  • 说明:

    意图的置信度，即表示对当前推测的用户意图有多大把握。

name

  • 类型: Union[str, CommandName_T]

  • 说明:

    命令的名字。

args

  • 类型: Optional[CommandArgs_T]

  • 说明:

    命令的（初始）参数。

current_arg

  • 类型: Optional[str]

  • 说明:

    命令的当前输入参数。

__init__(confidence, name, args=None, current_arg=None)

  • 说明:

    初始化 IntentCommand 对象，参数即为上面的几个属性。

class NLPResult

用于表示自然语言处理的结果，是一个 namedtuple，由自然语言处理器返回。

confidence

  • 类型: float

  • 说明:

    自然语言处理结果的置信度，即消息意图确实符合此 NLPResult 的概率。

cmd_name

  • 类型: Union[str, CommandName_T]

  • 说明:

    消息所对应的命令的名称。

cmd_args

  • 类型: Optional[CommandArgs_T]

  • 说明:

    消息所对应的命令的参数。

__init__(confidence, cmd_name, cmd_args=None)

  • 说明:

    初始化 NLPResult 对象，参数即为上面的三个属性。

nonebot.notice_request 模块

decorator on_notice(*events)

  • 说明:

    将函数装饰为通知处理器。

  • 参数:

    • *events: str: 要处理的通知类型（notice_type），若不传入，则处理所有通知

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 NoticeSession，即形如：

    async def func(session: NoticeSession):
    pass

  • 用法:

    @on_notice
async def _(session: NoticeSession):
    logger.info('有新的通知事件：%s', session.event)

@on_notice('group_increase')
async def _(session: NoticeSession):
    await session.send('欢迎新朋友～')

    收到所有通知时打日志，收到新成员进群通知时除了打日志还发送欢迎信息。

decorator on_request(*events)

  • 说明:

    将函数装饰为请求处理器。

  • 参数:

    • *events: str: 要处理的请求类型（request_type），若不传入，则处理所有请求

  • 要求:

    被装饰函数必须是一个 async 函数，且必须接收且仅接收一个位置参数，类型为 RequestSession，即形如：

    async def func(session: RequestSession):
    pass

  • 用法:

    @on_request
async def _(session: RequestSession):
    logger.info('有新的请求事件：%s', session.event)

@on_request('group')
async def _(session: RequestSession):
    await session.approve()

    收到所有请求时打日志，收到群请求时除了打日志还同意请求。

class NoticeSession

继承自 BaseSession 类，表示通知类事件的 Session。

class RequestSession

继承自 BaseSession 类，表示请求类事件的 Session。

coroutine approve(remark='')

  • 说明:

    同意当前请求。

  • 参数:

    • remark: str: 好友备注，只在好友请求时有效

  • 返回:

    • None

  • 异常:

    • CQHttpError: 发送失败时抛出，实际由 aiocqhttp 抛出，等价于 aiocqhttp.Error

  • 用法:

    await session.approve()

coroutine reject(reason='')

  • 说明:

    拒绝当前请求。

  • 参数:

    • reason: str: 拒绝理由，只在群请求时有效

  • 返回:

    • None

  • 异常:

    • CQHttpError: 发送失败时抛出，实际由 aiocqhttp 抛出，等价于 aiocqhttp.Error

  • 用法:

    await session.reject()

nonebot.session 模块

class BaseSession

基础 session 类，CommandSession 等均继承自此类。

bot

  • 类型: NoneBot

  • 说明:

    Session 对应的 NoneBot 对象。

  • 用法:

    await session.bot.send('hello')

    在当前 Session 对应的上下文中发送 hello。

event

  • 类型: aiocqhttp.Event

  • 说明:

    CQHTTP 上报的事件数据对象，具体请参考 aiocqhttp.Event 和 事件上报。

  • 用法:

    user_id = session.event['user_id']
group_id = session.event.group_id

    获取当前事件的 user_id 和 group_id 字段。

ctx

  • 类型: aiocqhttp.Event

  • 说明:

    CQHTTP 上报的事件数据对象，或称事件上下文，具体请参考 事件上报。

  • 用法:

    user_id = session.ctx['user_id']

    获取当前事件的 user_id 字段。

readonly property self_id

  • 类型: int

  • 说明:

    当前 session 对应的 QQ 机器人账号，在多个机器人账号使用同一个 NoneBot 后端时可用于区分当前收到消息或事件的是哪一个机器人。

    等价于 session.event.self_id。

  • 用法:

    await bot.send_private_msg(self_id=session.self_id, user_id=12345678, message='Hello')

coroutine send(message, *, at_sender=False, ensure_private=False, ignore_failure=True, **kwargs)

  • 说明:

    发送消息到 Session 对应的上下文中。

  • 参数:

    • message: Message_T: 要发送的消息内容
    • at_sender: bool: 是否 @ 发送者，对私聊不起作用
    • ensure_private: bool: 确保消息发送到私聊，对于群组和讨论组消息上下文，会私聊发送者
    • ignore_failure: bool: 发送失败时忽略 CQHttpError 异常
    • **kwargs: Any: 其它传入 CQHttp.send() 的命名参数

  • 返回:

    • Any : 返回 CQHTTP 插件发送消息接口的调用返回值，具体见 aiocqhttp 的 API 调用

  • 异常:

    • CQHttpError: 发送失败时抛出，实际由 aiocqhttp 抛出，等价于 aiocqhttp.Error

  • 用法:

    await session.send('hello')

    在当前 Session 对应的上下文中发送 hello。

nonebot.permission 模块

权限声明常量

  • PRIVATE_FRIEND: 好友私聊
  • PRIVATE_GROUP: 群临时私聊
  • PRIVATE_DISCUSS: 讨论组临时私聊
  • PRIVATE_OTHER: 其它私聊
  • PRIVATE: 任何私聊
  • DISCUSS: 讨论组
  • GROUP_MEMBER: 群成员
  • GROUP_ADMIN: 群管理员
  • GROUP_OWNER: 群主
  • GROUP: 任何群成员
  • SUPERUSER: 超级用户
  • EVERYBODY: 任何人

用于权限声明的常量可通过 | 合并，在命令或自然语言处理器装饰器的 permission 参数中传入，表示允许触发相应命令或自然语言处理器的用户类型。

例如下面的代码中，只有私聊和群管理员可以访问 hello 命令：

@nonebot.on_command('hello', permission=PRIVATE | GROUP_ADMIN)
async def _(session):
    pass

需要注意的是，当一个用户是「群管理员」时，ta 同时也是「群成员」；当 ta 是「群主」时，ta 同时也是「群管理员」和「群成员」。

coroutine check_permission(bot, event, permission_required)

  • 说明:

    检查用户是否具有所要求的权限。

  • 参数:

    • bot: NoneBot: NoneBot 对象
    • event: aiocqhttp.Event: 消息事件对象
    • permission_required: int: 要求的权限值

  • 返回:

    • bool: 消息事件所对应的上下文是否具有所要求的权限

  • 用法:

    has_perm = await check_permission(bot, event, cmd.permission)

nonebot.log 模块

logger

  • 类型: logging.Logger

  • 说明:

    NoneBot 全局的 logger。

  • 用法:

    logger.debug('Some log message here')

nonebot.helpers 模块

context_id(event, *, mode='default', use_hash=False)

  • 说明:

    获取事件对应的上下文的唯一 ID。

  • 参数:

    • event: aiocqhttp.Event: 事件对象
    • mode: str: ID 的计算模式
      • 'default': 默认模式，任何一个上下文都有其唯一 ID
      • 'group': 群组模式，同一个群组或讨论组的上下文（即使是不同用户）具有相同 ID
      • 'user': 用户模式，同一个用户的上下文（即使在不同群组）具有相同 ID
    • use_hash: bool: 是否将计算出的 ID 使用 MD5 进行哈希

  • 返回:

    • str: 事件对应的上下文的唯一 ID

  • 用法:

    ctx_id = context_id(session.event, use_hash=True)

    获取当前 Session 的事件对应的上下文的唯一 ID，并进行 MD5 哈希，得到的结果可用于图灵机器人等 API 的调用。

coroutine send(bot, event, message, *, ensure_private=False, ignore_failure=True, **kwargs)

  • 说明:

    发送消息到指定事件的上下文中。

  • 参数:

    • bot: NoneBot: NoneBot 对象
    • event: aiocqhttp.Event: 事件对象
    • message: Message_T: 要发送的消息内容
    • ensure_private: bool: 确保消息发送到私聊，对于群组和讨论组消息上下文，会私聊发送者
    • ignore_failure: bool: 发送失败时忽略 CQHttpError 异常
    • **kwargs: Any: 其它传入 CQHttp.send() 的命名参数

  • 返回:

    • Any : 返回 CQHTTP 插件发送消息接口的调用返回值，具体见 aiocqhttp 的 API 调用

  • 异常:

    • CQHttpError: 发送失败时抛出，实际由 aiocqhttp 抛出，等价于 aiocqhttp.Error

  • 用法:

    await send(bot, event, 'hello')

render_expression(expr, *args, escape_args=True, **kwargs)

  • 说明:

    渲染 Expression。

  • 参数:

    • expr: Expression_T: 要渲染的 Expression，对于 Expression 的三种类型：str、Sequence[str]、Callable，行为分别是：
      • str：以 *args、**kwargs 为参数，使用 str.format() 进行格式化
      • Sequence[str]：随机选择其中之一，进行上面 str 的操作
      • Callable：以 *args、**kwargs 为参数，调用该可调用对象/函数，对返回的字符串进行上面 str 的操作
    • escape_args: bool: 是否对渲染参数进行转义
    • *args: Any: 渲染参数
    • **kwargs: Any: 渲染参数

  • 返回:

    • str: 渲染出的消息字符串

  • 用法:

    msg1 = render_expression(
    ['你好，{username}！', '欢迎，{username}～'],
    username=username
)
msg2 = render_expression('你所查询的城市是{}', city)

nonebot.argparse 模块

class ArgumentParser

继承自 argparse.ArgumentParser 类，修改部分函数实现使其适用于命令型聊天机器人。

此类可用于命令参数的解析。基本用法和 Python 内置的 argparse.ArgumentParser 类一致，下面主要列出与 Python 原生含义和行为不同的属性和方法。

  • 用法:

    USAGE = r"""
创建计划任务

使用方法：
XXXXXX
""".strip()

@on_command('schedule', shell_like=True)
async def _(session: CommandSession):
    parser = ArgumentParser(session=session, usage=USAGE)
    parser.add_argument('-S', '--second')
    parser.add_argument('-M', '--minute')
    parser.add_argument('-H', '--hour')
    parser.add_argument('-d', '--day')
    parser.add_argument('-m', '--month')
    parser.add_argument('-w', '--day-of-week')
    parser.add_argument('-f', '--force', action='store_true', default=False)
    parser.add_argument('-v', '--verbose', action='store_true', default=False)
    parser.add_argument('--name', required=True)
    parser.add_argument('commands', nargs='+')

    args = parser.parse_args(session.argv)
    name = args.name
    # ...

__init__(session=None, usage=None, **kwargs)

  • 说明:

    初始化 ArgumentParser 对象。

  • 参数:

    • session: CommandSession: 当前需要解析参数的命令会话，用于解析失败或遇到 --help 时发送提示消息
    • usage: str: 命令的使用帮助，在参数为空或遇到 --help 时发送
    • **kwargs: Any: 和 Python argparse.ArgumentParser 类一致

parse_args(args=None, namespace=None)

  • 说明:

    解析参数。

    Python 原生的「打印到控制台」行为变为「发送消息到用户」，「退出程序」变为「结束当前命令会话」。

  • 参数:

    和 Python argparse.ArgumentParser 类一致。

  • 异常:

    无。

nonebot.sched 模块

class Scheduler

继承自 apscheduler.schedulers.asyncio.AsyncIOScheduler 类，功能不变。

当 Python 环境中没有安装 APScheduler 包时，此类不存在，Scheduler 为 None。