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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 2.6.

Type:

Collection[IntegrationType]]

@command(**kwargs)

An alias for application_command().

참고

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

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

    Added in version 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.

Added in version 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.

Added in version 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().

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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().

Added in version 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.

Added in version 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.

생성:

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.

Added in version 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.

Added in version 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.

생성:

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.

Added in version 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.

Added in version 2.4.

반환:

The bot’s role connection metadata records.

반환 형식:

list[ApplicationRoleConnectionMetadata]

await fetch_skus()

This function is a coroutine.

Fetches the bot’s SKUs.

Added in version 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.

Added in version 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.

Added in version 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.

생성:

abc.GuildChannel – A channel the client can ‘access’.

반환 형식:

Generator[GuildChannel, None, None]

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
생성:

Member – A member the client can see.

반환 형식:

Generator[Member, None, None]

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

Get an ApplicationCommand from the internal list of commands.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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().

Added in version 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.

Added in version 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.

Added in version 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.

    Added in version 1.7.

  • recursive (Optional[bool]) –

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

    Added in version 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.

    Added in version 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.

    Added in version 1.7.

  • recursive (Optional[bool]) –

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

    Added in version 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.

    Added in version 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.

Added in version 2.0.

property polls: list[Poll]

The polls that the connected client has.

Added in version 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.

Added in version 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.

Added in version 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.

    Added in version 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.

Added in version 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().

Added in version 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.

Added in version 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.

Added in version 2.0.

property store_url: str

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

Added in version 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].

Added in version 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.

    Added in version 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.

Added in version 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.

생성:

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

반환 형식:

Generator[ApplicationCommand, None, None]

class discord.AutoShardedBot(description=None, *args, **options)[소스]

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

Added in version 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.

    Added in version 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.

    Added in version 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.

    Added in version 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.

    Added in version 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.

    Added in version 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.

    Added in version 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.

    Added in version 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().

    Added in version 2.7.

  • cache_default_sounds (bool) –

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

    Added in version 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.

생성:

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.

Added in version 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.

Added in version 2.0.

property polls: list[Poll]

The polls that the connected client has.

Added in version 2.6.

property cached_messages: Sequence[Message]

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

Added in version 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.

Added in version 2.0.

property application_flags: ApplicationFlags

The client’s application flags.

Added in version 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.

Added in version 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.

Added in version 1.4.

property intents: Intents

The intents configured for this connection.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

생성:

abc.GuildChannel – A channel the client can ‘access’.

반환 형식:

Generator[GuildChannel, None, None]

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
생성:

Member – A member the client can see.

반환 형식:

Generator[Member, None, None]

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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 2.0.

await fetch_role_connection_metadata_records()[소스]

This function is a coroutine.

Fetches the bot’s role connection metadata records.

Added in version 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.

Added in version 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.

Added in version 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.

Added in version 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.

생성:

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.

Added in version 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.

Added in version 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.

Added in version 2.7.

await fetch_default_sounds()[소스]

This function is a coroutine.

Fetches the bot’s default sounds.

Added in version 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().

Added in version 1.6.

반환 형식:

bool