API 参考¶

以下部分概述了 qq.py 的命令扩展模块的 API。

机器人¶

Bot¶

Attributes

cached_messages
case_insensitive
cogs
command_prefix
commands
description
extensions
guilds
help_command
latency
owner_id
owner_ids
strip_after_prefix
user

Methods

defadd_check
defadd_cog
defadd_command
defadd_listener
defafter_invoke
defbefore_invoke
defcheck
defcheck_once
defclear
asyncclose
defcommand
asyncconnect
asynccreate_dm
defevent
asyncfetch_guild
asyncfetch_guilds
defget_all_channels
defget_all_members
defget_channel
defget_cog
defget_command
asyncget_context
defget_guild
asyncget_prefix
defget_user
defgroup
asyncinvoke
defis_closed
asyncis_owner
defis_ready
deflisten
defload_extension
asynclogin
asyncon_command_error
asyncon_error
asyncprocess_commands
defreload_extension
defremove_check
defremove_cog
defremove_command
defremove_listener
defrun
asyncstart
defunload_extension
asyncwait_for
asyncwait_until_ready
defwalk_commands

class qq.ext.commands.Bot(command_prefix, help_command=<default-help-command>, description=None, **options)¶

代表一个qq机器人。

这个类是 qq.Client 的子类，因此你可以用这个机器人做任何你可以 qq.Client 用做的事情。

该类还继承了 GroupMixin 以提供管理命令的功能。

command_prefix¶

命令前缀是消息内容最初必须包含的内容才能调用命令。这个前缀可以是一个字符串来指示前缀应该是什么，或者是一个可调用的，它接受机器人作为它的第一个参数和 qq.Message 作为它的第二个参数并返回前缀。这是为了方便“动态`` 命令前缀。这个可调用对象可以是常规函数或协程。

空字符串作为前缀将始终匹配，启用无前缀命令调用。虽然这在私聊中可能很有用，但在服务器中应该避免，因为它可能会导致性能问题和意外的命令调用。

命令前缀也可以是一个可迭代的字符串，表示应该对前缀进行多次检查，第一个匹配的将是调用前缀。你可以通过 Context.prefix 得到这个前缀。为避免混淆，不允许使用空的可迭代对象。

注解

传递多个前缀时，请注意不要传递与序列中后面出现的较长前缀相匹配的前缀。例如，如果命令前缀是 ('!', '!?') '!?' 前缀将永远不会与任何消息匹配，因为前一个匹配 ! 是后一个的子集。这在传递空字符串时尤其重要，它应该始终放在最后，因为在匹配之后没有前缀能够被匹配。

case_insensitive¶

命令是否应该不区分大小写。默认为 False 。此属性不会延续到组。如果你还要求组命令不区分大小写，则必须将其设置为每个组。

Type: bool

description¶

默认帮助消息中带有前缀的内容。

Type: str

help_command¶

要使用的帮助命令实现。这可以在运行时动态设置。删除帮助命令传递 None 。有关实现帮助命令的更多信息，请参阅帮助命令。

Type: Optional[HelpCommand]

owner_id¶

拥有机器人的用户 ID。必须设置 owner_id 或 owner_ids 其中一个

Type: Optional[int]

owner_ids¶

拥有机器人的多个用户 ID。这类似于 owner_id。出于性能原因，建议使用 set。必须设置 owner_id 或 owner_ids 其中一个

Type: Optional[Collection[int]]

strip_after_prefix¶

遇到命令前缀后是否去除空白字符。这允许 ! hello 和 !hello 都生效，默认为 ‘’False’’ 。

Type: bool

@after_invoke¶

将协程注册为调用后钩的装饰器。

在调用命令后直接调用调用后钩。这使其成为清理数据库连接或任何类型的清理所需的有用功能。

这个调用后钩有一个唯一的参数，一个 Context。

注解

类似于 before_invoke()，除非检查和参数解析过程成功，否则不会调用它。但是，无论内部命令回调是否引发错误（即 CommandInvokeError），都会始终调用此钩子。这使其成为清理的理想选择。

参数: coro (coroutine) – 要注册为调用后钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@before_invoke¶

将协程注册为调用前钩的装饰器。

在调用命令之前直接调用调用前钩。这使得它成为设置数据库连接或所需的任何类型的设置的有用功能。

这个调用前钩有一个唯一的参数，一个 Context。

注解

before_invoke() 和 after_invoke() 钩子只有在所有检查和参数解析过程无错误通过时才会被调用。如果任何检查或参数解析过程失败，则不会调用挂钩。

参数: coro (coroutine) – 要注册为调用前钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@check¶

向机器人添加全局检查的装饰器。

全局检查类似于基于每个命令应用的 check()，不同之处在于它在任何命令检查被验证之前运行并适用于机器人拥有的每个命令。

注解

此函数可以是常规函数或协程。

类似于命令 check() ，它接受一个类型为 Context 的参数，并且只能引发从 CommandError 继承的异常。

示例

@bot.check
def check_commands(ctx):
    return ctx.command.qualified_name in allowed_commands

@check_once¶

向机器人添加 调用一次 全局检查的装饰器。

与常规的全局检查不同，每个 invoke() 调用只调用一次。

每当调用命令或调用 Command.can_run() 时，都会调用常规的全局检查。这种类型的检查绕过它并确保它只被调用一次，即使在默认的帮助命令中也是如此。

注解

使用此函数时，发送到组子命令的 Context 可能只解析父命令而不解析子命令，因为它在每个 Bot.invoke() 调用中被调用一次。

注解

此函数可以是常规函数或协程。

类似于命令 check()，它接受一个类型为 Context 的参数，并且只能引发从 CommandError 继承的异常。

示例

@bot.check_once
def whitelist(ctx):
    return ctx.message.author.id in my_whitelist

@command(*args, **kwargs)¶

调用 command() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为命令的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Command]

@event¶

注册要监听的事件的装饰器。你可以在下面的文档上找到有关事件的更多信息. 事件必须是协程，如果不是，则引发 TypeError 。

示例

@client.event
async def on_ready():
print('Ready!')

引发: TypeError – coro 需要是协程但实际上并不是协程。

@group(*args, **kwargs)¶

调用 group() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为 Group 的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Group]

@listen(name=None)¶

将另一个函数注册为外部事件监听器的装饰器。基本上，这允许你收听来自不同地方的多个事件，例如 on_ready()

被监听的函数必须是一个 coroutine 。

示例

@bot.listen()
async def on_message(message):
    print('one')

# 在其他文件中...

@bot.listen('on_message')
async def my_message(message):
    print('two')

将以未指定的顺序输出一和二。

引发: TypeError – 被监听的函数不是协程。

add_check(func, *, call_once=False)¶

向机器人添加全局检查。

这是 check() 和 check_once() 的非装饰器接口。

参数

func – 用作全局检查的函数。
call_once (bool) – 如果为 True 每个 invoke() 调用只应调用一次该函数。

add_cog(cog, *, override=False)¶

向机器人添加一个 齿轮 。

齿轮是一个拥有自己的事件监听器和命令的类。

参数

cog (Cog) – 注册到机器人的齿轮。
override (bool) – 如果之前加载的同名 cog 应该被覆盖而不是引发错误。

引发

TypeError – 齿轮不是从 Cog 继承的。
CommandError – 加载过程中发生错误。
ClientException – 已加载同名的齿轮。

add_command(command)¶

将 Command 添加到内部命令列表中。

这通常不被调用，而是使用 command() 或 group() 快捷装饰器。

参数

command (Command) – 要添加的命令。

引发

CommandRegistrationError – 如果该命令或其别名已被不同的命令注册。
TypeError – 如果传递的命令不是 Command 的子类。

add_listener(func, name=...)¶

listen() 的非装饰器替代品。

参数

func (coroutine) – 要调用的函数。
name (str) – 要监听的事件的名称。默认为 func.__name__ 。

示例

async def on_ready(): pass
async def my_message(message): pass

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')

property cached_messages: Sequence[Message]¶

连接的客户端已缓存的消息的只读列表。

Type: Sequence[Message]

clear()¶: 清除机器人的内部状态。在此之后，机器人可以被视为 重新连接 ，即 is_closed() 和 is_ready() 都返回 False 以及清除机器人的内部缓存。

await close()¶: 这个函数是一个 coroutine。关闭与 QQ 的连接。

property cogs: Mapping[str, qq.ext.commands.cog.Cog]¶

齿轮名到齿轮的只读映射。

Type: Mapping[str, Cog]

property commands: Set[qq.ext.commands.core.Command[qq.ext.commands.core.CogT, Any, Any]]¶

一组独特的没有注册别名的命令。

Type: Set[Command]

await connect(*, reconnect=True)¶

这个函数是一个 coroutine。创建一个 websocket 连接并让 websocket 监听来自 QQ 的消息。这运行整个事件系统和库的其他方面的循环。在 WebSocket 连接终止之前，不会恢复控制。

参数

reconnect (bool) – 我们应不应该尝试重新连接，无论是由于互联网故障还是 QQ 的特定故障。某些导致错误状态的断开连接将不会得到处理（例如无效的分片或错误的令牌）。

引发

GatewayNotFound – 如果找不到连接到 QQ 的网关。通常，如果抛出此问题，则会导致 QQ API 中断。
ConnectionClosed – websocket 连接已终止。

await create_dm(user, guild)¶

这个函数是一个 coroutine。用这个用户创建一个 DMChannel。这应该很少被调用，因为这对大多数人来说都不需要用到的。

参数

user (User) – 用于创建私信的用户。
guild – 用于创建私信的源频道

返回

创建的频道。

返回类型

DMChannel

property extensions: Mapping[str, module]¶

扩展名到扩展的只读映射。

Type: Mapping[str, types.ModuleType]

await fetch_guild(guild_id)¶

这个函数是一个 coroutine。

从 ID 中检索 Guild 。

注解

使用它，你将不会收到 Guild.channels 、 Guild.members 。

注解

此方法是 API 调用。对于一般用法，请考虑 get_guild() 。

参数

guild_id (int) – 要从中获取的频道 ID。

引发

Forbidden – 你无权访问频道。
HTTPException – 获得频道失败。

返回

来自ID的频道。

返回类型

Guild

await fetch_guilds(*, limit=100)¶

获得一个 AsyncIterator 来接收你的频道。

注解

该方法是一个 API 调用。对于一般用法，请考虑 guilds。

实际案例

用法

async for guild in client.fetch_guilds(limit=150):
    print(guild.name)

展平成一个列表

guilds = await client.fetch_guilds(limit=150).flatten()
# guilds is now a list of Guild...

所有参数都是可选的。

参数: limit (Optional[int]) – 要检索的频道数量。如果为 None ，它将检索你有权访问的每个频道。但是请注意，这会使其操作变慢。默认为“100”。
引发: HTTPException – 获取频道失败。
生成器: Guild – 已解析频道数据的频道。

for ... in get_all_channels()¶

一个生成器，它检索客户端可以“访问”的每个 abc.GuildChannel。

这相当于：

for guild in client.guilds:
    for channel in guild.channels:
        yield channel

生成器: abc.GuildChannel – 客户端可以“访问”的子频道。

for ... in get_all_members()¶

返回一个生成器，其中包含客户端可以看到的每个 Member。

这相当于：

for guild in client.guilds:
    for member in guild.members:
        yield member

生成器: Member – 客户端可以看到的成员。

get_channel(id, /)¶

返回具有给定 ID 的子频道。 :param id: 要搜索的 ID。 :type id: int

返回: 返回的子频道或 ``None``（如果未找到）。
返回类型: Optional[Union[abc.GuildChannel, Thread, abc.PrivateChannel]]

get_cog(name)¶

获取请求的齿轮实例。

如果没有找到齿轮，则返回 None 。

参数: name (str) – 你请求的齿轮的名称。这相当于在类创建中通过关键字参数传递的名称或在未指定参数的时候为类名称。
返回: 请求的齿轮。如果未找到，则返回 None 。
返回类型: Optional[Cog]

get_command(name)¶

从内部命令列表中获取 Command 。

这也可以用作获取别名的一种方式。

该名称可以是完全限定的（例如 foo bar ）将获得组命令 foo 的子命令 bar 。如果未找到子命令，则像往常一样返回 None 。

参数: name (str) – 要获取的命令的名称。
返回: 请求的命令。如果未找到，则返回 None 。
返回类型: Optional[Command]

await get_context(message, *, cls=<class 'qq.ext.commands.context.Context'>)¶

这个函数是一个 coroutine。

从消息中返回调用context。

这是 process_commands() 的一个更底层的对应部分，允许用户对处理进行更细度的控制。

返回的 context 不能保证是有效的调用context，必须检查 Context.valid 以确保它是有效的。如果 context 无效，则它不会在 invoke() 下调用。

参数

message (qq.Message) – 从中获取调用 context 的消息。
cls – 将用于创建 context 的工厂类。默认情况下，这是 Context。如果提供自定义类，它必须与 Context的接口足够相似。

返回

调用 context 。这个类型可以通过 cls 参数改变。

返回类型

Context

get_guild(id, /)¶

返回具有给定 ID 的频道。

参数: id (int) – 要搜索的 ID。
返回: 如果未找到频道则 None 。
返回类型: Optional[Guild]

await get_prefix(message)¶

这个函数是一个 coroutine。

检索机器人正在监听的前缀，并将消息作为 context。

参数: message (qq.Message) – 要获取前缀的 context 。
返回: 机器人正在监听的前缀列表或单个前缀。
返回类型: Union[List[str], str]

get_user(id, /)¶

返回具有给定 ID 的用户。

参数: id (int) – 要搜索的 ID。
返回: 如果未找到，则为 None 。
返回类型: Optional[User]

property guilds: List[qq.guild.Guild]¶

连接的客户端所属的频道。

Type: List[Guild]

await invoke(ctx)¶

这个函数是一个 coroutine。

调用在调用 context 下给出的命令并处理所有内部事件调度机制。

参数: ctx (Context) – 要调用的调用 context 。

is_closed()¶: bool: 指示 websocket 连接是否关闭。

await is_owner(user)¶

这个函数是一个 coroutine。

检查 User 或 Member 是否是这个机器人的所有者。

如果 owner_id 未设置，则会通过使用 application_info() 自动获取。

如果 owner_ids 未设置，该函数还会检查应用程序是否为团队所有。

参数: user (abc.User) – 要检查的用户。
返回: 用户是否为所有者。
返回类型: bool

is_ready()¶: bool: 指定客户端的内部缓存是否可以使用。

property latency: float¶

以秒为单位测量 HEARTBEAT 和 HEARTBEAT_ACK 之间的延迟。这可以称为 QQ WebSocket 协议延迟。

Type: float

load_extension(name, *, package=None, extras=None)¶

加载扩展。

扩展是包含命令、cog 或监听器的 Python 模块。

扩展必须有一个全局函数，setup 定义为加载扩展时要执行的操作的入口点。这个入口点必须有一个参数，bot 。

参数

name (str) – 要加载的扩展名。如果访问子模块，它必须像常规 Python 导入一样用点分隔。例如如果你想导入 foo/test.py 你可以使用 foo.test 。
package (Optional[str]) – 用于解析相对导入的包名。当使用相对路径加载扩展时，这是必需的，例如 .foo.test 。默认为 None 。

extras (Optional[dict]) –

kwargs 到要作为关键字参数传递给 cog 的 __init__ 方法的值的映射。

Usage

# main.py

bot.load_extensions("cogs.me_cog", extras={"keyword_arg": True})

# cogs/me_cog.py
class MeCog(commands.Cog):
    def __init__(self, bot, keyword_arg):
        self.bot = bot
        self.keyword_arg = keyword_arg
def setup(bot, **kwargs):
    bot.add_cog(MeCog(bot, **kwargs))

# 或者
def setup(bot, keyword_arg):
    bot.add_cog(MeCog(bot, keyword_arg))

1.1.0 新版功能.

引发

ExtensionNotFound – 无法导入扩展。如果无法使用提供的 package 参数解析扩展的名称，也会引发此问题。
ExtensionAlreadyLoaded – 扩展已经加载。
NoEntryPointError – 该扩展没有 setup 函数。
ExtensionFailed – 扩展程序或其设置函数有执行错误。
InvalidSetupArguments – load_extension 被赋予了 extras 但 setup 函数没有接受任何额外的参数。

await login(token)¶

这个函数是一个 coroutine。使用指定的凭据登录客户端。

参数

token (str) – 身份验证令牌。不要在这个令牌前面加上任何东西，因为库会为你做这件事。

引发

LoginFailure – 传递了错误的凭据。
HTTPException – 发生未知的 HTTP 相关错误，通常是当它不是 200 或已知的错误。

await on_command_error(context, exception)¶

这个函数是一个 coroutine。

机器人提供的默认命令错误处理程序。

默认情况下，这会打印到 sys.stderr 但是它可以被覆盖以使用不同的实现。

仅当你没有为命令错误指定任何监听器时才会触发。

await on_error(event_method, *args, **kwargs)¶: 这个函数是一个 coroutine。客户端提供的默认错误处理程序。默认情况下，这会打印到 sys.stderr 但是它可以被覆盖以使用不同的实现。看看 on_error() 以获取更多详细信息。

await process_commands(message)¶

这个函数是一个 coroutine。

函数处理已注册到机器人和其他组的命令。如果没有这个协程，将不会触发任何命令。

默认情况下，这个协程在 on_message() 事件中被调用。如果你选择覆盖 on_message() 事件，那么你也应该调用这个协程。

这是使用其他低级工具构建的，相当于调用 get_context() 然后调用 invoke()。

这还会检查消息的作者是否是机器人，如果是，则不会调用 get_context() 或 invoke()。

参数: message (qq.Message) – 要为其处理命令的消息。

reload_extension(name, *, package=None)¶

以原子性的方式重新加载扩展。

这会用相同的扩展名替换扩展名，只是刷新了而已。除了以原子性的方式完成，这相当于一个 unload_extension() 后跟一个 meth:load_extension 。也就是说，如果操作在重新加载过程中失败，那么机器人将回滚到之前的工作状态。

参数

name (str) – 要重新加载的扩展名。如果访问子模块，它必须像常规 Python 导入一样用点分隔。例如如果你想导入 foo/test.py 你可以使用 foo.test 。
package (Optional[str]) – 用于解析相对导入的包名。当使用相对路径加载扩展时，这是必需的，例如 .foo.test 。默认为 None 。

引发

ExtensionNotLoaded – 未加载扩展。
ExtensionNotFound – 无法导入扩展。如果无法使用提供的 package 参数解析扩展的名称，也会引发此错误。
NoEntryPointError – 该扩展没有 setup 函数。
ExtensionFailed – 扩展 setup 函数有一个错误。

remove_check(func, *, call_once=False)¶

从机器人中删除全局检查。

此函数是幂等的，如果该函数不在全局检查中，则不会引发异常。

参数

func – 要从全局检查中删除的函数。
call_once (bool) – 如果函数是在 Bot.add_check() 调用中添加了 call_once=True 或使用 check_once()。

remove_cog(name)¶

从机器人中移除一个齿轮并返回它。

齿轮注册的所有注册命令和事件监听器也将被删除。

如果未找到齿轮，则此方法无效。

参数: name (str) – 要移除的齿轮的名称。
返回: 被移除的齿轮。如果未找到，则为 None 。
返回类型: Optional[Cog]

remove_command(name)¶

从内部命令列表中删除 Command。

这也可以用作删除别名的方法。

参数: name (str) – 要删除的命令的名称。
返回: 删除的命令。如果名称无效，则返回 None 。
返回类型: Optional[Command]

remove_listener(func, name=...)¶

从监听器池中删除一个监听器。

参数

func – 用作要删除的监听器的函数。
name (str) – 要删除的事件的名称。默认为 func.__name__ 。

run(*args, **kwargs)¶

一个阻塞调用，它从你那里抽象出事件循环初始化。如果你想对事件循环进行更多控制，则不应使用此函数。使用 start() 协程或 connect() + login()。

大致相当于：

try:
    loop.run_until_complete(start(*args, **kwargs))
except KeyboardInterrupt:
    loop.run_until_complete(close())
    # cancel all tasks lingering
finally:
    loop.close()

警告

由于它是阻塞的，因此该函数必须是最后一个调用的函数。这意味着在此函数调用之后注册的事件或任何被调用的东西在它返回之前不会执行。

await start(token, reconnect=True)¶

这个函数是一个 coroutine。 login() + connect() 的协程。

引发: TypeError – 收到意外的关键字参数。

unload_extension(name, *, package=None)¶

卸载扩展。

卸载扩展后，所有命令、监听器和齿轮都将从机器人中删除，并且模块将取消导入。

扩展可以提供一个可选的全局函数 teardown ，以便在必要时进行杂项清理。这个函数接受一个参数， bot ，类似于 load_extension() 中的 setup 。

参数

name (str) – 要卸载的扩展名。如果访问子模块，它必须像常规 Python 导入一样用点分隔。例如如果你想导入 foo/test.py 你可以使用 foo.test 。
package (Optional[str]) – 用于解析相对导入的包名。当使用相对路径加载扩展时，这是必需的，例如 .foo.test 。默认为 None 。

引发

ExtensionNotFound – 无法导入扩展。如果无法使用提供的 package 参数解析扩展的名称，也会引发此问题。
ExtensionNotLoaded – 未加载扩展。

property user: Optional[qq.user.ClientUser]¶

代表连接的客户端。如果未登录，则为 None 。

Type: Optional[ClientUser]

wait_for(event, *, check=None, timeout=None)¶

这个函数是一个 coroutine。等待调度 WebSocket 事件。这可用于等待用户回复消息，或对消息做出反应，或以独立的方式编辑消息。 timeout 参数传递给 asyncio.wait_for()。默认情况下，它不会超时。请注意，为了便于使用这在超时的时候会传播 asyncio.TimeoutError 。如果事件返回多个参数，则返回包含这些参数的 tuple 。请查看文档以获取事件列表及其参数。该函数返回 第一个符合要求的事件 。

实际案例

等待用户回复：

@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')
        def check(m):
            return m.content == 'hello' and m.channel == channel
        msg = await client.wait_for('message', check=check)
        await channel.send(f'Hello {msg.author}!')

等待消息作者的 reaction ：

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        def check(reaction, user):
            return user == message.author
        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('Got it')
        else:
            await channel.send('Time out')

参数

event (str) – 事件名称，类似于事件指南，但没有 on_ 前缀，用于等待。
check (Optional[Callable[…, bool]]) – 检查等待什么的检查函数。参数必须满足正在等待的事件的参数。
timeout (Optional[float]) – 在超时和引发 asyncio.TimeoutError 之前等待的秒数。

引发

asyncio.TimeoutError – 如果提供超时并且已达到。

返回

不返回任何参数、单个参数或多个参数的元组，这些参数反映在 :ref:`事件指南`<qq-api-events> 中传递的参数。

返回类型

Any

await wait_until_ready()¶: 这个函数是一个 coroutine。等到客户端的内部缓存准备就绪。

for ... in walk_commands()¶

递归遍历所有命令和子命令的迭代器。

生成器: Union[Command, Group] – 来自内部命令列表的命令或组。

AutoShardedBot¶

class qq.ext.commands.AutoShardedBot(command_prefix, help_command=<default-help-command>, description=None, **options)¶: 除了它是从 qq.AutoShardedClient 继承的，其他与 Bot 类似。

前缀助手¶

qq.ext.commands.when_mentioned(bot, msg)¶

实现与提及的命令前缀等效的可调用对象。

这些旨在传递到 Bot.command_prefix 属性。

qq.ext.commands.when_mentioned_or(*prefixes)¶

在提及或提供其他前缀时实现的可调用对象。

这些旨在传递到 Bot.command_prefix 属性。

示例

bot = commands.Bot(command_prefix=commands.when_mentioned_or('!'))

注解

此可调用对象返回另一个可调用对象，因此如果这是在自定义可调用对象中完成的，则必须调用返回的可调用对象，例如：

async def get_prefix(bot, message):
    extras = await prefixes_for(message.guild) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

参见

when_mentioned()

事件参考¶

这些事件的功能类似于常规事件，但是它们来自命令扩展模块。

qq.ext.commands.on_command_error(ctx, error)¶

一个错误处理程序，当在命令中通过用户输入错误、检查失败或你自己的代码中的错误引发错误时调用。

提供了一个默认的（ Bot.on_command_error() ）。

参数

ctx (Context) – 调用 context。
error (CommandError derived) – 引发的错误。

qq.ext.commands.on_command(ctx)¶

在找到命令并即将被调用时调用的事件。

无论命令本身是通过错误成功还是完成，都会调用此事件。

参数: ctx (Context) – 调用 context。

qq.ext.commands.on_command_completion(ctx)¶

当命令完成其调用时调用的事件。

仅当命令成功时才调用此事件，即所有检查均已通过且用户正确输入。

参数: ctx (Context) – 调用 context。

命令¶

装饰器¶

@qq.ext.commands.command(name=..., cls=..., **attrs)¶

将函数转换为 Command 或如果使用 group() 则转为 Group 的装饰器。

默认情况下，help 属性是从函数的文档字符串中自动接收的，并使用``inspect.cleandoc`` 进行清理。如果 docstring 是 bytes，则使用 utf-8 编码将其解码为 str。

所有使用 check() 添加的检查都被添加到函数中。无法通过此装饰器提供你自己的检查。

参数

name (str) – 用于创建命令的名称。默认情况下，这使用未更改的函数名称。
cls – 要构造的类。默认情况下，这是 Command 。你通常不会更改此设置。
attrs – 传递到由 cls 表示的类的构造中的关键字参数。

引发

TypeError – 如果函数不是协程或已经是命令。

@qq.ext.commands.group(name=..., cls=..., **attrs)¶

将函数转换为 Group 的装饰器。

这类似于 command() 装饰器，但 cls 参数默认设置为 Group 。

命令¶

Methods

async__call__
defadd_check
defafter_invoke
defbefore_invoke
asynccan_run
defcopy
deferror
defget_cooldown_retry_after
defhas_error_handler
defis_on_cooldown
defremove_check
defreset_cooldown
defupdate

class qq.ext.commands.Command(*args, **kwargs)¶

一个实现机器人文本命令协议的类。

这些不是手动创建的，而是通过装饰器或功能接口创建的。

name¶

命令的名称。

Type: str

callback¶

调用命令时执行的协程。

Type: coroutine

help¶

命令的长帮助文本。

Type: Optional[str]

brief¶

命令的简短帮助文本。

Type: Optional[str]

usage¶

替换默认帮助文本中的参数。

Type: Optional[str]

aliases¶

可以在其下调用命令的别名列表。

Type: Union[List[str], Tuple[str]]

enabled¶

指示当前是否启用命令的布尔值。如果命令在禁用时被调用，则 DisabledCommand 将引发 on_command_error() 事件。默认为 True 。

Type: bool

parent¶

此命令所属的父组。 None 如果没有的话。

Type: Optional[Group]

cog¶

该命令所属的齿轮。 None 如果没有的话。

Type: Optional[Cog]

checks¶

一个检查函数列表，用于验证是否可以使用给定的 Context 作为唯一参数来执行命令。: 如果必须抛出异常以表示失败，则应使用继承自 CommandError 的异常。请注意，如果检查失败，则 CheckFailure 异常将引发到 on_command_error() 事件。

Type: List[Callable[[Context], bool]]

description¶

默认帮助命令中带有前缀的消息。

Type: str

hidden¶

如果为 True，则默认帮助命令不会在帮助输出中显示此内容。

Type: bool

rest_is_raw¶

如果 False 则仅关键字参数，则仅关键字参数将被剥离并处理，就好像它是处理 MissingRequiredArgument 和默认值的常规参数一样，而不是传递原始数据。如果 True 则仅关键字参数将以完全原始的方式传递其余参数。默认为 False 。

Type: bool

invoked_subcommand¶

调用的子命令（如果有）。

Type: Optional[Command]

require_var_positional¶

如果 True 并且指定了可变参数位置参数，则要求用户至少指定一个参数。默认为 False 。

Type: bool

ignore_extra¶

如果 True，如果它的所有要求都得到满足，则忽略传递给命令的无关字符串（例如 ?foo a b c 当只需要 a 和 b 时）。否则 on_command_error() 和本地错误处理程序使用 TooManyArguments 调用。默认为 True 。

Type: bool

cooldown_after_parsing¶

如果为 True，则在参数解析后完成冷却处理，这会调用转换器。如果 False 则首先完成冷却处理，然后再调用转换器。默认为 False 。

Type: bool

extras¶

用户的字典提供了附加到命令的附加内容。

注解

该对象可由库复制。

Type: dict

inherit_hooks¶

如果 True 并且这个命令有一个父 Group，那么这个命令将继承所有在 Group`的检查，``pre_invoke` 和 after_invoke 定义。

注解

在此定义的任何 pre_invoke 或 after_invoke 都将覆盖父项。

Type: bool, default=False

@after_invoke¶

将协程注册为调用后钩的装饰器。

在调用命令后直接调用后钩。这使其成为清理数据库连接或任何类型的清理所需的有用功能。

这个调用后钩有一个唯一的参数，一个 Context。

有关更多信息，请参阅 Bot.after_invoke()。

参数: coro (coroutine) – 要注册为调用后钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@before_invoke¶

将协程注册为调用前钩的装饰器。

在调用命令之前直接调用调用前钩。这使得它成为设置数据库连接或所需的任何类型的设置的有用功能。

这个调用前钩有一个唯一的参数，一个 Context。

有关更多信息，请参阅 Bot.before_invoke()。

参数: coro (coroutine) – 要注册为调用前钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@error¶

将协程注册为本地错误处理程序的装饰器。

本地错误处理程序是一个仅限于单个命令的 on_command_error() 事件。然而， on_command_error() 之后仍然会被调用。

参数: coro (coroutine) – 要注册为本地错误处理程序的协程。
引发: TypeError – 传递的协程实际上并不是协程。

add_check(func)¶

向命令添加检查。

这是 check() 的非装饰器接口。

参数: func – 将用作检查的函数。

remove_check(func)¶

从命令中删除检查。

此函数是幂等的，如果该函数不在命令的检查中，则不会引发异常。

参数: func – 要从检查中删除的函数。

update(**kwargs)¶

使用更新的属性更新 Command 实例。

这在参数方面与 command() 装饰器类似，因为它们被传递给 Command 或子类构造函数，没有名称和回调。

await __call__(context, *args, **kwargs)¶

这个函数是一个 coroutine。

调用命令持有的内部回调。

注解

这绕过了所有机制——包括检查、转换器、调用钩子、冷却等。你必须小心地将正确的参数和类型传递给这个函数。

copy()¶

创建此命令的副本。

返回: 此命令的新实例。
返回类型: Command

property clean_params: Dict[str, inspect.Parameter]¶

Dict[str, inspect.Parameter]: 检索没有上下文或自身参数的参数字典。

用于检查签名。

property full_parent_name: str¶

检索完全限定的父命令名称。

这是执行它所需的基本命令名称。例如，在 ?one two three 中，父名称将是 one two 。

Type: str

property parents: List[qq.ext.commands.core.Group]¶

检索此命令的父级。

如果该命令没有父级，则它返回一个空的 list。

例如在命令 ?a b c test 中，父级是 [c, b, a]。

Type: List[Group]

property root_parent: Optional[qq.ext.commands.core.Group]¶

检索此命令的根父级。

如果该命令没有父级，则返回 None 。

例如在命令 ?a b c test 中，根父节点是 a 。

Type: Optional[Group]

property qualified_name: str¶

检索完全限定的命令名称。

这也是带有命令名称的完整父名称。例如，在 ?one two three 中，限定名称将是 one two three 。

Type: str

is_on_cooldown(ctx)¶

检查命令当前是否处于冷却状态。

参数: ctx (Context) – 检查命令冷却状态时使用的调用上下文。
返回: 指示命令是否处于冷却状态的布尔值。
返回类型: bool

reset_cooldown(ctx)¶

重置此命令的冷却时间。

参数: ctx (Context) – 重置冷却时间的调用上下文。

get_cooldown_retry_after(ctx)¶

检索可以再次尝试此命令之前的秒数。

参数: ctx (Context) – 从中检索冷却时间的调用上下文。
返回: 此命令的冷却剩余时间（以秒为单位）。如果这是 0.0 ，则该命令不在冷却中。
返回类型: float

has_error_handler()¶: bool: 检查命令是否已注册错误处理程序。

property cog_name: Optional[str]¶

此命令所属的 cog 的名称（如果有）。

Type: Optional[str]

property short_doc: str¶

获取命令的 简短 文档。

默认情况下，这是 brief 属性。如果该查找导致空字符串，则使用 help 属性的第一行。

Type: str

property signature: str¶

返回对帮助命令输出有用的类似 POSIX 的签名。

Type: str

await can_run(ctx)¶

这个函数是一个 coroutine。

通过检查 checks 属性中的所有检查函数来检查命令是否可以执行。这还会检查命令是否被禁用。

参数: ctx (Context) – 当前正在调用的命令的 ctx。
引发: CommandError – 在检查调用期间引发的任何命令错误都将由此函数传播。
返回: 指示是否可以调用命令的布尔值。
返回类型: bool

命令组¶

Attributes

case_insensitive
clean_params
cog_name
commands
full_parent_name
invoke_without_command
parents
qualified_name
root_parent
short_doc
signature

Methods

defadd_check
defadd_command
defafter_invoke
defbefore_invoke
asynccan_run
defcommand
defcopy
deferror
defget_command
defget_cooldown_retry_after
defgroup
defhas_error_handler
defis_on_cooldown
defremove_check
defremove_command
defreset_cooldown
defupdate
defwalk_commands

class qq.ext.commands.Group(*args, **kwargs)¶

为作为子命令执行的命令实现分组协议的类。

这个类是 Command 的子类，因此所有在 Command 中有效的选项在这里也有效。

invoke_without_command¶

指示组回调是否应仅在未找到子命令时才开始解析和调用。用于制作一个错误处理函数以告诉用户未找到子命令或在未找到子命令的情况下具有不同的功能。如果这是 False ，则总是首先调用组回调。这意味着将执行由其参数指示的检查和解析。默认为 False 。

Type: bool

case_insensitive¶

指示组的命令是否应不区分大小写。默认为 False 。

Type: bool

@after_invoke¶

将协程注册为调用后钩的装饰器。

在调用命令后直接调用后钩。这使其成为清理数据库连接或任何类型的清理所需的有用功能。

这个调用后钩有一个唯一的参数，一个 Context。

有关更多信息，请参阅 Bot.after_invoke()。

参数: coro (coroutine) – 要注册为调用后钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@before_invoke¶

将协程注册为调用前钩的装饰器。

在调用命令之前直接调用调用前钩。这使得它成为设置数据库连接或所需的任何类型的设置的有用功能。

这个调用前钩有一个唯一的参数，一个 Context。

有关更多信息，请参阅 Bot.before_invoke()。

参数: coro (coroutine) – 要注册为调用前钩的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@command(*args, **kwargs)¶

调用 command() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为命令的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Command]

@error¶

将协程注册为本地错误处理程序的装饰器。

本地错误处理程序是一个仅限于单个命令的 on_command_error() 事件。然而， on_command_error() 之后仍然会被调用。

参数: coro (coroutine) – 要注册为本地错误处理程序的协程。
引发: TypeError – 传递的协程实际上并不是协程。

@group(*args, **kwargs)¶

调用 group() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为 Group 的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Group]

copy()¶

创建此 Group 的副本。

返回: 组的新实例。
返回类型: Group

add_check(func)¶

向命令添加检查。

这是 check() 的非装饰器接口。

参数: func – 将用作检查的函数。

add_command(command)¶

将 Command 添加到内部命令列表中。

这通常不被调用，而是使用 command() 或 group() 快捷装饰器。

参数

command (Command) – 要添加的命令。

引发

CommandRegistrationError – 如果该命令或其别名已被不同的命令注册。
TypeError – 如果传递的命令不是 Command 的子类。

await can_run(ctx)¶

这个函数是一个 coroutine。

通过检查 checks 属性中的所有检查函数来检查命令是否可以执行。这还会检查命令是否被禁用。

参数: ctx (Context) – 当前正在调用的命令的 ctx。
引发: CommandError – 在检查调用期间引发的任何命令错误都将由此函数传播。
返回: 指示是否可以调用命令的布尔值。
返回类型: bool

property clean_params: Dict[str, inspect.Parameter]¶

Dict[str, inspect.Parameter]: 检索没有上下文或自身参数的参数字典。

用于检查签名。

property cog_name: Optional[str]¶

此命令所属的 cog 的名称（如果有）。

Type: Optional[str]

property commands: Set[qq.ext.commands.core.Command[qq.ext.commands.core.CogT, Any, Any]]¶

一组独特的没有注册别名的命令。

Type: Set[Command]

property full_parent_name: str¶

检索完全限定的父命令名称。

这是执行它所需的基本命令名称。例如，在 ?one two three 中，父名称将是 one two 。

Type: str

get_command(name)¶

从内部命令列表中获取 Command 。

这也可以用作获取别名的一种方式。

该名称可以是完全限定的（例如 foo bar ）将获得组命令 foo 的子命令 bar 。如果未找到子命令，则像往常一样返回 None 。

参数: name (str) – 要获取的命令的名称。
返回: 请求的命令。如果未找到，则返回 None 。
返回类型: Optional[Command]

get_cooldown_retry_after(ctx)¶

检索可以再次尝试此命令之前的秒数。

参数: ctx (Context) – 从中检索冷却时间的调用上下文。
返回: 此命令的冷却剩余时间（以秒为单位）。如果这是 0.0 ，则该命令不在冷却中。
返回类型: float

has_error_handler()¶: bool: 检查命令是否已注册错误处理程序。

is_on_cooldown(ctx)¶

检查命令当前是否处于冷却状态。

参数: ctx (Context) – 检查命令冷却状态时使用的调用上下文。
返回: 指示命令是否处于冷却状态的布尔值。
返回类型: bool

property parents: List[qq.ext.commands.core.Group]¶

检索此命令的父级。

如果该命令没有父级，则它返回一个空的 list。

例如在命令 ?a b c test 中，父级是 [c, b, a]。

Type: List[Group]

property qualified_name: str¶

检索完全限定的命令名称。

这也是带有命令名称的完整父名称。例如，在 ?one two three 中，限定名称将是 one two three 。

Type: str

remove_check(func)¶

从命令中删除检查。

此函数是幂等的，如果该函数不在命令的检查中，则不会引发异常。

参数: func – 要从检查中删除的函数。

remove_command(name)¶

从内部命令列表中删除 Command。

这也可以用作删除别名的方法。

参数: name (str) – 要删除的命令的名称。
返回: 删除的命令。如果名称无效，则返回 None 。
返回类型: Optional[Command]

reset_cooldown(ctx)¶

重置此命令的冷却时间。

参数: ctx (Context) – 重置冷却时间的调用上下文。

property root_parent: Optional[qq.ext.commands.core.Group]¶

检索此命令的根父级。

如果该命令没有父级，则返回 None 。

例如在命令 ?a b c test 中，根父节点是 a 。

Type: Optional[Group]

property short_doc: str¶

获取命令的 简短 文档。

默认情况下，这是 brief 属性。如果该查找导致空字符串，则使用 help 属性的第一行。

Type: str

property signature: str¶

返回对帮助命令输出有用的类似 POSIX 的签名。

Type: str

update(**kwargs)¶

使用更新的属性更新 Command 实例。

这在参数方面与 command() 装饰器类似，因为它们被传递给 Command 或子类构造函数，没有名称和回调。

for ... in walk_commands()¶

递归遍历所有命令和子命令的迭代器。

生成器: Union[Command, Group] – 来自内部命令列表的命令或组。

命令组 Mixin¶

Attributes

all_commands
case_insensitive
commands

Methods

defadd_command
defcommand
defget_command
defgroup
defremove_command
defwalk_commands

class qq.ext.commands.GroupMixin(*args, **kwargs)¶

一个 mixin，它为行为类似于 Group 的类实现通用功能，并允许注册命令。

all_commands¶

命令名称到 Command 对象的映射。

Type: dict

case_insensitive¶

命令是否应该不区分大小写。默认为 False 。

Type: bool

@command(*args, **kwargs)¶

调用 command() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为命令的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Command]

@group(*args, **kwargs)¶

调用 group() 并通过 add_command() 将其添加到内部命令列表的快捷方式装饰器。

返回: 将提供的方法转换为 Group 的装饰器，将其添加到机器人，然后返回它。
返回类型: Callable[…, Group]

property commands: Set[qq.ext.commands.core.Command[qq.ext.commands.core.CogT, Any, Any]]¶

一组独特的没有注册别名的命令。

Type: Set[Command]

add_command(command)¶

将 Command 添加到内部命令列表中。

这通常不被调用，而是使用 command() 或 group() 快捷装饰器。

参数

command (Command) – 要添加的命令。

引发

CommandRegistrationError – 如果该命令或其别名已被不同的命令注册。
TypeError – 如果传递的命令不是 Command 的子类。

remove_command(name)¶

从内部命令列表中删除 Command。

这也可以用作删除别名的方法。

参数: name (str) – 要删除的命令的名称。
返回: 删除的命令。如果名称无效，则返回 None 。
返回类型: Optional[Command]

for ... in walk_commands()¶

递归遍历所有命令和子命令的迭代器。

生成器: Union[Command, Group] – 来自内部命令列表的命令或组。

get_command(name)¶

从内部命令列表中获取 Command 。

这也可以用作获取别名的一种方式。

该名称可以是完全限定的（例如 foo bar ）将获得组命令 foo 的子命令 bar 。如果未找到子命令，则像往常一样返回 None 。

参数: name (str) – 要获取的命令的名称。
返回: 请求的命令。如果未找到，则返回 None 。
返回类型: Optional[Command]

齿轮¶

Cog¶

Attributes

description
qualified_name

Methods

clsCog.listener
defbot_check
defbot_check_once
asynccog_after_invoke
asynccog_before_invoke
defcog_check
asynccog_command_error
defcog_unload
defget_commands
defget_listeners
defhas_error_handler
defwalk_commands

class qq.ext.commands.Cog(*args, **kwargs)¶

所有齿轮必须继承的基类。

齿轮是命令、侦听器和可选状态的集合，可帮助将命令组合在一起。关于它们的更多信息可以在齿轮页面上找到。

从此类继承时，CogMeta 中显示的选项在这里同样有效。

get_commands()¶

返回

在这个齿轮中定义的 Commands 的 list。

注解

这不包括子命令。

返回类型

List[Command]

property qualified_name: str¶

返回齿轮的指定名称，而不是类名称。

Type: str

property description: str¶

返回齿轮的描述，通常是清理过的文档字符串。

Type: str

for ... in walk_commands()¶

递归遍历此齿轮的命令和子命令的迭代器。

生成器: Union[Command, Group] – 来自齿轮的命令或命令组。

get_listeners()¶

返回在此齿轮中定义的侦听器的列表。

返回: 此齿轮中定义的侦听器。
返回类型: List[Tuple[str, coroutine]]

classmethod listener(name=...)¶

将函数标记为侦听器的装饰器。

这是 Bot.listen() 的齿轮版本。

参数: name (str) – 正在侦听的事件的名称。如果未提供，则默认为函数名称。
引发: TypeError – 该函数不是协程函数或未将字符串作为名称传递。

has_error_handler()¶: bool: 检查齿轮是否有错误处理程序。

cog_unload()¶

当齿轮被移除时调用的特殊方法。

此函数不能是协程。它必须是一个常规函数。

如果子类想要特殊的卸载行为，它们必须替换它。

bot_check_once(ctx)¶

注册为 Bot.check_once() 检查的特殊方法。

这个函数可以是一个协程，并且必须采用一个唯一的参数 ctx 来表示 Context。

bot_check(ctx)¶

注册为 Bot.check() 检查的特殊方法。

这个函数可以是一个协程，并且必须采用一个唯一的参数 ctx 来表示 Context。

cog_check(ctx)¶

一个特殊的方法，为这个齿轮中的每个命令和子命令注册为 check()。

这个函数可以是一个协程，并且必须采用一个唯一的参数 ctx 来表示 Context。

await cog_command_error(ctx, error)¶

每当在此齿轮内分派错误时调用的特殊方法。

除了仅应用于此齿轮内的命令，这与 on_command_error() 类似，。

这必须是一个协程。

参数

ctx (Context) – 发生错误的调用 context 。
error (CommandError) – 发生的错误。

await cog_before_invoke(ctx)¶

作为齿轮本地调用前钩的特殊方法。

这类似于 Command.before_invoke() 。

这必须是一个协程。

参数: ctx (Context) – 调用 context 。

await cog_after_invoke(ctx)¶

作为齿轮本地调用后钩的特殊方法。

这类似于:meth:.Command.after_invoke。

这必须是一个协程。

参数: ctx (Context) – 调用 context 。

CogMeta¶

Attributes

description
name

class qq.ext.commands.CogMeta(*args, **kwargs)¶

用于定义齿轮的元类。

请注意，你大概不应该直接使用它。它纯粹是为了文档目的而公开的，同时使自定义元类与其他元类混合，例如 abc.ABCMeta 元类。

例如，要创建一个抽象的 cog mixin 类，将执行以下操作。

import abc

class CogABCMeta(commands.CogMeta, abc.ABCMeta):
    pass

class SomeMixin(metaclass=abc.ABCMeta):
    pass

class SomeCogMixin(SomeMixin, commands.Cog, metaclass=CogABCMeta):
    pass

注解

当传递下面记录的元类的属性时，请注意你必须将其作为仅关键字参数传递给类创建，如下例所示：

class MyCog(commands.Cog, name='My Cog'):
    pass

name¶

齿轮名称。默认情况下，它是没有修改的类的名称。

Type: str

description¶

齿轮描述。默认情况下，它是类的文档字符串。

Type: str

command_attrs: dict

应用于此齿轮中每个命令的属性列表。字典将被传递到 __init__ 处的 Command 选项。如果你在类中的命令属性内指定属性，它将覆盖此属性内指定的属性。例如：

class MyCog(commands.Cog, command_attrs=dict(hidden=True)):
    @commands.command()
    async def foo(self, ctx):
        pass # hidden -> True

    @commands.command(hidden=False)
    async def bar(self, ctx):
        pass # hidden -> False

帮助命令¶

HelpCommand¶

Attributes

cog
command_attrs
context
invoked_with
show_hidden
verify_checks

Methods

defadd_check
asynccommand_callback
defcommand_not_found
asyncfilter_commands
defget_bot_mapping
defget_command_signature
defget_destination
defget_max_size
asyncon_help_command_error
asyncprepare_help_command
defremove_check
defremove_mentions
asyncsend_bot_help
asyncsend_cog_help
asyncsend_command_help
asyncsend_error_message
asyncsend_group_help
defsubcommand_not_found

class qq.ext.commands.HelpCommand(*args, **kwargs)¶

帮助命令格式的基本实现。

注解

每次调用命令本身时，都会在内部深度复制此类的实例，

这意味着在命令调用之间依赖于此类的状态相同将不会按预期工作。

context¶

调用此帮助格式化程序的 context 。这通常在分配的帮助命令 command_callback()被调用后设置。

Type: Optional[Context]

show_hidden¶

指定是否应在输出中显示隐藏命令。默认为 False 。

Type: bool

verify_checks¶

指定命令是否应该调用和验证它们的 Command.checks。如果 True，则总是调用 Command.checks。如果 None ，则仅在公会设置中调用 Command.checks。如果 False，则从不调用 Command.checks。默认为 True 。

Type: Optional[bool]

command_attrs¶

用于构建帮助命令的选项字典。这允许你在不实际更改命令的实现的情况下更改命令行为。这些属性将与传入 Command 构造函数的属性相同。

Type: dict

add_check(func)¶

向帮助命令添加检查。

参数: func – 将用作检查的函数。

remove_check(func)¶

从帮助命令中删除检查。

此函数是幂等的，如果该函数不在命令的检查中，则不会引发异常。

参数: func – 要从检查中删除的函数。

get_bot_mapping()¶: 检索传递给 send_bot_help() 的机器人映射。

property invoked_with¶

与 Context.invoked_with 类似，但是正确处理使用 Context.send_help() 的情况。

如果经常使用帮助命令，则返回 Context.invoked_with 属性。否则，如果使用 Context.send_help() 调用了帮助命令，则它返回帮助命令的内部命令名称。

返回: 触发此调用的命令名称。
返回类型: str

get_command_signature(command)¶

检索帮助页面的签名部分。

参数: command (Command) – 获取签名的命令。
返回: 命令的签名。
返回类型: str

remove_mentions(string)¶

从字符串中删除提及以防止滥用。

这包括 “@所有人”、成员提及和身份组提及。

返回: 删除了提及的字符串。
返回类型: str

property cog¶

用于检索或设置帮助命令的齿轮的属性。

当为 help 命令设置一个齿轮时，就好像 help 命令属于该齿轮。所有齿轮特殊方法都将应用于 help 命令，并且会在卸载时自动取消设置。

要从帮助命令中取消绑定齿轮，你可以将其设置为 None。

返回: 当前为 help 命令设置的齿轮。
返回类型: Optional[Cog]

command_not_found(string)¶

这个函数 可以是 coroutine。

在帮助命令中找不到命令时调用的方法。这对于 i18n 很有用。

默认为 未找到名为 {0} 的命令。

参数: string (str) – 包含无效命令的字符串。请注意，这已被删除以防止滥用。
返回: 未找到命令时使用的字符串。
返回类型: str

subcommand_not_found(command, string)¶

这个函数 可以是 coroutine。

当命令没有在帮助命令中请求的子命令时调用的方法。这对于 i18n 很有用。

Defaults to either:

'命令“{command.qualified_name}”没有子命令。'
- 如果 command 参数中没有子命令。
'命令“{command.qualified_name}”没有名为 {string} 的子命令'
- 如果 command 参数有子命令，但没有名为 string 的子命令。

参数

command (Command) – 没有请求子命令的命令。
string (str) – 包含无效子命令的字符串。请注意，这已被删除以防止滥用。

返回

当命令没有请求子命令时使用的字符串。

返回类型

str

await filter_commands(commands, *, sort=False, key=None)¶

这个函数是一个 coroutine。

返回过滤后的命令列表并可选择对它们进行排序。

这考虑了 verify_checks 和 show_hidden 属性。

参数

commands (Iterable[Command]) – 被过滤的命令的迭代。
sort (bool) – 是否对结果进行排序。
key (Optional[Callable[Command, Any]]) – 传递给 sorted() 的可选键函数，它以 Command 作为其唯一参数。如果 sort 作为 True 传递，那么这将默认为命令名称。

返回

通过过滤器的命令列表。

返回类型

List[Command]

get_max_size(commands)¶

返回指定命令列表的最大名称长度。

参数: commands (Sequence[Command]) – 检查最大尺寸的一系列命令。
返回: 命令的最大宽度。
返回类型: int

get_destination()¶

返回 Messageable 将在其中输出帮助命令。

你可以覆盖此方法以自定义行为。

默认情况下，这将返回 context 的子频道。

返回: 将输出帮助命令的目的地。
返回类型: abc.Messageable

await send_error_message(error)¶

这个函数是一个 coroutine。

在帮助命令中发生错误时处理实现。例如 command_not_found() 的结果会被传递到这里。

你可以覆盖此方法以自定义行为。

默认情况下，这会将错误消息发送到 get_destination() 指定的目的地。

注解

你可以使用 HelpCommand.context 访问调用 context 。

参数: error (str) – 要向用户显示的错误消息。请注意，这已被删除以防止滥用。

await on_help_command_error(ctx, error)¶

这个函数是一个 coroutine。

帮助命令的错误处理程序，由错误处理指定。

如果在调用错误处理程序时需要某些特定行为，则可用于覆盖。

默认情况下，此方法不执行任何操作，只会传播到默认错误处理程序。

参数

ctx (Context) – 调用 context 。
error (CommandError) – 引发的错误。

await send_bot_help(mapping)¶

这个函数是一个 coroutine。

处理帮助命令中 bot 命令页面的实现。当不带参数调用帮助命令时调用此函数。

应该注意的是，这个方法不返回任何东西——而是应该在这个方法内部完成实际的消息发送。行为良好的子类应该使用 get_destination() 来知道发送到哪里，因为这是其他用户的自定义点。

你可以覆盖此方法以自定义行为。

注解

你可以使用 HelpCommand.context 访问调用 context 。

此外，映射中的命令不会被过滤。要进行过滤，你必须自己调用 filter_commands()。

参数: mapping (Mapping[Optional[Cog], List[Command]]) – 齿轮到用户请求帮助的命令的映射。映射的键是命令所属的 Cog，如果没有，则为 None ，值是属于该齿轮的命令列表.

await send_cog_help(cog)¶

这个函数是一个 coroutine。

处理帮助命令中齿轮页面的实现。当使用齿轮作为参数调用 help 命令时，将调用此函数。

你可以覆盖此方法以自定义行为。

注解

你可以使用 HelpCommand.context 访问调用 context 。

要获取属于该齿轮的命令，请参见 Cog.get_commands() 。返回的命令未过滤。要进行过滤，你必须自己调用 filter_commands()。

参数: cog (Cog) – 被请求帮助的齿轮。

await send_group_help(group)¶

这个函数是一个 coroutine。

处理帮助命令中组页面的实现。当使用组作为参数调用帮助命令时，将调用此函数。

你可以覆盖此方法以自定义行为。

注解

你可以使用 HelpCommand.context 访问调用 context 。

要获取不带别名的属于该组的命令，请参阅 Group.commands。返回的命令未过滤。要进行过滤，你必须自己调用 filter_commands()。

参数: group (Group) – 被请求帮助的组。

await send_command_help(command)¶

这个函数是一个 coroutine。

处理帮助命令中单个命令页面的实现。

你可以覆盖此方法以自定义行为。

注解

你可以使用 HelpCommand.context 访问调用 context 。

显示帮助

某些属性和方法有助于帮助命令显示，例如：

Command.help
Command.brief
Command.short_doc
Command.description
get_command_signature()

不是只有是这些属性，但你可以从随意使用这些属性开始来帮助你开始获得所需的输出。

参数: command (Command) – 请求帮助的命令。

await prepare_help_command(ctx, command=None)¶

这个函数是一个 coroutine。

一种低级方法，可用于在执行任何操作之前准备帮助命令。例如，如果你需要在命令进行处理之前在子类中准备一些状态，那么这将是执行此操作的地方。

默认实现什么都不做。

注解

这在帮助命令回调主体内调用。因此，内部发生的所有常见规则也适用于此。

参数

ctx (Context) – 调用 context 。
command (Optional[str]) – 传递给 help 命令的参数。

await command_callback(ctx, *, command=None)¶

这个函数是一个 coroutine。

help 命令的实际执行。

不建议覆盖此方法，而是通过实际调度的方法更改行为。

send_bot_help()
send_cog_help()
send_group_help()
send_command_help()
get_destination()
command_not_found()
subcommand_not_found()
send_error_message()
on_help_command_error()
prepare_help_command()

默认帮助命令¶

Attributes

commands_heading
dm_help
dm_help_threshold
indent
no_category
paginator
sort_commands
width

Methods

defadd_command_formatting
defadd_indented_commands
defget_destination
defget_ending_note
asyncsend_pages
defshorten_text

class qq.ext.commands.DefaultHelpCommand(*args, **kwargs)¶

默认帮助命令的执行。

这继承自 HelpCommand 。

它使用以下属性对其进行了扩展。

width¶

适合一行的最大字符数。默认为 80。

Type: int

sort_commands¶

是否按字母顺序对输出中的命令进行排序。默认为“真”。

Type: bool

dm_help¶

一个三个选择参数，指示帮助命令是否应该私聊用户而不是将其发送到它接收它的频道。如果布尔值设置为 True ，则所有帮助输出都是私聊的。如果 False ，则没有任何帮助输出是私聊。如果 None ，那么当帮助消息变得太长（由超过 dm_help_threshold 字符决定）时，机器人只会发送私聊。默认为 False 。

Type: Optional[bool]

dm_help_threshold¶

如果 dm_help 设置为 None ，则分页器在将私聊发送给用户之前必须累积的字符数。默认为 1000 。

Type: Optional[int]

indent¶

从标题中缩进命令的程度。默认为 2 。

Type: int

commands_heading¶

当使用类别名称调用帮助命令时使用的命令列表的标题字符串。对 i18n 有用。默认为 "命令："

Type: str

no_category¶

存在不属于任何类别（cog）的命令时使用的字符串。对 i18n 有用。默认为 ``”无类别” ``

Type: str

paginator¶

用于对帮助命令输出进行分页的分页器。

Type: Paginator

shorten_text(text)¶: str: 缩短文本以适应 width。

get_ending_note()¶: str: 返回帮助命令的结束注释。这主要用于覆盖 i18n 目的。

add_indented_commands(commands, *, heading, max_size=None)¶

在指定标题后缩进命令列表。

格式添加到 paginator。

默认实现是命令名称由 indent 空格缩进，填充到 max_size 后跟命令的 Command.short_doc 然后缩短以适应 width。

参数

commands (Sequence[Command]) – 用于缩进输出的命令列表。
heading (str) – 要添加到输出的标题。仅当命令列表大于 0 时才添加此项。
max_size (Optional[int]) – 用于缩进间隙的最大尺寸。如果未指定，则在命令参数上调用 get_max_size()。

await send_pages()¶: 将页面输出从 paginator 发送到目的地的辅助实用程序。

add_command_formatting(command)¶

用于格式化命令和组的非缩进块的实用函数。

参数: command (Command) – 要格式化的命令。

get_destination()¶

返回 Messageable 将在其中输出帮助命令。

你可以覆盖此方法以自定义行为。

默认情况下，这将返回 context 的子频道。

返回: 将输出帮助命令的目的地。
返回类型: abc.Messageable

最小帮助命令¶

Attributes

aliases_heading
commands_heading
dm_help
dm_help_threshold
no_category
paginator
sort_commands

Methods

defadd_aliases_formatting
defadd_bot_commands_formatting
defadd_command_formatting
defadd_subcommand_formatting
defget_command_signature
defget_destination
defget_ending_note
defget_opening_note
asyncsend_pages

class qq.ext.commands.MinimalHelpCommand(*args, **kwargs)¶

具有最少输出的帮助命令的实现。

这继承自 HelpCommand。

sort_commands¶

是否按字母顺序对输出中的命令进行排序。默认为 True 。

Type: bool

commands_heading¶

当使用类别名称调用帮助命令时使用的命令列表的标题字符串。对 i18n 有用。默认为 “命令” 。

Type: str

aliases_heading¶

别名列表的标题字符串用于列出命令的别名。对 i18n 有用。默认为``”别名：”`` 。

Type: str

dm_help¶

Type: Optional[bool]

dm_help_threshold¶

如果 dm_help 设置为 None ，则分页器在将私聊发送给用户之前必须累积的字符数。默认为 1000 。

Type: Optional[int]

no_category¶

存在不属于任何类别（cog）的命令时使用的字符串。对 i18n 有用。默认为 ``”无类别:” ``

Type: str

paginator¶

用于对帮助命令输出进行分页的分页器。

Type: Paginator

await send_pages()¶: 将页面输出从 paginator 发送到目的地的辅助实用程序。

get_opening_note()¶

返回帮助命令的开头注释。这主要用于覆盖 i18n 目的。

默认实现返回

使用 `{prefix}{command_name} [命令]` 获取有关命令的更多信息。
你还可以使用 `{prefix}{command_name} [类别]` 获取有关类别的更多信息。

返回: The help command opening note.
返回类型: str

get_command_signature(command)¶

检索帮助页面的签名部分。

参数: command (Command) – 获取签名的命令。
返回: 命令的签名。
返回类型: str

get_ending_note()¶

返回帮助命令的结束注释。这主要用于覆盖 i18n 目的。

默认实现什么都不做。

返回: 帮助命令结束注释。
返回类型: str

add_bot_commands_formatting(commands, heading)¶

将带有命令的缩小机器人标题添加到输出中。

格式应该添加到 paginator。

默认实现是一个标题，下一行是由 EN SPACE (U+2002) 分隔的命令。

参数

commands (Sequence[Command]) – 属于标题的命令列表。
heading (str) – 要添加到行的标题。

add_subcommand_formatting(command)¶

在子命令上添加格式信息。

格式应该添加到 paginator。

默认实现是前缀和:attr:Command.qualified_name 可选后跟一个短划线和命令的:attr:Command.short_doc。

参数: command (Command) – 显示信息的命令。

add_aliases_formatting(aliases)¶

添加有关命令别名的格式信息。

格式应该添加到 paginator。

默认实现是 aliases_heading 跟逗号分隔的别名列表。

如果没有要格式化的别名，则不会调用此方法。

参数: aliases (Sequence[str]) – 要格式化的别名列表。

add_command_formatting(command)¶

用于格式化命令和组的实用程序函数。

参数: command (Command) – 要格式化的命令。

get_destination()¶

返回 Messageable 将在其中输出帮助命令。

你可以覆盖此方法以自定义行为。

默认情况下，这将返回 context 的子频道。

返回: 将输出帮助命令的目的地。
返回类型: abc.Messageable

分页器¶

Attributes

linesep
max_size
pages
prefix
suffix

Methods

defadd_line
defclear
defclose_page

class qq.ext.commands.Paginator(prefix='', suffix='', max_size=2000, linesep='\n')¶

一个有助于为 qq 消息分页代码块的类。

len(x): 返回分页器中的字符总数。

prefix¶

插入到每个页面的前缀。例如三个反引号。

Type: str

suffix¶

后缀附加在每一页的末尾。例如三个反引号。

Type: str

max_size¶

页面中允许的最大代码点数。

Type: int

linesep¶

行间插入的字符串。例如换行符。

Type: str

clear()¶: 清除分页器以使其没有页面。

add_line(line='', *, empty=False)¶

向当前页面添加一行。

如果该行超过 max_size，则会引发异常。

参数

line (str) – 要添加的行。
empty (bool) – 指示是否应添加另一个空行。

引发

RuntimeError – 该行对于当前的 max_size 来说太大了。

close_page()¶: 提前终止页面。

property pages¶

返回呈现的页面列表。

Type: List[str]

枚举¶

class qq.ext.commands.BucketType¶

指定桶的类型，例如冷却。

default¶: 默认存储桶在全局基础上运行。

user¶: 用户存储桶基于每个用户运行。

guild¶: 频道存储桶基于每个频道上运行。

channel¶: 子频道桶基于每个子频道上运行。

member¶: 成员存储桶基于每个成员运行。

category¶: 类别存储桶基于每个类别运行。

role¶: 身份组存储桶基于每个身份组运行。

检查¶

@qq.ext.commands.check(predicate)¶

向 Command 或其子类添加检查的装饰器。这些检查可以通过 Command.checks 访问。

这些检查应该是接受单个参数的检查函数，参数为 Context。如果检查返回类似 False的值，则在调用期间会引发 CheckFailure 异常并将其发送到 on_command_error() 事件。

如果检查函数中应该抛出异常，那么它应该是 CommandError 的子类。任何不是从它子类化的异常都将被传播，而那些子类将被发送到 on_command_error()。

名为 predicate 的特殊属性绑定到此装饰器返回的值，以检索传递给装饰器的检查函数。这允许完成以下内省和链接：

def owner_or_permissions(**perms):
    original = commands.has_permissions(**perms).predicate
    async def extended_check(ctx):
        if ctx.guild is None:
            return False
        return ctx.guild.owner_id == ctx.author.id or await original(ctx)
    return commands.check(extended_check)

注解

predicate 返回的函数始终是一个协程，即使原始函数不是协程。

实际案例

创建一个基本检查以查看命令调用者是否是你。

def check_if_it_is_me(ctx):
    return ctx.message.author.id == 114514

@bot.command()
@commands.check(check_if_it_is_me)
async def only_for_me(ctx):
    await ctx.send('我知道你!')

将常见检查转换为装饰器：

def is_me():
    def predicate(ctx):
        return ctx.message.author.id == 114514
    return commands.check(predicate)

@bot.command()
@is_me()
async def only_me(ctx):
    await ctx.send('只有你!')

参数: predicate (Callable[[Context], bool]) – 检查是否应调用命令的检查函数。

@qq.ext.commands.check_any(*checks)¶

添加了一个 check() 来检查是否有任何通过的检查会通过，即使用逻辑 OR。

如果所有检查都失败，则引发 CheckAnyFailure 以表示失败。它继承自 CheckFailure。

注解

这个函数的 predicate 属性是一个协程。

参数: *checks (Callable[[Context], bool]) – 已用 check() 装饰器装饰的检查的参数列表。
引发: TypeError – 通过的检查没有用 check() 装饰器装饰。

实际案例

创建基本检查以查看它是机器人所有者还是频道所有者：

def is_guild_owner():
    def predicate(ctx):
        return ctx.guild is not None and ctx.guild.owner_id == ctx.author.id
    return commands.check(predicate)

@bot.command()
@commands.check_any(commands.is_owner(), is_guild_owner())
async def only_for_owners(ctx):
    await ctx.send('先生你好！')

@qq.ext.commands.has_role(item)¶

添加的 check() 用于检查调用命令的成员是否具有通过指定的名称或 ID 指定的用户组。

如果指定了字符串，则必须给出用户组的确切名称，包括大写和拼写。

如果指定了整数，则必须提供用户组的确切 ID。

如果消息是在私人消息上下文中调用的，则检查将返回 False 。

此检查会引发两个特殊异常之一，如果用户缺少用户组，则为 MissingRole，如果在私人消息中使用了 NoPrivateMessage。两者都继承自 CheckFailure。

参数: item (Union[int, str]) – 要检查的用户组的名称或 ID。

@qq.ext.commands.has_any_role(*items)¶

A check() 添加的内容是检查调用命令的成员是否具有指定的 任何一个 用户组。这意味着如果他们有指定了三个用户组中的一个，那么此检查将返回 True。

与 has_role()类似，传入的名称或ID 必须准确无误。

此检查会引发两个特殊异常之一，如果用户缺少所有用户组，则为 MissingRole，如果在私人消息中使用了 NoPrivateMessage。两者都继承自 CheckFailure。

参数: items (List[Union[str, int]]) – 名称或 ID 的参数列表，用于检查成员是否具有用户组。

示例

@bot.command()
@commands.has_any_role('库开发人员', '管理员', 114514)
async def cool(ctx):
    await ctx.send('你确实很酷')

@qq.ext.commands.bot_has_role(item)¶

类似于 has_role()，但是是检查机器人本身是否具有用户组。

此检查会引发两个特殊异常之一，如果机器人缺少用户组，则为 MissingRole，如果在私人消息中使用了 NoPrivateMessage。两者都继承自 CheckFailure。

@qq.ext.commands.bot_has_any_role(*items)¶

类似于 has_any_role()，但是是检查机器人本身是否具有任何一个用户组。

此检查会引发两个特殊异常之一，如果机器人缺少所有用户组，则为 MissingRole，如果在私人消息中使用了 NoPrivateMessage。两者都继承自 CheckFailure。

@qq.ext.commands.cooldown(rate, per, type=qq.ext.commands.BucketType.default)¶

为 Command 添加冷却时间的装饰器

冷却时间允许命令在特定时间范围内仅使用特定次数。这些冷却时间可以基于每个公会、每个频道、每个用户、每个用户组或全局基础。由第三个参数 type 表示，它必须是枚举类型 BucketType。

如果冷却被触发，则 CommandOnCooldown 在 on_command_error() 和本地错误处理程序中被触发。

一个命令只能有一个冷却时间。

参数

rate (int) – 命令在触发冷却之前可以使用的次数。
per (float) – 触发时等待冷却的秒数。
type (Union[BucketType, Callable[[Message], Any]]) – 冷却时间的类型。

@qq.ext.commands.dynamic_cooldown(cooldown, type=BucketType.default)¶

为 Command 添加动态冷却时间的装饰器

这与 cooldown() 的不同之处在于它接受一个 qq.Message 类型的单个参数并且必须返回一个 Cooldown 或 None 的函数。如果返回 None ，则该冷却时间被有效绕过。

冷却时间允许命令在特定时间范围内仅使用特定次数。这些冷却时间可以基于每个公会、每个频道、每个用户、每个角色或全局基础。由 type 的第三个参数表示，它必须是枚举类型 BucketType 。

如果冷却被触发，则 CommandOnCooldown 在 on_command_error() 和本地错误处理程序中被触发。

一个命令只能有一个冷却时间。

参数

cooldown (Callable[[qq.Message], Optional[Cooldown]]) – 一个接收消息并返回冷却时间的函数，该冷却时间将应用于此调用，如果应该绕过冷却时间，则返回 None 。
type (BucketType) – 冷却时间的类型。

@qq.ext.commands.max_concurrency(number, per=qq.ext.commands.BucketType.default, *, wait=False)¶

为 Command 或其子类添加最大并发的装饰器。

这使你可以同时只允许一定数量的命令调用，例如，如果命令耗时过长或一次只有一个用户可以使用它。这与冷却时间不同，因为没有设定的等待期或令牌桶——只有设定数量的人可以运行命令。

参数

number (int) – 可以同时运行的此命令的最大调用次数。
per (BucketType) – 此并发所基于的存储桶，例如``BucketType.guild`` 将允许每个公会最多使用 number 次。
wait (bool) – 命令是否应该等待队列结束。如果这被设置为 False 则不是等到命令可以再次运行，该命令会引发 MaxConcurrencyReached 到其错误处理程序。如果这被设置为 True 则命令会等待直到它可以被执行。

@qq.ext.commands.before_invoke(coro)¶

将协程注册为调用前钩的装饰器。

这允许你在调用钩子之前引用一个不必在同一个齿轮中的几个命令。

示例

async def record_usage(ctx):
    print(ctx.author, 'used', ctx.command)

@bot.command()
@commands.before_invoke(record_usage)
async def who(ctx):
    await ctx.send('我是机器人')

class What(commands.Cog):

    @commands.command()
    async def where(self, ctx): # Output: <Nothing>
        await ctx.send('在QQ上')

    @commands.command()
    async def why(self, ctx): # Output: <Nothing>
        await ctx.send('因为有人做了我出来')

bot.add_cog(What())

@qq.ext.commands.after_invoke(coro)¶

将协程注册为调用后钩的装饰器。

这允许你在调用钩子后引用多个命令，这些命令不必位于同一个 cog 中。

@qq.ext.commands.guild_only()¶

一个 check() 表示这个命令只能在频道上下文中使用。基本上，使用该命令时不允许私人消息。

这个检查引发一个特殊的异常，NoPrivateMessage，它是从 CheckFailure 继承而来的。

@qq.ext.commands.dm_only()¶

一个 check() 表示这个命令只能在私信上下文中使用。使用该命令时只允许私信。

这个检查引发一个特殊的异常， PrivateMessageOnly，它继承自 CheckFailure。

@qq.ext.commands.is_owner()¶

一个 check() 检查调用此命令的人是否是机器人的所有者。

这是由 Bot.is_owner() 提供支持的。

这个检查引发了一个特殊的异常， NotOwner，它派生自 CheckFailure。

冷却¶

Attributes

per
rate

Methods

defcopy
defget_retry_after
defget_tokens
defreset
defupdate_rate_limit

class qq.ext.commands.Cooldown(rate, per)¶

表示命令的冷却时间。

rate¶

每 per 秒可用的令牌总数。

Type: int

per¶

以秒为单位的冷却时间长度。

Type: float

get_tokens(current=None)¶

返回应用速率限制之前可用令牌的数量。

参数: current (Optional[float]) – 自 Unix 纪元以来计算令牌的时间（以秒为单位）。如果未提供，则使用 time.time()。
返回: 应用冷却前可用的令牌数量。
返回类型: int

get_retry_after(current=None)¶

返回冷却时间重置之前的时间（以秒为单位）。

参数: current (Optional[float]) – 自 Unix 纪元以来的当前时间（以秒为单位）。如果未提供，则使用 time.time() 。
返回: 在此冷却时间将被重置之前等待的秒数。
返回类型: float

update_rate_limit(current=None)¶

更新冷却速度限制。

参数: current (Optional[float]) – 自 Unix 纪元以来更新速率限制的时间（以秒为单位）。如果未提供，则使用 time.time() 。
返回: 如果速率受限，则以秒为单位的重试时间。
返回类型: Optional[float]

reset()¶: 将冷却重置为其初始状态。

copy()¶

创建此冷却时间的副本。

返回: 此冷却时间的新实例。
返回类型: Cooldown

Context¶

Attributes

args
author
bot
channel
clean_prefix
cog
command
command_failed
current_parameter
guild
invoked_parents
invoked_subcommand
invoked_with
kwargs
me
message
prefix
subcommand_passed
valid

Methods

asyncfetch_message
defhistory
asyncinvoke
asyncreinvoke
asyncreply
asyncsend
asyncsend_help

class qq.ext.commands.Context(*, message, bot, view, args=..., kwargs=..., prefix=None, command=None, invoked_with=None, invoked_parents=..., invoked_subcommand=None, subcommand_passed=None, command_failed=False, current_parameter=None)¶

表示在其中调用命令的 context。

该类包含大量元数据，可帮助你更多地了解调用的实际情况。这个类不是手动创建的，而是作为第一个参数传递给命令的。

这个类实现了 Messageable ABC。

message¶

触发正在执行的命令的消息。

Type: Message

bot¶

包含正在执行的命令的机器人。

Type: Bot

args¶

传递给命令的转换参数列表。如果这是在 on_command_error() 事件期间访问的，则此列表可能不完整。

Type: list

kwargs¶

传递给命令的转换参数字典。类似于 args，如果在 on_command_error() 事件中访问了它，那么这个字典可能是不完整的。

Type: dict

current_parameter¶

当前正在检查和转换的参数。这仅用于内部转换器。

Type: Optional[inspect.Parameter]

prefix¶

用于调用命令的前缀。

Type: Optional[str]

command¶

当前正在调用的命令。

Type: Optional[Command]

invoked_with¶

触发此调用的命令名称。用于找出调用命令的别名。

Type: Optional[str]

invoked_parents¶

触发此调用的父级的命令名称。用于找出调用命令的别名。

例如在命令 ?a b c test 中，被调用的父对象是 ['a', 'b', 'c'] 。

Type: List[str]

invoked_subcommand¶

被调用的子命令。如果没有调用有效的子命令，则这等于 None 。

Type: Optional[Command]

subcommand_passed¶

试图调用子命令的字符串。这不必指向一个有效的注册子命令，而可以只指向一个无意义的字符串。如果没有传递任何内容来尝试调用子命令，则将其设置为 None 。

Type: Optional[str]

command_failed¶

指示命令是否未能解析、检查或调用的布尔值。

Type: bool

await invoke(command, /, *args, **kwargs)¶

这个函数是一个 coroutine。

使用给定的参数调用命令。

如果你只想调用 Command 在内部保存的回调，这很有用。

注解

这不会处理任何情况下的转换器、检查、冷却、调用前或调用后钩。它直接调用内部回调，就好像它是一个常规函数一样。

使用此函数时，你必须注意传递正确的参数。

参数

command (Command) – 将要调用的命令。
*args – 要使用的参数。
**kwargs – 要使用的关键字参数。

引发

TypeError – 缺少要调用的命令参数。

await reinvoke(*, call_hooks=False, restart=True)¶

这个函数是一个 coroutine。

再次调用命令。

这类似于 invoke() ，但是它绕过检查、冷却和错误处理程序。

注解

如果你想绕过 UserInputError 的异常，建议使用常规的 invoke() ，因为它会更自然地工作。毕竟，这最终会使用用户使用过的旧参数，因此只会再次失败。

参数

call_hooks (bool) – 是否调用调用前或调用后钩。
restart (bool) – 是从一开始还是从我们停止的地方开始调用链（即导致错误的命令）。默认是从我们停止的地方开始。

引发

ValueError – 要重新调用的 context 无效。

property valid: bool¶

检查调用 context 是否有效以进行调用。

Type: bool

property clean_prefix: str¶

清理后的调用前缀。即提及是 @名字 而不是 <@id> 。

Type: str

property cog: Optional[Cog]¶

返回与此 context 的命令关联的齿轮。如果不存在则 None 。

Type: Optional[Cog]

guild¶

返回与此 context 命令关联的频道。如果不可用则 None 。

Type: Optional[Guild]

channel¶

返回与此 context 命令关联的子频道。 Message.channel 的简写。

Type: Union[abc.Messageable]

author¶: Union[User, Member]: 返回与此 context 命令关联的作者。 Message.author 的简写

me¶: Union[Member, ClientUser]: 类似于 Guild.me ，但是它可以在私人消息 context 中返回 ClientUser。

await send_help(entity=<bot>)¶

这个函数是一个 coroutine。

如果给定，则显示指定实体的帮助命令。实体可以是命令或齿轮。

如果没有给出实体，那么它将显示整个机器人的帮助。

如果实体是一个字符串，那么它会查找它是 Cog 还是一个 Command。

注解

由于这个函数的工作方式，它不会返回类似于 command_not_found() 的东西，而是在错误输入或没有帮助命令时返回 None。

参数: entity (Optional[Union[Command, Cog, str]]) – 要为其显示帮助的实体。
返回: 帮助命令的结果，如果有的话。
返回类型: Any

await fetch_message(id, /)¶

这个函数是一个 coroutine。从目的地检索单个 Message。

参数

id (str) – 要查找的消息 ID。

引发

NotFound – 未找到指定的消息。
Forbidden – 你没有获取消息所需的权限。
HTTPException – 检索消息失败。

返回

消息要求。

返回类型

Message

history(*, limit=100, before=None, after=None, around=None, oldest_first=None)¶

返回允许接收目标消息历史记录的 AsyncIterator。

实际案例

用途

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

扁平化为列表:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

所有参数均为可选参数。

参数

limit (Optional[int]) – 要检索的消息数。如果为 None ，则检索频道中的每条消息。但是请注意，这会使其运行缓慢。
before (Optional[datetime.datetime]) – 检索此日期或消息之前的消息。如果提供了日期时间，建议使用 UTC 感知日期时间。如果 datetime 是本地的，则假定它是本地时间。
after (Optional[datetime.datetime]) – 在此日期或消息之后检索消息。如果提供了日期时间，建议使用 UTC 感知日期时间。如果 datetime 是本地的，则假定它是本地时间。
around (Optional[datetime.datetime]) – 检索围绕此日期或消息的消息。如果提供了日期时间，建议使用 UTC 感知日期时间。如果 datetime 是本地的，则假定它是本地时间。使用此参数时，最大限制为 101。请注意，如果限制为偶数，则最多返回 limit + 1 条消息。
oldest_first (Optional[bool]) – 如果设置为 True，以最旧->最新的顺序返回消息。如果指定了 after ，则默认为 True ，否则为 False 。

引发

Forbidden – 你无权获取频道消息历史记录。
HTTPException – 获取消息历史记录的请求失败。

生成器

Message – 已解析消息数据的消息。

await reply(content=None, **kwargs)¶

这个函数是一个 coroutine。 abc.Messageable.send() 回复 Message 的快捷方法。

引发

HTTPException – 发送消息失败。
Forbidden – 你没有发送消息的适当权限。
InvalidArgument – files 列表的大小不合适，或者你同时指定了 file 和 files。

返回

发送的消息。

返回类型

Message

await send(content=None, *, image=None, msg_id='MESSAGE_CREATE', event_id=None, reference=None, mention_author=None, ark=None, embed=None, markdown=None, file=None, delete_after=None, replace_url=True)¶

这个函数是一个 coroutine。使用给定的内容向目的地发送消息。 content 必须是可以通过 str(content) 转换为字符串的类型。如果不填入 reference 将会被腾讯视为主动消息。如果是主动信息，输出将会是 audit_id。

参数

content (Optional[str]) – 发送的信息内容。
image (str) – 要发送的图片链接
ark (Optional[qq.Ark]) – 要发送的 Ark 类
embed (Optional[qq.Embed]) – 要发送的 Embed 类
markdown (Optional[qq.Markdown]) – 要发送的 Markdown 类
msg_id (Optional[str]) – 被动消息使用的消息 ID
event_id (Optional[str]) –
被动消息使用的事件 ID

注解

如果不使用 msg_id ，系统将判断为主动消息，主动消息默认每天往每个频道可推送的消息数是 20 条，超过会被限制。
reference (Union[Message, MessageReference, PartialMessage]) – 对你正在回复的 Message 的引用，可以使用 to_reference() 创建或直接作为 Message 传递。
mention_author (Optional[qq.Member]) – 如果设置了，将会在消息前面提及该用户。
file (Optional[qq.File]) – 本地上传的图片文件。
delete_after (Optional[float]) – 如果设置了，则等待该秒数之后自动撤回消息。如果删除失败，则它会被静默忽略。
replace_url (Optional[bool]) – 是否添加转义字符来绕过腾讯的链接检测。默认为 True 。

引发

HTTPException – 发送信息失败。
Forbidden – 你没有发送消息的适当权限。
InvalidArgument – reference 不是 Message 、 MessageReference 或 PartialMessage 。

返回

发送的消息。

返回类型

Union[Message, MessageAudit]

转换器¶

class qq.ext.commands.Converter(*args, **kwargs)¶

需要传递 Context 的自定义转换器的基类才有用。

这允许你实现功能类似于特殊情况的 qq 类的转换器。

派生自此的类应覆盖 convert() 方法以执行其转换逻辑。这个方法必须是一个协程。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.ObjectConverter(*args, **kwargs)¶

转换为 Object。

参数必须遵循有效的 ID 或提及格式（例如`<@80088516616269824>`）。

查找策略如下（按顺序）：

通过ID查找。
按成员、身份组或频道提及查找。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.MemberConverter(*args, **kwargs)¶

转换为 Member。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。

2. 按提及查找。 4. 按名称查找。 5. 按昵称查找。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.UserConverter(*args, **kwargs)¶

转换为 User。

所有查找都是通过全局用户缓存进行的。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.MessageConverter(*args, **kwargs)¶

转换为 qq.Message。

查找策略如下（按顺序）：

按 {channel ID}-{message ID} 查找
按消息 ID 查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.PartialMessageConverter(*args, **kwargs)¶

转换为 qq.PartialMessage。

创建策略如下（按顺序）：

通过 {channel ID}-{message ID}
通过消息 ID

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.GuildChannelConverter(*args, **kwargs)¶

转换为 GuildChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.TextChannelConverter(*args, **kwargs)¶

转换为 TextChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.VoiceChannelConverter(*args, **kwargs)¶

转换为 VoiceChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.CategoryChannelConverter(*args, **kwargs)¶

转换为 CategoryChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.ThreadChannelConverter(*args, **kwargs)¶

转换为 ThreadChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.LiveChannelConverter(*args, **kwargs)¶

转换为 LiveChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.AppChannelConverter(*args, **kwargs)¶

转换为 AppChannel。

所有查找都是通过本地频道进行的。如果在 DM context 中，则查找由全局缓存完成。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.GuildConverter(*args, **kwargs)¶

转换为 Guild。

查找策略如下（按顺序）：

通过 ID 查找.
按名称查找。（对于具有多个匹配名称的频道，没有消歧义）。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.RoleConverter(*args, **kwargs)¶

转换为 Role。

所有查找都是通过本地频道进行的。如果在 DM context 中，转换器会引发 NoPrivateMessage 异常。

查找策略如下（按顺序）：

通过 ID 查找。
通过提及查找。
按名称查找

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.ColourConverter(*args, **kwargs)¶

转换为 Colour。

接受以下格式：

0x<hex>
#<hex>
0x#<hex>
rgb(<number>, <number>, <number>)
Colour 中的任何 classmethod
- 名称中的``_`` 可以选择替换为空格。

像 CSS 一样，<number> 可以是 0-255 或 0-100%，而 <hex> 可以是 6 位十六进制数字或 3 位十六进制快捷方式（例如 fff）。

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.clean_content(*, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False)¶

将参数转换为提及所述内容的清理版本。

这与 clean_content 的行为类似。

fix_channel_mentions¶

是否清理频道提及。

Type: bool

use_nicknames¶

转换提及时是否使用昵称。

Type: bool

escape_markdown¶

是否也转义特殊的 Markdown 字符。

Type: bool

remove_markdown¶

是否也删除特殊的 Markdown 字符。 escape_markdown 不支持此选项

1.7 新版功能.

Type: bool

await convert(ctx, argument)¶

这个函数是一个 coroutine。

要覆盖以执行转换逻辑的方法。

如果在转换时发现错误，建议引发 CommandError 派生异常，因为它会正确传播到错误处理程序。

参数

ctx (Context) – 正在使用参数的调用 context 。
argument (str) – 正在转换的参数。

引发

CommandError – 转换参数时发生一般异常。
BadArgument – 转换器无法转换参数。

class qq.ext.commands.Greedy¶

一个特殊的转换器，贪婪地消耗参数，直到它不能。由于这种行为，大多数输入错误都被悄悄丢弃，因为它被用作何时停止解析的指示器。

当遇到解析器错误时，贪婪转换器停止转换，撤消内部字符串解析例程，并继续定期解析。

例如，在以下代码中：

@commands.command()
async def test(ctx, numbers: Greedy[int], reason: str):
    await ctx.send("numbers: {}, reason: {}".format(numbers, reason))

调用 [p]test 1 2 3 4 5 6 hello 会传递 numbers 为 [1, 2, 3, 4, 5, 6] 和 reason 为 hello.

有关更多信息，请查看特殊转换器。

await qq.ext.commands.run_converters(ctx, converter, argument, param)¶

这个函数是一个 coroutine。

为给定的转换器、参数和参数运行转换器。

此函数执行的工作与库在后台执行的工作相同。

参数

ctx (Context) – 在其下运行转换器的调用 context 。
converter (Any) – 要运行的转换器，这对应于函数中的注释。
argument (str) – 要转换为的参数。
param (inspect.Parameter) – 被转换的参数。这主要用于错误报告。

引发

CommandError – 转换器无法转换。

返回

由此产生的转换。

返回类型

Any

标志转换器¶

class qq.ext.commands.FlagConverter¶

允许用户友好标志语法的转换器。

这些标志是使用 PEP 526 类型注释定义的，类似于 Python 模块 dataclasses 。有关此转换器如何工作的更多信息，请查看相应的文档。

iter(x): 返回 (flag_name, flag_value) 对的迭代器。例如，这允许将其构造为字典或对列表。请注意，未显示别名。

参数

case_insensitive (bool) – 用于切换标志解析不区分大小写的类参数。如果为 True ，则以不区分大小写的方式解析标志。默认为 False 。
prefix (str) – 所有标志都必须带有前缀的前缀。默认情况下没有前缀。
delimiter (str) – 将标志的参数与标志的名称分开的分隔符。默认情况下，这是 : 。

classmethod get_flags()¶: Dict[str, Flag]: 标志名称到此转换器具有的标志对象的映射。

classmethod await convert(ctx, argument)¶

这个函数是一个 coroutine。

实际将参数转换为标志映射的方法。

参数

cls (Type[FlagConverter]) – 标志转换器类。
ctx (Context) – 调用 context 。
argument (str) – 要转换的参数。

引发

FlagError – 与标志相关的解析错误。
CommandError – 命令相关的错误。

返回

已解析所有标志的标志转换器实例。

返回类型

FlagConverter

class qq.ext.commands.Flag¶

表示 FlagConverter 的标志参数。

flag() 函数有助于创建这些标志对象，但没有必要这样做。这些不能手动构建。

name¶

标志的名称。

Type: str

aliases¶

标志名称的别名。

Type: List[str]

attribute¶

与此标志对应的类中的属性。

Type: str

default¶

标志的默认值（如果可用）。

Type: Any

annotation¶

标志的基础评估注释。

Type: Any

max_args¶

标志可以接受的最大参数数。负值表示无限数量的参数。

Type: int

override¶

多个给定值是否覆盖先前的值。

Type: bool

property required: bool¶

是否需要标志。

必需标志没有默认值。

Type: bool

qq.ext.commands.flag(*, name=..., aliases=..., default=..., max_args=..., override=...)¶

覆盖底层 FlagConverter 类属性的默认功能和参数。

参数

name (str) – 标志名。如果未给出，则默认为属性名称。
aliases (List[str]) – 标志名称的别名。如果没有给出，则不会设置别名。
default (Any) – 默认参数。这可以是一个值，也可以是一个以 Context 作为其唯一参数的可调用对象。如果未给出，则默认为赋予属性的默认值。
max_args (int) – 标志可以接受的最大参数数。负值表示无限数量的参数。默认值取决于给定的注释。
override (bool) – 多个给定值是否覆盖先前的值。默认值取决于给定的注释。