Application Commands

This section documents everything about handling application commands with this extension.

Classes

Application Command

Attributes
Methods
class disnake.ext.commands.InvokableApplicationCommand(*args, **kwargs)[source]

A base class that implements the protocol for a bot application command.

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

The following classes implement this ABC:

name

The name of the command.

Type:

str

qualified_name

The full command name, including parent names in the case of slash subcommands or groups. For example, the qualified name for /one two three would be one two three.

Type:

str

body

An object being registered in the API.

Type:

ApplicationCommand

callback[source]

The coroutine function that is executed when the command is called.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the command could be executed with the given ApplicationCommandInteraction 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_slash_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

guild_ids

The list of IDs of the guilds where the command is synced. None if this command is global.

Type:

tuple[int, …] | None

auto_sync

Whether to automatically register the command.

Type:

bool

extras

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

New in version 2.5.

Type:

dict[str, Any]

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

copy()[source]

Create a copy of this application command.

Returns:

A new instance of this application command.

Return type:

InvokableApplicationCommand

property dm_permission[source]

Whether this command can be used in DMs.

Type:

bool

property default_member_permissions[source]

The default required member permissions for this command. A member must have all these permissions to be able to invoke the command in a guild.

This is a default value, the set of users/roles that may invoke this command can be overridden by moderators on a guild-specific basis, disregarding this setting.

If None is returned, it means everyone can use the command by default. If an empty Permissions object is returned (that is, all permissions set to False), this means no one can use the command.

New in version 2.5.

Type:

Permissions | None

property install_types[source]

The installation types where the command is available. Only available for global commands.

New in version 2.10.

Type:

ApplicationInstallTypes | None

property contexts[source]

The interaction contexts where the command can be used. Only available for global commands.

New in version 2.10.

Type:

InteractionContextTypes | None

add_check(func)[source]

Adds a check to the application command.

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

Parameters:

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

remove_check(func)[source]

Removes a check from the application command.

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

Parameters:

func – The function to remove from the checks.

is_on_cooldown(inter)[source]

Checks whether the application command is currently on cooldown.

Parameters:

inter (ApplicationCommandInteraction) – The interaction with the application command currently being invoked.

Returns:

A boolean indicating if the application command is on cooldown.

Return type:

bool

reset_cooldown(inter)[source]

Resets the cooldown on this application command.

Parameters:

inter (ApplicationCommandInteraction) – The interaction with this application command

get_cooldown_retry_after(inter)[source]

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

Parameters:

inter (ApplicationCommandInteraction) – The interaction with this application command.

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()[source]

Checks whether the application command has an error handler registered.

property cog_name[source]

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

Type:

str | None

await can_run(inter)[source]

This function is a coroutine.

Checks if the command can be executed by checking all the predicates inside the checks attribute.

Parameters:

inter (ApplicationCommandInteraction) – The interaction with the application command currently being invoked.

Raises:

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

Returns:

A boolean indicating if the application command can be invoked.

Return type:

bool

Slash Command

Attributes
Methods
class disnake.ext.commands.InvokableSlashCommand(*args, **kwargs)[source]

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

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

name

The name of the command.

Type:

str

qualified_name

The full command name, including parent names in the case of slash subcommands or groups. For example, the qualified name for /one two three would be one two three.

Type:

str

body

An object being registered in the API.

Type:

SlashCommand

callback[source]

The coroutine function that is executed when the command is called.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the command could be executed with the given ApplicationCommandInteraction 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_slash_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

guild_ids

The list of IDs of the guilds where the command is synced. None if this command is global.

Type:

tuple[int, …] | None

connectors

A mapping of option names to function parameter names, mainly for internal processes.

Type:

dict[str, str]

auto_sync

Whether to automatically register the command.

Type:

bool

extras

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

Note

This object may be copied by the library.

New in version 2.5.

Type:

dict[str, Any]

parent

This exists for consistency with SubCommand and SubCommandGroup. Always None.

New in version 2.6.

Type:

None

@sub_command(*args, **kwargs)[source]

A decorator that creates a subcommand under the base command.

Parameters:

  • name (str | Localized | None) –

    The name of the subcommand (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • description (str | Localized | None) –

    The description of the subcommand.

    Changed in version 2.5: Added support for localizations.

  • options (list[Option]) – the options of the subcommand for registration in API

  • connectors (dict[str, str]) – which function param states for each option. If the name of an option already matches the corresponding function param, you don’t have to specify the connectors. Connectors template: {"option-name": "param_name", ...}

  • extras (dict[str, Any]) –

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

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

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

Return type:

Callable[…, SubCommand]

@sub_command_group(*args, **kwargs)[source]

A decorator that creates a subcommand group under the base command.

Parameters:

  • name (str | Localized | None) –

    The name of the subcommand group (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • extras (dict[str, Any]) –

    A dict of user provided extras to attach to the subcommand group.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

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

Return type:

Callable[…, SubCommandGroup]

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

property root_parent[source]

This is for consistency with SubCommand and SubCommandGroup.

New in version 2.6.

Type:

None

property parents[source]

This is mainly for consistency with SubCommand, and is equivalent to an empty tuple.

New in version 2.6.

Type:

tuple[()]

property description[source]

The slash command’s description. Shorthand for self.body.description.

Type:

str

property options[source]

The list of options the slash command has. Shorthand for self.body.options.

Type:

list[Option]

autocomplete(option_name)[source]

A decorator that registers an autocomplete function for the specified option.

Parameters:

option_name (str) – The name of the slash command option.

Slash Subcommand

Attributes
Methods
class disnake.ext.commands.SubCommand(*args, **kwargs)[source]

A class that implements the protocol for a bot slash subcommand.

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

name

The name of the subcommand.

Type:

str

qualified_name

The full command name, including parent names in the case of slash subcommands or groups. For example, the qualified name for /one two three would be one two three.

Type:

str

parent

The parent command or group this subcommand belongs to.

New in version 2.6.

Type:

InvokableSlashCommand | SubCommandGroup

option

API representation of this subcommand.

Type:

Option

callback[source]

The coroutine function that is executed when the subcommand is called.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the subcommand could be executed with the given ApplicationCommandInteraction 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_slash_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

connectors

A mapping of option names to function parameter names, mainly for internal processes.

Type:

dict[str, str]

extras

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

Note

This object may be copied by the library.

New in version 2.5.

Type:

dict[str, Any]

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

property root_parent[source]

Returns the top-level slash command containing this subcommand, even if the parent is a SubCommandGroup.

New in version 2.6.

Type:

InvokableSlashCommand

property parents[source]

tuple[InvokableSlashCommand] | tuple[SubCommandGroup, InvokableSlashCommand]: Returns all parents of this subcommand.

For example, the parents of the c subcommand in /a b c are (b, a).

New in version 2.6.

property description[source]

The slash sub command’s description. Shorthand for self.body.description.

Type:

str

property body[source]

The API representation for this slash sub command. Shorthand for SubCommand.option

Type:

Option

autocomplete(option_name)[source]

A decorator that registers an autocomplete function for the specified option.

Parameters:

option_name (str) – The name of the slash command option.

Slash Subcommand Group

Attributes
Methods
class disnake.ext.commands.SubCommandGroup(*args, **kwargs)[source]

A class that implements the protocol for a bot slash command group.

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

name

The name of the group.

Type:

str

qualified_name

The full command name, including parent names in the case of slash subcommands or groups. For example, the qualified name for /one two three would be one two three.

Type:

str

parent

The parent command this group belongs to.

New in version 2.6.

Type:

InvokableSlashCommand

option

API representation of this subcommand.

Type:

Option

callback[source]

The coroutine function that is executed when the command group is invoked.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the group could be executed with the given ApplicationCommandInteraction 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_slash_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

extras

A dict of user provided extras to attach to the subcommand group.

Note

This object may be copied by the library.

New in version 2.5.

Type:

dict[str, Any]

@sub_command(*args, **kwargs)[source]

A decorator that creates a subcommand in the subcommand group. Parameters are the same as in InvokableSlashCommand.sub_command

Returns:

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

Return type:

Callable[…, SubCommand]

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

property root_parent[source]

Returns the slash command containing this group. This is mainly for consistency with SubCommand, and is equivalent to parent.

New in version 2.6.

Type:

InvokableSlashCommand

property parents[source]

Returns all parents of this group.

New in version 2.6.

Type:

tuple[InvokableSlashCommand]

User Command

Attributes
Methods
class disnake.ext.commands.InvokableUserCommand(*args, **kwargs)[source]

A class that implements the protocol for a bot user command (context menu).

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

name

The name of the user command.

Type:

str

qualified_name

The full command name, equivalent to name for this type of command.

Type:

str

body

An object being registered in the API.

Type:

UserCommand

callback[source]

The coroutine function that is executed when the user command is called.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the command could be executed with the given ApplicationCommandInteraction 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_user_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

guild_ids

The list of IDs of the guilds where the command is synced. None if this command is global.

Type:

tuple[int, …] | None

auto_sync

Whether to automatically register the command.

Type:

bool

extras

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

Note

This object may be copied by the library.

New in version 2.5.

Type:

dict[str, Any]

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

await __call__(interaction, target=None, *args, **kwargs)[source]

This function is a coroutine.

Calls the internal callback that the application 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.

Message Command

Attributes
Methods
class disnake.ext.commands.InvokableMessageCommand(*args, **kwargs)[source]

A class that implements the protocol for a bot message command (context menu).

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

name

The name of the message command.

Type:

str

qualified_name

The full command name, equivalent to name for this type of command.

Type:

str

body

An object being registered in the API.

Type:

MessageCommand

callback[source]

The coroutine function that is executed when the message command is called.

Type:

coroutine function

cog

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

Type:

Cog | None

checks

A list of predicates that verifies if the command could be executed with the given ApplicationCommandInteraction 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_message_command_error() event.

Type:

list[Callable[[ApplicationCommandInteraction], bool]]

guild_ids

The list of IDs of the guilds where the command is synced. None if this command is global.

Type:

tuple[int, …] | None

auto_sync

Whether to automatically register the command.

Type:

bool

extras

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

Note

This object may be copied by the library.

New in version 2.5.

Type:

dict[str, Any]

@after_invoke[source]

A decorator that registers a coroutine function as a post-invoke hook.

A post-invoke hook is called directly after the command is called.

This post-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

@before_invoke[source]

A decorator that registers a coroutine function as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called.

This pre-invoke hook takes a sole parameter, a ApplicationCommandInteraction.

Parameters:

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

Raises:

TypeError – The argument passed is not a coroutine function.

@error[source]

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

A local error handler is an error event limited to a single application command.

Parameters:

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

Raises:

TypeError – The argument passed is not actually a coroutine function.

await __call__(interaction, target=None, *args, **kwargs)[source]

This function is a coroutine.

Calls the internal callback that the application 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.

CommandSyncFlags

Attributes
Methods
class disnake.ext.commands.CommandSyncFlags[source]

Controls the library’s application command syncing policy.

This allows for finer grained control over what commands are synced automatically and in what cases.

To construct an object you can pass keyword arguments denoting the flags to enable or disable.

If command sync is disabled (see the docs of sync_commands for more info), other options will have no effect.

New in version 2.7.

x == y

Checks if two CommandSyncFlags instances are equal.

x != y

Checks if two CommandSyncFlags instances are not equal.

x <= y

Checks if a CommandSyncFlags instance is a subset of another CommandSyncFlags instance.

x >= y

Checks if a CommandSyncFlags instance is a superset of another CommandSyncFlags instance.

x < y

Checks if a CommandSyncFlags instance is a strict subset of another CommandSyncFlags instance.

x > y

Checks if a CommandSyncFlags instance is a strict superset of another CommandSyncFlags instance.

x | y, x |= y

Returns a new CommandSyncFlags instance with all enabled flags from both x and y. (Using |= will update in place).

x & y, x &= y

Returns a new CommandSyncFlags instance with only flags enabled on both x and y. (Using &= will update in place).

x ^ y, x ^= y

Returns a new CommandSyncFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

~x

Returns a new CommandSyncFlags instance with all flags from x inverted.

hash(x)

Return the flag’s hash.

iter(x)

Returns an iterator of (name, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

Additionally supported are a few operations on class attributes.

CommandSyncFlags.y | CommandSyncFlags.z, CommandSyncFlags(y=True) | CommandSyncFlags.z

Returns a CommandSyncFlags instance with all provided flags enabled.

~CommandSyncFlags.y

Returns a CommandSyncFlags instance with all flags except y inverted from their default value.

value

The raw value. You should query flags via the properties rather than using this raw value.

Type:

int

classmethod all()[source]

A factory method that creates a CommandSyncFlags with everything enabled.

classmethod none()[source]

A factory method that creates a CommandSyncFlags with everything disabled.

classmethod default()[source]

A factory method that creates a CommandSyncFlags with the default settings.

The default is all flags enabled except for sync_commands_debug.

sync_commands

Whether to sync global and guild app commands.

This controls the sync_global_commands and sync_guild_commands attributes.

Note that it is possible for sync to be enabled for guild or global commands yet this will return False.

Type:

bool

sync_commands_debug

Whether or not to show app command sync debug messages.

Type:

bool

sync_on_cog_actions

Whether or not to sync app commands on cog load, unload, or reload.

Type:

bool

allow_command_deletion

Whether to allow commands to be deleted by automatic command sync.

Current implementation of commands sync of renamed commands means that a rename of a command will result in the old one being deleted and a new command being created.

Type:

bool

sync_global_commands

Whether to sync global commands.

Type:

bool

sync_guild_commands

Whether to sync per-guild commands.

Type:

bool

Injection

Attributes
Methods
class disnake.ext.commands.Injection(function, *, autocompleters=None)[source]

Represents a slash command injection.

New in version 2.3.

Changed in version 2.6: Added keyword-only argument autocompleters.

function

The underlying injection function.

Type:

Callable

autocompleters

A mapping of injection’s option names to their respective autocompleters.

New in version 2.6.

Type:

dict[str, Callable]

@autocomplete(option_name)[source]

A decorator that registers an autocomplete function for the specified option.

New in version 2.6.

Parameters:

option_name (str) – The name of the option.

Raises:

  • ValueError – This injection already has an autocompleter set for the given option

  • TypeError – option_name is not str

__call__(*args, **kwargs)[source]

Calls the underlying function that the injection holds.

New in version 2.6.

ParamInfo

class disnake.ext.commands.ParamInfo(default=Ellipsis, *, name=None, description=None, converter=None, convert_default=False, autocomplete=None, choices=None, type=None, channel_types=None, lt=None, le=None, gt=None, ge=None, large=False, min_length=None, max_length=None)[source]

A class that basically connects function params with slash command options. The instances of this class are not created manually, but via the functional interface instead. See Param().

Parameters:

  • default (Any | Callable[[ApplicationCommandInteraction], Any]) – The actual default value for the corresponding function param. Can be a sync/async callable taking an interaction and returning a dynamic default value, if the user didn’t pass a value for this parameter.

  • name (str | Localized | None) –

    The name of this slash command option.

    Changed in version 2.5: Added support for localizations.

  • description (str | Localized | None) –

    The description of this slash command option.

    Changed in version 2.5: Added support for localizations.

  • choices (Sequence[OptionChoice] | Sequence[str | int | float] | Mapping[str, str | int | float]) – The pre-defined choices for this option.

  • ge (float) – The lowest allowed value for this option.

  • le (float) – The greatest allowed value for this option.

  • type (Any) – The type of the parameter.

  • channel_types (list[ChannelType]) – The list of channel types supported by this slash command option.

  • autocomplete (Callable[[ApplicationCommandInteraction, str], Any]) – The function that will suggest possible autocomplete options while typing.

  • converter (Callable[[ApplicationCommandInteraction, Any], Any]) – The function that will convert the original input to a desired format.

  • min_length (int) –

    The minimum length for this option, if it is a string option.

    New in version 2.6.

  • max_length (int) –

    The maximum length for this option, if it is a string option.

    New in version 2.6.

LargeInt

class disnake.ext.commands.LargeInt[source]

Type for large integers in slash commands.

This is a class which inherits from int to allow large numbers in slash commands, meant to be used only for annotations.

Range

class disnake.ext.commands.Range(underlying_type, min_value, max_value)[source]

Type representing a number with a limited range of allowed values.

See Number Ranges for more information.

New in version 2.4.

Changed in version 2.9: Syntax changed from Range[5, 10] to Range[int, 5, 10]; the type (int or float) must now be specified explicitly.

String

class disnake.ext.commands.String(underlying_type, min_value, max_value)[source]

Type representing a string option with a limited length.

See String Lengths for more information.

New in version 2.6.

Changed in version 2.9: Syntax changed from String[5, 10] to String[str, 5, 10]; the type (str) must now be specified explicitly.

Functions

disnake.ext.commands.Param(default=Ellipsis, *, name=None, description=None, choices=None, converter=None, convert_defaults=False, autocomplete=None, channel_types=None, lt=None, le=None, gt=None, ge=None, large=False, min_length=None, max_length=None, **kwargs)[source]

A special function that creates an instance of ParamInfo that contains some information about a slash command option. This instance should be assigned to a parameter of a function representing your slash command.

See Parameters for more info.

Parameters:

  • default (Any | Callable[[ApplicationCommandInteraction], Any]) – The actual default value of the function parameter that should be passed instead of the ParamInfo instance. Can be a sync/async callable taking an interaction and returning a dynamic default value, if the user didn’t pass a value for this parameter.

  • name (str | Localized | None) –

    The name of the option. By default, the option name is the parameter name.

    Changed in version 2.5: Added support for localizations.

  • description (str | Localized | None) –

    The description of the option. You can skip this kwarg and use docstrings. See Parameters. Kwarg aliases: desc.

    Changed in version 2.5: Added support for localizations.

  • choices (Sequence[OptionChoice] | Sequence[str | int | float] | Mapping[str, str | int | float]) – The pre-defined choices for this slash command option.

  • converter (Callable[[ApplicationCommandInteraction, Any], Any]) – A function that will convert the original input to a desired format. Kwarg aliases: conv.

  • convert_defaults (bool) –

    Whether to also apply the converter to the provided default value. Defaults to False.

    New in version 2.3.

  • autocomplete (Callable[[ApplicationCommandInteraction, str], Any]) – A function that will suggest possible autocomplete options while typing. See Parameters. Kwarg aliases: autocomp.

  • channel_types (Iterable[ChannelType]) – A list of channel types that should be allowed. By default these are discerned from the annotation.

  • lt (float) – The (exclusive) upper bound of values for this option (less-than).

  • le (float) – The (inclusive) upper bound of values for this option (less-than-or-equal). Kwarg aliases: max_value.

  • gt (float) – The (exclusive) lower bound of values for this option (greater-than).

  • ge (float) – The (inclusive) lower bound of values for this option (greater-than-or-equal). Kwarg aliases: min_value.

  • large (bool) –

    Whether to accept large int values (if this is False, only values in the range (-2^53, 2^53) would be accepted due to an API limitation).

    New in version 2.3.

  • min_length (int) –

    The minimum length for this option if this is a string option.

    New in version 2.6.

  • max_length (int) –

    The maximum length for this option if this is a string option.

    New in version 2.6.

Raises:

TypeError – Unexpected keyword arguments were provided.

Returns:

An instance with the option info.

Note

In terms of typing, this returns Any to avoid typing issues, but at runtime this is always a ParamInfo instance. You can find a more in-depth explanation here.

Return type:

ParamInfo

@disnake.ext.commands.slash_command(*, name=None, description=None, dm_permission=None, default_member_permissions=None, nsfw=None, install_types=None, contexts=None, options=None, guild_ids=None, connectors=None, auto_sync=None, extras=None, **kwargs)[source]

A decorator that builds a slash command.

Parameters:

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True.

  • name (str | Localized | None) –

    The name of the slash command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • description (str | Localized | None) –

    The description of the slash command. It will be visible in Discord.

    Changed in version 2.5: Added support for localizations.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • install_types (ApplicationInstallTypes | None) –

    The installation types where the command is available. Defaults to ApplicationInstallTypes.guild only. Only available for global commands.

    See Installation/Interaction Contexts for details.

    New in version 2.10.

  • contexts (InteractionContextTypes | None) –

    The interaction contexts where the command can be used. Only available for global commands.

    See Installation/Interaction Contexts for details.

    New in version 2.10.

  • options (list[Option]) – The list of slash command options. The options will be visible in Discord. This is the old way of specifying options. Consider using Parameters instead.

  • dm_permission (bool) –

    Whether this command can be used in DMs. Defaults to True.

    Deprecated since version 2.10: Use contexts instead. This is equivalent to the InteractionContextTypes.bot_dm flag.

  • default_member_permissions (Permissions | int | None) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • guild_ids (list[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • connectors (dict[str, str]) – Binds function names to option names. If the name of an option already matches the corresponding function param, you don’t have to specify the connectors. Connectors template: {"option-name": "param_name", ...}. If you’re using Parameters, you don’t need to specify this.

  • extras (dict[str, Any]) –

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

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableSlashCommand and returns it.

Return type:

Callable[…, InvokableSlashCommand]

@disnake.ext.commands.message_command(*, name=None, dm_permission=None, default_member_permissions=None, nsfw=None, install_types=None, contexts=None, guild_ids=None, auto_sync=None, extras=None, **kwargs)[source]

A shortcut decorator that builds a message command.

Parameters:
Returns:

A decorator that converts the provided method into an InvokableMessageCommand and then returns it.

Return type:

Callable[…, InvokableMessageCommand]

@disnake.ext.commands.user_command(*, name=None, dm_permission=None, default_member_permissions=None, nsfw=None, install_types=None, contexts=None, guild_ids=None, auto_sync=None, extras=None, **kwargs)[source]

A shortcut decorator that builds a user command.

Parameters:
Returns:

A decorator that converts the provided method into an InvokableUserCommand and returns it.

Return type:

Callable[…, InvokableUserCommand]

disnake.ext.commands.inject(function, *, autocompleters=None)[source]

A special function to use the provided function for injections. This should be assigned to a parameter of a function representing your slash command.

New in version 2.3.

Changed in version 2.6: Added autocompleters keyword-only argument.

Parameters:

  • function (Callable) – The injection function.

  • autocompleters (dict[str, Callable]) –

    A mapping of the injection’s option names to their respective autocompleters.

    See also Injection.autocomplete().

    New in version 2.6.

Returns:

The resulting injection

Note

The return type is annotated with Any to avoid typing issues caused by how this extension works, but at runtime this is always an Injection instance. You can find more in-depth explanation here.

Return type:

Injection

@disnake.ext.commands.register_injection(function, *, autocompleters=None)[source]

A decorator to register a global injection.

New in version 2.3.

Changed in version 2.6: Now returns Injection.

Changed in version 2.6: Added autocompleters keyword-only argument.

Raises:

TypeError – Injection doesn’t have a return annotation, or tries to overwrite builtin types.

Returns:

The injection being registered.

Return type:

Injection

@disnake.ext.commands.injection(*, autocompleters=None)[source]

Decorator interface for inject(). You can then assign this value to your slash commands’ parameters.

New in version 2.6.

Parameters:

autocompleters (dict[str, Callable]) –

A mapping of the injection’s option names to their respective autocompleters.

See also Injection.autocomplete().

Returns:

Decorator which turns your injection function into actual Injection.

Note

The decorator return type is annotated with Any to avoid typing issues caused by how this extension works, but at runtime this is always an Injection instance. You can find more in-depth explanation here.

Return type:

Callable[[Callable[…, Any]], Injection]

disnake.ext.commands.option_enum(choices, **kwargs)[source]

A utility function to create an enum type. Returns a new Enum based on the provided parameters.

New in version 2.1.

Parameters:

  • choices (dict[str, Any] | list[Any]) – A name/value mapping of choices, or a list of values whose stringified representations will be used as the names.

  • **kwargs – Name/value pairs to use instead of the choices parameter.

@disnake.ext.commands.default_member_permissions(value=0, **permissions)[source]

A decorator that sets default required member permissions for the application command. Unlike has_permissions(), this decorator does not add any checks. Instead, it prevents the command from being run by members without all required permissions, if not overridden by moderators on a guild-specific basis.

See also the default_member_permissions parameter for application command decorators.

Note

This does not work with slash subcommands/groups.

New in version 2.5.

Example

This would only allow members with manage_messages and view_audit_log permissions to use the command by default, however moderators can override this and allow/disallow specific users and roles to use the command in their guilds regardless of this setting.

@bot.slash_command()
@commands.default_member_permissions(manage_messages=True, view_audit_log=True)
async def purge(inter, num: int):
    ...
Parameters:

  • value (int) – A raw permission bitfield of an integer representing the required permissions. May be used instead of specifying kwargs.

  • **permissions (bool) – The required permissions for a command. A member must have all these permissions to be able to invoke the command. Setting a permission to False does not affect the result.

@disnake.ext.commands.install_types(*, guild=False, user=False)[source]

A decorator that sets the installation types where the application command is available.

See also the install_types parameter for application command decorators.

Note

This does not work with slash subcommands/groups.

New in version 2.10.

Parameters:

**params (bool) – The installation types; see ApplicationInstallTypes. Setting a parameter to False does not affect the result.

@disnake.ext.commands.contexts(*, guild=False, bot_dm=False, private_channel=False)[source]

A decorator that sets the interaction contexts where the application command can be used.

See also the contexts parameter for application command decorators.

Note

This does not work with slash subcommands/groups.

New in version 2.10.

Parameters:

**params (bool) – The interaction contexts; see InteractionContextTypes. Setting a parameter to False does not affect the result.

Events