API Reference

The following section outlines the API of discord-class-commands.

Note

This module requires the discord.py library to be installed. Check out Installing for more info.

Version Related Info

You can query version info using the below attribute. For guarantees, check Version Guarantees.

discord.ext.class_commands.__version__

A string representation of the version. e.g. '1.0.0rc1'. This is based off of PEP 440.

Classes

These classes are meant to be subclassed to be used as application commands.

Danger

The classes listed below are not intended to be instantiated.

You should not and cannot make your own SlashCommand instance. Instead, you should subclass SlashCommand and use it as a base class.

Command

Attributes

• interaction

Methods

• asynccallback
• asynccheck
• asyncdefer
• asyncon_error
• asyncsend

class discord.ext.class_commands.Command

Represents a class-based application command.

Note

Instances of this class are created on every command invocation.

This means that relying on the state of this class to be the same between command invocations would not work as expected.

Parameters

• name (str) – The name of the group. If not given, it defaults to a lower-case kebab-case version of the class name.

• description (str) –

  The description of the group. This shows up in the UI to describe the group. If not given, it defaults to the docstring of the class shortened to 100 characters.

  Due to a Discord limitation, context menu commands cannot have descriptions.

• guild (Snowflake) – The guild to restrict the command to.

• guilds (List[Snowflake]) – A list of guilds to restrict the command to. Cannot be used with guild.

• default_permissions (Optional[Permissions]) –

  The default permissions that can execute this group on Discord. Note that server administrators can override this value in the client. Setting an empty permissions field will disallow anyone except server administrators from using the command in a guild.

  Due to a Discord limitation, this does not work on subcommands.

• guild_only (bool) –

  Whether the group should only be usable in guild contexts. Defaults to False.

  Due to a Discord limitation, this does not work on subcommands.

• parent (Group) –

  The command’s parent.

  Due to a Discord limitation, context menu commands cannot have parents.

• nsfw (bool) –

  Whether the command is NSFW and should only work in NSFW channels. Defaults to False.

  Due to a Discord limitation, this does not work on subcommands.

  New in version 1.1.

interaction

The interaction that triggered the command.

Type

Interaction

await callback()

This function is a coroutine.

This method is called when the command is used.

All the parameters and interaction will be available at this point.

await check()

This function could be a coroutine.

This method is called before the callback is called.

If it returns a False-like value then during invocation a CheckFailure exception is raised and sent to the appropriate error handlers.

interaction will be available at this point.

await on_error(exception)

This function could be a coroutine.

This method is called whenever an exception occurs in autocomplete() or callback().

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

interaction will be available at this point.

Parameters

exception (AppCommandError) – The exception that was thrown.

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, view=None, suppress_embeds=False, ephemeral=False)

This function is a coroutine.

Responds to the interaction with the content given.

This does one of the following:

• send_message() if no response has been given.

• A followup message if a response has been given.

• Regular send if the interaction has expired

Parameters

• content (Optional[str]) – The content of the message to send.

• tts (bool) – Indicates if the message should be sent using text-to-speech.

• embed (Embed) – The rich embed for the content.

• file (File) – The file to upload.

• files (List[File]) – A list of files to upload. Must be a maximum of 10.

• nonce (int) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

• allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• view (discord.ui.View) – A Discord UI View to add to the message.

• embeds (List[Embed]) – A list of embeds to upload. Must be a maximum of 10.

• suppress_embeds (bool) – Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

• ephemeral (bool) – Indicates if the message should only be visible to the user who started the interaction. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

Raises

• HTTPException – Sending the message failed.

• Forbidden – You do not have the proper permissions to send the message.

• ValueError – The files list is not of the appropriate size.

• TypeError – You specified both file and files, or you specified both embed and embeds, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

Message

await defer(*, ephemeral=False)

This function is a coroutine.

Defers the interaction based contexts.

This is typically used when the interaction is acknowledged and a secondary action will be done later.

Parameters

ephemeral (bool) – Indicates whether the deferred message will eventually be ephemeral.

Raises

• HTTPException – Deferring the interaction failed.

• InteractionResponded – This interaction has already been responded to before.

Note

This class is not the same as discord.py’s discord.app_commands.Command.

SlashCommand

Methods

• asyncautocomplete
• asynccallback
• asynccheck
• asyncdefer
• asyncon_error
• asyncsend

class discord.ext.class_commands.SlashCommand(*args, **kwds)

Represents a class-based slash command.

Note

Instances of this class are created on every command invocation.

This means that relying on the state of this class to be the same between command invocations would not work as expected.

Parameters here refer to class parameters.

Parameters

• name (str) – The name of the group. If not given, it defaults to a lower-case kebab-case version of the class name.

• description (str) – The description of the group. This shows up in the UI to describe the group. If not given, it defaults to the docstring of the class shortened to 100 characters.

• guild (Snowflake) – The guild to restrict the command to.

• guilds (List[Snowflake]) – A list of guilds to restrict the command to. Cannot be used with guild.

• default_permissions (Optional[Permissions]) –

  The default permissions that can execute this group on Discord. Note that server administrators can override this value in the client. Setting an empty permissions field will disallow anyone except server administrators from using the command in a guild.

  Due to a Discord limitation, this does not work on subcommands.

• guild_only (bool) –

  Whether the group should only be usable in guild contexts. Defaults to False.

  Due to a Discord limitation, this does not work on subcommands.

• parent (Group) – The command’s parent.

await autocomplete(focused)

This function is a coroutine.

This method is called when an autocomplete interaction is triggered.

Some of the parameters and interaction will be available at this point.

Note

In autocomplete interactions, parameter values might not be validated or filled in. Discord does not send the resolved data as well, so this means that certain fields end up just as IDs rather than the resolved data. In these cases, a Object is returned instead.

This is a Discord limitation.

Parameters

focused (str) – The name of the option that is currently focused.

Returns

A list of choices to display.

Return type

List[Choice]

await callback()

This function is a coroutine.

This method is called when the command is used.

All the parameters and interaction will be available at this point.

await check()

This function could be a coroutine.

This method is called before the callback is called.

If it returns a False-like value then during invocation a CheckFailure exception is raised and sent to the appropriate error handlers.

interaction will be available at this point.

await defer(*, ephemeral=False)

This function is a coroutine.

Defers the interaction based contexts.

This is typically used when the interaction is acknowledged and a secondary action will be done later.

Parameters

ephemeral (bool) – Indicates whether the deferred message will eventually be ephemeral.

Raises

• HTTPException – Deferring the interaction failed.

• InteractionResponded – This interaction has already been responded to before.

await on_error(exception)

This function could be a coroutine.

This method is called whenever an exception occurs in autocomplete() or callback().

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

interaction will be available at this point.

Parameters

exception (AppCommandError) – The exception that was thrown.

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, view=None, suppress_embeds=False, ephemeral=False)

This function is a coroutine.

Responds to the interaction with the content given.

This does one of the following:

• send_message() if no response has been given.

• A followup message if a response has been given.

• Regular send if the interaction has expired

Parameters

• content (Optional[str]) – The content of the message to send.

• tts (bool) – Indicates if the message should be sent using text-to-speech.

• embed (Embed) – The rich embed for the content.

• file (File) – The file to upload.

• files (List[File]) – A list of files to upload. Must be a maximum of 10.

• nonce (int) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

• allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• view (discord.ui.View) – A Discord UI View to add to the message.

• embeds (List[Embed]) – A list of embeds to upload. Must be a maximum of 10.

• suppress_embeds (bool) – Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

• ephemeral (bool) – Indicates if the message should only be visible to the user who started the interaction. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

Raises

• HTTPException – Sending the message failed.

• Forbidden – You do not have the proper permissions to send the message.

• ValueError – The files list is not of the appropriate size.

• TypeError – You specified both file and files, or you specified both embed and embeds, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

Message

UserCommand

Attributes

• target

Methods

• asynccallback
• asynccheck
• asyncdefer
• asyncon_error
• asyncsend

class discord.ext.class_commands.UserCommand(*args, **kwds)

Represents a class-based user command.

Note

Instances of this class are created on every command invocation.

This means that relying on the state of this class to be the same between command invocations would not work as expected.

Parameters here refer to class parameters.

Parameters

• name (str) – The name of the group. If not given, it defaults to a lower-case kebab-case version of the class name.

• guild (Snowflake) – The guild to restrict the command to.

• guilds (List[Snowflake]) – A list of guilds to restrict the command to. Cannot be used with guild.

• default_permissions (Optional[Permissions]) –

  The default permissions that can execute this group on Discord. Note that server administrators can override this value in the client. Setting an empty permissions field will disallow anyone except server administrators from using the command in a guild.

  Due to a Discord limitation, this does not work on subcommands.

• guild_only (bool) –

  Whether the group should only be usable in guild contexts. Defaults to False.

  Due to a Discord limitation, this does not work on subcommands.

target

The user that the command is executed on.

Type

Union[User, Member]

await callback()

This function is a coroutine.

This method is called when the command is used.

All the parameters and interaction will be available at this point.

await check()

This function could be a coroutine.

This method is called before the callback is called.

If it returns a False-like value then during invocation a CheckFailure exception is raised and sent to the appropriate error handlers.

interaction will be available at this point.

await defer(*, ephemeral=False)

This function is a coroutine.

Defers the interaction based contexts.

This is typically used when the interaction is acknowledged and a secondary action will be done later.

Parameters

ephemeral (bool) – Indicates whether the deferred message will eventually be ephemeral.

Raises

• HTTPException – Deferring the interaction failed.

• InteractionResponded – This interaction has already been responded to before.

await on_error(exception)

This function could be a coroutine.

This method is called whenever an exception occurs in autocomplete() or callback().

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

interaction will be available at this point.

Parameters

exception (AppCommandError) – The exception that was thrown.

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, view=None, suppress_embeds=False, ephemeral=False)

This function is a coroutine.

Responds to the interaction with the content given.

This does one of the following:

• send_message() if no response has been given.

• A followup message if a response has been given.

• Regular send if the interaction has expired

Parameters

• content (Optional[str]) – The content of the message to send.

• tts (bool) – Indicates if the message should be sent using text-to-speech.

• embed (Embed) – The rich embed for the content.

• file (File) – The file to upload.

• files (List[File]) – A list of files to upload. Must be a maximum of 10.

• nonce (int) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

• allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• view (discord.ui.View) – A Discord UI View to add to the message.

• embeds (List[Embed]) – A list of embeds to upload. Must be a maximum of 10.

• suppress_embeds (bool) – Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

• ephemeral (bool) – Indicates if the message should only be visible to the user who started the interaction. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

Raises

• HTTPException – Sending the message failed.

• Forbidden – You do not have the proper permissions to send the message.

• ValueError – The files list is not of the appropriate size.

• TypeError – You specified both file and files, or you specified both embed and embeds, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

Message

MessageCommand

Attributes

• target

Methods

• asynccallback
• asynccheck
• asyncdefer
• asyncon_error
• asyncsend

class discord.ext.class_commands.MessageCommand(*args, **kwds)

Represents a class-based message command.

Note

Instances of this class are created on every command invocation.

This means that relying on the state of this class to be the same between command invocations would not work as expected.

Parameters here refer to class parameters.

Parameters

• name (str) – The name of the group. If not given, it defaults to a lower-case kebab-case version of the class name.

• guild (Snowflake) – The guild to restrict the command to.

• guilds (List[Snowflake]) – A list of guilds to restrict the command to. Cannot be used with guild.

• default_permissions (Optional[Permissions]) –

  The default permissions that can execute this group on Discord. Note that server administrators can override this value in the client. Setting an empty permissions field will disallow anyone except server administrators from using the command in a guild.

  Due to a Discord limitation, this does not work on subcommands.

• guild_only (bool) –

  Whether the group should only be usable in guild contexts. Defaults to False.

  Due to a Discord limitation, this does not work on subcommands.

target

The message that the command is executed on.

Type

Message

await callback()

This function is a coroutine.

This method is called when the command is used.

All the parameters and interaction will be available at this point.

await check()

This function could be a coroutine.

This method is called before the callback is called.

If it returns a False-like value then during invocation a CheckFailure exception is raised and sent to the appropriate error handlers.

interaction will be available at this point.

await defer(*, ephemeral=False)

This function is a coroutine.

Defers the interaction based contexts.

This is typically used when the interaction is acknowledged and a secondary action will be done later.

Parameters

ephemeral (bool) – Indicates whether the deferred message will eventually be ephemeral.

Raises

• HTTPException – Deferring the interaction failed.

• InteractionResponded – This interaction has already been responded to before.

await on_error(exception)

This function could be a coroutine.

This method is called whenever an exception occurs in autocomplete() or callback().

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

interaction will be available at this point.

Parameters

exception (AppCommandError) – The exception that was thrown.

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, nonce=None, allowed_mentions=None, view=None, suppress_embeds=False, ephemeral=False)

This function is a coroutine.

Responds to the interaction with the content given.

This does one of the following:

• send_message() if no response has been given.

• A followup message if a response has been given.

• Regular send if the interaction has expired

Parameters

• content (Optional[str]) – The content of the message to send.

• tts (bool) – Indicates if the message should be sent using text-to-speech.

• embed (Embed) – The rich embed for the content.

• file (File) – The file to upload.

• files (List[File]) – A list of files to upload. Must be a maximum of 10.

• nonce (int) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

• allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

• view (discord.ui.View) – A Discord UI View to add to the message.

• embeds (List[Embed]) – A list of embeds to upload. Must be a maximum of 10.

• suppress_embeds (bool) – Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

• ephemeral (bool) – Indicates if the message should only be visible to the user who started the interaction. If a view is sent with an ephemeral message and it has no timeout set then the timeout is set to 15 minutes.

Raises

• HTTPException – Sending the message failed.

• Forbidden – You do not have the proper permissions to send the message.

• ValueError – The files list is not of the appropriate size.

• TypeError – You specified both file and files, or you specified both embed and embeds, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

Message

Data Classes

These classes are designed to be used as data containers.

Unlike models you are allowed to create these yourself.

All classes here have __slots__ defined which means that it is impossible to have dynamic attributes to the data classes.

Option

Attributes

• autocomplete
• choices
• default
• description
• name

class discord.ext.class_commands.Option(default=..., name=..., description=..., *, autocomplete=False, choices=...)

Represents a command parameter.

default

The default value for the option if the option is optional.

Type

Any

name

The overriden name of the option.

Type

str

description

The description of the option.

Note

If not explicitly overrided here, the description is parsed from the class docstring. Else, it defaults to “…”.

Type

str

autocomplete

Whether or not the parameter should be autocompleted.

Type

bool

choices

The choices for the parameter.

Note

This is not the only way to provide choices to a command. There are two more ergonomic ways of doing this, using a typing.Literal annotation or a enum.Enum.

Type

List[Choice]