Client Objects

Bots

Attributes
Methods
class discord.Bot(description=None, *args, **options)[исходный код]

Represents a discord bot.

This class is a subclass of discord.Client and as a result anything that you can do with a discord.Client you can do with this bot.

This class also subclasses ApplicationCommandMixin to provide the functionality to manage commands.

Добавлено в версии 2.0.

description

The content prefixed into the default help message.

Type:

str

owner_id

The user ID that owns the bot. If this is not set and is then queried via is_owner() then it is fetched automatically using application_info(), returning the application owner.

Type:

Optional[int]

owner_ids

The user IDs that owns the bot. This is similar to owner_id. If this is not set and the application is team based, then it is fetched automatically using application_info(), returning all non read-only team members. For performance reasons it is recommended to use a set for the collection. You cannot set both owner_id and owner_ids.

Добавлено в версии 1.3.

Type:

Optional[Collection[int]]

debug_guilds

Guild IDs of guilds to use for testing commands. The bot will not create any global commands if debug guild IDs are passed.

Добавлено в версии 2.0.

Type:

Optional[List[int]]

auto_sync_commands

Whether to automatically sync slash commands. This will call sync_commands() in discord.on_connect(), and in process_application_commands if the command is not found. Defaults to True.

Добавлено в версии 2.0.

Type:

bool

default_command_contexts

The default context types that the bot will use for commands. Defaults to a set containing InteractionContextType.guild, InteractionContextType.bot_dm, and InteractionContextType.private_channel.

Добавлено в версии 2.6.

Type:

Collection[InteractionContextType]

default_command_integration_types

The default integration types that the bot will use for commands. Defaults to a set containing IntegrationType.guild_install.

Добавлено в версии 2.6.

Type:

Collection[IntegrationType]]

@command(**kwargs)

An alias for application_command().

Примечание

This decorator is overridden by discord.ext.commands.Bot.

Добавлено в версии 2.0.

Результат:

A decorator that converts the provided function into an ApplicationCommand, adds it to the bot, and returns it.

Тип результата:

Callable[…, ApplicationCommand]

@event(coro)

A decorator that registers an event to listen to.

You can find more info about the events on the documentation below.

The events must be a coroutine, if not, TypeError is raised.

Примечание

This replaces any default handlers. Developers are encouraged to use listen() for adding additional handlers instead of event() unless default method replacement is intended.

Исключение:

TypeError – The coroutine passed is not actually a coroutine.

Пример

@client.event
async def on_ready():
    print('Ready!')
Параметры:

coro (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]]))

Тип результата:

TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])

@message_command(*, checks=..., cog=..., contexts=..., cooldown=..., default_member_permissions=..., guild_ids=..., guild_only=..., integration_types=..., name=..., name_localizations=..., nsfw=..., **kwargs)

A shortcut decorator for adding a message command to the bot. This is equivalent to using application_command(), providing the MessageCommand class.

Добавлено в версии 2.0.

Результат:

A decorator that converts the provided function into a MessageCommand, adds it to the bot, and returns it.

Тип результата:

Callable[..., MessageCommand]

Параметры:
@slash_command(*, checks=..., cog=..., contexts=..., cooldown=..., default_member_permissions=..., description=..., description_localizations=..., guild_ids=..., guild_only=..., integration_types=..., name=..., name_localizations=..., nsfw=..., options=..., parent=..., **kwargs)

A shortcut decorator for adding a slash command to the bot. This is equivalent to using application_command(), providing the SlashCommand class.

Добавлено в версии 2.0.

Результат:

A decorator that converts the provided function into a SlashCommand, adds it to the bot, and returns it.

Тип результата:

Callable[..., SlashCommand]

Параметры:
@user_command(*, checks=..., cog=..., contexts=..., cooldown=..., default_member_permissions=..., guild_ids=..., guild_only=..., integration_types=..., name=..., name_localizations=..., nsfw=..., **kwargs)

A shortcut decorator for adding a user command to the bot. This is equivalent to using application_command(), providing the UserCommand class.

Добавлено в версии 2.0.

Результат:

A decorator that converts the provided function into a UserCommand, adds it to the bot, and returns it.

Тип результата:

Callable[..., UserCommand]

Параметры:
@listen(name=..., once=False)

A decorator that registers another function as an external event listener. Basically this allows you to listen to multiple events from different places e.g. such as on_ready()

The functions being listened to must be a coroutine.

Исключение:

  • TypeError – The function being listened to is not a coroutine.

  • ValueError – The name (event name) does not start with on_.

Пример

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

# in some other file...

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

# listen to the first event only
@client.listen('on_ready', once=True)
async def on_ready():
    print('ready!')

Would print one and two in an unspecified order.

Параметры:
Тип результата:

Callable[[TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])], TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])]

property activity: Activity | Game | CustomActivity | Streaming | Spotify | None

The activity being used upon logging in.

Тип результата:

Optional[BaseActivity]

add_application_command(command)

Adds an ApplicationCommand into the internal list of commands.

This is usually not called, instead the command() or other shortcut decorators are used instead.

Добавлено в версии 2.0.

Параметры:

command (ApplicationCommand) – The command to add.

Тип результата:

None

add_check(func, *, call_once=False)

Adds a global check to the bot. This is the non-decorator interface to check() and check_once().

Параметры:

  • func – The function that was used as a global check.

  • call_once (bool) – If the function should only be called once per Bot.invoke() call.

Тип результата:

None

add_cog(cog, *, override=False)

Adds a «cog» to the bot.

A cog is a class that has its own event listeners and commands.

Изменено в версии 2.0: ClientException is raised when a cog with the same name is already loaded.

Параметры:

  • cog (Cog) – The cog to register to the bot.

  • override (bool) –

    If a previously loaded cog with the same name should be ejected instead of raising an error.

    Добавлено в версии 2.0.

Исключение:
Тип результата:

None

add_listener(func, name=...)

The non decorator alternative to listen().

Параметры:
Исключение:

  • TypeError – The func parameter is not a coroutine function.

  • ValueError – The name (event name) does not start with on_.

Тип результата:

None

Пример

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

client.add_listener(on_ready)
client.add_listener(my_message, 'on_message')
add_view(view, *, message_id=None)

Registers a BaseView for persistent listening.

This method should be used for when a view is comprised of components that last longer than the lifecycle of the program.

Добавлено в версии 2.0.

Параметры:

  • view (BaseView) – The view to register for dispatching.

  • message_id (int | None) – The message ID that the view is attached to. This is currently used to refresh the view’s state during message update events. If not given then message update events are not propagated for the view.

Исключение:

  • TypeError – A view was not passed.

  • ValueError – The view is not persistent. A persistent view has no timeout and all their components have an explicitly provided custom_id.

Тип результата:

None

after_invoke(coro)

A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required. This post-invoke hook takes a sole parameter, a Context.

Примечание

Similar to before_invoke(), this is not called unless checks and argument parsing procedures succeed. This hook is, however, always called regardless of the internal command callback raising an error (i.e. CommandInvokeError). This makes it ideal for clean-up scenarios.

Параметры:

coro (coroutine) – The coroutine to register as the post-invoke hook.

Исключение:

TypeError – The coroutine passed is not actually a coroutine.

property allowed_mentions: AllowedMentions | None

The allowed mention configuration.

Добавлено в версии 1.4.

property app_emojis: list[AppEmoji]

The AppEmoji that the connected client has.

Примечание

This is only available if cache_app_emojis is True.

application_command(*, cls=<class 'discord.commands.core.SlashCommand'>, checks=..., cog=..., contexts=..., cooldown=..., default_member_permissions=..., description=..., description_localizations=..., guild_ids=..., guild_only=..., integration_types=..., name=..., name_localizations=..., nsfw=..., options=..., parent=..., **kwargs)

A shortcut decorator that converts the provided function into an application command via command() and adds it to the internal command list via add_application_command().

Добавлено в версии 2.0.

Параметры:
Результат:

A decorator that converts the provided function into an ApplicationCommand, adds it to the bot, and returns it.

Тип результата:

Callable[..., TypeVar(C, bound= MessageCommand | SlashCommand | UserCommand)]

property application_flags: ApplicationFlags

The client’s application flags.

Добавлено в версии 2.0.

property application_id: int | None

The client’s application ID.

If this is not passed via __init__ then this is retrieved through the gateway when an event contains the data. Usually after on_connect() is called.

Добавлено в версии 2.0.

await application_info()

This function is a coroutine.

Retrieves the bot’s application information.

Результат:

The bot’s application information.

Тип результата:

AppInfo

Исключение:

HTTPException – Retrieving the information failed somehow.

await before_identify_hook(shard_id, *, initial=False)

This function is a coroutine.

A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients.

The default implementation sleeps for 5 seconds.

Добавлено в версии 1.4.

Параметры:

  • shard_id (int | None) – The shard ID that requested being IDENTIFY’d

  • initial (bool) – Whether this IDENTIFY is the first initial IDENTIFY.

Тип результата:

None

before_invoke(coro)

A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required. This pre-invoke hook takes a sole parameter, a Context.

Примечание

The before_invoke() and after_invoke() hooks are only called if all checks and argument parsing procedures pass without error. If any check or argument parsing procedures fail then the hooks are not called.

Параметры:

coro (coroutine) – The coroutine to register as the pre-invoke hook.

Исключение:

TypeError – The coroutine passed is not actually a coroutine.

property cached_messages: Sequence[Message]

Read-only list of messages the connected client has cached.

Добавлено в версии 1.1.

await change_presence(*, activity=None, status=None)

This function is a coroutine.

Changes the client’s presence.

Параметры:

  • activity (BaseActivity | None) – The activity being done. None if no currently active activity is done.

  • status (Status | None) – Indicates what status to change to. If None, then Status.online is used.

Исключение:

InvalidArgument – If the activity parameter is not the proper type.

Пример

game = discord.Game("with the API")
await client.change_presence(status=discord.Status.idle, activity=game)

Изменено в версии 2.0: Removed the afk keyword-only parameter.

check(func)

A decorator that adds a global check to the bot. A global check is similar to a check() that is applied on a per-command basis except it is run before any command checks have been verified and applies to every command the bot has.

Примечание

This function can either be a regular function or a coroutine. Similar to a command check(), this takes a single parameter of type Context and can only raise exceptions inherited from ApplicationCommandError.

Пример

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

A decorator that adds a «call once» global check to the bot. Unlike regular global checks, this one is called only once per Bot.invoke() call. Regular global checks are called whenever a command is called or Command.can_run() is called. This type of check bypasses that and ensures that it’s called only once, even inside the default help command.

Примечание

When using this function the Context sent to a group subcommand may only parse the parent command and not the subcommands due to it being invoked once per Bot.invoke() call.

Примечание

This function can either be a regular function or a coroutine. Similar to a command check(), this takes a single parameter of type Context and can only raise exceptions inherited from ApplicationCommandError.

Пример

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

Clears the internal state of the bot.

After this, the bot can be considered «re-opened», i.e. is_closed() and is_ready() both return False along with the bot’s internal cache cleared.

Тип результата:

None

await close()

This function is a coroutine.

Closes the connection to Discord.

Тип результата:

None

property cogs: Mapping[str, Cog]

A read-only mapping of cog name to cog.

await connect(*, reconnect=True)

This function is a coroutine.

Creates a WebSocket connection and lets the WebSocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

Параметры:

reconnect (bool) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

Исключение:

  • GatewayNotFound – The gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

  • ConnectionClosed – The WebSocket connection has been terminated.

Тип результата:

None

await create_dm(user)

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Добавлено в версии 2.0.

Параметры:

user (Snowflake) – The user to create a DM with.

Результат:

The channel that was created.

Тип результата:

DMChannel

await create_emoji(*, name, image)

This function is a coroutine.

Creates a custom AppEmoji for the application.

There is currently a limit of 2000 emojis per application.

Параметры:

  • name (str) – The emoji name. Must be at least 2 characters.

  • image (bytes) – The bytes-like object representing the image data to use. Only JPG, PNG and GIF images are supported.

Исключение:

HTTPException – An error occurred creating an emoji.

Результат:

The created emoji.

Тип результата:

AppEmoji

create_group(name, description=None, guild_ids=None, **kwargs)

A shortcut method that creates a slash command group with no subcommands and adds it to the internal command list via add_application_command().

Добавлено в версии 2.0.

Параметры:

  • name (str) – The name of the group to create.

  • description (str | None) – The description of the group to create.

  • guild_ids (list[int] | None) – A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if None is passed.

  • kwargs – Any additional keyword arguments to pass to SlashCommandGroup.

Результат:

The slash command group that was created.

Тип результата:

SlashCommandGroup

await delete_emoji(emoji)

This function is a coroutine.

Deletes the custom AppEmoji from the application.

Параметры:

emoji (Snowflake) – The emoji you are deleting.

Исключение:

HTTPException – An error occurred deleting the emoji.

Тип результата:

None

await delete_invite(invite)

This function is a coroutine.

Revokes an Invite, URL, or ID to an invite.

You must have the manage_channels permission in the associated guild to do this.

Параметры:

invite (Invite | str) – The invite to revoke.

Исключение:

  • Forbidden – You do not have permissions to revoke invites.

  • NotFound – The invite is invalid or expired.

  • HTTPException – Revoking the invite failed.

Тип результата:

None

property emojis: list[GuildEmoji | AppEmoji]

The emojis that the connected client has.

Примечание

This only includes the application’s emojis if cache_app_emojis is True.

entitlements(user=None, skus=None, before=None, after=None, limit=100, guild=None, exclude_ended=False)

Returns an AsyncIterator that enables fetching the application’s entitlements.

Добавлено в версии 2.6.

Параметры:

  • user (Snowflake | None) – Limit the fetched entitlements to entitlements owned by this user.

  • skus (list[Snowflake] | None) – Limit the fetched entitlements to entitlements that are for these SKUs.

  • before (Snowflake | datetime | None) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Snowflake | datetime | None) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time.

  • limit (int | None) – The number of entitlements to retrieve. If None, retrieves every entitlement, which may be slow. Defaults to 100.

  • guild (Snowflake | None) – Limit the fetched entitlements to entitlements owned by this guild.

  • exclude_ended (bool) – Whether to limit the fetched entitlements to those that have not ended. Defaults to False.

Yields:

Entitlement – The application’s entitlements.

Исключение:

HTTPException – Retrieving the entitlements failed.

Тип результата:

EntitlementIterator

Примеры

Usage

async for entitlement in client.entitlements():
    print(entitlement.user_id)

Flattening into a list

entitlements = await user.entitlements().flatten()

All parameters are optional.

property extensions: Mapping[str, ModuleType]

A read-only mapping of extension name to extension.

await fetch_application(application_id, /)

This function is a coroutine. Retrieves a PartialAppInfo from an application ID.

Параметры:

application_id (int) – The application ID to retrieve information from.

Результат:

The application information.

Тип результата:

PartialAppInfo

Исключение:

  • NotFound – An application with this ID does not exist.

  • HTTPException – Retrieving the application failed.

await fetch_channel(channel_id, /)

This function is a coroutine.

Retrieves a abc.GuildChannel, abc.PrivateChannel, or Thread with the specified ID.

Примечание

This method is an API call. For general usage, consider get_channel() instead.

Добавлено в версии 1.2.

Результат:

The channel from the ID.

Тип результата:

GuildChannel | PrivateChannel | Thread

Исключение:

  • InvalidData – An unknown channel type was received from Discord.

  • HTTPException – Retrieving the channel failed.

  • NotFound – Invalid Channel ID.

  • Forbidden – You do not have permission to fetch this channel.

Параметры:

channel_id (int)

await fetch_default_sounds()

This function is a coroutine.

Fetches the bot’s default sounds.

Добавлено в версии 2.7.

Результат:

The bot’s default sounds.

Тип результата:

list[SoundboardSound]

await fetch_emoji(emoji_id, /)

This function is a coroutine.

Retrieves a custom AppEmoji from the application.

Параметры:

emoji_id (int) – The emoji’s ID.

Результат:

The retrieved emoji.

Тип результата:

AppEmoji

Исключение:

  • NotFound – The emoji requested could not be found.

  • HTTPException – An error occurred fetching the emoji.

await fetch_emojis()

This function is a coroutine.

Retrieves all custom AppEmojis from the application.

Исключение:

HTTPException – An error occurred fetching the emojis.

Результат:

The retrieved emojis.

Тип результата:

list[AppEmoji]

await fetch_guild(guild_id, /, *, with_counts=True)

This function is a coroutine.

Retrieves a Guild from an ID.

Примечание

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Примечание

This method is an API call. For general usage, consider get_guild() instead.

Параметры:
Результат:

The guild from the ID.

Тип результата:

Guild

Исключение:
fetch_guilds(*, limit=100, before=None, after=None, with_counts=True)

Retrieves an AsyncIterator that enables receiving your guilds.

Примечание

Using this, you will only receive Guild.owner, Guild.icon, Guild.id, and Guild.name per Guild.

Примечание

This method is an API call. For general usage, consider guilds instead.

Параметры:

  • limit (int | None) – The number of guilds to retrieve. If None, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to 100.

  • before (Snowflake | datetime) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Snowflake | datetime) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • with_counts (bool) – Whether to include member count information in guilds. This fills the Guild.approximate_member_count and Guild.approximate_presence_count fields. Defaults to True.

Yields:

Guild – The guild with the guild data parsed.

Исключение:

HTTPException – Getting the guilds failed.

Тип результата:

GuildIterator

Примеры

Usage

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

Flattening into a list

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

All parameters are optional.

await fetch_invite(url, *, with_counts=True, with_expiration=True, event_id=None)

This function is a coroutine.

Gets an Invite from a discord.gg URL or ID.

Примечание

If the invite is for a guild you have not joined, the guild and channel attributes of the returned Invite will be PartialInviteGuild and PartialInviteChannel respectively.

Параметры:
Результат:

The invite from the URL/ID.

Тип результата:

Invite

Исключение:
await fetch_premium_sticker_packs()

This function is a coroutine.

Retrieves all available premium sticker packs.

Добавлено в версии 2.0.

Результат:

All available premium sticker packs.

Тип результата:

list[StickerPack]

Исключение:

HTTPException – Retrieving the sticker packs failed.

await fetch_role_connection_metadata_records()

This function is a coroutine.

Fetches the bot’s role connection metadata records.

Добавлено в версии 2.4.

Результат:

The bot’s role connection metadata records.

Тип результата:

list[ApplicationRoleConnectionMetadata]

await fetch_skus()

This function is a coroutine.

Fetches the bot’s SKUs.

Добавлено в версии 2.5.

Результат:

The bot’s SKUs.

Тип результата:

list[SKU]

await fetch_stage_instance(channel_id, /)

This function is a coroutine.

Gets a StageInstance for a stage channel id.

Добавлено в версии 2.0.

Параметры:

channel_id (int) – The stage channel ID.

Результат:

The stage instance from the stage channel ID.

Тип результата:

StageInstance

Исключение:

  • NotFound – The stage instance or channel could not be found.

  • HTTPException – Getting the stage instance failed.

await fetch_sticker(sticker_id, /)

This function is a coroutine.

Retrieves a Sticker with the specified ID.

Добавлено в версии 2.0.

Результат:

The sticker you requested.

Тип результата:

StandardSticker | GuildSticker

Исключение:
Параметры:

sticker_id (int)

await fetch_template(code)

This function is a coroutine.

Gets a Template from a discord.new URL or code.

Параметры:

code (Template | str) – The Discord Template Code or URL (must be a discord.new URL).

Результат:

The template from the URL/code.

Тип результата:

Template

Исключение:
await fetch_user(user_id, /)

This function is a coroutine.

Retrieves a User based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

Примечание

This method is an API call. If you have discord.Intents.members and member cache enabled, consider get_user() instead.

Параметры:

user_id (int) – The user’s ID to fetch from.

Результат:

The user you requested.

Тип результата:

User

Исключение:
await fetch_webhook(webhook_id, /)

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Результат:

The webhook you requested.

Тип результата:

Webhook

Исключение:
Параметры:

webhook_id (int)

await fetch_widget(guild_id, /)

This function is a coroutine.

Gets a Widget from a guild ID.

Примечание

The guild must have the widget enabled to get this information.

Параметры:

guild_id (int) – The ID of the guild.

Результат:

The guild’s widget.

Тип результата:

Widget

Исключение:
get_all_channels()

A generator that retrieves every abc.GuildChannel the client can „access“.

This is equivalent to:

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

Примечание

Just because you receive a abc.GuildChannel does not mean that you can communicate in said channel. abc.GuildChannel.permissions_for() should be used for that.

Yields:

abc.GuildChannel – A channel the client can „access“.

get_all_members()

Returns a generator with every Member the client can see.

This is equivalent to:

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

Member – A member the client can see.

get_application_command(name, guild_ids=None, type=<class 'discord.commands.core.ApplicationCommand'>)

Get an ApplicationCommand from the internal list of commands.

Добавлено в версии 2.0.

Параметры:
Результат:

The command that was requested. If not found, returns None.

Тип результата:

ApplicationCommand | None

await get_application_context(interaction, cls=<class 'discord.commands.context.ApplicationContext'>)

This function is a coroutine.

Returns the invocation context from the interaction.

This is a more low-level counter-part for process_application_commands() to allow users more fine-grained control over the processing.

Параметры:

  • interaction (Interaction) – The interaction to get the invocation context from.

  • cls (Any) – The factory class that will be used to create the context. By default, this is ApplicationContext. Should a custom class be provided, it must be similar enough to ApplicationContext's interface.

Результат:

The invocation context. The type of this can change via the cls parameter.

Тип результата:

ApplicationContext

await get_autocomplete_context(interaction, cls=<class 'discord.commands.context.AutocompleteContext'>)

This function is a coroutine.

Returns the autocomplete context from the interaction.

This is a more low-level counter-part for process_application_commands() to allow users more fine-grained control over the processing.

Параметры:

  • interaction (Interaction) – The interaction to get the invocation context from.

  • cls (Any) – The factory class that will be used to create the context. By default, this is AutocompleteContext. Should a custom class be provided, it must be similar enough to AutocompleteContext's interface.

Результат:

The autocomplete context. The type of this can change via the cls parameter.

Тип результата:

AutocompleteContext

get_channel(id, /)

Returns a channel or thread with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The returned channel or None if not found.

Тип результата:

GuildChannel | Thread | PrivateChannel | None

get_cog(name)

Gets the cog instance requested.

If the cog is not found, None is returned instead.

Параметры:

name (str) – The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified.

Результат:

The cog that was requested. If not found, returns None.

Тип результата:

Cog | None

property get_command

Shortcut for get_application_command().

Примечание

Overridden in ext.commands.Bot.

Добавлено в версии 2.0.

await get_desynced_commands(guild_id=None, prefetched=None)

This function is a coroutine.

Gets the list of commands that are desynced from discord. If guild_id is specified, it will only return guild commands that are desynced from said guild, else it will return global commands.

Примечание

This function is meant to be used internally, and should only be used if you want to override the default command registration behavior.

Добавлено в версии 2.0.

Параметры:

  • guild_id (int | None) – The guild id to get the desynced commands for, else global commands if unspecified.

  • prefetched (list[ApplicationCommand] | None) – If you already fetched the commands, you can pass them here to be used. Not recommended for typical usage.

Результат:

A list of the desynced commands. Each will come with at least the cmd and action keys, which respectively contain the command and the action to perform. Other keys may also be present depending on the action, including id.

Тип результата:

list[dict[str, Any]]

get_emoji(id, /)

Returns an emoji with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The custom emoji or None if not found.

Тип результата:

GuildEmoji | AppEmoji | None

get_guild(id, /)

Returns a guild with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The guild or None if not found.

Тип результата:

Guild | None

get_message(id, /)

Returns a message the given ID.

This is useful if you have a message_id but don’t want to do an API call to access the message.

Параметры:

id (int) – The ID to search for.

Результат:

The returned message or None if not found.

Тип результата:

Message | None

await get_or_fetch(object_type, object_id, default=None)

Shortcut method to get data from an object either by returning the cached version, or if it does not exist, attempting to fetch it from the API.

Параметры:

  • object_type (type[TypeVar(_FETCHABLE, bound= VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | Role | GuildEmoji | AppEmoji)]) – Type of object to fetch or get.

  • object_id (int | None) – ID of object to get. If None, returns default if provided, else None.

  • default (TypeVar(_D)) – A default to return instead of raising if fetch fails.

  • self (Client)

Результат:

The object if found, or default if provided when not found.

Тип результата:

TypeVar(_FETCHABLE, bound= VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | Role | GuildEmoji | AppEmoji) | TypeVar(_D) | None

Исключение:

  • TypeError – Raised when required parameters are missing or invalid types are provided.

  • InvalidArgument – Raised when an unsupported or incompatible object type is used.

await get_or_fetch_user(id, /)

This function is a coroutine.

Looks up a user in the user cache or fetches if not found.

Параметры:

id (int) – The ID to search for.

Результат:

The user or None if not found.

Тип результата:

User | None

get_partial_messageable(id, *, type=None)

Returns a partial messageable with the given channel ID.

This is useful if you have a channel_id but don’t want to do an API call to send messages to it.

Добавлено в версии 2.0.

Параметры:

  • id (int) – The channel ID to create a partial messageable for.

  • type (ChannelType | None) – The underlying channel type for the partial messageable.

Результат:

The partial messageable

Тип результата:

PartialMessageable

get_poll(id, /)

Returns a poll attached to the given message ID.

Параметры:

id (int) – The message ID of the poll to search for.

Результат:

The poll or None if not found.

Тип результата:

Poll | None

get_sound(sound_id)

Gets a Sound from the bot’s sound cache.

Добавлено в версии 2.7.

Параметры:

sound_id (int) – The ID of the sound to get.

Результат:

The sound with the given ID.

Тип результата:

SoundboardSound | None

get_stage_instance(id, /)

Returns a stage instance with the given stage channel ID.

Добавлено в версии 2.0.

Параметры:

id (int) – The ID to search for.

Результат:

The stage instance or None if not found.

Тип результата:

StageInstance | None

get_sticker(id, /)

Returns a guild sticker with the given ID.

Добавлено в версии 2.0.

Примечание

To retrieve standard stickers, use fetch_sticker(). or fetch_premium_sticker_packs().

Результат:

The sticker or None if not found.

Тип результата:

GuildSticker | None

Параметры:

id (int)

get_user(id, /)

Returns a user with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The user or None if not found.

Тип результата:

User | None

group(name=None, description=None, guild_ids=None)

A shortcut decorator that initializes the provided subclass of SlashCommandGroup and adds it to the internal command list via add_application_command().

Добавлено в версии 2.0.

Параметры:

  • name (str | None) – The name of the group to create. This will resolve to the name of the decorated class if None is passed.

  • description (str | None) – The description of the group to create.

  • guild_ids (list[int] | None) – A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if None is passed.

Результат:

The slash command group that was created.

Тип результата:

Callable[[type[SlashCommandGroup]], SlashCommandGroup]

property guild_emojis: list[GuildEmoji]

The GuildEmoji that the connected client has.

property guilds: list[Guild]

The guilds that the connected client is a member of.

property intents: Intents

The intents configured for this connection.

Добавлено в версии 1.5.

await invoke_application_command(ctx)

This function is a coroutine.

Invokes the application command given under the invocation context and handles all the internal event dispatch mechanisms.

Параметры:

ctx (ApplicationContext) – The invocation context to invoke.

Тип результата:

None

is_closed()

Indicates if the WebSocket connection is closed.

Тип результата:

bool

await is_owner(user)

This function is a coroutine.

Checks if a User or Member is the owner of this bot.

If an owner_id is not set, it is fetched automatically through the use of application_info(), returning the application owner, or all non read-only team members.

Изменено в версии 1.3: The function also checks if the application is team-owned if owner_ids is not set.

Параметры:

user (User | Member) – The user to check for.

Результат:

Whether the user is the owner.

Тип результата:

bool

is_ready()

Specifies if the client’s internal cache is ready for use.

Тип результата:

bool

is_ws_ratelimited()

Whether the WebSocket is currently rate limited.

This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

Добавлено в версии 1.6.

Тип результата:

bool

property latency: float

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. If no websocket is present, this returns nan, and if no heartbeat has been received yet, this returns float('inf').

This could be referred to as the Discord WebSocket protocol latency.

load_extension(name, *, package=None, recursive=False, store=False)

Loads an extension.

An extension is a python module that contains commands, cogs, or listeners.

An extension must have a global function, setup defined as the entry point on what to do when the extension is loaded. This entry point must have a single argument, the bot.

The extension passed can either be the direct name of a file within the current working directory or a folder that contains multiple extensions.

Параметры:

  • name (str) – The extension or folder name to load. It must be dot separated like regular Python imports if accessing a submodule. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g .foo.test. Defaults to None.

    Добавлено в версии 1.7.

  • recursive (Optional[bool]) –

    If subdirectories under the given head directory should be recursively loaded. Defaults to False.

    Добавлено в версии 2.0.

  • store (Optional[bool]) –

    If exceptions should be stored or raised. If set to True, all exceptions encountered will be stored in a returned dictionary as a load status. If set to False, if any exceptions are encountered they will be raised and the bot will be closed. If no exceptions are encountered, a list of loaded extension names will be returned. Defaults to False.

    Добавлено в версии 2.0.

Результат:

If the store parameter is set to True, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension or a True boolean representing a successful load. If the store parameter is set to False, either a list containing a list of loaded extensions or nothing due to an encountered exception.

Тип результата:

dict[str, Exception | bool] | list[str] | None

Исключение:

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • ExtensionAlreadyLoaded – The extension is already loaded.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension or its setup function had an execution error.

load_extensions(*names, package=None, recursive=False, store=False)

Loads multiple extensions at once.

This method simplifies the process of loading multiple extensions by handling the looping of load_extension.

Параметры:

  • names (str) – The extension or folder names to load. It must be dot separated like regular Python imports if accessing a submodule. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g .foo.test. Defaults to None.

    Добавлено в версии 1.7.

  • recursive (Optional[bool]) –

    If subdirectories under the given head directory should be recursively loaded. Defaults to False.

    Добавлено в версии 2.0.

  • store (Optional[bool]) –

    If exceptions should be stored or raised. If set to True, all exceptions encountered will be stored in a returned dictionary as a load status. If set to False, if any exceptions are encountered they will be raised and the bot will be closed. If no exceptions are encountered, a list of loaded extension names will be returned. Defaults to False.

    Добавлено в версии 2.0.

Результат:

If the store parameter is set to True, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension or a True boolean representing a successful load. If the store parameter is set to False, either a list containing names of loaded extensions or nothing due to an encountered exception.

Тип результата:

dict[str, Exception | bool] | list[str] | None

Исключение:

  • ExtensionNotFound – A given extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • ExtensionAlreadyLoaded – A given extension is already loaded.

  • NoEntryPointError – A given extension does not have a setup function.

  • ExtensionFailed – A given extension or its setup function had an execution error.

await login(token)

This function is a coroutine.

Logs in the client with the specified credentials.

Параметры:

token (str) – The authentication token. Do not prefix this token with anything as the library will do it for you.

Исключение:

  • TypeError – The token was in invalid type.

  • LoginFailure – The wrong credentials are passed.

  • HTTPException – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code.

Тип результата:

None

await on_application_command_error(context, exception)

This function is a coroutine.

The default command error handler provided by the bot.

By default, this prints to sys.stderr however it could be overridden to have a different implementation.

This only fires if you do not specify any listeners for command error.

Параметры:
Тип результата:

None

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

This function is a coroutine.

The default error handler provided by the client.

By default, this prints to sys.stderr however it could be overridden to have a different implementation. Check on_error() for more details.

Параметры:
Тип результата:

None

await on_modal_error(error, interaction)

This function is a coroutine.

The default modal error handler provided by the client. The default implementation prints the traceback to stderr.

This only fires for a modal if you did not define its on_error().

Параметры:

  • error (Exception) – The exception that was raised.

  • interaction (Interaction) – The interaction that was received.

Тип результата:

None

await on_view_error(error, item, interaction)

This function is a coroutine.

The default view error handler provided by the client.

This only fires for a view if you did not define its on_error().

Параметры:

  • error (Exception) – The exception that was raised.

  • item (ViewItem) – The item that the user interacted with.

  • interaction (Interaction) – The interaction that was received.

Тип результата:

None

property persistent_views: Sequence[BaseView]

A sequence of persistent views added to the client.

Добавлено в версии 2.0.

property polls: list[Poll]

The polls that the connected client has.

Добавлено в версии 2.6.

property private_channels: list[PrivateChannel]

The private channels that the connected client is participating on.

Примечание

This returns only up to 128 most recent private channels due to an internal working on how Discord deals with private channels.

await process_application_commands(interaction, auto_sync=None)

This function is a coroutine.

This function processes the commands that have been registered to the bot and other groups. Without this coroutine, none of the commands will be triggered.

By default, this coroutine is called inside the on_interaction() event. If you choose to override the on_interaction() event, then you should invoke this coroutine as well.

This function finds a registered command matching the interaction id from application commands and invokes it. If no matching command was found, it replies to the interaction with a default message.

Добавлено в версии 2.0.

Параметры:

  • interaction (Interaction) – The interaction to process

  • auto_sync (bool | None) – Whether to automatically sync and unregister the command if it is not found in the internal cache. This will invoke the sync_commands() method on the context of the command, either globally or per-guild, based on the type of the command, respectively. Defaults to Bot.auto_sync_commands.

Тип результата:

None

await register_command(command, force=True, guild_ids=None)

This function is a coroutine.

Registers a command. If the command has guild_ids set, or if the guild_ids parameter is passed, the command will be registered as a guild command for those guilds.

Параметры:

  • command (ApplicationCommand) – The command to register.

  • force (bool) – Whether to force the command to be registered. If this is set to False, the command will only be registered if it seems to already be registered and up to date with our internal cache. Defaults to True.

  • guild_ids (list[int] | None) – A list of guild ids to register the command for. If this is not set, the command’s ApplicationCommand.guild_ids attribute will be used.

Результат:

The command that was registered

Тип результата:

None

await register_commands(commands=None, guild_id=None, method='bulk', force=False, delete_existing=True)

This function is a coroutine.

Register a list of commands.

Добавлено в версии 2.0.

Параметры:

  • commands (list[ApplicationCommand] | None) – A list of commands to register. If this is not set (None), then all commands will be registered.

  • guild_id (int | None) – If this is set, the commands will be registered as a guild command for the respective guild. If it is not set, the commands will be registered according to their ApplicationCommand.guild_ids attribute.

  • method (Literal['individual', 'bulk', 'auto']) – The method to use when registering the commands. If this is set to «individual», then each command will be registered individually. If this is set to «bulk», then all commands will be registered in bulk. If this is set to «auto», then the method will be determined automatically. Defaults to «bulk».

  • force (bool) – Registers the commands regardless of the state of the command on Discord. This uses one less API call, but can result in hitting rate limits more often. Defaults to False.

  • delete_existing (bool) – Whether to delete existing commands that are not in the list of commands to register. Defaults to True.

Тип результата:

list[ApplicationCommand]

reload_extension(name, *, package=None)

Atomically reloads an extension.

This replaces the extension with the same extension, only refreshed. This is equivalent to a unload_extension() followed by a load_extension() except done in an atomic way. That is, if an operation fails mid-reload then the bot will roll back to the prior working state.

Параметры:

  • name (str) – The extension name to reload. It must be dot separated like regular Python imports if accessing a submodule. e.g. foo.test if you want to import foo/test.py.

  • package (str | None) –

    The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g .foo.test. Defaults to None.

    Добавлено в версии 1.7.

Исключение:

  • ExtensionNotLoaded – The extension was not loaded.

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension setup function had an execution error.

Тип результата:

None

remove_application_command(command)

Remove an ApplicationCommand from the internal list of commands.

Добавлено в версии 2.0.

Параметры:

command (ApplicationCommand) – The command to remove.

Результат:

The command that was removed. If the command has not been added, None is returned instead.

Тип результата:

ApplicationCommand | None

remove_check(func, *, call_once=False)

Removes a global check from the bot. This function is idempotent and will not raise an exception if the function is not in the global checks.

Параметры:

  • func – The function to remove from the global checks.

  • call_once (bool) – If the function was added with call_once=True in the Bot.add_check() call or using check_once().

Тип результата:

None

remove_cog(name)

Removes a cog from the bot and returns it.

All registered commands and event listeners that the cog has registered will be removed as well.

If no cog is found then this method has no effect.

Параметры:

name (str) – The name of the cog to remove.

Результат:

The cog that was removed. None if not found.

Тип результата:

Cog | None

remove_listener(func, name=...)

Removes a listener from the pool of listeners.

Параметры:

  • func (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) – The function that was used as a listener to remove.

  • name (str) – The name of the event we want to remove. Defaults to func.__name__.

Тип результата:

None

run(*args, **kwargs)

A blocking call that abstracts away the event loop initialisation from you.

If you want more control over the event loop then this function should not be used. Use start() coroutine or connect() + login().

Roughly Equivalent to:

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

Предупреждение

This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns.

Параметры:
Тип результата:

None

slash_group(name=None, description=None, guild_ids=None)

A shortcut decorator that initializes the provided subclass of SlashCommandGroup and adds it to the internal command list via add_application_command().

Добавлено в версии 2.0.

Параметры:

  • name (str | None) – The name of the group to create. This will resolve to the name of the decorated class if None is passed.

  • description (str | None) – The description of the group to create.

  • guild_ids (list[int] | None) – A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if None is passed.

Результат:

The slash command group that was created.

Тип результата:

Callable[[type[SlashCommandGroup]], SlashCommandGroup]

property sounds: list[SoundboardSound]

A list of all the sounds the bot can see.

Добавлено в версии 2.7.

await start(token, *, reconnect=True)

This function is a coroutine.

A shorthand coroutine for login() + connect().

Исключение:

TypeError – An unexpected keyword argument was received.

Параметры:
Тип результата:

None

property status: Status

The status being used upon logging on to Discord.

property stickers: list[GuildSticker]

The stickers that the connected client has.

Добавлено в версии 2.0.

property store_url: str

The URL that leads to the application’s store page for monetization.

Добавлено в версии 2.6.

Type:

str

await sync_commands(commands=None, method='bulk', force=False, guild_ids=None, register_guild_commands=True, check_guilds=[], delete_existing=True)

This function is a coroutine.

Registers all commands that have been added through add_application_command(). This method cleans up all commands over the API and should sync them with the internal cache of commands. It attempts to register the commands in the most efficient way possible, unless force is set to True, in which case it will always register all commands.

By default, this coroutine is called inside the on_connect() event. If you choose to override the on_connect() event, then you should invoke this coroutine as well such as the following:

@bot.event
async def on_connect():
    if bot.auto_sync_commands:
        await bot.sync_commands()
    print(f"{bot.user.name} connected.")

Примечание

If you remove all guild commands from a particular guild, the library may not be able to detect and update the commands accordingly, as it would have to individually check for each guild. To force the library to unregister a guild’s commands, call this function with commands=[] and guild_ids=[guild_id].

Добавлено в версии 2.0.

Параметры:

  • commands (list[ApplicationCommand] | None) – A list of commands to register. If this is not set (None), then all commands will be registered.

  • method (Literal['individual', 'bulk', 'auto']) – The method to use when registering the commands. If this is set to «individual», then each command will be registered individually. If this is set to «bulk», then all commands will be registered in bulk. If this is set to «auto», then the method will be determined automatically. Defaults to «bulk».

  • force (bool) – Registers the commands regardless of the state of the command on Discord. This uses one less API call, but can result in hitting rate limits more often. Defaults to False.

  • guild_ids (list[int] | None) – A list of guild ids to register the commands for. If this is not set, the commands“ guild_ids attribute will be used.

  • register_guild_commands (bool) – Whether to register guild commands. Defaults to True.

  • check_guilds (list[int] | None) – A list of guilds ids to check for commands to unregister, since the bot would otherwise have to check all guilds. Unlike guild_ids, this does not alter the commands“ guild_ids attribute, instead it adds the guild ids to a list of guilds to sync commands for. If register_guild_commands is set to False, then this parameter is ignored.

  • delete_existing (bool) – Whether to delete existing commands that are not in the list of commands to register. Defaults to True.

Тип результата:

None

unload_extension(name, *, package=None)

Unloads an extension.

When the extension is unloaded, all commands, listeners, and cogs are removed from the bot and the module is un-imported.

The extension can provide an optional global function, teardown, to do miscellaneous clean-up if necessary. This function takes a single parameter, the bot, similar to setup from load_extension().

Параметры:

  • name (str) – The extension name to unload. It must be dot separated like regular Python imports if accessing a submodule. e.g. foo.test if you want to import foo/test.py.

  • package (str | None) –

    The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g .foo.test. Defaults to None.

    Добавлено в версии 1.7.

Исключение:
Тип результата:

None

await update_role_connection_metadata_records(*role_connection_metadata)

This function is a coroutine.

Updates the bot’s role connection metadata records.

Добавлено в версии 2.4.

Параметры:

*role_connection_metadata (ApplicationRoleConnectionMetadata) – The new metadata records to send to Discord.

Результат:

The updated role connection metadata records.

Тип результата:

list[ApplicationRoleConnectionMetadata]

property user: ClientUser | None

Represents the connected client. None if not logged in.

property users: list[User]

Returns a list of all the users the bot can see.

property voice_clients: list[VoiceProtocol[Self]]

Represents a list of voice connections.

These are usually VoiceClient instances.

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

This function is a coroutine.

Waits for a WebSocket event to be dispatched.

This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use.

In case the event returns multiple arguments, a tuple containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

This function returns the first event that meets the requirements.

Параметры:

  • event (str) – The event name, similar to the event reference, but without the on_ prefix, to wait for.

  • check (Callable[..., bool] | None) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

  • timeout (float | None) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Результат:

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event reference.

Тип результата:

Any

Исключение:

asyncio.TimeoutError – Raised if a timeout is provided and reached.

Примеры

Waiting for a user reply:

@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}!')

Waiting for a thumbs up reaction from the message author:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction, user):
            return user == message.author and str(reaction.emoji) == '👍'

        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')
await wait_until_ready()

This function is a coroutine.

Waits until the client’s internal cache is all ready.

Тип результата:

None

walk_application_commands()

An iterator that recursively walks through all application commands and subcommands.

Yields:

ApplicationCommand – An application command from the internal list of application commands.

class discord.AutoShardedBot(description=None, *args, **options)[исходный код]

This is similar to Bot except that it is inherited from discord.AutoShardedClient instead.

Добавлено в версии 2.0.

Clients

Attributes
Methods
class discord.Client(*, loop=None, **options)[исходный код]

Represents a client connection that connects to Discord. This class is used to interact with the Discord WebSocket and API.

A number of options can be passed to the Client.

Параметры:

  • max_messages (Optional[int]) –

    The maximum number of messages to store in the internal message cache. This defaults to 1000. Passing in None disables the message cache.

    Изменено в версии 1.3: Allow disabling the message cache and change the default size to 1000.

  • loop (AbstractEventLoop | None) – The asyncio.AbstractEventLoop to use for asynchronous operations. Defaults to None, in which case the default event loop is used via asyncio.get_event_loop() if it exists or one is created via asyncio.new_event_loop().

  • connector (Optional[aiohttp.BaseConnector]) – The connector to use for connection pooling.

  • proxy (Optional[str]) – Proxy URL.

  • proxy_auth (Optional[aiohttp.BasicAuth]) – An object that represents proxy HTTP Basic Authorization.

  • shard_id (Optional[int]) – Integer starting at 0 and less than shard_count.

  • shard_count (Optional[int]) – The total number of shards.

  • application_id (int) – The client’s application ID.

  • intents (Intents) –

    The intents that you want to enable for the session. This is a way of disabling and enabling certain gateway events from triggering and being sent. If not given, defaults to a regularly constructed Intents class.

    Добавлено в версии 1.5.

  • member_cache_flags (MemberCacheFlags) –

    Allows for finer control over how the library caches members. If not given, defaults to cache as much as possible with the currently selected intents.

    Добавлено в версии 1.5.

  • chunk_guilds_at_startup (bool) –

    Indicates if on_ready() should be delayed to chunk all guilds at start-up if necessary. This operation is incredibly slow for large amounts of guilds. The default is True if Intents.members is True.

    Добавлено в версии 1.5.

  • status (Optional[Status]) – A status to start your presence with upon logging on to Discord.

  • activity (Optional[BaseActivity]) – An activity to start your presence with upon logging on to Discord.

  • allowed_mentions (Optional[AllowedMentions]) –

    Control how the client handles mentions by default on every message sent.

    Добавлено в версии 1.4.

  • heartbeat_timeout (float) – The maximum numbers of seconds before timing out and restarting the WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if processing the initial packets take too long to the point of disconnecting you. The default timeout is 60 seconds.

  • guild_ready_timeout (float) –

    The maximum number of seconds to wait for the GUILD_CREATE stream to end before preparing the member cache and firing READY. The default timeout is 2 seconds.

    Добавлено в версии 1.4.

  • assume_unsync_clock (bool) –

    Whether to assume the system clock is unsynced. This applies to the ratelimit handling code. If this is set to True, the default, then the library uses the time to reset a rate limit bucket given by Discord. If this is False then your system clock is used to calculate how long to sleep for. If this is set to False it is recommended to sync your system clock to Google’s NTP server.

    Добавлено в версии 1.3.

  • enable_debug_events (bool) –

    Whether to enable events that are useful only for debugging gateway related information.

    Right now this involves on_socket_raw_receive() and on_socket_raw_send(). If this is False then those events will not be dispatched (due to performance considerations). To enable these events, this must be set to True. Defaults to False.

    Добавлено в версии 2.0.

  • cache_app_emojis (bool) –

    Whether to automatically fetch and cache the application’s emojis on startup and when fetching. Defaults to False.

    Предупреждение

    There are no events related to application emojis - if any are created/deleted on the Developer Dashboard while the client is running, the cache will not be updated until you manually run fetch_emojis().

    Добавлено в версии 2.7.

  • cache_default_sounds (bool) –

    Whether to automatically fetch and cache the default soundboard sounds on startup. Defaults to True.

    Добавлено в версии 2.8.

ws

The WebSocket gateway the client is currently connected to. Could be None.

loop

The event loop that the client uses for asynchronous operations.

Type:

asyncio.AbstractEventLoop

Параметры:

options (Any)

@event(coro)[исходный код]

A decorator that registers an event to listen to.

You can find more info about the events on the documentation below.

The events must be a coroutine, if not, TypeError is raised.

Примечание

This replaces any default handlers. Developers are encouraged to use listen() for adding additional handlers instead of event() unless default method replacement is intended.

Исключение:

TypeError – The coroutine passed is not actually a coroutine.

Пример

@client.event
async def on_ready():
    print('Ready!')
Параметры:

coro (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]]))

Тип результата:

TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])

async for ... in fetch_guilds(*, limit=100, before=None, after=None, with_counts=True)[исходный код]

Retrieves an AsyncIterator that enables receiving your guilds.

Примечание

Using this, you will only receive Guild.owner, Guild.icon, Guild.id, and Guild.name per Guild.

Примечание

This method is an API call. For general usage, consider guilds instead.

Параметры:

  • limit (int | None) – The number of guilds to retrieve. If None, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to 100.

  • before (Snowflake | datetime) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Snowflake | datetime) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • with_counts (bool) – Whether to include member count information in guilds. This fills the Guild.approximate_member_count and Guild.approximate_presence_count fields. Defaults to True.

Yields:

Guild – The guild with the guild data parsed.

Исключение:

HTTPException – Getting the guilds failed.

Тип результата:

GuildIterator

Примеры

Usage

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

Flattening into a list

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

All parameters are optional.

@listen(name=..., once=False)[исходный код]

A decorator that registers another function as an external event listener. Basically this allows you to listen to multiple events from different places e.g. such as on_ready()

The functions being listened to must be a coroutine.

Исключение:

  • TypeError – The function being listened to is not a coroutine.

  • ValueError – The name (event name) does not start with on_.

Пример

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

# in some other file...

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

# listen to the first event only
@client.listen('on_ready', once=True)
async def on_ready():
    print('ready!')

Would print one and two in an unspecified order.

Параметры:
Тип результата:

Callable[[TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])], TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])]

property latency: float

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. If no websocket is present, this returns nan, and if no heartbeat has been received yet, this returns float('inf').

This could be referred to as the Discord WebSocket protocol latency.

is_ws_ratelimited()[исходный код]

Whether the WebSocket is currently rate limited.

This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

Добавлено в версии 1.6.

Тип результата:

bool

property user: ClientUser | None

Represents the connected client. None if not logged in.

property guilds: list[Guild]

The guilds that the connected client is a member of.

property emojis: list[GuildEmoji | AppEmoji]

The emojis that the connected client has.

Примечание

This only includes the application’s emojis if cache_app_emojis is True.

property guild_emojis: list[GuildEmoji]

The GuildEmoji that the connected client has.

property app_emojis: list[AppEmoji]

The AppEmoji that the connected client has.

Примечание

This is only available if cache_app_emojis is True.

property stickers: list[GuildSticker]

The stickers that the connected client has.

Добавлено в версии 2.0.

property polls: list[Poll]

The polls that the connected client has.

Добавлено в версии 2.6.

property cached_messages: Sequence[Message]

Read-only list of messages the connected client has cached.

Добавлено в версии 1.1.

property private_channels: list[PrivateChannel]

The private channels that the connected client is participating on.

Примечание

This returns only up to 128 most recent private channels due to an internal working on how Discord deals with private channels.

property voice_clients: list[VoiceProtocol[Self]]

Represents a list of voice connections.

These are usually VoiceClient instances.

property application_id: int | None

The client’s application ID.

If this is not passed via __init__ then this is retrieved through the gateway when an event contains the data. Usually after on_connect() is called.

Добавлено в версии 2.0.

property application_flags: ApplicationFlags

The client’s application flags.

Добавлено в версии 2.0.

is_ready()[исходный код]

Specifies if the client’s internal cache is ready for use.

Тип результата:

bool

await on_error(event_method, *args, **kwargs)[исходный код]

This function is a coroutine.

The default error handler provided by the client.

By default, this prints to sys.stderr however it could be overridden to have a different implementation. Check on_error() for more details.

Параметры:
Тип результата:

None

await on_view_error(error, item, interaction)[исходный код]

This function is a coroutine.

The default view error handler provided by the client.

This only fires for a view if you did not define its on_error().

Параметры:

  • error (Exception) – The exception that was raised.

  • item (ViewItem) – The item that the user interacted with.

  • interaction (Interaction) – The interaction that was received.

Тип результата:

None

await on_modal_error(error, interaction)[исходный код]

This function is a coroutine.

The default modal error handler provided by the client. The default implementation prints the traceback to stderr.

This only fires for a modal if you did not define its on_error().

Параметры:

  • error (Exception) – The exception that was raised.

  • interaction (Interaction) – The interaction that was received.

Тип результата:

None

await before_identify_hook(shard_id, *, initial=False)[исходный код]

This function is a coroutine.

A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients.

The default implementation sleeps for 5 seconds.

Добавлено в версии 1.4.

Параметры:

  • shard_id (int | None) – The shard ID that requested being IDENTIFY’d

  • initial (bool) – Whether this IDENTIFY is the first initial IDENTIFY.

Тип результата:

None

await login(token)[исходный код]

This function is a coroutine.

Logs in the client with the specified credentials.

Параметры:

token (str) – The authentication token. Do not prefix this token with anything as the library will do it for you.

Исключение:

  • TypeError – The token was in invalid type.

  • LoginFailure – The wrong credentials are passed.

  • HTTPException – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code.

Тип результата:

None

await connect(*, reconnect=True)[исходный код]

This function is a coroutine.

Creates a WebSocket connection and lets the WebSocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

Параметры:

reconnect (bool) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

Исключение:

  • GatewayNotFound – The gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

  • ConnectionClosed – The WebSocket connection has been terminated.

Тип результата:

None

await close()[исходный код]

This function is a coroutine.

Closes the connection to Discord.

Тип результата:

None

clear()[исходный код]

Clears the internal state of the bot.

After this, the bot can be considered «re-opened», i.e. is_closed() and is_ready() both return False along with the bot’s internal cache cleared.

Тип результата:

None

await start(token, *, reconnect=True)[исходный код]

This function is a coroutine.

A shorthand coroutine for login() + connect().

Исключение:

TypeError – An unexpected keyword argument was received.

Параметры:
Тип результата:

None

run(*args, **kwargs)[исходный код]

A blocking call that abstracts away the event loop initialisation from you.

If you want more control over the event loop then this function should not be used. Use start() coroutine or connect() + login().

Roughly Equivalent to:

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

Предупреждение

This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns.

Параметры:
Тип результата:

None

is_closed()[исходный код]

Indicates if the WebSocket connection is closed.

Тип результата:

bool

property activity: Activity | Game | CustomActivity | Streaming | Spotify | None

The activity being used upon logging in.

Тип результата:

Optional[BaseActivity]

property status: Status

The status being used upon logging on to Discord.

property allowed_mentions: AllowedMentions | None

The allowed mention configuration.

Добавлено в версии 1.4.

property intents: Intents

The intents configured for this connection.

Добавлено в версии 1.5.

property users: list[User]

Returns a list of all the users the bot can see.

await fetch_application(application_id, /)[исходный код]

This function is a coroutine. Retrieves a PartialAppInfo from an application ID.

Параметры:

application_id (int) – The application ID to retrieve information from.

Результат:

The application information.

Тип результата:

PartialAppInfo

Исключение:

  • NotFound – An application with this ID does not exist.

  • HTTPException – Retrieving the application failed.

get_channel(id, /)[исходный код]

Returns a channel or thread with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The returned channel or None if not found.

Тип результата:

GuildChannel | Thread | PrivateChannel | None

get_message(id, /)[исходный код]

Returns a message the given ID.

This is useful if you have a message_id but don’t want to do an API call to access the message.

Параметры:

id (int) – The ID to search for.

Результат:

The returned message or None if not found.

Тип результата:

Message | None

get_partial_messageable(id, *, type=None)[исходный код]

Returns a partial messageable with the given channel ID.

This is useful if you have a channel_id but don’t want to do an API call to send messages to it.

Добавлено в версии 2.0.

Параметры:

  • id (int) – The channel ID to create a partial messageable for.

  • type (ChannelType | None) – The underlying channel type for the partial messageable.

Результат:

The partial messageable

Тип результата:

PartialMessageable

get_stage_instance(id, /)[исходный код]

Returns a stage instance with the given stage channel ID.

Добавлено в версии 2.0.

Параметры:

id (int) – The ID to search for.

Результат:

The stage instance or None if not found.

Тип результата:

StageInstance | None

get_guild(id, /)[исходный код]

Returns a guild with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The guild or None if not found.

Тип результата:

Guild | None

get_user(id, /)[исходный код]

Returns a user with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The user or None if not found.

Тип результата:

User | None

get_emoji(id, /)[исходный код]

Returns an emoji with the given ID.

Параметры:

id (int) – The ID to search for.

Результат:

The custom emoji or None if not found.

Тип результата:

GuildEmoji | AppEmoji | None

get_sticker(id, /)[исходный код]

Returns a guild sticker with the given ID.

Добавлено в версии 2.0.

Примечание

To retrieve standard stickers, use fetch_sticker(). or fetch_premium_sticker_packs().

Результат:

The sticker or None if not found.

Тип результата:

GuildSticker | None

Параметры:

id (int)

get_poll(id, /)[исходный код]

Returns a poll attached to the given message ID.

Параметры:

id (int) – The message ID of the poll to search for.

Результат:

The poll or None if not found.

Тип результата:

Poll | None

get_all_channels()[исходный код]

A generator that retrieves every abc.GuildChannel the client can „access“.

This is equivalent to:

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

Примечание

Just because you receive a abc.GuildChannel does not mean that you can communicate in said channel. abc.GuildChannel.permissions_for() should be used for that.

Yields:

abc.GuildChannel – A channel the client can „access“.

get_all_members()[исходный код]

Returns a generator with every Member the client can see.

This is equivalent to:

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

Member – A member the client can see.

await get_or_fetch_user(id, /)[исходный код]

This function is a coroutine.

Looks up a user in the user cache or fetches if not found.

Параметры:

id (int) – The ID to search for.

Результат:

The user or None if not found.

Тип результата:

User | None

await get_or_fetch(object_type, object_id, default=None)[исходный код]

Shortcut method to get data from an object either by returning the cached version, or if it does not exist, attempting to fetch it from the API.

Параметры:

  • object_type (type[TypeVar(_FETCHABLE, bound= VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | Role | GuildEmoji | AppEmoji)]) – Type of object to fetch or get.

  • object_id (int | None) – ID of object to get. If None, returns default if provided, else None.

  • default (TypeVar(_D)) – A default to return instead of raising if fetch fails.

  • self (Client)

Результат:

The object if found, or default if provided when not found.

Тип результата:

TypeVar(_FETCHABLE, bound= VoiceChannel | TextChannel | ForumChannel | StageChannel | CategoryChannel | Thread | Member | User | Guild | Role | GuildEmoji | AppEmoji) | TypeVar(_D) | None

Исключение:

  • TypeError – Raised when required parameters are missing or invalid types are provided.

  • InvalidArgument – Raised when an unsupported or incompatible object type is used.

await wait_until_ready()[исходный код]

This function is a coroutine.

Waits until the client’s internal cache is all ready.

Тип результата:

None

wait_for(event, *, check=None, timeout=None)[исходный код]

This function is a coroutine.

Waits for a WebSocket event to be dispatched.

This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use.

In case the event returns multiple arguments, a tuple containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

This function returns the first event that meets the requirements.

Параметры:

  • event (str) – The event name, similar to the event reference, but without the on_ prefix, to wait for.

  • check (Callable[..., bool] | None) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

  • timeout (float | None) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Результат:

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event reference.

Тип результата:

Any

Исключение:

asyncio.TimeoutError – Raised if a timeout is provided and reached.

Примеры

Waiting for a user reply:

@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}!')

Waiting for a thumbs up reaction from the message author:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction, user):
            return user == message.author and str(reaction.emoji) == '👍'

        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')
add_listener(func, name=...)[исходный код]

The non decorator alternative to listen().

Параметры:
Исключение:

  • TypeError – The func parameter is not a coroutine function.

  • ValueError – The name (event name) does not start with on_.

Тип результата:

None

Пример

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

client.add_listener(on_ready)
client.add_listener(my_message, 'on_message')
remove_listener(func, name=...)[исходный код]

Removes a listener from the pool of listeners.

Параметры:

  • func (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) – The function that was used as a listener to remove.

  • name (str) – The name of the event we want to remove. Defaults to func.__name__.

Тип результата:

None

await change_presence(*, activity=None, status=None)[исходный код]

This function is a coroutine.

Changes the client’s presence.

Параметры:

  • activity (BaseActivity | None) – The activity being done. None if no currently active activity is done.

  • status (Status | None) – Indicates what status to change to. If None, then Status.online is used.

Исключение:

InvalidArgument – If the activity parameter is not the proper type.

Пример

game = discord.Game("with the API")
await client.change_presence(status=discord.Status.idle, activity=game)

Изменено в версии 2.0: Removed the afk keyword-only parameter.

await fetch_template(code)[исходный код]

This function is a coroutine.

Gets a Template from a discord.new URL or code.

Параметры:

code (Template | str) – The Discord Template Code or URL (must be a discord.new URL).

Результат:

The template from the URL/code.

Тип результата:

Template

Исключение:
await fetch_guild(guild_id, /, *, with_counts=True)[исходный код]

This function is a coroutine.

Retrieves a Guild from an ID.

Примечание

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Примечание

This method is an API call. For general usage, consider get_guild() instead.

Параметры:
Результат:

The guild from the ID.

Тип результата:

Guild

Исключение:
await fetch_stage_instance(channel_id, /)[исходный код]

This function is a coroutine.

Gets a StageInstance for a stage channel id.

Добавлено в версии 2.0.

Параметры:

channel_id (int) – The stage channel ID.

Результат:

The stage instance from the stage channel ID.

Тип результата:

StageInstance

Исключение:

  • NotFound – The stage instance or channel could not be found.

  • HTTPException – Getting the stage instance failed.

await fetch_invite(url, *, with_counts=True, with_expiration=True, event_id=None)[исходный код]

This function is a coroutine.

Gets an Invite from a discord.gg URL or ID.

Примечание

If the invite is for a guild you have not joined, the guild and channel attributes of the returned Invite will be PartialInviteGuild and PartialInviteChannel respectively.

Параметры:
Результат:

The invite from the URL/ID.

Тип результата:

Invite

Исключение:
await delete_invite(invite)[исходный код]

This function is a coroutine.

Revokes an Invite, URL, or ID to an invite.

You must have the manage_channels permission in the associated guild to do this.

Параметры:

invite (Invite | str) – The invite to revoke.

Исключение:

  • Forbidden – You do not have permissions to revoke invites.

  • NotFound – The invite is invalid or expired.

  • HTTPException – Revoking the invite failed.

Тип результата:

None

await fetch_widget(guild_id, /)[исходный код]

This function is a coroutine.

Gets a Widget from a guild ID.

Примечание

The guild must have the widget enabled to get this information.

Параметры:

guild_id (int) – The ID of the guild.

Результат:

The guild’s widget.

Тип результата:

Widget

Исключение:
await application_info()[исходный код]

This function is a coroutine.

Retrieves the bot’s application information.

Результат:

The bot’s application information.

Тип результата:

AppInfo

Исключение:

HTTPException – Retrieving the information failed somehow.

await fetch_user(user_id, /)[исходный код]

This function is a coroutine.

Retrieves a User based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

Примечание

This method is an API call. If you have discord.Intents.members and member cache enabled, consider get_user() instead.

Параметры:

user_id (int) – The user’s ID to fetch from.

Результат:

The user you requested.

Тип результата:

User

Исключение:
await fetch_channel(channel_id, /)[исходный код]

This function is a coroutine.

Retrieves a abc.GuildChannel, abc.PrivateChannel, or Thread with the specified ID.

Примечание

This method is an API call. For general usage, consider get_channel() instead.

Добавлено в версии 1.2.

Результат:

The channel from the ID.

Тип результата:

GuildChannel | PrivateChannel | Thread

Исключение:

  • InvalidData – An unknown channel type was received from Discord.

  • HTTPException – Retrieving the channel failed.

  • NotFound – Invalid Channel ID.

  • Forbidden – You do not have permission to fetch this channel.

Параметры:

channel_id (int)

await fetch_webhook(webhook_id, /)[исходный код]

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Результат:

The webhook you requested.

Тип результата:

Webhook

Исключение:
Параметры:

webhook_id (int)

await fetch_sticker(sticker_id, /)[исходный код]

This function is a coroutine.

Retrieves a Sticker with the specified ID.

Добавлено в версии 2.0.

Результат:

The sticker you requested.

Тип результата:

StandardSticker | GuildSticker

Исключение:
Параметры:

sticker_id (int)

await fetch_premium_sticker_packs()[исходный код]

This function is a coroutine.

Retrieves all available premium sticker packs.

Добавлено в версии 2.0.

Результат:

All available premium sticker packs.

Тип результата:

list[StickerPack]

Исключение:

HTTPException – Retrieving the sticker packs failed.

await create_dm(user)[исходный код]

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Добавлено в версии 2.0.

Параметры:

user (Snowflake) – The user to create a DM with.

Результат:

The channel that was created.

Тип результата:

DMChannel

add_view(view, *, message_id=None)[исходный код]

Registers a BaseView for persistent listening.

This method should be used for when a view is comprised of components that last longer than the lifecycle of the program.

Добавлено в версии 2.0.

Параметры:

  • view (BaseView) – The view to register for dispatching.

  • message_id (int | None) – The message ID that the view is attached to. This is currently used to refresh the view’s state during message update events. If not given then message update events are not propagated for the view.

Исключение:

  • TypeError – A view was not passed.

  • ValueError – The view is not persistent. A persistent view has no timeout and all their components have an explicitly provided custom_id.

Тип результата:

None

property persistent_views: Sequence[BaseView]

A sequence of persistent views added to the client.

Добавлено в версии 2.0.

await fetch_role_connection_metadata_records()[исходный код]

This function is a coroutine.

Fetches the bot’s role connection metadata records.

Добавлено в версии 2.4.

Результат:

The bot’s role connection metadata records.

Тип результата:

list[ApplicationRoleConnectionMetadata]

await update_role_connection_metadata_records(*role_connection_metadata)[исходный код]

This function is a coroutine.

Updates the bot’s role connection metadata records.

Добавлено в версии 2.4.

Параметры:

*role_connection_metadata (ApplicationRoleConnectionMetadata) – The new metadata records to send to Discord.

Результат:

The updated role connection metadata records.

Тип результата:

list[ApplicationRoleConnectionMetadata]

await fetch_skus()[исходный код]

This function is a coroutine.

Fetches the bot’s SKUs.

Добавлено в версии 2.5.

Результат:

The bot’s SKUs.

Тип результата:

list[SKU]

entitlements(user=None, skus=None, before=None, after=None, limit=100, guild=None, exclude_ended=False)[исходный код]

Returns an AsyncIterator that enables fetching the application’s entitlements.

Добавлено в версии 2.6.

Параметры:

  • user (Snowflake | None) – Limit the fetched entitlements to entitlements owned by this user.

  • skus (list[Snowflake] | None) – Limit the fetched entitlements to entitlements that are for these SKUs.

  • before (Snowflake | datetime | None) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Snowflake | datetime | None) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time.

  • limit (int | None) – The number of entitlements to retrieve. If None, retrieves every entitlement, which may be slow. Defaults to 100.

  • guild (Snowflake | None) – Limit the fetched entitlements to entitlements owned by this guild.

  • exclude_ended (bool) – Whether to limit the fetched entitlements to those that have not ended. Defaults to False.

Yields:

Entitlement – The application’s entitlements.

Исключение:

HTTPException – Retrieving the entitlements failed.

Тип результата:

EntitlementIterator

Примеры

Usage

async for entitlement in client.entitlements():
    print(entitlement.user_id)

Flattening into a list

entitlements = await user.entitlements().flatten()

All parameters are optional.

property store_url: str

The URL that leads to the application’s store page for monetization.

Добавлено в версии 2.6.

Type:

str

await fetch_emojis()[исходный код]

This function is a coroutine.

Retrieves all custom AppEmojis from the application.

Исключение:

HTTPException – An error occurred fetching the emojis.

Результат:

The retrieved emojis.

Тип результата:

list[AppEmoji]

await fetch_emoji(emoji_id, /)[исходный код]

This function is a coroutine.

Retrieves a custom AppEmoji from the application.

Параметры:

emoji_id (int) – The emoji’s ID.

Результат:

The retrieved emoji.

Тип результата:

AppEmoji

Исключение:

  • NotFound – The emoji requested could not be found.

  • HTTPException – An error occurred fetching the emoji.

await create_emoji(*, name, image)[исходный код]

This function is a coroutine.

Creates a custom AppEmoji for the application.

There is currently a limit of 2000 emojis per application.

Параметры:

  • name (str) – The emoji name. Must be at least 2 characters.

  • image (bytes) – The bytes-like object representing the image data to use. Only JPG, PNG and GIF images are supported.

Исключение:

HTTPException – An error occurred creating an emoji.

Результат:

The created emoji.

Тип результата:

AppEmoji

await delete_emoji(emoji)[исходный код]

This function is a coroutine.

Deletes the custom AppEmoji from the application.

Параметры:

emoji (Snowflake) – The emoji you are deleting.

Исключение:

HTTPException – An error occurred deleting the emoji.

Тип результата:

None

get_sound(sound_id)[исходный код]

Gets a Sound from the bot’s sound cache.

Добавлено в версии 2.7.

Параметры:

sound_id (int) – The ID of the sound to get.

Результат:

The sound with the given ID.

Тип результата:

SoundboardSound | None

property sounds: list[SoundboardSound]

A list of all the sounds the bot can see.

Добавлено в версии 2.7.

await fetch_default_sounds()[исходный код]

This function is a coroutine.

Fetches the bot’s default sounds.

Добавлено в версии 2.7.

Результат:

The bot’s default sounds.

Тип результата:

list[SoundboardSound]

Attributes
Methods
class discord.AutoShardedClient(*args, loop=None, **kwargs)[исходный код]

A client similar to Client except it handles the complications of sharding for the user into a more manageable and transparent single process bot.

When using this client, you will be able to use it as-if it was a regular Client with a single shard when implementation wise internally it is split up into multiple shards. This allows you to not have to deal with IPC or other complicated infrastructure.

It is recommended to use this client only if you have surpassed at least 1000 guilds.

If no shard_count is provided, then the library will use the Bot Gateway endpoint call to figure out how many shards to use.

If a shard_ids parameter is given, then those shard IDs will be used to launch the internal shards. Note that shard_count must be provided if this is used. By default, when omitted, the client will launch shards from 0 to shard_count - 1.

shard_ids

An optional list of shard_ids to launch the shards with.

Type:

Optional[List[int]]

Параметры:
property latency: float

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This operates similarly to Client.latency() except it uses the average latency of every shard’s latency. To get a list of shard latency, check the latencies property. Returns nan if there are no shards ready.

property latencies: list[tuple[int, float]]

A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This returns a list of tuples with elements (shard_id, latency).

get_shard(shard_id)[исходный код]

Gets the shard information at a given shard ID or None if not found.

Параметры:

shard_id (int)

Тип результата:

ShardInfo | None

property shards: dict[int, ShardInfo]

Returns a mapping of shard IDs to their respective info object.

await connect(*, reconnect=True)[исходный код]

This function is a coroutine.

Creates a WebSocket connection and lets the WebSocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

Параметры:

reconnect (bool) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

Исключение:

  • GatewayNotFound – The gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

  • ConnectionClosed – The WebSocket connection has been terminated.

Тип результата:

None

await close()[исходный код]

This function is a coroutine.

Closes the connection to Discord.

Тип результата:

None

await change_presence(*, activity=None, status=None, shard_id=None)[исходный код]

This function is a coroutine.

Changes the client’s presence.

Example:

game = discord.Game("with the API")
await client.change_presence(status=discord.Status.idle, activity=game)

Изменено в версии 2.0: Removed the afk keyword-only parameter.

Параметры:

  • activity (BaseActivity | None) – The activity being done. None if no currently active activity is done.

  • status (Status | None) – Indicates what status to change to. If None, then Status.online is used.

  • shard_id (int) – The shard_id to change the presence to. If not specified or None, then it will change the presence of every shard the bot can see.

Исключение:

InvalidArgument – If the activity parameter is not of proper type.

Тип результата:

None

is_ws_ratelimited()[исходный код]

Whether the websocket is currently rate limited.

This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

This implementation checks if any of the shards are rate limited. For more granular control, consider ShardInfo.is_ws_ratelimited().

Добавлено в версии 1.6.

Тип результата:

bool