API 参考

以下部分概述了 qq.py 的 API。

注解

此模块使用 Python 日志记录模块以独立于输出的方式记录诊断和错误。 如果没有配置日志模块，这些日志将不会输出到任何地方。 有关如何使用 qq.py 设置和使用日志记录模块的更多信息，请参阅 设置日志。

版本相关信息

查询库的版本信息主要有两种方式。

qq.version_info

一个命名元组，类似于 sys.version_info.

就像 sys.version_info ， releaselevel 的有效值为

alpha 、 beta 、 candidate 和 final 。

qq.__version__

版本的字符串表示。 e.g. '1.0.0rc1'。 这是基于 PEP 440 。

客户端

Client

Attributes
Methods
class qq.Client(*, loop=None, **options)

代表了客户端与 QQ 之间的连接 此类用于与 QQ WebSocket 和 API 进行交互。 许多选项可以传递给 Client。

参数

  • max_messages (Optional[int]) – 要存储在内部消息缓存中的最大消息数。 这默认为 1000 。传入 None 会禁用消息缓存。

  • loop (Optional[asyncio.AbstractEventLoop]) – 用于异步操作的 asyncio.AbstractEventLoop 。 默认为 None ，在这种情况下，默认事件循环通过 asyncio.get_event_loop() 使用。

  • connector (Optional[aiohttp.BaseConnector]) – 用于连接池的连接器。

  • proxy (Optional[str]) – 代理网址。

  • proxy_auth (Optional[aiohttp.BasicAuth]) – 代表代理 HTTP 基本授权的对象。

  • shard_id (Optional[int]) – 从 0 开始并且小于 shard_count 的整数。

  • shard_count (Optional[int]) – 分片总数。

  • intents (Intents) –

    你要为会话启用的意图。 这是一种禁用和启用某些网关事件触发和发送的方法。

    如果未给出，则默认为默认的 Intents 类。

  • heartbeat_timeout (float) – 在未收到 HEARTBEAT_ACK 的情况下超时和重新启动 WebSocket 之前的最大秒数。 如果处理初始数据包花费的时间太长而导致你断开连接，则很有用。默认超时为 59 秒。

  • guild_ready_timeout (float) – 在准备成员缓存和触发 READY 之前等待 GUILD_CREATE 流结束的最大秒数。默认超时为 2 秒。

ws

客户端当前连接到的 websocket 网关。可能是 None 。

loop

客户端用于异步操作的事件循环。

Type

asyncio.AbstractEventLoop

@event

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

示例

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

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

async for ... in 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 – 已解析频道数据的频道。

await on_error(event_method, *args, **kwargs)

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

await login(token)

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

参数

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

引发

  • LoginFailure – 传递了错误的凭据。

  • HTTPException – 发生未知的 HTTP 相关错误，通常是当它不是 200 或已知的错误。

property latency: float

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

Type

float

is_ready()

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

property user: Optional[qq.user.ClientUser]

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

Type

Optional[ClientUser]

property guilds: List[qq.guild.Guild]

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

Type

List[Guild]

property cached_messages: Sequence[Message]

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

Type

Sequence[Message]

get_guild(id, /)

返回具有给定 ID 的频道。

参数

id (int) – 要搜索的 ID。

返回

如果未找到频道则 None 。

返回类型

Optional[Guild]

get_user(id, /)

返回具有给定 ID 的用户。

参数

id (int) – 要搜索的 ID。

返回

如果未找到，则为 None 。

返回类型

Optional[User]

await fetch_guild(guild_id)

这个函数是一个 coroutine。

从 ID 中检索 Guild 。

注解

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

注解

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

参数

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

引发
返回

来自ID的频道。

返回类型

Guild

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 – 收到意外的关键字参数。

clear()

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

is_closed()

bool: 指示 websocket 连接是否关闭。

await connect(*, reconnect=True)

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

参数

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

引发

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

  • ConnectionClosed – websocket 连接已终止。

await close()

这个函数是一个 coroutine。 关闭与 QQ 的连接。

get_channel(id, /)

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

返回

返回的子频道或 ``None``（如果未找到）。

返回类型

Optional[Union[abc.GuildChannel, Thread, abc.PrivateChannel]]

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 – 客户端可以看到的成员。

await wait_until_ready()

这个函数是一个 coroutine。 等到客户端的内部缓存准备就绪。

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 create_dm(user, guild)

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

参数

  • user (User) – 用于创建私信的用户。

  • guild – 用于创建私信的源频道

返回

创建的频道。

返回类型

DMChannel

AutoShardedClient

Attributes
Methods
class qq.AutoShardedClient(*args, loop=None, **kwargs)

一个类似于 Client 的客户端， 只是它将用户分片的复杂性处理成一个更易于管理和透明的单进程机器人。 当使用这个客户端时，你将能够像 Client 一样使用它，就像它是一个带有单个分片的常规客户端，当在内部实现时，它被分成多个分片。 这使你不必处理 IPC 或其他复杂的基础。 建议人数超过1000人以上才使用此客户端。 如果没有提供 shard_count，则库将使用 Bot Gateway 端点调用来确定要使用多少个分片。 如果给出了 shard_ids 参数，则这些分片 ID 将用于启动内部分片。 请注意，如果使用 shard_count ，则必须提供。默认情况下，当省略时，客户端将启动从 0 到 shard_count - 1 的分片。

shard_ids

用于启动分片的可选 shard_id 列表。

Type

Optional[List[int]]

property latency: float

以秒为单位测量 HEARTBEAT 和 HEARTBEAT_ACK 之间的延迟。 这与 Client.latency() 的操作类似，但是它使用每个分片延迟的平均延迟。 要获取分片延迟列表，请检查 latencies 属性。如果没有分片，则返回 nan 。

Type

float

property latencies: List[Tuple[int, float]]

HEARTBEAT 和 HEARTBEAT_ACK 之间的延迟列表（以秒为单位）。 这将返回一个包含元素 (shard_id, latency) 的元组列表。

Type

List[Tuple[int, float]]

get_shard(shard_id)

Optional[ShardInfo]: 获取给定分片 ID 的分片信息，如果未找到则为 None 。

property shards: Dict[int, qq.shard.ShardInfo]

返回分片 ID 到其各自信息对象的映射。

Type

Mapping[int, ShardInfo]

await connect(*, reconnect=True)

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

参数

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

引发

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

  • ConnectionClosed – websocket 连接已终止。

await close()

这个函数是一个 coroutine。 关闭与 QQ 的连接。

is_ws_ratelimited()

bool: websocket 当前是否有速率限制。 此实现检查是否有任何分片受速率限制。如需更精细的控制，请考虑 ShardInfo.is_ws_ratelimited() 。

事件参考

本节概述了 Client 监听的不同类型的事件。

注册事件有两种方式，第一种方式是通过使用:meth:Client.event。第二种方法是通过子类化 Client 并覆盖特定事件。例如：

import qq

class MyClient(qq.Client):
    async def on_message(self, message):
        if message.author == self.user:
            return

        if message.content.startswith('$hello'):
            await message.channel.send('Hello World!')

如果事件处理程序引发异常， on_error() 将被调用来处理它，默认打印回溯并忽略异常。

警告

所有事件都必须是 coroutine。如果不是，那么你可能会遇到意外错误。为了将函数转换为协程，它们必须是“async def”函数。

qq.on_connect()

当客户端成功连接到 QQ 时调用。这与客户端完全准备好不同，请参阅:func:on_ready。 on_ready() 上的警告也适用。

qq.on_shard_connect(shard_id)

类似于:func:on_connect，除了被:class:AutoShardedClient 用来表示特定分片 ID 何时连接到 QQ。

1.4 新版功能.

参数

shard_id (int) – 已连接的分片 ID。

qq.on_disconnect()

当客户端与 QQ 断开连接或尝试连接 QQ 失败时调用。 这可能通过互联网断开、明确调用关闭或 QQ 以一种或另一种方式终止连接而发生。

这个函数可以在没有相应的:func:on_connect 调用的情况下被多次调用。

qq.on_shard_disconnect(shard_id)

类似于:func:on_disconnect，除了被:class:AutoShardedClient 用来表示特定分片 ID 何时与 QQ 断开连接。

1.4 新版功能.

参数

shard_id (int) – 已断开连接的分片 ID。

qq.on_ready()

当客户端准备好从 QQ 接收到的数据时调用。通常在登录成功后 Client.guilds 和 co. 被填满后。

此函数不能保证是第一个调用的事件。同样，这个函数也 不能 保证只被调用一次。 库实现了重新连接逻辑，因此只要 RESUME 请求失败，就会最终调用此事件。

qq.on_shard_ready(shard_id)

类似于:func:on_ready，除了被:class:AutoShardedClient 用来表示特定分片ID 何时准备就绪。

参数

shard_id (int) – 准备好的分片 ID。

qq.on_resumed()

当客户端恢复会话时调用。

qq.on_shard_resumed(shard_id)

类似于:func:on_resumed，除了被:class:AutoShardedClient 用来表示特定分片ID 何时恢复会话。

1.4 新版功能.

参数

shard_id (int) – 已恢复的分片 ID。

qq.on_error(event, *args, **kwargs)

通常，当事件引发未捕获的异常时，会将回溯打印到 stderr 并忽略异常。 如果你想更改此行为并出于任何原因自己处理异常，则可以覆盖此事件。完成后，将取消打印回溯的默认操作。

引发异常的信息和异常本身可以通过标准调用 sys.exc_info() 来检索。

如果你希望异常从 Client 类传播出去，你可以定义一个 on_error 处理程序，它由一个空的 raise 语句 组成。 on_error 引发的异常不会以任何方式由 Client 处理。

注解

on_error 只会被分派到 Client.event()。

它不会被 Client.wait_for() 接收，或者，如果有使用，机器人 侦听器， 例如 listen() 或 listener()。

参数

  • event (str) – 引发异常的事件的名称。

  • args – 引发异常的事件的位置参数。

  • kwargs – 引发异常的事件的关键字参数。

qq.on_socket_event_type(event_type)

每当从 WebSocket 接收到 websocket 事件时调用。

这主要用于记录你从 QQ 网关接收到的事件数量。

2.0 新版功能.

参数

event_type (str) – 收到的来自 QQ 的事件类型，例如 READY.

qq.on_socket_raw_receive(msg)

在处理和解析消息之前从 WebSocket 完全接收到消息时调用。 当收到完整的消息并且不以任何方式解析传递的数据时，始终调度此事件。

这仅对获取 WebSocket 流和调试有用。

这需要在 Client 中设置 enable_debug_events 设置。

注解

这仅适用于从客户端 WebSocket 接收的消息。语音 WebSocket 不会触发此事件。

参数

msg (str) – 从 WebSocket 传入的消息。

qq.on_socket_raw_send(payload)

在发送消息之前在 WebSocket 上完成发送操作时调用。传递的参数是发送到 WebSocket 的消息。

这仅对获取 WebSocket 流和调试有用。

这需要在 Client 中设置 enable_debug_events 设置。

注解

这仅适用于从客户端 WebSocket 发送的消息。语音 WebSocket 不会触发此事件。

参数

payload – 即将传递到 WebSocket 库的消息。它可以是 bytes 表示二进制消息或 str 表示常规文本消息。

qq.on_audio_start(audio)

音频开始播放时调用。

这需要启用 Intents.audio。

参数

audio – 音频资料。

qq.on_audio_stop(audio)

音频停止播放时调用。

这需要启用 Intents.audio。

参数

audio – 音频资料。

qq.on_mic_start(audio)

有人上麦时时调用。

这需要启用 Intents.audio。

参数

audio – 音频资料。

qq.on_mic_stop(audio)

有人下麦时时调用。

这需要启用 Intents.audio。

参数

audio – 音频资料。

qq.on_message(message)

在创建和发送 Message 时调用。

这需要启用 Intents.messages。

警告

你的机器人自己的消息通过此事件发送。 这可能会导致“递归”的情况，具体取决于你的机器人的编程方式。 如果你希望机器人不回复自己，请考虑检查用户 ID。注意 Bot 没有这个问题。

参数

message (Message) – 当前消息。

qq.on_message_delete(message)

当删除一条信息时调用。如果内部信息缓存中没有该信息，则不会调用此事件。 如果消息太旧或客户端参加了高流量频道，则消息可能不在缓存中。

如果出现这种情况，请增加 max_messages 参数，或改用 on_raw_message_delete() 事件。

这需要启用 Intents.messages。

参数

message (Message) – 删除的消息

qq.on_raw_message_delete(payload)

当删除一条消息时调用。与 on_message_delete() 不同，无论消息是否在内部消息缓存中，都会调用该函数。

如果在信息缓存中找到了信息，则可通过 RawMessageDeleteEvent.cached_message 访问该信息。

这需要启用 Intents.messages。

参数

payload (RawMessageDeleteEvent) – 原始事件有效载荷数据。

qq.on_message_audit(audit)

在消息审核通过或拒绝时调用。

这需要启用 Intents.audit。

参数

audit – 当前消息审核。

qq.on_guild_channel_delete(channel)
qq.on_guild_channel_create(channel)

每当删除或创建子频道时调用。

请注意，你可以从 guild 获取频道。

这需要启用 Intents.guilds。

参数

channel (abc.GuildChannel) – 创建或删除的频道频道。

qq.on_guild_channel_update(before, after)

每当更新子频道时调用。 例如 更改名称。

这需要启用 Intents.guilds。

参数
qq.on_member_join(member)
qq.on_member_remove(member)

当 Member 离开或加入 Guild 时调用。

这需要启用 Intents.members。

参数

member (Member) – 加入或离开的成员。

qq.on_member_update(before, after)

当 Member 更新他们的个人资料时调用。

这需要启用 Intents.members。

参数

  • before (Member) – 更新成员的旧信息。

  • after (Member) – 更新成员的新信息。

qq.on_guild_join(guild)

当 Guild 由 Client 创建或当:class:Client 加入频道时调用。

这需要启用 Intents.guilds。

参数

guild (Guild) – 加入的频道。

qq.on_guild_remove(guild)

当 Guild 从 Client 中移除时调用。

这是通过但不限于以下情况发生的：

  • 客户端被踢了。

  • 客户端离开了频道。

  • 客户端或频道所有者删除了频道。

为了调用这个事件，Client 必须是频道的一部分。 （即它是 Client.guilds 的一部分）

这需要启用 Intents.guilds。

参数

guild (Guild) – 被移除的频道。

qq.on_guild_update(before, after)

当 Guild 更新时调用，例如：

  • 更名

  • 等等

这需要启用 Intents.guilds 。

参数

  • before (Guild) – 更新前的频道。

  • after (Guild) – 更新后的频道。

qq.on_raw_interaction(payload)

当触发了互动时调用。与:func:on_interaction 不同，无论内部消息缓存的状态如何，以及数据是否标准，都会调用它。

这需要启用 Intents.interaction。

参数

payload (RawInteractionActionEvent) – 原始事件负载数据。

qq.on_interaction(payload)

当触发了互动时调用。如果数据不标准，则不会调用此事件。

这需要启用 Intents.interaction。

参数

payload (Interaction) – 互动的信息。

qq.on_reaction_add(reaction, user)

当消息添加了反应时调用。类似于:func:on_message_edit ，如果在内部消息缓存中找不到该消息，则不会调用此事件。 考虑使用 on_raw_reaction_add() 代替。

注解

要让 Message 得到响应，请通过:attr:Reaction.message 访问它。

这需要启用 Intents.reactions 。

参数

  • reaction (Reaction) – 反应的当前状态。

  • user (Union[Member, User]) – 添加反应的用户。

qq.on_raw_reaction_add(payload)

当消息添加了反应时调用。与 on_reaction_add() 不同，无论内部消息缓存的状态如何，都会调用它。

这需要启用 Intents.reactions。

参数

payload (RawReactionActionEvent) – 原始事件负载数据。

qq.on_reaction_remove(reaction, user)

当消息已删除反应时调用。与 on_message_edit() 类似，如果在内部消息缓存中找不到该消息，则不会调用此事件。

注解

要获得正在响应的消息，请通过:attr:Reaction.message 访问它。

这需要同时启用 Intents.reactions 和 Intents.members 。

参数

  • reaction (Reaction) – 反应的当前状态。

  • user (Union[Member, User]) – 添加反应的用户。

qq.on_raw_reaction_remove(payload)

当消息已删除反应时调用。与:func:on_reaction_remove 不同，无论内部消息缓存的状态如何，都会调用它。

这需要启用 Intents.reactions。

参数

payload (RawReactionActionEvent) – 原始事件负载数据。

qq.on_reaction_clear(message, reactions)

当一条消息的所有反应都被移除时调用。类似于:func:on_message_edit ， 如果在内部消息缓存中找不到该消息，则不会调用此事件。考虑使用 on_raw_reaction_clear() 代替。

这需要启用 Intents.reactions 。

参数

  • message (Message) – 已清除其反应的消息。

  • reactions (List[Reaction]) – 被移除的反应。

qq.on_raw_reaction_clear(payload)

当消息的所有反应都被删除时调用。与:func:on_reaction_clear 不同，无论内部消息缓存的状态如何，都会调用它。

这需要启用 Intents.reactions。

参数

payload (RawReactionClearEvent) – 原始事件负载数据。

qq.on_reaction_clear_emoji(reaction)

当消息已删除特定反应时调用。类似于:func:on_message_edit，如果在内部消息缓存中找不到该消息，则不会调用此事件。 考虑使用 on_raw_reaction_clear_emoji() 代替。

这需要启用 Intents.reactions。

1.3 新版功能.

参数

reaction (Reaction) – 得到清除的反应。

qq.on_raw_reaction_clear_emoji(payload)

当消息已删除特定反应时调用。与 on_reaction_clear_emoji() 不同，无论内部消息缓存的状态如何，它都会被调用。

这需要启用 Intents.reactions。

1.3 新版功能.

参数

payload (RawReactionClearEmojiEvent) – 原始事件负载数据。

实用功能

qq.utils.find(predicate, seq)

返回在满足 predicate 的序列中找到的第一个元素的帮助器。例如：

member = qq.utils.find(lambda m: m.name == 'Foo', channel.guild.members)

会找到第一个名字是 Mighty 的 Member 并返回它。 如果未找到条目，则返回 None 。 这与 filter() 不同，因为它在找到有效条目时停止。

参数

  • predicate – 返回类似布尔值的结果的函数。

  • seq (collections.abc.Iterable) – 要搜索的可迭代对象。

qq.utils.get(iterable, **attrs)

一个帮助器，它返回可迭代对象中满足 attrs 中传递的所有特征的第一个元素。这是 find() 的替代方案。 指定多个属性时，将使用逻辑 AND 而不是逻辑 OR 检查它们。 这意味着他们必须满足传入的每个属性，而不是其中之一。 要进行嵌套属性搜索（即通过 x.y 搜索），然后传入 x__y 作为关键字参数。 如果没有找到与传递的属性匹配的属性，则返回 None 。

实际案例

基本用法:

member = qq.utils.get(message.guild.members, name='Foo')

多属性匹配:

member = qq.utils.get(message.guild.members, name='Foo', bot=False)

嵌套属性匹配：

member = qq.utils.get(message.guild.members, avatar__url='xxx', name='Foo')
参数

  • iterable – 一个可迭代的搜索对象。

  • **attrs – 表示要搜索的属性的关键字参数。

qq.utils.remove_markdown(text, *, ignore_links=True)

删除 Markdown 字符的辅助函数。

注解

此功能不会解析 Markdown ，可能会从原文中删除含义。 例如， 如果输入包含 10 * 5 ，那么它将被转换为 10 5 。

参数

  • text (str) – 要从中删除Markdown的文本。

  • ignore_links (bool) – 删除 Markdown 时是否留下链接。 例如，如果文本中的 URL 包含诸如 _ 之类的字符，则它将单独保留。默认为 True 。

返回

删除了 Markdown 特殊字符的文本。

返回类型

str

qq.utils.escape_markdown(text, *, as_needed=False, ignore_links=True)

转义 Markdown 的辅助函数。

参数

  • text (str) – 转义 markdown 的文本。

  • as_needed (bool) – 是否根据需要转义Markdown字符。 这意味着如果没有必要，它不会转义无关的字符，例如 hello 转义为 \\hello 而不是 \\hello\\ 。 但是请注意，这可能会让你面临一些奇怪的语法滥用。默认为 False 。

  • ignore_links (bool) – 转义 markdown 时是否留下链接。例如，如果文本中的 URL 包含诸如 _ 之类的字符，则它将单独保留。 as_needed 不支持此选项。 默认为 True 。

返回

带有 Markdown 特殊字符的文本用斜杠转义。

返回类型

str

qq.utils.escape_mentions(text)

一个帮助函数，可以转义所有成员，身份组和用户提及。

注解

这不包括频道提及。

注解

要对消息中的提及内容进行更精细的控制，请参阅 AllowedMentions 类。

参数

text (str) – 要转义的文本。

返回

删除了提及的文本。

返回类型

str

await qq.utils.sleep_until(when, result=None)

这个函数是一个 coroutine。 睡眠到指定时间。 如果提供的时间在过去，则此函数将立即返回。

参数

  • when (datetime.datetime) – 休眠到的时间戳。如果日期时间是 native 的，那么它被假定为本地时间。

  • result (Any) – 如果提供，则在协程完成时返回给调用者。

qq.utils.utcnow()

一个辅助函数，用于返回表示当前时间的 UTC datetime。 这应该比 datetime.datetime.utcnow() 更可取，因为与标准库中的原始日期时间相比，它是一个 aware 的 datetime。

返回

UTC 中的当前 datetime datetime。

返回类型

datetime.datetime

qq.utils.format_dt(dt, /, style=None)

用于格式化 datetime.以在 QQ 中展示的辅助函数。

样式

示例输出

描述

t

22:57

短时间

T

22:57:58

长时间

d

17/05/2016

短日期

D

17 May 2016

长日期

f

17 May 2016 22:57

短日期时间

F

Tuesday, 17 May 2016 22:57

长日期时间

R

5 years ago

相对时间

请注意，确切的输出取决于客户端中用户的区域设置。显示的示例输出使用 en-GB 语言环境。

参数

  • dt (datetime.datetime) – 要格式化的 datetime 。

  • style (str) – 格式化日期时间的样式。

返回

格式化的字符串。

返回类型

str

枚举

API 为某些类型的字符串提供了一些枚举，以避免 API 被字符串类型化，以防将来字符串发生变化。 所有枚举都是内部类的子类，它模仿了 enum.Enum 的行为。

class qq.ChannelType

指定频道的类型。

text

一个文字频道。

voice

一个语音通道。

category

一个分类频道。

app

一个应用频道。

thread

一个论坛频道。

live

一个直播频道。

class qq.AudioStatusType

音频的状态。

START

开始播放操作。

PAUSE

暂停播放操作。

RESUME

继续播放操作。

STOP

停止播放操作

异步迭代器

一些 API 函数返回一个“异步迭代器”。 异步迭代器是能够在 async for 语句 中使用的东西。

这些异步迭代器可以按如下方式使用：:

async for elem in await client.fetch_guilds():
    # do stuff with elem here

某些实用程序可以更轻松地使用异步迭代器，详情如下。

class qq.AsyncIterator

代表“AsyncIterator”概念。 请注意，不存在这样的类，它纯粹是抽象的。

async for x in y

迭代异步迭代器的内容。

await next()

这个函数是一个 coroutine。

如果可能，将迭代器推进 1。 如果没有找到更多的项目，那么这会引发 NoMoreItems。

await get(**attrs)

这个函数是一个 coroutine。

类似于 utils.get() ，除了运行异步迭代器。

获取名为 “Test” 的频道：

guild = await await client.fetch_guilds().get(name='Test')
await find(predicate)

这个函数是一个 coroutine。

类似于 utils.find()，除了运行异步迭代器。

不像:func:utils.find，提供的检查函数可以是 coroutine 。

参数

predicate – 要使用的检查函数。 可能是 coroutine 。

返回

为检查函数返回“True”或“None”的第一个元素。

await flatten()

这个函数是一个 coroutine。

将异步迭代器扁平化为一个包含所有元素的列表。

返回

异步迭代器中每个元素的列表。

返回类型

list

chunk(max_size)

将项目收集到最大给定大小的块中。 另一个 AsyncIterator 被返回，它将项目收集到给定大小的 lists 中。 最大块大小必须是正整数。

警告

收集的最后一个块可能没有“max_size”那么大。

参数

max_size – 单个块的大小。

返回类型

AsyncIterator

map(func)

这类似于内置的 map 函数。 另一个类：AsyncIterator 被返回，它在它迭代的每个元素上执行该函数。 这个函数可以是一个普通函数，也可以是一个 coroutine。 创建内容迭代器:

def transform(guild):
    return guild.name

async for content in await client.fetch_guilds().map(transform):
    guild_name = content
参数

func – 在每个元素上调用的函数。 可能是 coroutine 。

返回类型

AsyncIterator

filter(predicate)

这类似于内置的 filter 函数。 返回另一个 AsyncIterator 过滤原始异步迭代器。 该检查函数可以是常规函数或 coroutine 。 获取非名为 ‘Test’ 的频道：

def predicate(guild):
    return guild.name == 'Test'

async for elem in await client.fetch_guilds().filter(predicate):
    ...
参数

predicate – 调用每个元素的检查函数。 可能是 coroutine。

返回类型

AsyncIterator

抽象基类

一个 抽象基类 (也被称为 abc) 是模型可以继承以获取行为的类。 抽象基类不应该被实例化。 它们主要用于 isinstance() 和 issubclass()。

GuildChannel

Attributes
Methods
class qq.abc.GuildChannel

详细介绍 QQ 子频道上常见操作的 ABC。

以下实现了这个 ABC：

name

子频道名称。

Type

str

guild

子频道所属的频道。

Type

Guild

position

在频道列表中的位置。这是一个从 0 开始的数字。例如顶部子是位置 0。

Type

int

property mention: str

允许你提及频道的字符串。

Type

str

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发

Messageable

Methods
class qq.abc.Messageable

一个 记录了可以发送消息的模型上的常见操作的ABC。

以下实现了这个 ABC：

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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 – 已解析消息数据的消息。

QQ 模型

模型是从 QQ 接收的类，并不打算由库的用户创建。

危险

下面列出的类 不是由用户创建的 ，也是 只读的 。

例如，这意味着你不应该创建自己的 User 实例，也不应该自己修改 User 实例。

如果你想获得这些模型类实例中的一个， 必须通过缓存，而一种常见的方法是通过 utils.find() 函数或 从 qq-api-events 中指定的事件获取 。

注解

这里几乎所有的类都定义了 __slots__，这意味着数据类不可能有动态属性。

ClientUser

Attributes
Methods
class qq.ClientUser

代表你的 QQ 用户。

x == y

检查两个用户是否相等。

x != y

检查两个用户是否不相等。

hash(x)

返回用户的哈希值。

str(x)

返回用户名。

name

用户的用户名。

Type

str

id

用户的唯一 ID。

Type

int

bot

指定用户是否为机器人帐户。

Type

bool

property avatar: Optional[qq.asset.Asset]

返回用户拥有的头像的 Asset。 如果用户没有传统头像，则返回 None。 如果你想要用户显示的头像，请考虑 display_avatar。

Type

Optional[Asset]

property display_avatar: qq.asset.Asset

返回用户的显示头像。 对于普通用户，这只是他们的默认头像或上传的头像。

Type

Asset

property display_name: str

返回用户的显示名称。 对于普通用户，这只是他们的用户名，但如果他们有频道特定的昵称，则返回该昵称。

Type

str

property mention: str

返回一个字符串，允许你提及给定的用户。

Type

str

mentioned_in(message)

检查用户是否在指定的消息中被提及。

参数

message (Message) – 用于检查是否被提及的消息。

返回

指示消息中是否提到了用户。

返回类型

bool

User

Attributes
Methods
class qq.User

代表一个 QQ 用户。

x == y

检查两个用户是否相等。

x != y

检查两个用户是否不相等。

hash(x)

返回用户的哈希值。

str(x)

返回用户名。

name

用户的用户名。

Type

str

id

用户的唯一 ID。

Type

int

bot

指定用户是否为机器人帐户。

Type

bool

property dm_channel: Optional[DMChannel]

如果存在，则返回与此用户关联的子频道。 如果返回 None ，您可以通过调用 create_dm() 协程函数来创建私信子频道。

Type

Optional[DMChannel]

property avatar: Optional[qq.asset.Asset]

返回用户拥有的头像的 Asset。 如果用户没有传统头像，则返回 None。 如果你想要用户显示的头像，请考虑 display_avatar。

Type

Optional[Asset]

property display_avatar: qq.asset.Asset

返回用户的显示头像。 对于普通用户，这只是他们的默认头像或上传的头像。

Type

Asset

property display_name: str

返回用户的显示名称。 对于普通用户，这只是他们的用户名，但如果他们有频道特定的昵称，则返回该昵称。

Type

str

await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 – 已解析消息数据的消息。

property mention: str

返回一个字符串，允许你提及给定的用户。

Type

str

mentioned_in(message)

检查用户是否在指定的消息中被提及。

参数

message (Message) – 用于检查是否被提及的消息。

返回

指示消息中是否提到了用户。

返回类型

bool

property mutual_guilds: List[Guild]

用户与客户端共同的频道。

注解

这只会返回客户端内部缓存中的共同频道。

Type

List[Guild]

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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

await create_dm(guild)

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

参数

guild – 用于创建私信的源频道

返回

创建的频道。

返回类型

DMChannel

Attachment

Attributes
Methods
class qq.Attachment

代表来自 QQ 的附件。

id

附件的 ID。

Type

int

size

附件的大小。

Type

int

height

附件的高度，只对视频和图片适用。

Type

Optional[int]

width

附件的宽度，只对视频和图片适用。

Type

Optional[int]

filename

附件的文件名

Type

str

url

附件网址。 如果此附件被删除，则这将是 404。

Type

str

content_type

附件的 类型

Type

Optional[str]

await save(fp, *, seek_begin=True)

这个函数是一个 coroutine。 将此附件保存到类文件对象中。

参数

  • fp (Union[io.BufferedIOBase, os.PathLike]) – 将此附件保存到的类文件对象或要使用的文件名。 如果传递了文件名，则会使用该文件名创建一个文件并改为使用该文件。

  • seek_begin (bool) – 保存成功后是否查找文件开头。

引发
返回

写入的字节数。

返回类型

int

await read()

这个函数是一个 coroutine。 检索此附件的内容作为 bytes 对象。

引发
返回

附件的内容。

返回类型

bytes

await to_file()

这个函数是一个 coroutine。 将附件转换为适合通过 abc.Messageable.send() 发送的 File。

引发
返回

附件作为适合发送的文件。

返回类型

File

Asset

Attributes
Methods
class qq.Asset

代表 QQ 上的素材。

str(x)

返回素材的 URL。

len(x)

返回素材 URL 的长度。

x == y

检查素材是否等于另一个素材。

x != y

检查素材是否不等于另一个素材。

hash(x)

返回素材的哈希值。

property url: str

返回素材的底层 URL。

Type

str

property key: str

返回素材的识别键。

Type

str

await read()

这个函数是一个 coroutine。 获得这个素材的 bytes 内容。

引发
返回

素材的内容。

返回类型

bytes

await save(fp, *, seek_begin=True)

这个函数是一个 coroutine。 将此素材保存到类似文件的对象中。

参数

  • fp (Union[io.BufferedIOBase, os.PathLike]) – 将此附件保存到的类文件对象或要使用的文件名。 如果传递了文件名，则会使用该文件名创建一个文件并改为使用该文件。

  • seek_begin (bool) – 保存成功后是否查找文件开头。

引发
返回

写入的字节数。

返回类型

int

Message

Attributes
Methods
class qq.Message

代表来自 QQ 的消息。

x == y

检查两个消息是否相等。

x != y

检查两个消息是否不相等。

hash(x)

返回消息的哈希值。

author

发送消息的 User。

Type

User

content

消息的实际内容。

Type

str

embeds

消息所具有的 Embed 的列表。

Type

List[Embed]

channel

发送消息的 TextChannel。

Type

TextChannel

mention_everyone

指定消息是否提及所有人。

Type

bool

reactions

消息的回应/反应列表

注解

这不会检查 @全体成员 文本是否在消息本身中。 因此你需要在检查 @全体成员 文本是否在消息中 的同时 看这个是否是 True 。

Type

List[Reaction]

mentions

@到的 Member 列表。

警告

提及列表的顺序没有任何特定顺序，因此你不应依赖它。 这是 QQ 的限制，与库无关。

Type

List[Member]

role_mentions

提到的 Role 列表。 (官方还没有实现)

Type

List[Role]

id

消息ID。

Type

int

attachments

提供给消息的附件列表。

Type

List[Attachment]

guild

消息所属的频道（如果适用）。

Type

Optional[Guild]

direct

是否是私聊消息

Type

bool

clean_content

str:

以“清理”方式返回内容的属性。 这代表把提及转换成客户展示它的方式。 例如 <#id> 将转换为 #name。 这也会将 @全体成员 提及转换为未提及。

这 不 影响 Markdown 。 如果你想转义或删除 Markdown，请分别使用 utils.escape_markdown() 或 utils.remove_markdown() 以及此功能。

raw_mentions

返回与消息内容中的 <@user_id> 语法匹配的用户 ID 数组的属性。

这允许你即使在私人消息上下文中也可以接收提到用户的用户 ID。

Type

List[int]

raw_channel_mentions

返回与消息内容中的 <#channel_id> 语法匹配的子频道 ID 数组的属性。

Type

List[int]

raw_role_mentions

返回与消息内容中的 <@&role_id> 语法匹配的身份组 ID 数组的属性。

Type

List[int]

await delete(*, delay=None, hidetip=False)

这个函数是一个 coroutine。 撤回消息。

参数

  • delay (Optional[float]) – 如果提供，则在删除消息之前在后台等待的秒数。如果删除失败，则它会被静默忽略。

  • hidetip (bool) – 如果为 True ，将隐藏撤回灰条，默认为 False

引发
property edited_at: Optional[datetime.datetime]

包含消息编辑时间的 aware UTC datetime 对象。

Type

Optional[datetime.datetime]

await reply(content=None, **kwargs)

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

引发

  • HTTPException – 发送消息失败。

  • Forbidden – 你没有发送消息的适当权限。

  • InvalidArgument – files 列表的大小不合适，或者你同时指定了 file 和 files。

返回

发送的消息。

返回类型

Message

to_reference(*, fail_if_not_exists=True)

从当前消息创建一个 MessageReference。

参数

fail_if_not_exists (bool) – 如果消息不再存在或 QQ 无法获取消息，使用消息引用回复是否应该引发 HTTPException

返回

对此消息的引用。

返回类型

MessageReference

await global_pin(*, reason=None)

这个函数是一个 coroutine。 把这条消息设为全局公告。

参数

reason (Optional[str]) – 设为公告的原因。

引发

  • Forbidden – 你没有足够权限设置公告。

  • NotFound – 消息或频道无法被找到，可能被删除了

  • HTTPException – 设置公告失败.

await global_unpin(*, reason=None)

这个函数是一个 coroutine。 删除这条消息的全局公告。

参数

reason (Optional[str]) – 删除公告的原因。

引发

  • Forbidden – 你没有足够权限删除公告。.

  • NotFound – 消息或频道无法被找到，可能被删除了.

  • HTTPException – 删除公告失败。

await channel_pin(*, reason=None)

这个函数是一个 coroutine。 把这条消息设为子频道公告。

参数

reason (Optional[str]) – 设为公告的原因。

引发

  • Forbidden – 你没有足够权限设置公告。

  • NotFound – 消息或频道无法被找到，可能被删除了

  • HTTPException – 设置公告失败.

await channel_unpin(*, reason=None)

这个函数是一个 coroutine。 删除这条消息的子频道公告。

参数

reason (Optional[str]) – 删除公告的原因。

引发

  • Forbidden – 你没有足够权限删除公告。.

  • NotFound – 消息或频道无法被找到，可能被删除了.

  • HTTPException – 删除公告失败。

await add_reaction(emoji)

这个函数是一个 coroutine。 向消息添加表态。 表情符号可能是 unicode 表情符号或自定义 PartialEmoji 。

参数

emoji (Union[Reaction, PartialEmoji, str]) – 要表态的 emoji。

引发
await remove_reaction(emoji)

这个函数是一个 coroutine。 删除自己的表态。 表情符号可能是 unicode 表情符号或自定义 PartialEmoji 。

参数

emoji (Union[Reaction, PartialEmoji, str]) – 要删除表态的 emoji。

引发

MessageAudit

Attributes
class qq.MessageAudit

表示消息审核情况。

x == y

检查两个审核是否相等。

x != y

检查两个审核是否不相等。

id

审核的 ID 。

Type

str

message_id

消息 ID，只有审核通过事件才会有值。

Type

Optional[str]

audit_time

消息审核时间

Type

datetime.datetime

create_time

消息创建时间

Type

datetime.datetime

channel_id

审核消息的子频道 ID

Type

int

guild_id

审核消息的频道 ID

Type

str

property passed

返回消息是否通过审核

Type

bool

property rejected

返回消息是否没通过审核

Type

bool

property pending

返回消息是否正在审核

Type

bool

Interaction

Attributes
Methods
class qq.Interaction

代表一个互动。

请注意你需要在结束处理，或者判断权限结束后通过 Interaction.success() 等函数回应互动，不然会导致超时。

你也可以使用 async with 表达式在离开作用域时，如果未曾响应则自动调用 Interaction.success() 回复成功。

application_id

应用名称

Type

str

id

互动 ID

Type

int

guild

互动所发生的频道

Type

Guild

channel

互动所发生的子频道

Type

Channel

message

互动所发生的消息

Type

Message

author

互动造成的用户

Type

Member

chat_type

聊天类型？

Type

int

button_data

按钮名称/数据

Type

str

button_id

按钮 ID

Type

str

version

互动版本

Type

Optional[str]

await reply(content=None, **kwargs)

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

引发

  • HTTPException – 发送消息失败。

  • Forbidden – 你没有发送消息的适当权限。

  • InvalidArgument – files 列表的大小不合适，或者你同时指定了 file 和 files。

返回

发送的消息。

返回类型

Message

await success()

这个函数是一个 coroutine。

回复操作成功。

await failed()

这个函数是一个 coroutine。

回复操作失败。

await too_frequent()

这个函数是一个 coroutine。

回复操作过于频繁。

await duplicated()

这个函数是一个 coroutine。

回复操作为重复操作。

await no_permission()

这个函数是一个 coroutine。

回复操作权限不足。

await only_admin()

这个函数是一个 coroutine。

回复操作仅能被管理员调用。

Guild

Attributes
Methods
class qq.Guild

代表一个 QQ guild. 这在官方 QQ UI 中称为 频道 。

x == y
检查两个 guild 是否相等。
x != y
检查两个 guild 是否不相等。
hash(x)
返回 guild 的哈希值。
str(x)
返回 guild 的名称。
name

guild 名称。

Type

str

id

guild 的 ID。

Type

int

owner_id

guild 所有者的ID。使用 Guild.owner 代替。

Type

int

unavailable

指示频道是否不可用。如果这是 True 则 Guild.id 之外的其他属性的可靠性很小，它们可能都是 None。 如果频道不可用，最好不要对频道做任何事情。

Type

bool

max_members

guild 成员的最大数量。

注解

该属性只能通过 Client.fetch_guild() 获得。

Type

Optional[int]

description

guild 的说明。

Type

Optional[str]

property permissions: List[qq.api_permission.Permission]

属于该频道的权限列表。

Type

List[qq.Permission]

get_permission(path, method)

返回具有给定 path 和 method 的权限。

参数

  • path (str) – 要搜索的 path。

  • method (str) – 要搜索的 method。

返回

Role 或如果未找到，则 None 。

返回类型

Optional[Permission]

property channels: List[GuildChannel]

属于该频道的子频道列表。

Type

List[abc.GuildChannel]

property shard_id: int

如果适用，返回此频道的分片 ID。

Type

int

property owner: Optional[qq.member.Member]

拥有频道的成员。

Type

Optional[Member]

property members: List[qq.member.Member]

属于该频道的成员列表。

Type

List[Member]

property large: bool

指示频道是否是 大型 频道。 大型频道被定义为拥有超过 large_threshold 计数的成员，本库的最大值设置为 250。

Type

bool

get_role(role_id, /)

返回具有给定 ID 的 Role。

参数

role_id (int) – 要搜索的 ID。

返回

Role 或如果未找到，则 None 。

返回类型

Optional[Role]

property me: qq.member.Member

类似于 Client.user ，除了它是 Member 的一个实例。 这主要用于获取你自己的 Member 版本。

Type

Member

property text_channels: List[qq.channel.TextChannel]

属于该频道的文本频道列表。这是按位置排序的，从上到下按 UI 顺序排列。

Type

List[TextChannel]

property app_channels: List[qq.channel.AppChannel]

属于该频道的应用频道列表。这是按位置排序的，从上到下按 UI 顺序排列。

Type

List[AppChannel]

property categories: List[qq.channel.CategoryChannel]

属于该频道的类别列表。这是按位置排序的，从上到下按 UI 顺序排列。

Type

List[CategoryChannel]

by_category()

返回每个 CategoryChannel 及其关联的频道。 这些频道和类别按官方 QQ UI 顺序排序。 如果频道没有类别，则元组的第一个元素是 None 。

返回

类别及其关联的频道。

返回类型

List[Tuple[Optional[CategoryChannel], List[abc.GuildChannel]]]

get_channel(channel_id, /)

返回具有给定 ID 的频道。

参数

channel_id (int) – 要搜索的 ID。

返回

返回的频道或 ``None``（如果未找到）。

返回类型

Optional[abc.GuildChannel]

get_member(user_id, /)

返回具有给定 ID 的成员。

参数

user_id (int) – 要搜索的 ID。

返回

返回成员或如果未找到 None 。

返回类型

Optional[Member]

property roles: List[qq.role.Role]

以层级顺序返回频道身份组的 list。此列表的第一个元素将是层次结构中的最低身份组。

Type

List[Role]

get_member_named(name, /)

返回找到的第一个与提供的名称匹配的成员。 如果传递了昵称，则通过昵称查找它。 如果没有找到成员，则返回 None 。

参数

name (str) – 要查找的成员的名称。

返回

此频道中具有关联名称的成员。如果未找到，则返回 None 。

返回类型

Optional[Member]

property member_count: int

无论是否完全加载，都返回真实的成员计数。

警告

由于 QQ 的限制，为了使该属性保持最新和准确，它需要指定 Intents.members 。

Type

int

await create_text_channel(name, position, category=..., private_type=..., private_members=..., *, reason=None)

这个函数是一个 coroutine。 为频道创建一个 TextChannel 。

注解

创建指定位置的频道不会更新其他频道的位置。需要 edit() 后续调用来更新频道在频道列表中的位置。

实际案例

创建基本频道：

channel = await guild.create_text_channel('cool-channel')
参数

  • name (str) – 子频道的名称。

  • position (int) – 在子频道列表中的位置。这是一个从 0 开始的数字。例如顶部子频道是位置 0。

  • category (Optional[CategoryChannel]) – 新子频道的分组。

  • private_type (Optional[int]) – 子频道的私密类型，0 公开频道, 1 群主管理员可见, 2 群主管理员+指定成员

  • private_members (Optional[List[qq.Member]]) – 如果 private_type 为 2 ，则代表指定成员列表

  • reason (Optional[str]) – 创建此子频道的原因。

引发
返回

刚刚创建的频道。

返回类型

TextChannel

await create_live_channel(name, *, position=..., category=None, reason=None)

这个函数是一个 coroutine。 这类似于 create_text_channel() ，除了创建一个 LiveChannel 。

参数

  • name (str) – 频道的名称。

  • category (Optional[LiveChannel]) – 将新创建的频道置于其下的类别。

  • position (int) – 在频道列表中的位置。这是一个从 0 开始的数字。例如顶部通道是位置 0。

  • reason (Optional[str]) – 创建此频道的原因。

引发
返回

刚刚创建的频道。

返回类型

LiveChannel

await create_app_channel(name, *, position=..., category=None, reason=None)

这个函数是一个 coroutine。 这类似于 create_text_channel() ，除了生成一个 AppChannel。

参数

  • name (str) – 频道的名称。

  • category (Optional[AppChannel]) – 将新创建的频道置于其下的类别。

  • position (int) – 在频道列表中的位置。这是一个从 0 开始的数字。例如顶部通道是位置 0。

  • reason (Optional[str]) – 创建此频道的原因。

引发
返回

刚刚创建的频道。

返回类型

AppChannel

await create_thread_channel(name, *, position=..., category=None, reason=None)

这个函数是一个 coroutine。 这类似于 create_text_channel() ，除了生成一个 ThreadChannel。

参数

  • name (str) – 频道的名称。

  • category (Optional[ThreadChannel]) – 将新创建的频道置于其下的类别。

  • position (int) – 在频道列表中的位置。这是一个从 0 开始的数字。例如顶部通道是位置 0。

  • reason (Optional[str]) – 创建此频道的原因。

引发
返回

刚刚创建的频道。

返回类型

LiveChannel

await create_category(name, *, reason=None, position=...)

这个函数是一个 coroutine。 与 create_text_channel() 相同，除了创建一个 CategoryChannel。

注解

此函数不支持 category 参数，因为类别不能有类别。

引发
返回

刚刚创建的频道。

返回类型

CategoryChannel

await create_category_channel(name, *, reason=None, position=...)

这个函数是一个 coroutine。 与 create_text_channel() 相同，除了创建一个 CategoryChannel。

注解

此函数不支持 category 参数，因为类别不能有类别。

引发
返回

刚刚创建的频道。

返回类型

CategoryChannel

await fetch_channels()

这个函数是一个 coroutine。 检索频道拥有的所有 abc.GuildChannel。

注解

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

引发
返回

频道内的所有频道。

返回类型

Sequence[abc.GuildChannel]

fetch_members(*, limit=1000, after=0)

检索一个 AsyncIterator 来接收频道的成员。为了使用它，必须启用:meth:Intents.members。

注解

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

参数

  • limit (Optional[int]) – 要检索的成员数。默认为 1000。传递 None 以获取所有成员。请注意，这可能很慢。

  • after (Optional[Union[qq.Member, int]]) – 检索这个成员 id 之后的成员

引发
生成器

Member – 已解析成员数据的成员。

实际案例

用法

async for member in guild.fetch_members(limit=150):
    print(member.name)

展平成一个列表

members = await guild.fetch_members(limit=150).flatten()
# 成员现在是一个Member列表 ...
await fetch_member(member_id, /)

这个函数是一个 coroutine。 从频道 ID 和成员 ID 中检索:class:Member。

注解

该方法是一个 API 调用。如果你启用了 Intents.members 和成员缓存，请考虑使用 get_member()。

参数

member_id (int) – 要从中获取的成员 ID。

引发
返回

来自会员 ID 的会员。

返回类型

Member

await fetch_channel(channel_id, /)

这个函数是一个 coroutine。 检索具有指定 ID 的 abc.GuildChannel。

注解

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

引发

  • InvalidData – 从 QQ 接收到未知的频道类型或频道所属的频道与此对象中指向的频道不同。

  • HTTPException – 检索频道失败。

  • NotFound – 无效的频道 ID。

  • Forbidden – 你无权获取此频道。

返回

来自 ID 的频道。

返回类型

abc.GuildChannel

await fetch_roles()

这个函数是一个 coroutine。 检索频道拥有的所有 Role。 .. note:

该方法是一个 API 调用。对于一般用法，请考虑 :attr:`roles`。
引发

HTTPException – 检索身份组失败。

返回

频道中的所有身份组。

返回类型

List[Role]

await create_role(*, name=..., color=..., colour=..., hoist=..., mentionable=..., reason=None)

这个函数是一个 coroutine。 为频道创建一个身份组。

参数

  • name (str) – 身份组名称。

  • colour (Union[Colour, int]) – 身份组的颜色。默认为 Colour.default() 。这也是 Color 的别名。

  • hoist (bool) – 指示身份组是否应单独显示在成员列表中。默认为 False。

  • mentionable (bool) – 指示身份组是否应该被其他人提及。默认为 False。

  • reason (Optional[str]) – 创建此身份组的原因。

引发
返回

新创建的身份组。

返回类型

Role

await kick(user, *, reason=None)

这个函数是一个 coroutine。 将一个用户踢出频道。

参数

  • user (Member) – 踢出的用户。

  • reason (Optional[str]) – 用户被踢的原因。

引发
await ban(user, *, reason=None, delete_message_days=1)

这个函数是一个 coroutine。 封禁频道用户。

参数

  • user (qq.Member) – 要封禁的用户

  • delete_message_days (int) – 要删除的消息的天数 在频道中。 最小值为 0，最大值为 7。

  • reason (Optional[str]) – 该用户被封禁的原因

引发
await unmute_member(user, *, reason=None)

这个函数是一个 coroutine。 频道指定成员解除禁言。

参数

  • user (qq.Member) – 这个频道解除禁言的用户。

  • reason (Optional[str]) – 解除禁言的原因。

引发
await unmute_members(user, *, reason=None)

这个函数是一个 coroutine。 频道多个成员解除禁言。

参数

  • user (List[qq.Member]) – 这个频道解除禁言的用户列表。

  • reason (Optional[str]) – 解除禁言的原因。

引发
await mute_member(user, *, duration=10, reason=None)

这个函数是一个 coroutine。 频道指定成员禁言。

参数

  • user (qq.Member) – 这个频道禁言的用户。

  • duration (Union[datetime.datetime, int]) – 禁言的时间，可以是结束时间的一个 datetime.datetime ， 也可以是持续的秒数。

  • reason (Optional[str]) – 禁言的原因。

引发
await mute_members(user, *, duration=10, reason=None)

这个函数是一个 coroutine。 频道多个成员禁言。

参数

  • user (List[qq.Member]) – 这个频道禁言的用户的列表。

  • duration (Union[datetime.datetime, int]) – 禁言的时间，可以是结束时间的一个 datetime.datetime ， 也可以是持续的秒数。

  • reason (Optional[str]) – 禁言的原因。

引发
await mute_guild(*, duration=10, reason=None)

这个函数是一个 coroutine。 频道全局禁言。 需要使用的token对应的用户(或机器人)具备管理员权限。

参数
引发
property bots: List[qq.member.Member]

属于该频道的机器人列表。

1.1.0 新版功能.

Type

List[Member]

property humans: List[qq.member.Member]

属于该频道的用户帐户列表。

警告

由于 QQ 的限制，为了使该属性保持最新和准确，它需要 Intents.members。

1.1.0 新版功能.

Type

List[Member]

await unpin(reason=None)

删除所有此频道的全局公告。

参数

reason (Optional[str]) – 删除公告的原因。

引发

  • Forbidden – 你没有足够权限删除公告。.

  • NotFound – 消息或频道无法被找到，可能被删除了.

  • HTTPException – 删除公告失败。

Permission

Attributes
class qq.Permission

代表机器人 API 接口权限

path

API 接口名，例如 /guilds/{guild_id}/members/{user_id}

Type

str

method

请求方法，例如 GET

Type

str

desc

API 接口名称，例如 获取频道信

Type

str

property enabled

是否已经启用。

Type

bool

property disabled

是否已经禁用。

Type

bool

Member

Attributes
Methods
class qq.Member

代表一个 Guild 的 QQ 成员。这实现了 User 的很多功能。

x == y

检查两个成员是否相等。 请注意，这也适用于 User 实例。

x != y

检查两个成员是否不相等。 请注意，这也适用于 User 实例。

hash(x)

返回成员的哈希值。

str(x)

返回成员的名称。

joined_at

一个 datetime 对象，它指定成员加入频道的日期和时间。 如果成员离开并重新加入频道，这将是最新的日期。在某些情况下，这可以是 None 。

Type

Optional[datetime.datetime]

guild

成员所属的频道。

Type

Guild

nick

用户的频道特定昵称。

Type

Optional[str]

property name

Equivalent to User.name

property id

Equivalent to User.id

property bot

Equivalent to User.bot

property avatar

Equivalent to User.avatar

property mutual_guilds

Equivalent to User.mutual_guilds

property colour: qq.colour.Colour

返回颜色的 property，该颜色表示成员的呈现颜色。 如果默认颜色是渲染的颜色，则返回一个 Colour.default() 实例。 这个 property 有一个别名:attr:color。

Type

Colour

property color: qq.colour.Colour

返回颜色的 property，该颜色表示成员的呈现颜色。 如果默认颜色是渲染的颜色，则返回一个 Colour.default() 实例。 这个 property 有一个别名:attr:colour。

Type

Colour

property roles: List[Role]

成员所属的 Role 的 list 。

Type

List[Role]

property mention: str

返回一个字符串，允许你提及该成员。

Type

str

property display_name: str

返回用户的显示名称。 对于普通用户，这只是他们的用户名，但如果他们有频道特定的昵称，则返回该昵称。

Type

str

property display_avatar: Asset

返回成员的显示头像。

Type

Asset

mentioned_in(message)

检查指定消息中是否提及该成员。

参数

message (Message) – 用于检查是否被提及的消息。

返回

指示消息中是否提及该成员。

返回类型

bool

await add_roles(*roles, reason=None, atomic=True, channel=None)

这个函数是一个 coroutine。 给成员一些 Role 。

参数

  • *roles (Role) – 一个给成员的 Role 。

  • reason (Optional[str]) – 添加这些身份组的原因。

  • atomic (bool) – 是否以 atomic 方式添加身份组。这将确保无论缓存的当前状态如何，都将始终应用多个操作。

  • channel (Optional[abc.GuildChannel]) – 仅在添加身份组为 5 (子频道管理员) 的时候需要

引发
await remove_roles(*roles, channel=None, reason=None, atomic=True)

这个函数是一个 coroutine。 从此成员中删除一些 Role 。

参数

  • *roles (Role) – 一个给成员的 Role 。

  • reason (Optional[str]) – 删除这些身份组的原因。

  • atomic (bool) – 是否以 atomic 方式删除身份组。这将确保无论缓存的当前状态如何，都将始终应用多个操作。

  • channel (Optional[abc.GuildChannel]) – 仅在添加身份组为 5 (子频道管理员) 的时候需要

引发
await unmute(*, reason=None)

这个函数是一个 coroutine。 禁言这个用户，相当于 Guild.unmute_member() 。

await mute(duration=10, *, reason=None)

这个函数是一个 coroutine。 禁言这个用户，相当于 Guild.mute_member() 。

await kick(*, reason=None)

这个函数是一个 coroutine。 踢出这个成员。 与 Guild.kick() 相似。

await ban(*, delete_message_days=1, reason=None)

这个函数是一个 coroutine。 封禁这个用户。 与 Guild.ban() 相似。

await create_dm(guild)

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

参数

guild – 用于创建私信的源频道

返回

创建的频道。

返回类型

DMChannel

property dm_channel

Equivalent to User.dm_channel

await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

Role

Attributes
Methods
class qq.Role

代表 Guild 中的 QQ 身份组。

x == y

检查两个身份组是否相等。

x != y

检查两个身份组是否不相等。

hash(x)

返回身份组的哈希值。

str(x)

返回身份组的名称。

id

身份组的 ID。

Type

int

name

身份组名称。

Type

str

guild

身份组所属的公会。

Type

Guild

hoist

指示身份组是否将与其他成员分开显示。

Type

bool

is_default()

bool: 检查身份组是否为默认身份组。

property colour: qq.colour.Colour

返回身份组颜色。 存在 color 别名。

Type

Colour

property color: qq.colour.Colour

返回身份组颜色。 存在 color 别名。

Type

Colour

property mention: str

返回允许你提及身份组的字符串。

Type

str

property members: List[Member]

返回具有此身份组的所有成员。

Type

List[Member]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除身份组。

参数

reason (Optional[str]) – 删除该身份组的原因。

引发

PartialMessageable

Methods
class qq.PartialMessageable
await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

TextChannel

Attributes
Methods
class qq.TextChannel

代表 QQ 频道中的文字子频道

name

子频道的名称。

Type

str

guild

子频道所属的频道。

Type

Guild

id

子频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

category_id

这个子频道属于的分类频道，如果没有则返回 None 。

Type

Optional[int]

position

在子频道列表中的位置。 这是一个从 0 开始的数字。例如顶部子频道是位置 0。

Type

int

last_message_id

发送到此通道的消息的最后一个消息 ID。 它可能 不 指向现有的或有效的消息。

Type

Optional[int]

property members: List[Member]

返回可以看到此子频道的所有成员。

Type

List[Member]

get_partial_message(message_id, /)

从消息 ID 创建一个 PartialMessage。 如果你想处理消息并且只有它的 ID 而不进行不必要的 API 调用，这将非常有用。

参数

message_id (int) – 要为其创建部分消息的消息 ID。

返回

部分消息。

返回类型

PartialMessage

await edit(*, reason=None, **options)

这个函数是一个 coroutine。 编辑子频道。

参数

  • name (str) – 新频道名称。

  • position (int) – 新频道的位置。

  • category (Optional[CategoryChannel]) – 此频道的新类别。可以是 None 以删除类别。

  • type (ChannelType) – 更改此文本频道的类型。 不保证能够成功转换。

  • reason (Optional[str]) – 编辑此频道的原因。显示在审计日志中。

引发
返回

新编辑的文本通道。如果编辑只是位置性的，则返回 None 。

返回类型

Optional[TextChannel]

await delete_messages(messages)

这个函数是一个 coroutine。 删除消息列表。这类似于 Message.delete()，除了它批量删除多条消息。 作为一种特殊情况，如果消息数为 0，则什么也不做。如果消息数为 1，则完成单个消息删除。 如果超过两个，则使用批量删除。你不能批量删除超过 100 条消息或超过 14 天的消息。

参数

messages (Iterable[qq.Message]) – 一个可迭代的消息，表示要批量删除的消息。

引发
await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=False, bulk=True)

这个函数是一个 coroutine。 清除符合检查函数 check 给定标准的消息列表。 如果未提供 check ，则所有消息都将被删除，一视同仁。

实际案例

删除机器人的消息:

def is_me(m):
    return m.author == client.user
deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'已删除 {len(deleted)} 个消息')
参数

  • limit (Optional[int]) – 要搜索的消息数。这不是将被删除的消息数，尽管可以是。

  • check (Callable[[Message], bool]) – 用于检查是否应删除消息的功能。它必须将 Message 作为其唯一参数。

  • before (Optional[datetime.datetime]) – 与 history() 中的 before 相同。

  • after (Optional[datetime.datetime]) – 与 history() 中的 after 相同。

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – 与 history`中的 ``around`() 相同。

  • oldest_first (Optional[bool]) – 与 history() 中的 oldest_first 相同。

  • bulk (bool) – 如果 True ，使用批量删除。

引发
返回

已删除的消息列表。

返回类型

List[Message]

await unpin(reason=None)

删除所有此子频道的公告。

参数

reason (Optional[str]) – 删除公告的原因。

引发

  • Forbidden – 你没有足够权限删除公告。

  • NotFound – 消息或频道无法被找到，可能被删除了.

  • HTTPException – 删除公告失败。

await send_guide(content)

发送主动消息引导信息。

参数

content (str) – 要发送的内容。

引发
property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 – 已解析消息数据的消息。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发
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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

VoiceChannel

Attributes
Methods
class qq.VoiceChannel

表示 QQ 语音子频道。

x == y

检查两个子频道是否相等。

x != y

检查两个子频道是否不相等。

hash(x)

返回子频道的哈希值。

str(x)

返回子频道的名称。

name

子频道名称。

Type

str

guild

子频道所属的频道。

Type

Guild

id

频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

position

在类别列表中的位置。 这是一个从 0 开始的数字。例如顶部频道是位置 0。

Type

int

property type: qq.enum.ChannelType

子频道的QQ类型。

Type

ChannelType

await edit(*, reason=None, **options)

这个函数是一个 coroutine。 编辑频道。

参数

  • name (str) – 新频道的名称。

  • position (int) – 新频道的位置。

  • category (Optional[CategoryChannel]) – 此频道的新类别。可以是 None 以删除类别。

  • reason (Optional[str]) – 编辑此频道的原因。显示在审计日志中。

引发
返回

新编辑的语音通道。如果编辑只是位置性的，则返回 None 。

返回类型

Optional[VoiceChannel]

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发

CategoryChannel

Attributes
Methods
class qq.CategoryChannel

表示 QQ 频道类别。 这些对于将频道分组到逻辑区间很有用。

x == y

检查两个频道是否相等。

x != y

检查两个频道是否不相等。

hash(x)

返回类别的哈希值。

str(x)

返回类别的名称。

name

类别名称。

Type

str

guild

类别所属的公会。

Type

Guild

id

类别频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

position

在类别列表中的位置。 这是一个从 0 开始的数字。例如顶部频道是位置 0。

Type

int

property type: qq.enum.ChannelType

频道的 QQ 类型。

Type

ChannelType

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发

AppChannel

Attributes
Methods
class qq.AppChannel

表示 QQ 应用子频道。

x == y

检查两个子频道是否相等。

x != y

检查两个子频道是否不相等。

hash(x)

返回子频道的哈希值。

str(x)

返回子频道的名称。

name

子频道名称。

Type

str

guild

子频道所属的频道。

Type

Guild

id

频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

position

在类别列表中的位置。 这是一个从 0 开始的数字。例如顶部频道是位置 0。

Type

int

await create_schedule(name, start, end, jump_channel, remind_type, description=None)

返回具有给定 path 和 method 的权限。

参数

  • name (str) – 成员所属的频道。

  • description (Optional[str]) –

  • start (Union[datetime.datetime, float]) – 日程开始的时间。

  • end (Union[datetime.datetime, float]) – 日程开始的时间。

  • jump_channel (GuildChannel) – 日程开始的时间。

  • remind_type (str) – 日程提醒类型。

返回

Role 或如果未找到，则 None 。

返回类型

Optional[Schedule]

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发

LiveChannel

Attributes
Methods
class qq.LiveChannel

表示 QQ 直播子频道。

x == y

检查两个子频道是否相等。

x != y

检查两个子频道是否不相等。

hash(x)

返回子频道的哈希值。

str(x)

返回子频道的名称。

name

子频道名称。

Type

str

guild

子频道所属的频道。

Type

Guild

id

频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

position

在类别列表中的位置。 这是一个从 0 开始的数字。例如顶部频道是位置 0。

Type

int

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

await fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 – 已解析消息数据的消息。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发
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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

ThreadChannel

Attributes
Methods
class qq.ThreadChannel

表示 QQ 论坛子频道。

x == y

检查两个子频道是否相等。

x != y

检查两个子频道是否不相等。

hash(x)

返回子频道的哈希值。

str(x)

返回子频道的名称。

name

子频道名称。

Type

str

guild

子频道所属的频道。

Type

Guild

id

频道 ID。

Type

int

private_type

子频道私密类型。

值

含义

0

公开频道

1

群主管理员可见

2

群主管理员+指定成员
Type

int

position

在类别列表中的位置。 这是一个从 0 开始的数字。例如顶部频道是位置 0。

Type

int

await fetch_threads()

这个函数是一个 coroutine。 获取频道的所有帖子。

返回

频道的帖子列表，注意可能不完全。

返回类型

List[Thread]

await create_thread(title, content, thread_type)

这个函数是一个 coroutine。 使用给定的内容向频道发送帖子。

参数

  • title (str) – 帖子标题。

  • content (str) – 帖子内容。

  • thread_type (int) – 帖子类型。

await send_text(title, content)

这个函数是一个 coroutine。 使用给定的内容向频道发送普通文本帖子。

参数

  • title (str) – 帖子标题。

  • content (str) – 帖子内容。

await send_html(title, content)

这个函数是一个 coroutine。 使用给定的内容向频道发送HTML帖子。

参数

  • title (str) – 帖子标题。

  • content (str) – 帖子内容。

await send_markdown(title, content)

这个函数是一个 coroutine。 使用给定的内容向频道发送Markdown帖子。

参数

  • title (str) – 帖子标题。

  • content (str) – 帖子内容。

await send_json(title, content)

这个函数是一个 coroutine。 使用给定的内容向频道发送JSON帖子。

参数

  • title (str) – 帖子标题。

  • content (str) – 帖子内容。

property category: Optional[CategoryChannel]

此频道所属的类别。如果没有类别，则为 None。

Type

Optional[CategoryChannel]

await delete(*, reason=None)

这个函数是一个 coroutine。 删除频道。

property mention: str

允许你提及频道的字符串。

Type

str

await move(**kwargs)

这个函数是一个 coroutine。 帮助你相对于其他频道移动频道。 如果需要精确的位置移动，则应使用 edit 代替。

参数

  • beginning (bool) – 是否将频道移动到频道列表（或类别，如果给定）的开头。这与 end 、 before 和 after 是互斥的。

  • end (bool) – 是否将频道移动到频道列表（或类别，如果给定）的末尾。这与 beginning 、 before 和 after 是互斥的。

  • before (GuildChannel) – 应该在我们当前频道之前的频道。这与 beginning 、 end 和` after` 是互斥的。

  • after (GuildChannel) – 应该在我们当前频道之后的频道。这与 beginning 、 end 和 before 是互斥的。

  • offset (int) – 偏移移动的通道数。 例如，带有 beginning=True 的 2 偏移量会在开始后移动 2。 正数将其移至下方，而负数将其移至上方。请注意，这个数字是相对的，并且是在 beginning 、 end 、 before 和 after 参数之后计算的。

  • category (Optional[GuildChannel]) – 将此频道移动到的类别。如果给出 None，则将其移出类别。如果移动类别频道，则忽略此参数。

引发

Thread

Attributes
Methods
class qq.Thread

代表一个 QQ 帖子。

author

帖子的作者。

Type

User

guild

帖子所在的服务器。

Type

Guild

channel

帖子所在的频道。

Type

ThreadChannel

id

帖子 ID。

Type

int

title

帖子标题。

Type

str

content

帖子内容。

Type

str

created_at

发布时间。

Type

datetime.datetime

await fetch()

从服务器获取最新的帖子数据。

await delete()

删除帖子。

DMChannel

Attributes
Methods
class qq.DMChannel

代表一个QQ私信子频道。

recipient

在私信子频道中参与的用户。如果通过网关接收此子频道，则接收者信息可能并不总是可用。

Type

Optional[User]

me

代表你自己的用户。

Type

ClientUser

id

私信会话关联的子频道 id

Type

int

channel_id

垃圾资讯，无视即可，官方不知道在搞什么jb东西

Type

int

async for ... in 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 fetch_message(id, /)

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

参数

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

引发
返回

消息要求。

返回类型

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 。

引发
返回

发送的消息。

返回类型

Union[Message, MessageAudit]

property type: qq.enum.ChannelType

频道的 QQ 类型。

Type

ChannelType

get_partial_message(message_id, /)

从消息 ID 创建一个 PartialMessage 。 如果您想处理消息并且只拥有其 ID 而不进行不必要的 API 调用，这将非常有用。

参数

message_id (int) – 要为其创建部分消息的消息 ID。

返回

部分消息。

返回类型

PartialMessage

Schedule

Attributes
Methods
class qq.Schedule

代表一个 AppChannel 的日历。。

id

一个 datetime 对象，它指定成员加入频道的日期和时间。 如果成员离开并重新加入频道，这将是最新的日期。在某些情况下，这可以是 None 。

Type

str

name

成员所属的频道。

Type

str

guild

日程所在的频道

Type

Guild

channel

日程所在的频道

Type

GuildChannel

description

用户的频道特定昵称。

Type

Optional[str]

start

日程开始的时间。

Type

datatime.datetime

end

日程结束的时间。

Type

start: datatime.datetime

creator

日程创建者。

Type

Member

jump_channel

日程跳转频道。

Type

GuildChannel

remind_type

日程提醒类型。

Type

str

classmethod from_id(channel, schedule_id)

创建一个不完全的 Schedule ，主要用语 Schedule.delete()

await delete(reason=None)

这个函数是一个 coroutine。 删除这个日历。

RawMessageDeleteEvent

Attributes
class qq.RawMessageDeleteEvent

表示 on_raw_message_delete() 事件的事件负载。

channel_id

发生删除的子频道 ID。

Type

int

guild_id

发生删除的频道 ID（如果适用）。

Type

Optional[int]

message_id

被删除的消息 ID。

Type

str

cached_message

缓存的消息（如果在内部消息缓存中找到）。

Type

Optional[Message]

数据类

有些类只是为了数据容器，这里列出了它们。

与 models 不同，你可以自己创建其中的大部分，即使它们也可以用来保存属性。

这里几乎所有的类都定义了 __slots__，这意味着数据类不可能有动态属性。

这个规则的唯一例外是:class:Object，它考虑到了动态属性。

Object

Attributes
class qq.Object(id)

代表一个通用的 QQ 对象。 这个类的目的是允许你创建数据类的 微型 版，让你只传入一个 ID。 大多数接受带有 ID 的特定数据类的函数也可以接受这个类作为替代。 请注意，即使是这种情况，并非所有对象（如果有）实际上都继承自此类。 在某些情况下，某些 websocket 事件以奇怪的顺序接收，当发生此类事件时， 你将收到此类而不是实际的数据类。这些情况极为罕见。

x == y

检查两个对象是否相等。

x != y

检查两个对象是否不相等。

hash(x)

返回对象的哈希值。

id

对象的 ID。

Type

int

Markdown

Attributes
Methods
class qq.Markdown(*, template_id=None, custom_template_id=None, content=None)

代表一个 QQ Markdown。

bool(b)

返回 Markdown 是否有任何数据集。

template_id

要使用的模版 ID。

Type

int

custom_template_id

要使用的自定义模版 ID。

Type

str

content

原生 markdown 内容，如果设置了此项，将忽略 template_id 和 custom_template_id。

Type

str

set_attribute(key, value)

向 Markdown 对象添加字段。此函数返回类实例以允许流式链接。

参数

  • key (str) – 字段的名称。

  • value (str) – 字段的值。

with_keyboard()

向此 Markdown 添加一个键盘。此函数返回 Keyboard 实例以允许流式链接。

clear_fields()

从此 Markdown 中删除所有字段。

classmethod from_dict(template_id, data=None)

从字典创建一个 Markdown 对象。

Ark

Attributes
Methods
class qq.Ark(*, colour=Embed.Empty, color=Embed.Empty, template_id)

代表一个 QQ Ark。

len(x)

返回嵌入的总大小。用于检查它是否在 6000 个字符限制内。

bool(b)

返回嵌入是否有任何数据集。

template_id

要使用的模版 ID。

Type

str

colour

嵌入的颜色代码。别名为 color。这可以在初始化期间设置。目前官方还没有实现

Type

Union[Colour, int]

property fields: List[_EmbedFieldProxy]

List[Union[EmbedProxy, Empty]]: 返回 EmbedProxy 的一个列表，表示字段内容。有关你可以访问的可能值，请参阅 add_field()。 如果该属性没有值，则返回 Empty。

set_attribute(key, value)

向 Ark 对象添加字段。此函数返回类实例以允许流式链接。

参数

  • key (str) – 字段的名称。

  • value (str) – 字段的值。

add_field(*, desc, url=None)

向 Ark 对象添加字段。此函数返回类实例以允许流式链接。

参数

  • desc (str) – 字段的值。

  • url (str) – 字段的 Url。

insert_field_at(index, *, desc, url=None)

在 Ark 的指定索引之前插入一个字段。此函数返回类实例以允许流式链接。

参数

  • index (int) – 插入字段的位置的索引。

  • desc (str) – 字段的值。

  • url (str) – 字段的 Url。

clear_fields()

从此 Ark 中删除所有字段。

to_dict()

将此 Ark 对象转换为字典。

Embed

Attributes
Methods
class qq.Embed(*, title=Embed.Empty, colour=Embed.Empty, color=Embed.Empty, description=Embed.Empty, prompt=Embed.Empty, timestamp=None)

代表一个 QQ 嵌入。

len(x)

返回嵌入的总大小。用于检查它是否在 6000 个字符限制内。

bool(b)

返回嵌入是否有任何数据集。

某些属性返回一个 EmbedProxy ， 除了使用点访问，该类型的行为类似于常规 dict，例如 embed.author.icon_url。 如果属性无效或为空，则返回一个特殊的值，Embed.Empty。

为了便于使用，所有需要 str 的参数都为你隐式转换为 str。

title

嵌入的标题。这可以在初始化期间设置。

Type

str

description

嵌入的描述。这可以在初始化期间设置。

Type

str

timestamp

嵌入内容的时间戳。这是一个 aware 的 datetime。如果传递了一个简单的 datetime，它会被转换为具有本地时区的已知 datetime。

Type

datetime.datetime

colour

嵌入的颜色代码。别名为 color。这可以在初始化期间设置。目前官方还没有实现

Type

Union[Colour, int]

prompt

嵌入的弹出窗口。这可以在初始化期间设置。

Type
class

str

classmethod from_dict(data)

将 dict 转换为 Embed，前提是它采用 QQ 期望的格式。 你可以在 官方 QQ 文档 中找到有关此格式的信息。

https://bot.q.qq.com/wiki/develop/api/openapi/message/model.html#messageembed

参数

data (dict) – 要转换为嵌入的字典。

copy()

返回嵌入的浅表副本。

property footer: _EmbedFooterProxy

返回表示页脚内容的 EmbedProxy。 请参阅 set_footer() 以获取你可以访问的可能值。 如果该属性没有值，则返回 Empty。

设置嵌入内容的页脚。此函数返回类实例以允许流式链接。

参数

  • text (str) – 页脚文本。

  • icon_url (str) – 页脚图标的 URL。仅支持 HTTP(S)。

清除嵌入的页脚信息。此函数返回类实例以允许流式链接。

property image: _EmbedMediaProxy

返回表示图像内容的 EmbedProxy 。

你可以访问的可能属性是：

  • url

  • proxy_url

  • width

  • height

如果该属性没有值，则返回 Empty。

set_image(*, url)

设置嵌入内容的图像。 此函数返回类实例以允许流式链接。 传递 Empty 会删除图像。

参数

url (str) – 图像的源 URL。仅支持 HTTP(S)。

property thumbnail: _EmbedMediaProxy

返回表示缩略图内容的 EmbedProxy 。

你可以访问的可能属性是：

  • url

  • proxy_url

  • width

  • height

如果该属性没有值，则返回 Empty。

set_thumbnail(*, url)

设置嵌入内容的缩略图。此函数返回类实例以允许流式链接。传递 Empty 会删除缩略图。

参数

url (str) – 缩略图的源 URL。仅支持 HTTP(S)。

property video: _EmbedVideoProxy

返回表示视频内容的 EmbedProxy 。

可能的属性包括：

  • url 视频网址。

  • height 视频高度。

  • width 视频宽度。

如果该属性没有值，则返回 Empty。

property provider: _EmbedProviderProxy

返回表示提供者内容的 EmbedProxy 。 可能被访问的唯一属性是 name 和 url 。如果该属性没有值，则返回 Empty。

property author: _EmbedAuthorProxy

返回表示作者内容的 EmbedProxy 。有关你可以访问的可能值，请参阅 set_author()。 如果该属性没有值，则返回 Empty。

set_author(*, name, url=Embed.Empty, icon_url=Embed.Empty)

设置嵌入内容的作者。此函数返回类实例以允许流式链接。

参数

  • name (str) – 作者的名字。

  • url (str) – 作者的 URL。

  • icon_url (str) – 作者图标的 URL。仅支持 HTTP(S)。

remove_author()

清除嵌入的作者信息。此函数返回类实例以允许流式链接。

property fields: List[_EmbedFieldProxy]

List[Union[EmbedProxy, Empty]]: 返回 EmbedProxy 的一个列表，表示字段内容。有关你可以访问的可能值，请参阅 add_field()。 如果该属性没有值，则返回 Empty。

add_field(*, name, value='', inline=True)

向嵌入对象添加字段。此函数返回类实例以允许流式链接。

参数

  • name (str) – 字段的名称。

  • value (str) – 字段的值。目前并无作用

  • inline (bool) – 该字段是否应内联显示。目前并无作用

insert_field_at(index, *, name, value='', inline=True)

在嵌入的指定索引之前插入一个字段。此函数返回类实例以允许流式链接。

参数

  • index (int) – 插入字段的位置的索引。

  • name (str) – 字段的名称。

  • value (str) – 字段的值。目前并无作用

  • inline (bool) – 该字段是否应内联显示。目前并无作用

clear_fields()

从此嵌入中删除所有字段。

remove_field(index)

删除指定索引处的字段。 如果索引无效或越界，则错误会被默默吞下。

注解

当按索引删除一个字段时，其他字段的索引会移动以填补空白，就像常规列表一样。

参数

index (int) – 要删除的字段的索引。

set_field_at(index, *, name, value, inline=True)

修改嵌入对象的字段。索引必须指向一个有效的预先存在的字段。此函数返回类实例以允许流式链接。

参数

  • index (int) – 要修改的字段的索引。

  • name (str) – 字段的名称。

  • value (str) – 字段的值。

  • inline (bool) – 该字段是否应内联显示。

引发

IndexError – 提供了无效的索引。

to_dict()

将此嵌入对象转换为字典。

Keyboard

Attributes
Methods
class qq.Keyboard

代表一个 Markdown 的键盘配置

bool(b)

返回 Keyboard 是否有任何按钮。

buttons

按钮列表。

Type

List[List[Button]]

add_button(row, button_id)

向第 row 行添加一个按钮。如果超出范围该按钮不会被添加至键盘中。 此函数返回 Button 实例以允许流式链接。

参数

  • row (int) – 添加至的行数。最大只能是 4 ，键盘按钮最多只能有五行。

  • button_id (str) – 按钮 ID。

with_id(keyboard_id)

设定 keyboard 模板 id，请注意设定了之后按钮设置将失效。

参数

keyboard_id (str) – keyboard 模板 id。

Button

Methods
class qq.Button(button_id)

代表一个 Keyboard 中的按钮

label(label)

设定按纽上的文字。此函数返回类实例以允许流式链接。

参数

label (str) – 按纽上的文字。

visited_label(visited_label)

设定按纽上的文字。此函数返回类实例以允许流式链接。

参数

visited_label (str) – 按纽上的文字。

gray_border()

设定按纽为灰色边框。此函数返回类实例以允许流式链接。

blue_border()

设定按纽为蓝色边框。此函数返回类实例以允许流式链接。

do_http(url)

设定按纽动作为访问 url 或者打开小程序。此函数返回类实例以允许流式链接。

参数

url (str) – 访问的 Url 或者小程序客户端识别 schem。

do_notify_backend(data)

设定按纽动作为回调后台接口, data 传给后台。此函数返回类实例以允许流式链接。

参数

data (str) – 回调数据。

do_command(msg, show_channel_list)

设定按纽动作为输入指令，自动在输入框 @bot data。此函数返回类实例以允许流式链接。

参数

  • msg (str) – 要输入的指令。

  • show_channel_list (bool) – 是否弹出子频道选择器。

click_limit(click_limit)

可点击的次数, 默认不限。此函数返回类实例以允许流式链接。

参数

click_limit (int) – 可点击的次数。

allow_specific_user(users)

指定用户可操作。此函数返回类实例以允许流式链接。

参数

users (List[User]) – 指定用户。

allow_admin()

仅管理者可操作。此函数返回类实例以允许流式链接。

allow_everyone()

所有人可操作。此函数返回类实例以允许流式链接。

allow_specific_role(roles)

指定身份组可操作。此函数返回类实例以允许流式链接。

参数

roles (List[Role]) – 指定身份组。

AllowedMentions

Attributes
Methods
class qq.AllowedMentions(*, everyone=True, users=True, roles=True, replied_user=True)

一个类，表示消息中允许提及的内容。 这个类可以在 Client 初始化期间设置，以应用于每条发送的消息。 它也可以通过 abc.Messageable.send() 在每条消息的基础上应用，以获得更细粒度的控制。

everyone

是否允许所有人和这里提到。 默认为 True。

Type

bool

users

控制被提及的用户。 如果为 True （默认值），则根据消息内容提及用户。 如果 False 则根本不会提及用户。 如果给出了 Member 的列表，则只提及所提供的用户，前提是这些用户在消息内容中。

Type

Union[bool, List[Member]]

roles

控制提到的用户组。 如果为 True （默认值），则根据消息内容提及用户组。 如果 False 则根本不提及用户组。 如果给出了 Role 的列表，则只提及所提供的用户组，前提是这些用户组在消息内容中。

Type

Union[bool, List[Role]]

replied_user

是否提及正在回复的消息的作者。 默认为 True 。

Type

bool

classmethod all()

返回一个 AllowedMentions 的工厂方法，其中所有字段都显式设置为 True

classmethod none()

一个工厂方法，返回一个 AllowedMentions，所有字段都设置为 False

MessageReference

Attributes
Methods
class qq.MessageReference(*, message_id, channel_id, guild_id=None, fail_if_not_exists=True)

表示对 Message 的引用。 这个类现在可以由用户构建。

message_id

引用的消息的 ID。

Type

Optional[int]

channel_id

引用的消息的子频道 ID。

Type

Optional[int]

guild_id

所引用消息的频道 ID。

Type

Optional[int]

fail_if_not_exists

回复引用的消息是否应该引发 HTTPException 如果消息不再存在或 QQ 无法获取消息。

Type

bool

resolved

此引用将解析为的消息。 如果这是 None ，那么原始消息没有被获取，要么是因为 QQ API 没有尝试解析它，要么在创建时它不可用。

目前，这主要是用户回复消息时的回复消息。

Type

Optional[Message]

classmethod from_message(message, *, fail_if_not_exists=True)

从现有的 Message 创建一个 MessageReference 。

参数

  • message (Message) – 要转换为引用的消息。

  • fail_if_not_exists (bool) – 回复引用的消息是否应该引发 HTTPException 如果消息不再存在或 QQ 无法获取消息。

返回

对消息的引用。

返回类型

MessageReference

property cached_message: Optional[qq.message.Message]

缓存的消息（如果在内部消息缓存中找到）。

Type

Optional[Message]

PartialMessage

Attributes
Methods
class qq.PartialMessage(*, channel, id)

当仅存在消息和通道 ID 时，只使用部分消息以帮助处理消息。 有两种方法可以构造这个类。第一个是通过构造函数本身，第二个是通过以下方式：

注意这个类是被修剪过的，没有丰富的属性。

x == y
检查两个部分消息是否相等。
x != y
检查两个部分消息是否不相等。
hash(x)
返回部分消息的哈希值。
channel

与此部分消息关联的频道。

Type

TextChannel

id

消息 ID。

Type

int

guild

部分消息所属的频道（如果适用）。

Type

Optional[Guild]

await fetch()

这个函数是一个 coroutine。 将部分消息获取到完整的 Message 。

引发
返回

完整的消息。

返回类型

Message

Intents

Attributes
Methods
class qq.Intents(**kwargs)
classmethod all()

一个工厂方法，它创建一个 Intents 并启用所有内容。

classmethod none()

一个工厂方法，它创建一个禁用一切的 Intents 。

classmethod default()

一个工厂方法，它创建一个 Intents， 除了 guilds, members 和 at_guild_messages 之外的所有内容都禁用。

guilds

频道相关事件是否开启。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

警告

强烈建议你启用此意图，以便你的机器人正常运行。

Type

bool

members

频道成员相关事件是否开启。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

Type

bool

guild_messages

频道消息相关事件是否开启。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

注解

现在来说，这个 Intents 需要额外的申请，如果没有适当的权限 Websocket 将无法连接。

Type

bool

guild_reactions

频道消息反应相关事件是否开启。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

注解

现在来说，这个 Intents 需要额外的申请，如果没有适当的权限 Websocket 将无法连接。

Type

bool

messages

是否启用频道和直接消息相关事件。 这是设置或获取 guild_messages 和 dm_messages 的快捷方式。

这对应于以下事件： - on_message() (both guilds and DMs)

这也对应于缓存方面的以下属性和类： - Message - Client.cached_messages

注解

现在来说，这个 Intents 需要额外的申请，如果没有适当的权限 Websocket 将无法连接。

Type

bool

dm_messages

是否启用直接消息相关事件。 另见 guild_messages 来获取频道信息或 messages 同时获取两者。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

注解

现在来说，这个 Intents 需要额外的申请，如果没有适当的权限 Websocket 将无法连接。

Type

bool

interaction

互动事件相关事件是否开启。

这对应于以下事件：

Type

bool

audit

消息审核相关事件是否开启。

这对应于以下事件：

Type

bool

thread

论坛相关事件是否开启。

这将对应于以下事件：

  • on_thread_create()

  • on_thread_update()

  • on_thread_delete()

  • on_post_create()

  • on_post_delete()

  • on_reply_create()

  • on_reply_delete()

注解

现在没人有需要用这个事件，以上事件咕了。有需要欢迎找我。

Type

bool

audio

频道提及机器人的消息相关事件是否开启。

这对应于以下事件：

Type

bool

at_guild_messages

频道提及机器人的消息相关事件是否开启。

这对应于以下事件：

这也对应于缓存方面的以下属性和类：

Type

bool

File

Attributes
class qq.File(fp, filename=None)

用于 abc.Messageable.send() 的参数对象，用于发送文件对象。

注解

文件对象是一次性的，不能在多个 abc.Messageable.send() 中重复使用。

fp

以二进制模式和读取模式打开的类文件对象或表示硬盘中要打开的文件的文件名。

注解

如果传递的类文件对象是通过 open 打开的，则应使用 rb 模式。 要传递二进制数据，请考虑使用 io.BytesIO。

Type

Union[os.PathLike, io.BufferedIOBase]

filename

上传到 QQ 时显示的文件名。 如果没有给出，那么它默认为 fp.name 或者如果 fp 是一个字符串，那么 filename 将默认为给定的字符串。

Type

Optional[str]

Colour

Attributes
Methods
class qq.Colour(value)

代表 QQ 颜色。这个类类似于（红、绿、蓝）:class:tuple 。 这个有一个别名叫做 Color。

x == y

检查两种颜色是否相等。

x != y

检查两种颜色是否不相等。

hash(x)

返回颜色的哈希值。

str(x)

返回颜色的十六进制格式。

int(x)

返回原始颜色值。

value

原始整数颜色值。

Type

int

property r: int

返回颜色的红色部分。

Type

int

property g: int

返回颜色的绿色部分。

Type

int

property b: int

返回颜色的蓝色部分。

Type

int

to_rgb()

Tuple[int, int, int]: 返回表示颜色的 (r, g, b) 元组。

classmethod from_rgb(r, g, b)

Constructs a Colour 来自 RGB 元组。

classmethod from_hsv(h, s, v)

Constructs a Colour 来自 HSV 元组。

classmethod default()

一个工厂方法，它返回一个 Colour 的值为 0 。

classmethod random(*, seed=None)

返回带有随机色调的 Colour 的工厂方法。

注解

随机算法的工作原理是选择具有随机色调但饱和度和值最大化的颜色。

参数

seed (Optional[Union[int, str, float, bytes, bytearray]]) – 用于初始化随机数生成器的种子。如果传递 None，则使用默认随机数生成器。

classmethod teal()

一个工厂方法，返回一个值为 0x1abc9c 的 Colour 。

classmethod dark_teal()

一个工厂方法，返回一个值为 0x11806a 的 Colour 。

classmethod brand_green()

一个工厂方法，返回一个值为 0x57F287 的 Colour 。

classmethod green()

一个工厂方法，返回一个值为 0x2ecc71 的 Colour 。

classmethod dark_green()

一个工厂方法，返回一个值为 0x1f8b4c 的 Colour 。

classmethod blue()

一个工厂方法，返回一个值为 0x3498db 的 Colour 。

classmethod dark_blue()

一个工厂方法，返回一个值为 0x206694 的 Colour 。

classmethod purple()

一个工厂方法，返回一个值为 0x9b59b6 的 Colour 。

classmethod dark_purple()

一个工厂方法，返回一个值为 0x71368a 的 Colour 。

classmethod magenta()

一个工厂方法，返回一个值为 0xe91e63 的 Colour 。

classmethod dark_magenta()

一个工厂方法，返回一个值为 0xad1457 的 Colour 。

classmethod gold()

一个工厂方法，返回一个值为 0xf1c40f 的 Colour 。

classmethod dark_gold()

一个工厂方法，返回一个值为 0xc27c0e 的 Colour 。

classmethod orange()

一个工厂方法，返回一个值为 0xe67e22 的 Colour 。

classmethod dark_orange()

一个工厂方法，返回一个值为 0xa84300 的 Colour 。

classmethod brand_red()

一个工厂方法，返回一个值为 0xED4245 的 Colour 。

classmethod red()

一个工厂方法，返回一个值为 0xe74c3c 的 Colour 。

classmethod dark_red()

一个工厂方法，返回一个值为 0x992d22 的 Colour 。

classmethod lighter_grey()

一个工厂方法，返回一个值为 0x95a5a6 的 Colour 。

classmethod lighter_gray()

一个工厂方法，返回一个值为 0x95a5a6 的 Colour 。

classmethod dark_grey()

一个工厂方法，返回一个值为 0x607d8b 的 Colour 。

classmethod dark_gray()

一个工厂方法，返回一个值为 0x607d8b 的 Colour 。

classmethod light_grey()

一个工厂方法，返回一个值为 0x979c9f 的 Colour 。

classmethod light_gray()

一个工厂方法，返回一个值为 0x979c9f 的 Colour 。

classmethod darker_grey()

一个工厂方法，返回一个值为 0x546e7a 的 Colour 。

classmethod darker_gray()

一个工厂方法，返回一个值为 0x546e7a 的 Colour 。

classmethod og_blurple()

一个工厂方法，返回一个值为 0x7289da 的 Colour 。

classmethod blurple()

一个工厂方法，返回一个值为 0x5865F2 的 Colour 。

classmethod greyple()

一个工厂方法，返回一个值为 0x99aab5 的 Colour 。

classmethod dark_theme()

一个工厂方法，返回一个值为 0x36393F 的 Colour 。

classmethod fuchsia()

一个工厂方法，返回一个值为 0xEB459E 的 Colour 。

classmethod yellow()

一个工厂方法，返回一个值为 0xFEE75C 的 Colour 。

Permissions

Attributes
Methods
class qq.Permissions(permissions=0, **kwargs)

QQ 权限值。提供的属性有两种方式。你可以使用属性设置和检索单个位，就像它们是常规布尔值一样。这允许你编辑权限。

x == y

检查两个权限是否相等。

x != y

检查两个权限是否不相等。

x <= y

检查一个权限是否是另一个权限的子集。

x >= y

检查一个权限是否是另一个权限的超集。

x < y

检查一个权限是否是另一个权限的严格子集。

x > y

检查一个权限是否是另一个权限的严格超集。

hash(x)

返回权限的哈希值。

iter(x)

返回 (perm, value) 对的迭代器。 例如，这允许将其构造为字典或对列表。请注意，未显示别名。

value

原始值。该值是一个 53 位整数的位数组字段，表示当前可用的权限。你应该通过属性查询权限，而不是使用此原始值。

Type

int

is_subset(other)

如果 self 与 other 具有相同或更少的权限，则返回 True 。

is_superset(other)

如果 self 与 other 具有相同或更多的权限，则返回 True 。

is_strict_subset(other)

如果其他权限是自身权限的严格子集，则返回 True 。

is_strict_superset(other)

如果 other 上的权限是 self 上的权限的严格超集，则返回 True 。

classmethod none()

创建一个 Permissions 的工厂方法，所有权限都设置为 False 。

classmethod all()

创建一个 Permissions 的工厂方法，所有权限都设置为 True。

update(**kwargs)

批量更新此权限对象。 允许你使用关键字参数设置多个属性。名称必须与列出的属性相同。无关的键值对将被默默忽略。

参数

**kwargs – 用于批量更新权限的键/值对列表。

read_messages

如果用户可以从所有或特定文本频道读取消息，则返回 True 。

Type

bool

view_channel

read_messages 的别名。

Type

bool

manage_channels

如果用户可以在公会中编辑、删除或创建频道，则返回 True 。

Type

bool

send_messages

如果用户可以从所有或特定文本频道发送消息，则返回 True。

Type

bool

PermissionOverwrite

Methods
class qq.PermissionOverwrite(**kwargs)

用于表示特定于子频道的权限的类型。 与常规的 Permissions不同，权限的默认值相当于 None 而不是 False 。 将值设置为 False 是 明确主动拒绝 该权限， 将值设置为 True 是 明确主动允许 该权限。

它支持的值与 Permissions 相同，但增加了将其设置为 None 的可能性。

x == y

检查两个覆盖是否相等。

x != y

检查两个覆盖是否不相等。

iter(x)

返回 (perm, value) 对的迭代器。例如，这允许将其构造为字典或列表。请注意，未显示别名。

参数

**kwargs – 按名称设置权限值。

pair()

Tuple[Permissions, Permissions]: 从此覆盖返回 (allow, deny) 对。

classmethod from_pair(allow, deny)

从允许拒绝的 Permissions 对创建覆盖。

is_empty()

检查权限覆盖当前是否为空。空权限覆盖是没有设置为 True 或 False 的覆盖。

返回

指示覆盖是否为空。

返回类型

bool

update(**kwargs)

批量更新此权限覆盖对象。允许你使用关键字参数设置多个属性。名称必须与列出的属性相同。无关的键值对将被默默忽略。

参数

**kwargs – 用于批量更新的键值对列表。

ShardInfo

Attributes
Methods
class qq.ShardInfo

提供信息和控制特定分片的类。 你可以通过 AutoShardedClient.get_shard() 或 AutoShardedClient.shards 检索这个对象。

id

此分片的分片 ID。

Type

int

shard_count

此集群的分片计数。如果这是 None ，则机器人尚未启动。

Type

Optional[int]

is_closed()

bool: 分片连接当前是否关闭。

await disconnect()

这个函数是一个 coroutine。 断开分片。当这个被调用时，分片连接将关闭。 如果分片已经断开连接，则不会执行任何操作。

await reconnect()

这个函数是一个 coroutine。 断开连接，然后再次连接分片。

await connect()

这个函数是一个 coroutine。 连接一个分片。如果分片已连接，则不会执行任何操作。

property latency: float

测量此分片的 HEARTBEAT 和 HEARTBEAT_ACK 之间的延迟（以秒为单位）。

Type

float

is_ws_ratelimited()

bool: websocket 当前是否有速率限制。

错误

库能够抛出以下异常。

exception qq.QQException

qq.py 的基本异常类，可以捕获从库引发的任何异常。

exception qq.ClientException

当 Client 中的操作失败时引发的异常。 这些通常是由于用户输入而发生的异常。

exception qq.LoginFailure

当 Client.login() 函数无法通过不正确的凭据或其他一些杂项登录时引发的异常。

exception qq.NoMoreItems

当异步迭代操作没有更多项目时引发的异常。

exception qq.HTTPException(response, message, route=None)

HTTP 请求操作失败时引发的异常。

response

失败的 HTTP 请求的响应。 这是 aiohttp.ClientResponse 的一个实例。 在某些情况下，这也可能是一个 requests.Response。

Type

aiohttp.ClientResponse

text

错误的文本。可能是一个空字符串。

Type

str

status

HTTP 请求的状态码。

Type

int

code

失败的 QQ 特定错误代码。

Type

int

route

HTTP 请求的路径

Type

Optional[qq.Route]

exception qq.Forbidden(response, message, route=None)

发生状态代码 403 时引发的异常。 HTTPException 的子类

exception qq.NotFound(response, message, route=None)

发生状态代码 404 时引发的异常。 HTTPException 的子类

exception qq.QQServerError(response, message, route=None)

发生 500 范围状态代码时引发的异常。 HTTPException 的子类。

exception qq.InvalidData

当库遇到来自 QQ 的未知或无效数据时引发的异常。

exception qq.InvalidArgument

当函数的参数以某种方式无效时引发的异常（例如错误的值或错误的类型）。 除了继承自 ClientException 和 QQException，这可以被认为是类似于 ValueError 和 TypeError 。

exception qq.GatewayNotFound

找不到QQ网关时引发的异常

exception qq.ConnectionClosed(socket, *, shard_id, code=None)

由于无法在内部处理的原因关闭网关连接时引发的异常。

code

websocket 的关闭代码。

Type

int

reason

提供了关闭的原因。

Type

str

shard_id

如果适用，已关闭的分片 ID。

Type

Optional[int]

异常层次结构