On command error discord py

Bot¶

class discord.ext.commands.Bot(command_prefix, *, help_command=<default-help-command>, tree_cls=<class ‘discord.app_commands.tree.CommandTree’>, description=None, intents, **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 GroupMixin to provide the functionality
to manage commands.

Unlike discord.Client, this class does not require manually setting
a CommandTree and is automatically set upon
instantiating the class.

async with x

Asynchronously initialises the bot and automatically cleans up.

New in version 2.0.

command_prefix¶

The command prefix is what the message content must contain initially
to have a command invoked. This prefix could either be a string to
indicate what the prefix should be, or a callable that takes in the bot
as its first parameter and discord.Message as its second
parameter and returns the prefix. This is to facilitate “dynamic”
command prefixes. This callable can be either a regular function or
a coroutine.

An empty string as the prefix always matches, enabling prefix-less
command invocation. While this may be useful in DMs it should be avoided
in servers, as it’s likely to cause performance issues and unintended
command invocations.

The command prefix could also be an iterable of strings indicating that
multiple checks for the prefix should be used and the first one to
match will be the invocation prefix. You can get this prefix via
Context.prefix.

Note

When passing multiple prefixes be careful to not pass a prefix
that matches a longer prefix occurring later in the sequence. For
example, if the command prefix is ('!', '!?') the '!?'
prefix will never be matched to any message as the previous one
matches messages starting with !?. This is especially important
when passing an empty string, it should always be last as no prefix
after it will be matched.

case_insensitive¶

Whether the commands should be case insensitive. Defaults to False. This
attribute does not carry over to groups. You must set it to every group if
you require group commands to be case insensitive as well.

Type

bool

description¶

The content prefixed into the default help message.

Type

str

help_command¶

The help command implementation to use. This can be dynamically
set at runtime. To remove the help command pass None. For more
information on implementing a help command, see Help Commands.

Type

Optional[HelpCommand]

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().

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().
For performance reasons it is recommended to use a set
for the collection. You cannot set both owner_id and owner_ids.

New in version 1.3.

Type

Optional[Collection[int]]

strip_after_prefix¶

Whether to strip whitespace characters after encountering the command
prefix. This allows for !   hello and !hello to both work if
the command_prefix is set to !. Defaults to False.

New in version 1.7.

Type

bool

tree_cls¶

The type of application command tree to use. Defaults to CommandTree.

New in version 2.0.

Type

Type[CommandTree]

@after_invoke¶

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.

Note

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.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke¶

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.

Note

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.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@check¶

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.

Note

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
CommandError.

Example

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

Changed in version 2.0: func parameter is now positional-only.

@check_once¶

A decorator that adds a “call once” global check to the bot.

Unlike regular global checks, this one is called only once
per 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.

Note

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.

Note

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
CommandError.

Example

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

Changed in version 2.0: func parameter is now positional-only.

@command(*args, **kwargs)¶

A shortcut decorator that invokes command() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type

Callable[…, Command]

@event¶

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.

Example

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

Changed in version 2.0: coro parameter is now positional-only.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@group(*args, **kwargs)¶

A shortcut decorator that invokes group() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type

Callable[…, Group]

@hybrid_command(name=…, with_app_command=True, *args, **kwargs)¶

A shortcut decorator that invokes hybrid_command() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type

Callable[…, HybridCommand]

@hybrid_group(name=…, with_app_command=True, *args, **kwargs)¶

A shortcut decorator that invokes hybrid_group() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type

Callable[…, HybridGroup]

@listen(name=None)¶

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.

Example

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

# in some other file...

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

Would print one and two in an unspecified order.

Raises

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

property activity¶

The activity being used upon
logging in.

Type

Optional[BaseActivity]

add_check(func, /, *, call_once=False)¶

Adds a global check to the bot.

This is the non-decorator interface to check()
and check_once().

Changed in version 2.0: func parameter is now positional-only.

See also

The check() decorator

Parameters

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

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

await add_cog(cog, /, *, override=False, guild=…, guilds=…)¶

This function is a coroutine.

Adds a “cog” to the bot.

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

If the cog is a app_commands.Group then it is added to
the bot’s CommandTree as well.

Note

Exceptions raised inside a Cog’s cog_load() method will be
propagated to the caller.

Changed in version 2.0: ClientException is raised when a cog with the same name
is already loaded.

Changed in version 2.0: cog parameter is now positional-only.

Changed in version 2.0: This method is now a coroutine.

Parameters

• 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.

  New in version 2.0.

• guild (Optional[Snowflake]) –

  If the cog is an application command group, then this would be the
  guild where the cog group would be added to. If not given then
  it becomes a global command instead.

  New in version 2.0.

• guilds (List[Snowflake]) –

  If the cog is an application command group, then this would be the
  guilds where the cog group would be added to. If not given then
  it becomes a global command instead. Cannot be mixed with
  guild.

  New in version 2.0.

Raises

• TypeError – The cog does not inherit from Cog.

• CommandError – An error happened during loading.

• ClientException – A cog with the same name is already loaded.

add_command(command, /)¶

Adds a Command into the internal list of commands.

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

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Changed in version 2.0: command parameter is now positional-only.

Parameters

command (Command) – The command to add.

Raises

• CommandRegistrationError – If the command or its alias is already registered by different command.

• TypeError – If the command passed is not a subclass of Command.

add_listener(func, /, name=…)¶

The non decorator alternative to listen().

Changed in version 2.0: func parameter is now positional-only.

Parameters

• func (coroutine) – The function to call.

• name (str) – The name of the event to listen for. Defaults to func.__name__.

Example

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

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

add_view(view, *, message_id=None)¶

Registers a View 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.

New in version 2.0.

Parameters

• view (discord.ui.View) – The view to register for dispatching.

• message_id (Optional[int]) – 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.

Raises

• 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.

property allowed_mentions¶

The allowed mention configuration.

New in version 1.4.

Type

Optional[AllowedMentions]

property application¶

The client’s application info.

This is retrieved on login() and is not updated
afterwards. This allows populating the application_id without requiring a
gateway connection.

This is None if accessed before login() is called.

New in version 2.0.

Type

Optional[AppInfo]

property application_flags¶

The client’s application flags.

New in version 2.0.

Type

ApplicationFlags

property application_id¶

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 or after a call
to login(). Usually after on_connect()
is called.

New in version 2.0.

Type

Optional[int]

await application_info()¶

This function is a coroutine.

Retrieves the bot’s application information.

Raises

HTTPException – Retrieving the information failed somehow.

Returns

The bot’s application information.

Return type

AppInfo

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.

New in version 1.4.

Parameters

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

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

property cached_messages¶

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

New in version 1.1.

Type

Sequence[Message]

await change_presence(*, activity=None, status=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)

Changed in version 2.0: Removed the afk keyword-only parameter.

Changed in version 2.0: This function will now raise TypeError instead of
InvalidArgument.

Parameters

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

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

Raises

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

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.

await close()¶

This function is a coroutine.

Closes the connection to Discord.

property cogs¶

A read-only mapping of cog name to cog.

Type

Mapping[str, Cog]

property commands¶

A unique set of commands without aliases that are registered.

Type

Set[Command]

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.

Parameters

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).

Raises

• GatewayNotFound – If 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.

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.

New in version 2.0.

Parameters

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

Returns

The channel that was created.

Return type

DMChannel

await create_guild(*, name, icon=…, code=…)¶

This function is a coroutine.

Creates a Guild.

Bot accounts in more than 10 guilds are not allowed to create guilds.

Changed in version 2.0: name and icon parameters are now keyword-only. The region parameter has been removed.

Changed in version 2.0: This function will now raise ValueError instead of
InvalidArgument.

Parameters

• name (str) – The name of the guild.

• icon (Optional[bytes]) – The bytes-like object representing the icon. See ClientUser.edit()
  for more details on what is expected.

• code (str) –

  The code for a template to create the guild with.

  New in version 1.4.

Raises

• HTTPException – Guild creation failed.

• ValueError – Invalid icon image format given. Must be PNG or JPG.

Returns

The guild created. This is not the same guild that is
added to cache.

Return type

Guild

await delete_invite(invite, /)¶

This function is a coroutine.

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

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

Changed in version 2.0: invite parameter is now positional-only.

Parameters

invite (Union[Invite, str]) – The invite to revoke.

Raises

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

• NotFound – The invite is invalid or expired.

• HTTPException – Revoking the invite failed.

property emojis¶

The emojis that the connected client has.

Type

Sequence[Emoji]

property extensions¶

A read-only mapping of extension name to extension.

Type

Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)¶

This function is a coroutine.

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

Note

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

New in version 1.2.

Changed in version 2.0: channel_id parameter is now positional-only.

Raises

• 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.

Returns

The channel from the ID.

Return type

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

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

This function is a coroutine.

Retrieves a Guild from an ID.

Note

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

Changed in version 2.0: guild_id parameter is now positional-only.

Parameters

• guild_id (int) – The guild’s ID to fetch from.

• with_counts (bool) –

  Whether to include count information in the guild. This fills the
  Guild.approximate_member_count and Guild.approximate_presence_count
  attributes without needing any privileged intents. Defaults to True.

  New in version 2.0.

Raises

• Forbidden – You do not have access to the guild.

• HTTPException – Getting the guild failed.

Returns

The guild from the ID.

Return type

Guild

async for … in fetch_guilds(*, limit=200, before=None, after=None)¶

Retrieves an asynchronous iterator that enables receiving your guilds.

Note

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

Examples

Usage

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

Flattening into a list

guilds = [guild async for guild in client.fetch_guilds(limit=150)]
# guilds is now a list of Guild...

All parameters are optional.

Parameters

• limit (Optional[int]) –

  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 200.

  Changed in version 2.0: The default has been changed to 200.

• before (Union[abc.Snowflake, datetime.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 (Union[abc.Snowflake, datetime.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.

Raises

HTTPException – Getting the guilds failed.

Yields

Guild – The guild with the guild data parsed.

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

This function is a coroutine.

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

Parameters

• url (Union[Invite, str]) – The Discord invite ID or URL (must be a discord.gg URL).

• with_counts (bool) – Whether to include count information in the invite. This fills the
  Invite.approximate_member_count and Invite.approximate_presence_count
  fields.

• with_expiration (bool) –

  Whether to include the expiration date of the invite. This fills the
  Invite.expires_at field.

  New in version 2.0.

• scheduled_event_id (Optional[int]) –

  The ID of the scheduled event this invite is for.

  Note

  It is not possible to provide a url that contains an event_id parameter
  when using this parameter.

  New in version 2.0.

Raises

• ValueError – The url contains an event_id, but scheduled_event_id has also been provided.

• NotFound – The invite has expired or is invalid.

• HTTPException – Getting the invite failed.

Returns

The invite from the URL/ID.

Return type

Invite

await fetch_premium_sticker_packs()¶

This function is a coroutine.

Retrieves all available premium sticker packs.

New in version 2.0.

Raises

HTTPException – Retrieving the sticker packs failed.

Returns

All available premium sticker packs.

Return type

List[StickerPack]

await fetch_stage_instance(channel_id, /)¶

This function is a coroutine.

Gets a StageInstance for a stage channel id.

New in version 2.0.

Parameters

channel_id (int) – The stage channel ID.

Raises

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

• HTTPException – Getting the stage instance failed.

Returns

The stage instance from the stage channel ID.

Return type

StageInstance

await fetch_sticker(sticker_id, /)¶

This function is a coroutine.

Retrieves a Sticker with the specified ID.

New in version 2.0.

Raises

• HTTPException – Retrieving the sticker failed.

• NotFound – Invalid sticker ID.

Returns

The sticker you requested.

Return type

Union[StandardSticker, GuildSticker]

await fetch_template(code)¶

This function is a coroutine.

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

Parameters

code (Union[Template, str]) – The Discord Template Code or URL (must be a discord.new URL).

Raises

• NotFound – The template is invalid.

• HTTPException – Getting the template failed.

Returns

The template from the URL/code.

Return type

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.

Changed in version 2.0: user_id parameter is now positional-only.

Parameters

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

Raises

• NotFound – A user with this ID does not exist.

• HTTPException – Fetching the user failed.

Returns

The user you requested.

Return type

User

await fetch_webhook(webhook_id, /)¶

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Changed in version 2.0: webhook_id parameter is now positional-only.

Raises

• HTTPException – Retrieving the webhook failed.

• NotFound – Invalid webhook ID.

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

Returns

The webhook you requested.

Return type

Webhook

await fetch_widget(guild_id, /)¶

This function is a coroutine.

Gets a Widget from a guild ID.

Note

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

Changed in version 2.0: guild_id parameter is now positional-only.

Parameters

guild_id (int) – The ID of the guild.

Raises

• Forbidden – The widget for this guild is disabled.

• HTTPException – Retrieving the widget failed.

Returns

The guild’s widget.

Return type

Widget

for … in 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

Yields

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

for … in get_all_members()¶

Returns a generator with every Member the client can see.

This is equivalent to:

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

Yields

Member – A member the client can see.

get_channel(id, /)¶

Returns a channel or thread with the given ID.

Changed in version 2.0: id parameter is now positional-only.

Parameters

id (int) – The ID to search for.

Returns

The returned channel or None if not found.

Return type

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

get_cog(name, /)¶

Gets the cog instance requested.

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

Changed in version 2.0: name parameter is now positional-only.

Parameters

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.

Returns

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

Return type

Optional[Cog]

get_command(name, /)¶

Get a Command from the internal list
of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get
the subcommand bar of the group command foo. If a
subcommand is not found then None is returned just as usual.

Changed in version 2.0: name parameter is now positional-only.

Parameters

name (str) – The name of the command to get.

Returns

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

Return type

Optional[Command]

await get_context(origin, /, *, cls=…)¶

This function is a coroutine.

Returns the invocation context from the message or interaction.

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

The returned context is not guaranteed to be a valid invocation
context, Context.valid must be checked to make sure it is.
If the context is not valid then it is not a valid candidate to be
invoked under invoke().

Note

In order for the custom context to be used inside an interaction-based
context (such as HybridCommand) then this method must be
overridden to return that class.

Changed in version 2.0: message parameter is now positional-only and renamed to origin.

Parameters

• origin (Union[discord.Message, discord.Interaction]) – The message or interaction to get the invocation context from.

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

Returns

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

Return type

Context

get_emoji(id, /)¶

Returns an emoji with the given ID.

Changed in version 2.0: id parameter is now positional-only.

Parameters

id (int) – The ID to search for.

Returns

The custom emoji or None if not found.

Return type

Optional[Emoji]

get_guild(id, /)¶

Returns a guild with the given ID.

Changed in version 2.0: id parameter is now positional-only.

Parameters

id (int) – The ID to search for.

Returns

The guild or None if not found.

Return type

Optional[Guild]

get_partial_messageable(id, *, guild_id=None, 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.

New in version 2.0.

Parameters

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

• guild_id (Optional[int]) –

  The optional guild ID to create a partial messageable for.

  This is not required to actually send messages, but it does allow the
  jump_url() and
  guild properties to function properly.

• type (Optional[ChannelType]) – The underlying channel type for the partial messageable.

Returns

The partial messageable

Return type

PartialMessageable

await get_prefix(message, /)¶

This function is a coroutine.

Retrieves the prefix the bot is listening to
with the message as a context.

Changed in version 2.0: message parameter is now positional-only.

Parameters

message (discord.Message) – The message context to get the prefix of.

Returns

A list of prefixes or a single prefix that the bot is
listening for.

Return type

Union[List[str], str]

get_stage_instance(id, /)¶

Returns a stage instance with the given stage channel ID.

New in version 2.0.

Parameters

id (int) – The ID to search for.

Returns

The stage instance or None if not found.

Return type

Optional[StageInstance]

get_sticker(id, /)¶

Returns a guild sticker with the given ID.

New in version 2.0.

Note

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

Returns

The sticker or None if not found.

Return type

Optional[GuildSticker]

get_user(id, /)¶

Returns a user with the given ID.

Changed in version 2.0: id parameter is now positional-only.

Parameters

id (int) – The ID to search for.

Returns

The user or None if not found.

Return type

Optional[User]

property guilds¶

The guilds that the connected client is a member of.

Type

Sequence[Guild]

property intents¶

The intents configured for this connection.

New in version 1.5.

Type

Intents

await invoke(ctx, /)¶

This function is a coroutine.

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

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to invoke.

is_closed()¶

bool: Indicates if the websocket connection is closed.

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().

Changed in version 1.3: The function also checks if the application is team-owned if
owner_ids is not set.

Changed in version 2.0: user parameter is now positional-only.

Parameters

user (abc.User) – The user to check for.

Returns

Whether the user is the owner.

Return type

bool

is_ready()¶

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

is_ws_ratelimited()¶

bool: 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.

New in version 1.6.

property latency¶

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

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

Type

float

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

This function is a coroutine.

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.

Changed in version 2.0: This method is now a coroutine.

Parameters

• name (str) – The extension name to load. It must be dot separated like
  regular Python imports if accessing a sub-module. 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.

  New in version 1.7.

Raises

• 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.

await login(token)¶

This function is a coroutine.

Logs in the client with the specified credentials and
calls the setup_hook().

Parameters

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

Raises

• 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.

await on_command_error(context, exception, /)¶

This function is a coroutine.

The default command error handler provided by the bot.

By default this logs to the library logger, however it could be
overridden to have a different implementation.

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

Changed in version 2.0: context and exception parameters are now positional-only.
Instead of writing to sys.stderr this now uses the library logger.

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

This function is a coroutine.

The default error handler provided by the client.

By default this logs to the library logger however it could be
overridden to have a different implementation.
Check on_error() for more details.

Changed in version 2.0: event_method parameter is now positional-only
and instead of writing to sys.stderr it logs instead.

property persistent_views¶

A sequence of persistent views added to the client.

New in version 2.0.

Type

Sequence[View]

property private_channels¶

The private channels that the connected client is participating on.

Note

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

Type

Sequence[abc.PrivateChannel]

await process_commands(message, /)¶

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_message()
event. If you choose to override the on_message() event, then
you should invoke this coroutine as well.

This is built using other low level tools, and is equivalent to a
call to get_context() followed by a call to invoke().

This also checks if the message’s author is a bot and doesn’t
call get_context() or invoke() if so.

Changed in version 2.0: message parameter is now positional-only.

Parameters

message (discord.Message) – The message to process commands for.

await reload_extension(name, *, package=None)¶

This function is a coroutine.

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.

Parameters

• name (str) – The extension name to reload. It must be dot separated like
  regular Python imports if accessing a sub-module. 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 reloading an extension using a relative path, e.g .foo.test.
  Defaults to None.

  New in version 1.7.

Raises

• 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.

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.

Changed in version 2.0: func parameter is now positional-only.

Parameters

• 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().

await remove_cog(name, /, *, guild=…, guilds=…)¶

This function is a coroutine.

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.

Changed in version 2.0: name parameter is now positional-only.

Changed in version 2.0: This method is now a coroutine.

Parameters

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

• guild (Optional[Snowflake]) –

  If the cog is an application command group, then this would be the
  guild where the cog group would be removed from. If not given then
  a global command is removed instead instead.

  New in version 2.0.

• guilds (List[Snowflake]) –

  If the cog is an application command group, then this would be the
  guilds where the cog group would be removed from. If not given then
  a global command is removed instead instead. Cannot be mixed with
  guild.

  New in version 2.0.

Returns

The cog that was removed. None if not found.

Return type

Optional[Cog]

remove_command(name, /)¶

Remove a Command from the internal list
of commands.

This could also be used as a way to remove aliases.

Changed in version 2.0: name parameter is now positional-only.

Parameters

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

Returns

The command that was removed. If the name is not valid then
None is returned instead.

Return type

Optional[Command]

remove_listener(func, /, name=…)¶

Removes a listener from the pool of listeners.

Changed in version 2.0: func parameter is now positional-only.

Parameters

• func – 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__.

run(token, *, reconnect=True, log_handler=…, log_formatter=…, log_level=…, root_logger=False)¶

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().

This function also sets up the logging library to make it easier
for beginners to know what is going on with the library. For more
advanced users, this can be disabled by passing None to
the log_handler parameter.

Warning

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.

Parameters

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

• 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).

• log_handler (Optional[logging.Handler]) –

  The log handler to use for the library’s logger. If this is None
  then the library will not set up anything logging related. Logging
  will still work if None is passed, though it is your responsibility
  to set it up.

  The default log handler if not provided is logging.StreamHandler.

  New in version 2.0.

• log_formatter (logging.Formatter) –

  The formatter to use with the given log handler. If not provided then it
  defaults to a colour based logging formatter (if available).

  New in version 2.0.

• log_level (int) –

  The default log level for the library’s logger. This is only applied if the
  log_handler parameter is not None. Defaults to logging.INFO.

  New in version 2.0.

• root_logger (bool) –

  Whether to set up the root logger rather than the library logger.
  By default, only the library logger ('discord') is set up. If this
  is set to True then the root logger is set up as well.

  Defaults to False.

  New in version 2.0.

await setup_hook()¶

This function is a coroutine.

A coroutine to be called to setup the bot, by default this is blank.

To perform asynchronous setup after the bot is logged in but before
it has connected to the Websocket, overwrite this coroutine.

This is only called once, in login(), and will be called before
any events are dispatched, making it a better solution than doing such
setup in the on_ready() event.

Warning

Since this is called before the websocket connection is made therefore
anything that waits for the websocket will deadlock, this includes things
like wait_for() and wait_until_ready().

New in version 2.0.

await start(token, *, reconnect=True)¶

This function is a coroutine.

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

Parameters

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

• 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).

Raises

TypeError – An unexpected keyword argument was received.

property status¶

Status:
The status being used upon logging on to Discord.

property stickers¶

The stickers that the connected client has.

New in version 2.0.

Type

Sequence[GuildSticker]

property tree¶

The command tree responsible for handling the application commands
in this bot.

New in version 2.0.

Type

CommandTree

await unload_extension(name, *, package=None)¶

This function is a coroutine.

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().

Changed in version 2.0: This method is now a coroutine.

Parameters

• name (str) – The extension name to unload. It must be dot separated like
  regular Python imports if accessing a sub-module. 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 unloading an extension using a relative path, e.g .foo.test.
  Defaults to None.

  New in version 1.7.

Raises

• ExtensionNotFound – The name of the extension could not
  be resolved using the provided package parameter.

• ExtensionNotLoaded – The extension was not loaded.

property user¶

Represents the connected client. None if not logged in.

Type

Optional[ClientUser]

property users¶

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

Type

List[User]

property voice_clients¶

Represents a list of voice connections.

These are usually VoiceClient instances.

Type

List[VoiceProtocol]

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.

Examples

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('👍')

Changed in version 2.0: event parameter is now positional-only.

Parameters

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

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

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

Raises

asyncio.TimeoutError – If a timeout is provided and it was reached.

Returns

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

Return type

Any

await wait_until_ready()¶

This function is a coroutine.

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

Warning

Calling this inside setup_hook() can lead to a deadlock.

for … in walk_commands()¶

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields

Union[Command, Group] – A command or group from the internal list of commands.

AutoShardedBot¶

class discord.ext.commands.AutoShardedBot(command_prefix, *, help_command=<default-help-command>, tree_cls=<class ‘discord.app_commands.tree.CommandTree’>, description=None, intents, **options)¶

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

async with x

Asynchronously initialises the bot and automatically cleans.

New in version 2.0.

Decorators¶

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

A decorator that transforms a function into a Command
or if called with group(), Group.

By default the help attribute is received automatically from the
docstring of the function and is cleaned up with the use of
inspect.cleandoc. If the docstring is bytes, then it is decoded
into str using utf-8 encoding.

All checks added using the check() & co. decorators are added into
the function. There is no way to supply your own checks through this
decorator.

Parameters

• name (str) – The name to create the command with. By default this uses the
  function name unchanged.

• cls – The class to construct with. By default this is Command.
  You usually do not change this.

• attrs – Keyword arguments to pass into the construction of the class denoted
  by cls.

Raises

TypeError – If the function is not a coroutine or is already a command.

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

A decorator that transforms a function into a Group.

This is similar to the command() decorator but the cls
parameter is set to Group by default.

Changed in version 1.1: The cls parameter can now be passed.

@discord.ext.commands.hybrid_command(name=…, *, with_app_command=True, **attrs)¶

A decorator that transforms a function into a HybridCommand.

A hybrid command is one that functions both as a regular Command
and one that is also a app_commands.Command.

The callback being attached to the command must be representable as an
application command callback. Converters are silently converted into a
Transformer with a
discord.AppCommandOptionType.string type.

Checks and error handlers are dispatched and called as-if they were commands
similar to Command. This means that they take Context as
a parameter rather than discord.Interaction.

All checks added using the check() & co. decorators are added into
the function. There is no way to supply your own checks through this
decorator.

New in version 2.0.

Parameters

• name (Union[str, locale_str]) – The name to create the command with. By default this uses the
  function name unchanged.

• with_app_command (bool) – Whether to register the command also as an application command.

• **attrs – Keyword arguments to pass into the construction of the
  hybrid command.

Raises

TypeError – If the function is not a coroutine or is already a command.

@discord.ext.commands.hybrid_group(name=…, *, with_app_command=True, **attrs)¶

A decorator that transforms a function into a HybridGroup.

This is similar to the group() decorator except it creates
a hybrid group instead.

Parameters

with_app_command (bool) – Whether to register the command also as an application command.

Raises

TypeError – If the function is not a coroutine or is already a command.

Command¶

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

A class that implements the protocol for a bot text command.

These are not created manually, instead they are created via the
decorator or functional interface.

name¶

The name of the command.

Type

str

callback¶

The coroutine that is executed when the command is called.

Type

coroutine

help¶

The long help text for the command.

Type

Optional[str]

brief¶

The short help text for the command.

Type

Optional[str]

usage¶

A replacement for arguments in the default help text.

Type

Optional[str]

aliases¶

The list of aliases the command can be invoked under.

Type

Union[List[str], Tuple[str]]

enabled¶

A boolean that indicates if the command is currently enabled.
If the command is invoked while it is disabled, then
DisabledCommand is raised to the on_command_error()
event. Defaults to True.

Type

bool

parent¶

The parent group that this command belongs to. None if there
isn’t one.

Type

Optional[Group]

cog¶

The cog that this command belongs to. None if there isn’t one.

Type

Optional[Cog]

checks¶

A list of predicates that verifies if the command could be executed
with the given Context as the sole parameter. If an exception
is necessary to be thrown to signal failure, then one inherited from
CommandError should be used. Note that if the checks fail then
CheckFailure exception is raised to the on_command_error()
event.

Type

List[Callable[[Context], bool]]

description¶

The message prefixed into the default help command.

Type

str

hidden¶

If True, the default help command does not show this in the
help output.

Type

bool

rest_is_raw¶

If False and a keyword-only argument is provided then the keyword
only argument is stripped and handled as if it was a regular argument
that handles MissingRequiredArgument and default values in a
regular matter rather than passing the rest completely raw. If True
then the keyword-only argument will pass in the rest of the arguments
in a completely raw matter. Defaults to False.

Type

bool

invoked_subcommand¶

The subcommand that was invoked, if any.

Type

Optional[Command]

require_var_positional¶

If True and a variadic positional argument is specified, requires
the user to specify at least one argument. Defaults to False.

New in version 1.5.

Type

bool

ignore_extra¶

If True, ignores extraneous strings passed to a command if all its
requirements are met (e.g. ?foo a b c when only expecting a
and b). Otherwise on_command_error() and local error handlers
are called with TooManyArguments. Defaults to True.

Type

bool

cooldown_after_parsing¶

If True, cooldown processing is done after argument parsing,
which calls converters. If False then cooldown processing is done
first and then the converters are called second. Defaults to False.

Type

bool

extras¶

A dict of user provided extras to attach to the Command.

Note

This object may be copied by the library.

Type

dict

New in version 2.0.

@after_invoke¶

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.

See Bot.after_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke¶

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.

See Bot.before_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error¶

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to
a single command. However, the on_command_error() is still
invoked afterwards as the catch-all.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

coro (coroutine) – The coroutine to register as the local error handler.

Raises

TypeError – The coroutine passed is not actually a coroutine.

add_check(func, /)¶

Adds a check to the command.

This is the non-decorator interface to check().

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

See also

The check() decorator

Parameters

func – The function that will be used as a check.

remove_check(func, /)¶

Removes a check from the command.

This function is idempotent and will not raise an exception
if the function is not in the command’s checks.

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

Parameters

func – The function to remove from the checks.

update(**kwargs)¶

Updates Command instance with updated attribute.

This works similarly to the command() decorator in terms
of parameters in that they are passed to the Command or
subclass constructors, sans the name and callback.

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

This function is a coroutine.

Calls the internal callback that the command holds.

Note

This bypasses all mechanisms – including checks, converters,
invoke hooks, cooldowns, etc. You must take care to pass
the proper arguments and types to this function.

New in version 1.3.

Changed in version 2.0: context parameter is now positional-only.

copy()¶

Creates a copy of this command.

Returns

A new instance of this command.

Return type

Command

property clean_params¶

Dict[str, Parameter]:
Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property cooldown¶

The cooldown of a command when invoked
or None if the command doesn’t have a registered cooldown.

New in version 2.0.

Type

Optional[Cooldown]

property full_parent_name¶

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example,
in ?one two three the parent name would be one two.

Type

str

property parents¶

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

New in version 1.1.

Type

List[Group]

property root_parent¶

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type

Optional[Group]

property qualified_name¶

Retrieves the fully qualified command name.

This is the full parent name with the command name as well.
For example, in ?one two three the qualified name would be
one two three.

Type

str

is_on_cooldown(ctx, /)¶

Checks whether the command is currently on cooldown.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to use when checking the commands cooldown status.

Returns

A boolean indicating if the command is on cooldown.

Return type

bool

reset_cooldown(ctx, /)¶

Resets the cooldown on this command.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to reset the cooldown under.

get_cooldown_retry_after(ctx, /)¶

Retrieves the amount of seconds before this command can be tried again.

New in version 1.4.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to retrieve the cooldown from.

Returns

The amount of time left on this command’s cooldown in seconds.
If this is 0.0 then the command isn’t on cooldown.

Return type

float

has_error_handler()¶

bool: Checks whether the command has an error handler registered.

New in version 1.7.

property cog_name¶

The name of the cog this command belongs to, if any.

Type

Optional[str]

property short_doc¶

Gets the “short” documentation of a command.

By default, this is the brief attribute.
If that lookup leads to an empty string then the first line of the
help attribute is used instead.

Type

str

property signature¶

Returns a POSIX-like signature useful for help command output.

Type

str

await can_run(ctx, /)¶

This function is a coroutine.

Checks if the command can be executed by checking all the predicates
inside the checks attribute. This also checks whether the
command is disabled.

Changed in version 1.3: Checks whether the command is disabled or not

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The ctx of the command currently being invoked.

Raises

CommandError – Any command error that was raised during a check call will be propagated
by this function.

Returns

A boolean indicating if the command can be invoked.

Return type

bool

Group¶

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

A class that implements a grouping protocol for commands to be
executed as subcommands.

This class is a subclass of Command and thus all options
valid in Command are valid in here as well.

invoke_without_command¶

Indicates if the group callback should begin parsing and
invocation only if no subcommand was found. Useful for
making it an error handling function to tell the user that
no subcommand was found or to have different functionality
in case no subcommand was found. If this is False, then
the group callback will always be invoked first. This means
that the checks and the parsing dictated by its parameters
will be executed. Defaults to False.

Type

bool

case_insensitive¶

Indicates if the group’s commands should be case insensitive.
Defaults to False.

Type

bool

@after_invoke¶

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.

See Bot.after_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke¶

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.

See Bot.before_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@command(*args, **kwargs)¶

A shortcut decorator that invokes command() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type

Callable[…, Command]

@error¶

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to
a single command. However, the on_command_error() is still
invoked afterwards as the catch-all.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

coro (coroutine) – The coroutine to register as the local error handler.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@group(*args, **kwargs)¶

A shortcut decorator that invokes group() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type

Callable[…, Group]

copy()¶

Creates a copy of this Group.

Returns

A new instance of this group.

Return type

Group

add_check(func, /)¶

Adds a check to the command.

This is the non-decorator interface to check().

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

See also

The check() decorator

Parameters

func – The function that will be used as a check.

add_command(command, /)¶

Adds a Command into the internal list of commands.

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

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Changed in version 2.0: command parameter is now positional-only.

Parameters

command (Command) – The command to add.

Raises

• CommandRegistrationError – If the command or its alias is already registered by different command.

• TypeError – If the command passed is not a subclass of Command.

await can_run(ctx, /)¶

This function is a coroutine.

Checks if the command can be executed by checking all the predicates
inside the checks attribute. This also checks whether the
command is disabled.

Changed in version 1.3: Checks whether the command is disabled or not

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The ctx of the command currently being invoked.

Raises

CommandError – Any command error that was raised during a check call will be propagated
by this function.

Returns

A boolean indicating if the command can be invoked.

Return type

bool

property clean_params¶

Dict[str, Parameter]:
Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property cog_name¶

The name of the cog this command belongs to, if any.

Type

Optional[str]

property commands¶

A unique set of commands without aliases that are registered.

Type

Set[Command]

property cooldown¶

The cooldown of a command when invoked
or None if the command doesn’t have a registered cooldown.

New in version 2.0.

Type

Optional[Cooldown]

property full_parent_name¶

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example,
in ?one two three the parent name would be one two.

Type

str

get_command(name, /)¶

Get a Command from the internal list
of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get
the subcommand bar of the group command foo. If a
subcommand is not found then None is returned just as usual.

Changed in version 2.0: name parameter is now positional-only.

Parameters

name (str) – The name of the command to get.

Returns

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

Return type

Optional[Command]

get_cooldown_retry_after(ctx, /)¶

Retrieves the amount of seconds before this command can be tried again.

New in version 1.4.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to retrieve the cooldown from.

Returns

The amount of time left on this command’s cooldown in seconds.
If this is 0.0 then the command isn’t on cooldown.

Return type

float

has_error_handler()¶

bool: Checks whether the command has an error handler registered.

New in version 1.7.

is_on_cooldown(ctx, /)¶

Checks whether the command is currently on cooldown.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to use when checking the commands cooldown status.

Returns

A boolean indicating if the command is on cooldown.

Return type

bool

property parents¶

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

New in version 1.1.

Type

List[Group]

property qualified_name¶

Retrieves the fully qualified command name.

This is the full parent name with the command name as well.
For example, in ?one two three the qualified name would be
one two three.

Type

str

remove_check(func, /)¶

Removes a check from the command.

This function is idempotent and will not raise an exception
if the function is not in the command’s checks.

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

Parameters

func – The function to remove from the checks.

remove_command(name, /)¶

Remove a Command from the internal list
of commands.

This could also be used as a way to remove aliases.

Changed in version 2.0: name parameter is now positional-only.

Parameters

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

Returns

The command that was removed. If the name is not valid then
None is returned instead.

Return type

Optional[Command]

reset_cooldown(ctx, /)¶

Resets the cooldown on this command.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to reset the cooldown under.

property root_parent¶

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type

Optional[Group]

property short_doc¶

Gets the “short” documentation of a command.

By default, this is the brief attribute.
If that lookup leads to an empty string then the first line of the
help attribute is used instead.

Type

str

property signature¶

Returns a POSIX-like signature useful for help command output.

Type

str

update(**kwargs)¶

Updates Command instance with updated attribute.

This works similarly to the command() decorator in terms
of parameters in that they are passed to the Command or
subclass constructors, sans the name and callback.

for … in walk_commands()¶

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields

Union[Command, Group] – A command or group from the internal list of commands.

GroupMixin¶

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

A mixin that implements common functionality for classes that behave
similar to Group and are allowed to register commands.

all_commands¶

A mapping of command name to Command
objects.

Type

dict

case_insensitive¶

Whether the commands should be case insensitive. Defaults to False.

Type

bool

@command(*args, **kwargs)¶

A shortcut decorator that invokes command() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type

Callable[…, Command]

@group(*args, **kwargs)¶

A shortcut decorator that invokes group() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type

Callable[…, Group]

property commands¶

A unique set of commands without aliases that are registered.

Type

Set[Command]

add_command(command, /)¶

Adds a Command into the internal list of commands.

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

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Changed in version 2.0: command parameter is now positional-only.

Parameters

command (Command) – The command to add.

Raises

• CommandRegistrationError – If the command or its alias is already registered by different command.

• TypeError – If the command passed is not a subclass of Command.

remove_command(name, /)¶

Remove a Command from the internal list
of commands.

This could also be used as a way to remove aliases.

Changed in version 2.0: name parameter is now positional-only.

Parameters

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

Returns

The command that was removed. If the name is not valid then
None is returned instead.

Return type

Optional[Command]

for … in walk_commands()¶

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields

Union[Command, Group] – A command or group from the internal list of commands.

get_command(name, /)¶

Get a Command from the internal list
of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get
the subcommand bar of the group command foo. If a
subcommand is not found then None is returned just as usual.

Changed in version 2.0: name parameter is now positional-only.

Parameters

name (str) – The name of the command to get.

Returns

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

Return type

Optional[Command]

HybridCommand¶

class discord.ext.commands.HybridCommand(*args, **kwargs)¶

A class that is both an application command and a regular text command.

This has the same parameters and attributes as a regular Command.
However, it also doubles as an application command. In order
for this to work, the callbacks must have the same subset that is supported by application
commands.

These are not created manually, instead they are created via the
decorator or functional interface.

New in version 2.0.

@after_invoke¶

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.

See Bot.after_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@autocomplete(name)¶

A decorator that registers a coroutine as an autocomplete prompt for a parameter.

This is the same as autocomplete(). It is only
applicable for the application command and doesn’t do anything if the command is
a regular command.

Parameters

name (str) – The parameter name to register as autocomplete.

Raises

TypeError – The coroutine passed is not actually a coroutine or
the parameter is not found or of an invalid type.

@before_invoke¶

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.

See Bot.before_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error¶

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to
a single command. However, the on_command_error() is still
invoked afterwards as the catch-all.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

coro (coroutine) – The coroutine to register as the local error handler.

Raises

TypeError – The coroutine passed is not actually a coroutine.

await can_run(ctx, /)¶

This function is a coroutine.

Checks if the command can be executed by checking all the predicates
inside the checks attribute. This also checks whether the
command is disabled.

Changed in version 1.3: Checks whether the command is disabled or not

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The ctx of the command currently being invoked.

Raises

CommandError – Any command error that was raised during a check call will be propagated
by this function.

Returns

A boolean indicating if the command can be invoked.

Return type

bool

HybridGroup¶

class discord.ext.commands.HybridGroup(*args, **kwargs)¶

A class that is both an application command group and a regular text group.

This has the same parameters and attributes as a regular Group.
However, it also doubles as an application command group.
Note that application commands groups cannot have callbacks associated with them, so the callback
is only called if it’s not invoked as an application command.

Hybrid groups will always have Group.invoke_without_command set to True.

These are not created manually, instead they are created via the
decorator or functional interface.

New in version 2.0.

fallback¶

The command name to use as a fallback for the application command. Since
application command groups cannot be invoked, this creates a subcommand within
the group that can be invoked with the given group callback. If None
then no fallback command is given. Defaults to None.

Type

Optional[str]

@after_invoke¶

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.

See Bot.after_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@autocomplete(name)¶

A decorator that registers a coroutine as an autocomplete prompt for a parameter.

This is the same as autocomplete(). It is only
applicable for the application command and doesn’t do anything if the command is
a regular command.

This is only available if the group has a fallback application command registered.

Parameters

name (str) – The parameter name to register as autocomplete.

Raises

TypeError – The coroutine passed is not actually a coroutine or
the parameter is not found or of an invalid type.

@before_invoke¶

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.

See Bot.before_invoke() for more info.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@command(*args, **kwargs)¶

A shortcut decorator that invokes hybrid_command() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type

Callable[…, HybridCommand]

@error¶

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to
a single command. However, the on_command_error() is still
invoked afterwards as the catch-all.

Changed in version 2.0: coro parameter is now positional-only.

Parameters

coro (coroutine) – The coroutine to register as the local error handler.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@group(*args, **kwargs)¶

A shortcut decorator that invokes hybrid_group() and adds it to
the internal command list via add_command().

Returns

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type

Callable[…, HybridGroup]

await can_run(ctx, /)¶

This function is a coroutine.

Checks if the command can be executed by checking all the predicates
inside the checks attribute. This also checks whether the
command is disabled.

Changed in version 1.3: Checks whether the command is disabled or not

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The ctx of the command currently being invoked.

Raises

CommandError – Any command error that was raised during a check call will be propagated
by this function.

Returns

A boolean indicating if the command can be invoked.

Return type

bool

add_check(func, /)¶

Adds a check to the command.

This is the non-decorator interface to check().

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

See also

The check() decorator

Parameters

func – The function that will be used as a check.

add_command(command, /)¶

Adds a HybridCommand into the internal list of commands.

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

Parameters

command (HybridCommand) – The command to add.

Raises

• CommandRegistrationError – If the command or its alias is already registered by different command.

• TypeError – If the command passed is not a subclass of HybridCommand.

property clean_params¶

Dict[str, Parameter]:
Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property cog_name¶

The name of the cog this command belongs to, if any.

Type

Optional[str]

property commands¶

A unique set of commands without aliases that are registered.

Type

Set[Command]

property cooldown¶

The cooldown of a command when invoked
or None if the command doesn’t have a registered cooldown.

New in version 2.0.

Type

Optional[Cooldown]

copy()¶

Creates a copy of this Group.

Returns

A new instance of this group.

Return type

Group

property full_parent_name¶

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example,
in ?one two three the parent name would be one two.

Type

str

get_command(name, /)¶

Get a Command from the internal list
of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get
the subcommand bar of the group command foo. If a
subcommand is not found then None is returned just as usual.

Changed in version 2.0: name parameter is now positional-only.

Parameters

name (str) – The name of the command to get.

Returns

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

Return type

Optional[Command]

get_cooldown_retry_after(ctx, /)¶

Retrieves the amount of seconds before this command can be tried again.

New in version 1.4.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to retrieve the cooldown from.

Returns

The amount of time left on this command’s cooldown in seconds.
If this is 0.0 then the command isn’t on cooldown.

Return type

float

has_error_handler()¶

bool: Checks whether the command has an error handler registered.

New in version 1.7.

is_on_cooldown(ctx, /)¶

Checks whether the command is currently on cooldown.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to use when checking the commands cooldown status.

Returns

A boolean indicating if the command is on cooldown.

Return type

bool

property parents¶

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

New in version 1.1.

Type

List[Group]

property qualified_name¶

Retrieves the fully qualified command name.

This is the full parent name with the command name as well.
For example, in ?one two three the qualified name would be
one two three.

Type

str

remove_check(func, /)¶

Removes a check from the command.

This function is idempotent and will not raise an exception
if the function is not in the command’s checks.

New in version 1.3.

Changed in version 2.0: func parameter is now positional-only.

Parameters

func – The function to remove from the checks.

reset_cooldown(ctx, /)¶

Resets the cooldown on this command.

Changed in version 2.0: ctx parameter is now positional-only.

Parameters

ctx (Context) – The invocation context to reset the cooldown under.

property root_parent¶

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type

Optional[Group]

property short_doc¶

Gets the “short” documentation of a command.

By default, this is the brief attribute.
If that lookup leads to an empty string then the first line of the
help attribute is used instead.

Type

str

property signature¶

Returns a POSIX-like signature useful for help command output.

Type

str

update(**kwargs)¶

Updates Command instance with updated attribute.

This works similarly to the command() decorator in terms
of parameters in that they are passed to the Command or
subclass constructors, sans the name and callback.

for … in walk_commands()¶

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields

Union[Command, Group] – A command or group from the internal list of commands.

remove_command(name, /)¶

Remove a Command from the internal list
of commands.

This could also be used as a way to remove aliases.

Changed in version 2.0: name parameter is now positional-only.

Parameters

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

Returns

The command that was removed. If the name is not valid then
None is returned instead.

Return type

Optional[Command]