API Reference

The following section outlines the API of disnake’s command extension module.

Bots

Bot

Methods
class disnake.ext.commands.Bot(command_prefix=None, help_command=<default-help-command>, description=None, **options)[source]

Represents a discord bot.

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

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

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 disnake.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. To avoid confusion empty iterables are not allowed.

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

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

test_guilds

The list of IDs of the guilds where you’re going to test your application commands. Defaults to None, which means global registration of commands across all guilds.

New in version 2.1.

Type

List[int]

sync_commands

Whether to enable automatic synchronization of application commands in your code. Defaults to True, which means that commands in API are automatically synced with the commands in your code.

New in version 2.1.

Type

bool

sync_commands_on_cog_unload

Whether to sync the application commands on cog unload / reload. Defaults to True.

New in version 2.1.

Type

bool

sync_commands_debug

Whether to always show sync debug logs (uses INFO log level if it’s enabled, prints otherwise). If disabled, uses the default DEBUG log level which isn’t shown unless the log level is changed manually. Useful for tracking the commands being registered in the API. Defaults to False.

New in version 2.1.

Changed in version 2.4: Changes the log level of corresponding messages from DEBUG to INFO or prints them, instead of controlling whether they are enabled at all.

Type

bool

reload

Whether to enable automatic extension reloading on file modification for debugging. Whenever you save an extension with reloading enabled the file will be automatically reloaded for you so you do not have to reload the extension manually. Defaults to False

New in version 2.1.

Type

bool

localization_provider

An implementation of LocalizationProtocol to use for localization of application commands. If not provided, the default LocalizationStore implementation is used.

New in version 2.5.

Type

LocalizationProtocol

strict_localization

Whether to raise an exception when localizations for a specific key couldn’t be found. This is mainly useful for testing/debugging, consider disabling this eventually as missing localized names will automatically fall back to the default/base name without it. Only applicable if the localization_provider parameter is not provided. Defaults to False.

New in version 2.5.

Type

bool

@after_invoke[source]

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

This is for text commands only, and doesn’t apply to application commands.

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.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@after_slash_command_invoke[source]

Similar to Bot.after_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@after_user_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for user commands.

@after_message_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for message commands.

@before_invoke[source]

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

This is for text commands only, and doesn’t apply to application commands.

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.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_slash_command_invoke[source]

Similar to Bot.before_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@before_user_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for user commands.

@before_message_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for message commands.

@check[source]

A decorator that adds a global check to the bot.

This is for text commands only, and doesn’t apply to application commands.

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
@check_once[source]

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

This is for text commands only, and doesn’t apply to application commands.

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
@command(*args, **kwargs)[source]

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]

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

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

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

  • guild_ids (Sequence[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, adds it to the bot, then returns it.

Return type

Callable[…, InvokableSlashCommand]

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableUserCommand, adds it to the bot, then returns it.

Return type

Callable[…, InvokableUserCommand]

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableMessageCommand, adds it to the bot, then returns it.

Return type

Callable[…, InvokableMessageCommand]

@event[source]

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!')
Raises

TypeError – The coroutine passed is not actually a coroutine.

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

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]

@listen(name=None)[source]

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

The activity being used upon logging in.

Type

Optional[BaseActivity]

add_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Adds a global application command check to the bot.

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

You must specify at least one of the bool parameters, otherwise the check won’t be added.

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

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

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

add_check(func, *, call_once=False)[source]

Adds a global check to the bot.

This is for text commands only, and doesn’t apply to application commands.

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

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.

add_cog(cog, *, override=False)[source]

Adds a “cog” to the bot.

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

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

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.

Raises
add_command(command)[source]

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

Parameters

command (Command) – The command to add.

Raises
add_listener(func, name=...)[source]

The non decorator alternative to listen().

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')
Raises

TypeError – The function is not a coroutine.

add_message_command(message_command)[source]

Adds an InvokableMessageCommand into the internal list of message commands.

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

Parameters

message_command (InvokableMessageCommand) – The message command to add.

Raises
add_slash_command(slash_command)[source]

Adds an InvokableSlashCommand into the internal list of slash commands.

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

Parameters

slash_command (InvokableSlashCommand) – The slash command to add.

Raises
add_user_command(user_command)[source]

Adds an InvokableUserCommand into the internal list of user commands.

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

Parameters

user_command (InvokableUserCommand) – The user command to add.

Raises
add_view(view, *, message_id=None)[source]

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

The allowed mention configuration.

New in version 1.4.

Type

Optional[AllowedMentions]

application_command_check(*, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

A decorator that adds a global application command 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 application command checks have been verified and applies to every application 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 ApplicationCommandInteraction and can only raise exceptions inherited from CommandError.

Example

@bot.application_command_check()
def check_app_commands(inter):
    return inter.channel_id in whitelisted_channels
Parameters
  • call_once (bool) – Whether the function should only be called once per InvokableApplicationCommand.invoke() call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

property application_commands[source]

A set of all application commands the bot has.

Type

Set[InvokableApplicationCommand]

property application_flags[source]

The client’s application flags.

New in version 2.0.

Type

ApplicationFlags

property application_id[source]

The client’s application ID.

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

New in version 2.0.

Type

Optional[int]

await application_info()[source]

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

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.

await bulk_fetch_command_permissions(guild_id)[source]

This function is a coroutine.

Retrieves a list of GuildApplicationCommandPermissions configured for the guild with the given ID.

New in version 2.1.

Parameters

guild_id (int) – The ID of the guild to inspect.

await bulk_overwrite_global_commands(application_commands)[source]

This function is a coroutine.

Overwrites several global application commands in one API request.

New in version 2.1.

Parameters

application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns

A list of registered application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await bulk_overwrite_guild_commands(guild_id, application_commands)[source]

This function is a coroutine.

Overwrites several guild application commands in one API request.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application commands should be overwritten.

  • application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns

A list of registered application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

property cached_messages[source]

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

This function is a coroutine.

Changes the client’s presence.

Example

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

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

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

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

clear()[source]

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

This function is a coroutine.

Closes the connection to Discord.

property cogs[source]

A read-only mapping of cog name to cog.

Type

Mapping[str, Cog]

property commands[source]

A unique set of commands without aliases that are registered.

Type

Set[Command]

await connect(*, reconnect=True)[source]

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

This function is a coroutine.

Creates a DMChannel with the given 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_global_command(application_command)[source]

This function is a coroutine.

Creates a global application command.

New in version 2.1.

Parameters

application_command (ApplicationCommand) – An object representing the application command to create.

Returns

The application command that was created.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await create_guild(*, name, icon=..., code=...)[source]

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.5: Removed the region parameter.

Parameters
Raises
Returns

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

Return type

Guild

await create_guild_command(guild_id, application_command)[source]

This function is a coroutine.

Creates a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application command should be created.

  • application_command (ApplicationCommand) – The application command.

Returns

The newly created application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await delete_global_command(command_id)[source]

This function is a coroutine.

Deletes a global application command.

New in version 2.1.

Parameters

command_id (int) – The ID of the application command to delete.

await delete_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Deletes a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the applcation command should be deleted.

  • command_id (int) – The ID of the application command to delete.

await delete_invite(invite)[source]

This function is a coroutine.

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

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

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.

await edit_global_command(command_id, new_command)[source]

This function is a coroutine.

Edits a global application command.

New in version 2.1.

Parameters
  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns

The edited application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_guild_command(guild_id, command_id, new_command)[source]

This function is a coroutine.

Edits a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application command should be edited.

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns

The newly edited application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property emojis[source]

The emojis that the connected client has.

Type

List[Emoji]

property extensions[source]

A read-only mapping of extension name to extension.

Type

Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)[source]

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.

Parameters

channel_id (int) – The ID of the channel to retrieve.

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_command_permissions(guild_id, command_id)[source]

This function is a coroutine.

Retrieves GuildApplicationCommandPermissions for a specific application command in the guild with the given ID.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to inspect.

  • command_id (int) –

    The ID of the application command, or the application ID to fetch application-wide permissions.

    Changed in version 2.5: Can now also fetch application-wide permissions.

Returns

The permissions configured for the specified application command.

Return type

GuildApplicationCommandPermissions

await fetch_global_command(command_id)[source]

This function is a coroutine.

Retrieves a global application command.

New in version 2.1.

Parameters

command_id (int) – The ID of the command to retrieve.

Returns

The requested application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_global_commands(*, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of global application commands.

New in version 2.1.

Parameters

with_localizations (bool) –

Whether to include localizations in the response. Defaults to True.

New in version 2.5.

Returns

A list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild(guild_id, /)[source]

This function is a coroutine.

Retrieves a Guild from the given ID.

Note

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

Note

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

Parameters

guild_id (int) – The ID of the guild to retrieve.

Raises
Returns

The guild from the given ID.

Return type

Guild

await fetch_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Retrieves a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to fetch command from.

  • command_id (int) – The ID of the application command to retrieve.

Returns

The requested application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_guild_commands(guild_id, *, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of guild application commands.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to fetch commands from.

  • with_localizations (bool) –

    Whether to include localizations in the response. Defaults to True.

    New in version 2.5.

Returns

A list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild_preview(guild_id, /)[source]

This function is a coroutine.

Retrieves a GuildPreview from the given ID. Your bot does not have to be in this guild.

Note

This method may fetch any guild that has DISCOVERABLE in Guild.features, but this information can not be known ahead of time.

This will work for any guild that you are in.

Parameters

guild_id (int) – The ID of the guild to to retrieve a preview object.

Raises

NotFound – Retrieving the guild preview failed.

Returns

The guild preview from the given ID.

Return type

GuildPreview

fetch_guilds(*, limit=100, before=None, after=None)[source]

Retrieves an AsyncIterator that enables receiving your guilds.

Note

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

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 = await client.fetch_guilds(limit=150).flatten()
# 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 100.

  • 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 – Retrieving the guilds failed.

Yields

Guild – The guild with the guild data parsed.

await fetch_invite(url, *, with_counts=True, with_expiration=True, guild_scheduled_event_id=None)[source]

This function is a coroutine.

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

Note

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

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.

  • guild_scheduled_event_id (int) –

    The ID of the scheduled event to include in the invite. If not provided, defaults to the event parameter in the URL if it exists, or the ID of the scheduled event contained in the provided invite object.

    New in version 2.3.

Raises
Returns

The invite from the URL/ID.

Return type

Invite

await fetch_premium_sticker_packs()[source]

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

This function is a coroutine.

Retrieves a StageInstance with the given ID.

Note

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

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 – Retrieving the stage instance failed.

Returns

The stage instance from the given ID.

Return type

StageInstance

await fetch_sticker(sticker_id, /)[source]

This function is a coroutine.

Retrieves a Sticker with the given ID.

New in version 2.0.

Parameters

sticker_id (int) – The ID of the sticker to retrieve.

Raises
Returns

The sticker you requested.

Return type

Union[StandardSticker, GuildSticker]

await fetch_template(code)[source]

This function is a coroutine.

Retrieves 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
Returns

The template from the URL/code.

Return type

Template

await fetch_user(user_id, /)[source]

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.

Note

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

Parameters

user_id (int) – The ID of the user to retrieve.

Raises
Returns

The user you requested.

Return type

User

await fetch_voice_regions(guild_id=None)[source]

Retrieves a list of VoiceRegions.

Retrieves voice regions for the user, or a guild if provided.

New in version 2.5.

Parameters

guild_id (Optional[int]) – The guild to get regions for, if provided.

Raises
  • HTTPException – Retrieving voice regions failed.

  • NotFound – The provided guild_id could not be found.

await fetch_webhook(webhook_id, /)[source]

This function is a coroutine.

Retrieves a Webhook with the given ID.

Parameters

webhook_id (int) – The ID of the webhook to retrieve.

Raises
Returns

The webhook you requested.

Return type

Webhook

await fetch_widget(guild_id, /)[source]

This function is a coroutine.

Retrieves a Widget for the given guild ID.

Note

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

Parameters

guild_id (int) – The ID of the guild.

Raises
Returns

The guild’s widget.

Return type

Widget

for ... in get_all_channels()[source]

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

Note

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

Yields

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

for ... in get_all_members()[source]

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

Returns a channel or thread with the given ID.

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

Gets the cog instance requested.

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

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

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.

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(message, *, cls=<class 'disnake.ext.commands.context.Context'>)[source]

This function is a coroutine.

Returns the invocation context from the message.

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

Parameters
  • message (disnake.Message) – The message 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, /)[source]

Returns an emoji with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The custom emoji or None if not found.

Return type

Optional[Emoji]

get_global_command(id)[source]

Returns a global application command with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_global_command_named(name, cmd_type=None)[source]

Returns a global application command matching the given name.

Parameters
  • name (str) – The name to look for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild(id, /)[source]

Returns a guild with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The guild or None if not found.

Return type

Optional[Guild]

get_guild_application_commands(guild_id)[source]

Returns a list of all application commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command(guild_id, id)[source]

Returns a guild application command with the given guild ID and application command ID.

Parameters
  • guild_id (int) – The guild ID to search for.

  • id (int) – The command ID to search for.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command_named(guild_id, name, cmd_type=None)[source]

Returns a guild application command matching the given name.

Parameters
  • guild_id (int) – The guild ID to search for.

  • name (str) – The command name to search for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_message_commands(guild_id)[source]

Returns a list of all message commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of message commands.

Return type

List[APIMessageCommand]

get_guild_slash_commands(guild_id)[source]

Returns a list of all slash commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of slash commands.

Return type

List[APISlashCommand]

get_guild_user_commands(guild_id)[source]

Returns a list of all user commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of user commands.

Return type

List[APIUserCommand]

get_message(id)[source]

Gets the message with the given ID from the bot’s message cache.

Parameters

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

Returns

The corresponding message.

Return type

Optional[Message]

get_message_command(name)[source]

Gets an InvokableMessageCommand from the internal list of message commands.

Parameters

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

Returns

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

Return type

Optional[InvokableMessageCommand]

await get_or_fetch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters

user_id (int) – The ID to search for.

Returns

The user with the given ID

Return type

User

get_partial_messageable(id, *, type=None)[source]

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.

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

Returns

The partial messageable

Return type

PartialMessageable

await get_prefix(message)[source]

This function is a coroutine.

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

Parameters

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

Returns

A list of prefixes or a single prefix that the bot is listening for. None if the bot isn’t listening for prefixes.

Return type

Optional[Union[List[str], str]]

get_slash_command(name)[source]

Works like Bot.get_command, but for slash commands.

If the name contains spaces, then it will assume that you are looking for a SubCommand or a SubCommandGroup. e.g: 'foo bar' will get the sub command group, or the sub command bar of the top-level slash command foo if found, otherwise None.

Parameters

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

Raises

TypeError – The name is not a string.

Returns

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

Return type

Optional[Union[InvokableSlashCommand, SubCommandGroup, SubCommand]]

get_stage_instance(id, /)[source]

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 returns stage instance or None if not found.

Return type

Optional[StageInstance]

get_sticker(id, /)[source]

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

Returns a user with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The user or None if not found.

Return type

Optional[User]

get_user_command(name)[source]

Gets an InvokableUserCommand from the internal list of user commands.

Parameters

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

Returns

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

Return type

Optional[InvokableUserCommand]

await getch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters

user_id (int) – The ID to search for.

Returns

The user with the given ID

Return type

User

property global_application_commands[source]

The client’s global application commands.

Type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property global_message_commands[source]

The client’s global message commands.

Type

List[APIMessageCommand]

property global_slash_commands[source]

The client’s global slash commands.

Type

List[APISlashCommand]

property global_user_commands[source]

The client’s global user commands.

Type

List[APIUserCommand]

property guilds[source]

The guilds that the connected client is a member of.

Type

List[Guild]

property intents[source]

The intents configured for this connection.

New in version 1.5.

Type

Intents

await invoke(ctx)[source]

This function is a coroutine.

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

Parameters

ctx (Context) – The invocation context to invoke.

is_closed()[source]

Whether the websocket connection is closed.

Return type

bool

await is_owner(user)[source]

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.

Parameters

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

Returns

Whether the user is the owner.

Return type

bool

is_ready()[source]

Whether the client’s internal cache is ready for use.

Return type

bool

is_ws_ratelimited()[source]

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.

Return type

bool

property latency[source]

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

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

Type

float

load_extension(name, *, package=None)[source]

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.

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.

load_extensions(path)[source]

Loads all extensions in a directory.

New in version 2.4.

Parameters

path (str) – The path to search for extensions

await login(token)[source]

This function is a coroutine.

Logs in the client with the specified credentials.

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.

message_command_check(func)[source]

Similar to check() but for message commands.

message_command_check_once(func)[source]

Similar to check_once() but for message commands.

property message_commands[source]

A set of all message commands the bot has.

Type

Set[InvokableMessageCommand]

await on_command_error(context, exception)[source]

This function is a coroutine.

The default command error handler provided by the bot.

This is for text commands only, and doesn’t apply to application commands.

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

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

await on_error(event_method, *args, **kwargs)[source]

This function is a coroutine.

The default error handler provided by the client.

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

await on_message_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for message commands.

await on_slash_command_error(interaction, exception)[source]

This function is a coroutine.

The default slash command error handler provided by the bot.

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

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

await on_user_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for user commands.

property persistent_views[source]

A sequence of persistent views added to the client.

New in version 2.0.

Type

Sequence[View]

property private_channels[source]

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

List[abc.PrivateChannel]

await process_app_command_autocompletion(inter)[source]

This function is a coroutine.

This function processes the application command autocompletions. Without this coroutine, none of the autocompletions will be performed.

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

Parameters

inter (disnake.ApplicationCommandInteraction) – The interaction to process.

await process_application_commands(interaction)[source]

This function is a coroutine.

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

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

Parameters

interaction (disnake.ApplicationCommandInteraction) – The interaction to process commands for.

await process_commands(message)[source]

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.

Parameters

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

reload_extension(name, *, package=None)[source]

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_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Removes a global application command check from the bot.

This function is idempotent and will not raise an exception if the function is not in the global checks.

You must specify at least one of the bool parameters, otherwise the check won’t be removed.

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

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

  • slash_commands (bool) – Whether this check was for slash commands.

  • user_commands (bool) – Whether this check was for user commands.

  • message_commands (bool) – Whether this check was for message commands.

remove_check(func, *, call_once=False)[source]

Removes a global check from the bot.

This is for text commands only, and doesn’t apply to application commands.

This function is idempotent and will not raise an exception if the function is not in the global checks.

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

remove_cog(name)[source]

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.

Parameters

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

Returns

The cog that was removed. Returns None if not found.

Return type

Optional[Cog]

remove_command(name)[source]

Remove a Command from the internal list of commands.

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

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

Removes a listener from the pool of listeners.

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

remove_message_command(name)[source]

Removes an InvokableMessageCommand from the internal list of message commands.

Parameters

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

Returns

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

Return type

Optional[InvokableMessageCommand]

remove_slash_command(name)[source]

Removes an InvokableSlashCommand from the internal list of slash commands.

Parameters

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

Returns

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

Return type

Optional[InvokableSlashCommand]

remove_user_command(name)[source]

Removes an InvokableUserCommand from the internal list of user commands.

Parameters

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

Returns

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

Return type

Optional[InvokableUserCommand]

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

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

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

Roughly Equivalent to:

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

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.

slash_command_check(func)[source]

Similar to check() but for slash commands.

slash_command_check_once(func)[source]

Similar to check_once() but for slash commands.

property slash_commands[source]

A set of all slash commands the bot has.

Type

Set[InvokableSlashCommand]

await start(token, *, reconnect=True)[source]

This function is a coroutine.

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

Raises

TypeError – An unexpected keyword argument was received.

property status[source]

The status being used upon logging on to Discord.

New in version 2.0.

Type

Status

property stickers[source]

The stickers that the connected client has.

New in version 2.0.

Type

List[GuildSticker]

unload_extension(name, *, package=None)[source]

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

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
property user[source]

Represents the connected client. None if not logged in.

Type

Optional[ClientUser]

user_command_check(func)[source]

Similar to check() but for user commands.

user_command_check_once(func)[source]

Similar to check_once() but for user commands.

property user_commands[source]

A set of all user commands the bot has.

Type

Set[InvokableUserCommand]

property users[source]

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

Type

List[User]

property voice_clients[source]

Represents a list of voice connections.

These are usually VoiceClient instances.

Type

List[VoiceProtocol]

wait_for(event, *, check=None, timeout=None)[source]

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

This function is a coroutine.

Waits until the first connect.

await wait_until_ready()[source]

This function is a coroutine.

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

for ... in walk_commands()[source]

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 disnake.ext.commands.AutoShardedBot(command_prefix=None, help_command=<default-help-command>, description=None, **options)[source]

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

InteractionBot

Methods
class disnake.ext.commands.InteractionBot(*, sync_commands=True, sync_commands_debug=False, sync_commands_on_cog_unload=True, test_guilds=None, **options)[source]

Represents a discord bot for application commands only.

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

This class also subclasses InteractionBotBase to provide the functionality to manage application commands.

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.

Type

Optional[Collection[int]]

test_guilds

The list of IDs of the guilds where you’re going to test your application commands. Defaults to None, which means global registration of commands across all guilds.

New in version 2.1.

Type

List[int]

sync_commands

Whether to enable automatic synchronization of application commands in your code. Defaults to True, which means that commands in API are automatically synced with the commands in your code.

New in version 2.1.

Type

bool

sync_commands_on_cog_unload

Whether to sync the application commands on cog unload / reload. Defaults to True.

New in version 2.1.

Type

bool

sync_commands_debug

Whether to always show sync debug logs (uses INFO log level if it’s enabled, prints otherwise). If disabled, uses the default DEBUG log level which isn’t shown unless the log level is changed manually. Useful for tracking the commands being registered in the API. Defaults to False.

New in version 2.1.

Changed in version 2.4: Changes the log level of corresponding messages from DEBUG to INFO or prints them, instead of controlling whether they are enabled at all.

Type

bool

reload

Whether to enable automatic extension reloading on file modification for debugging. Whenever you save an extension with reloading enabled the file will be automatically reloaded for you so you do not have to reload the extension manually. Defaults to False

New in version 2.1.

Type

bool

localization_provider

An implementation of LocalizationProtocol to use for localization of application commands. If not provided, the default LocalizationStore implementation is used.

New in version 2.5.

Type

LocalizationProtocol

strict_localization

Whether to raise an exception when localizations for a specific key couldn’t be found. This is mainly useful for testing/debugging, consider disabling this eventually as missing localized names will automatically fall back to the default/base name without it. Only applicable if the localization_provider parameter is not provided. Defaults to False.

New in version 2.5.

Type

bool

@after_slash_command_invoke[source]

Similar to Bot.after_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@after_user_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for user commands.

@after_message_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for message commands.

@before_slash_command_invoke[source]

Similar to Bot.before_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@before_user_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for user commands.

@before_message_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for message commands.

@application_command_check[source]

A decorator that adds a global application command 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 application command checks have been verified and applies to every application 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 ApplicationCommandInteraction and can only raise exceptions inherited from CommandError.

Example

@bot.application_command_check()
def check_app_commands(inter):
    return inter.channel_id in whitelisted_channels
Parameters
  • call_once (bool) – Whether the function should only be called once per InvokableApplicationCommand.invoke() call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

@slash_command_check[source]

Similar to check() but for slash commands.

@user_command_check[source]

Similar to check() but for user commands.

@message_command_check[source]

Similar to check() but for message commands.

@slash_command_check_once[source]

Similar to check_once() but for slash commands.

@user_command_check_once[source]

Similar to check_once() but for user commands.

@message_command_check_once[source]

Similar to check_once() but for message commands.

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

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

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

  • guild_ids (Sequence[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, adds it to the bot, then returns it.

Return type

Callable[…, InvokableSlashCommand]

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableUserCommand, adds it to the bot, then returns it.

Return type

Callable[…, InvokableUserCommand]

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

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

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableMessageCommand, adds it to the bot, then returns it.

Return type

Callable[…, InvokableMessageCommand]

@event[source]

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!')
Raises

TypeError – The coroutine passed is not actually a coroutine.

@listen(name=None)[source]

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

The activity being used upon logging in.

Type

Optional[BaseActivity]

add_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Adds a global application command check to the bot.

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

You must specify at least one of the bool parameters, otherwise the check won’t be added.

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

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

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

add_cog(cog, *, override=False)[source]

Adds a “cog” to the bot.

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

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

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.

Raises
add_listener(func, name=...)[source]

The non decorator alternative to listen().

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')
Raises

TypeError – The function is not a coroutine.

add_message_command(message_command)[source]

Adds an InvokableMessageCommand into the internal list of message commands.

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

Parameters

message_command (InvokableMessageCommand) – The message command to add.

Raises
add_slash_command(slash_command)[source]

Adds an InvokableSlashCommand into the internal list of slash commands.

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

Parameters

slash_command (InvokableSlashCommand) – The slash command to add.

Raises
add_user_command(user_command)[source]

Adds an InvokableUserCommand into the internal list of user commands.

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

Parameters

user_command (InvokableUserCommand) – The user command to add.

Raises
add_view(view, *, message_id=None)[source]

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

The allowed mention configuration.

New in version 1.4.

Type

Optional[AllowedMentions]

property application_commands[source]

A set of all application commands the bot has.

Type

Set[InvokableApplicationCommand]

property application_flags[source]

The client’s application flags.

New in version 2.0.

Type

ApplicationFlags

property application_id[source]

The client’s application ID.

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

New in version 2.0.

Type

Optional[int]

await application_info()[source]

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

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.

await bulk_fetch_command_permissions(guild_id)[source]

This function is a coroutine.

Retrieves a list of GuildApplicationCommandPermissions configured for the guild with the given ID.

New in version 2.1.

Parameters

guild_id (int) – The ID of the guild to inspect.

await bulk_overwrite_global_commands(application_commands)[source]

This function is a coroutine.

Overwrites several global application commands in one API request.

New in version 2.1.

Parameters

application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns

A list of registered application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await bulk_overwrite_guild_commands(guild_id, application_commands)[source]

This function is a coroutine.

Overwrites several guild application commands in one API request.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application commands should be overwritten.

  • application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns

A list of registered application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

property cached_messages[source]

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

This function is a coroutine.

Changes the client’s presence.

Example

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

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

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

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

clear()[source]

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

This function is a coroutine.

Closes the connection to Discord.

property cogs[source]

A read-only mapping of cog name to cog.

Type

Mapping[str, Cog]

await connect(*, reconnect=True)[source]

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

This function is a coroutine.

Creates a DMChannel with the given 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_global_command(application_command)[source]

This function is a coroutine.

Creates a global application command.

New in version 2.1.

Parameters

application_command (ApplicationCommand) – An object representing the application command to create.

Returns

The application command that was created.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await create_guild(*, name, icon=..., code=...)[source]

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.5: Removed the region parameter.

Parameters
Raises
Returns

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

Return type

Guild

await create_guild_command(guild_id, application_command)[source]

This function is a coroutine.

Creates a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application command should be created.

  • application_command (ApplicationCommand) – The application command.

Returns

The newly created application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await delete_global_command(command_id)[source]

This function is a coroutine.

Deletes a global application command.

New in version 2.1.

Parameters

command_id (int) – The ID of the application command to delete.

await delete_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Deletes a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the applcation command should be deleted.

  • command_id (int) – The ID of the application command to delete.

await delete_invite(invite)[source]

This function is a coroutine.

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

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

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.

await edit_global_command(command_id, new_command)[source]

This function is a coroutine.

Edits a global application command.

New in version 2.1.

Parameters
  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns

The edited application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_guild_command(guild_id, command_id, new_command)[source]

This function is a coroutine.

Edits a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild where the application command should be edited.

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns

The newly edited application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property emojis[source]

The emojis that the connected client has.

Type

List[Emoji]

property extensions[source]

A read-only mapping of extension name to extension.

Type

Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)[source]

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.

Parameters

channel_id (int) – The ID of the channel to retrieve.

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_command_permissions(guild_id, command_id)[source]

This function is a coroutine.

Retrieves GuildApplicationCommandPermissions for a specific application command in the guild with the given ID.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to inspect.

  • command_id (int) –

    The ID of the application command, or the application ID to fetch application-wide permissions.

    Changed in version 2.5: Can now also fetch application-wide permissions.

Returns

The permissions configured for the specified application command.

Return type

GuildApplicationCommandPermissions

await fetch_global_command(command_id)[source]

This function is a coroutine.

Retrieves a global application command.

New in version 2.1.

Parameters

command_id (int) – The ID of the command to retrieve.

Returns

The requested application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_global_commands(*, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of global application commands.

New in version 2.1.

Parameters

with_localizations (bool) –

Whether to include localizations in the response. Defaults to True.

New in version 2.5.

Returns

A list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild(guild_id, /)[source]

This function is a coroutine.

Retrieves a Guild from the given ID.

Note

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

Note

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

Parameters

guild_id (int) – The ID of the guild to retrieve.

Raises
Returns

The guild from the given ID.

Return type

Guild

await fetch_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Retrieves a guild application command.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to fetch command from.

  • command_id (int) – The ID of the application command to retrieve.

Returns

The requested application command.

Return type

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_guild_commands(guild_id, *, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of guild application commands.

New in version 2.1.

Parameters
  • guild_id (int) – The ID of the guild to fetch commands from.

  • with_localizations (bool) –

    Whether to include localizations in the response. Defaults to True.

    New in version 2.5.

Returns

A list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild_preview(guild_id, /)[source]

This function is a coroutine.

Retrieves a GuildPreview from the given ID. Your bot does not have to be in this guild.

Note

This method may fetch any guild that has DISCOVERABLE in Guild.features, but this information can not be known ahead of time.

This will work for any guild that you are in.

Parameters

guild_id (int) – The ID of the guild to to retrieve a preview object.

Raises

NotFound – Retrieving the guild preview failed.

Returns

The guild preview from the given ID.

Return type

GuildPreview

fetch_guilds(*, limit=100, before=None, after=None)[source]

Retrieves an AsyncIterator that enables receiving your guilds.

Note

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

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 = await client.fetch_guilds(limit=150).flatten()
# 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 100.

  • 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 – Retrieving the guilds failed.

Yields

Guild – The guild with the guild data parsed.

await fetch_invite(url, *, with_counts=True, with_expiration=True, guild_scheduled_event_id=None)[source]

This function is a coroutine.

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

Note

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

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.

  • guild_scheduled_event_id (int) –

    The ID of the scheduled event to include in the invite. If not provided, defaults to the event parameter in the URL if it exists, or the ID of the scheduled event contained in the provided invite object.

    New in version 2.3.

Raises
Returns

The invite from the URL/ID.

Return type

Invite

await fetch_premium_sticker_packs()[source]

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

This function is a coroutine.

Retrieves a StageInstance with the given ID.

Note

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

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 – Retrieving the stage instance failed.

Returns

The stage instance from the given ID.

Return type

StageInstance

await fetch_sticker(sticker_id, /)[source]

This function is a coroutine.

Retrieves a Sticker with the given ID.

New in version 2.0.

Parameters

sticker_id (int) – The ID of the sticker to retrieve.

Raises
Returns

The sticker you requested.

Return type

Union[StandardSticker, GuildSticker]

await fetch_template(code)[source]

This function is a coroutine.

Retrieves 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
Returns

The template from the URL/code.

Return type

Template

await fetch_user(user_id, /)[source]

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.

Note

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

Parameters

user_id (int) – The ID of the user to retrieve.

Raises
Returns

The user you requested.

Return type

User

await fetch_voice_regions(guild_id=None)[source]

Retrieves a list of VoiceRegions.

Retrieves voice regions for the user, or a guild if provided.

New in version 2.5.

Parameters

guild_id (Optional[int]) – The guild to get regions for, if provided.

Raises
  • HTTPException – Retrieving voice regions failed.

  • NotFound – The provided guild_id could not be found.

await fetch_webhook(webhook_id, /)[source]

This function is a coroutine.

Retrieves a Webhook with the given ID.

Parameters

webhook_id (int) – The ID of the webhook to retrieve.

Raises
Returns

The webhook you requested.

Return type

Webhook

await fetch_widget(guild_id, /)[source]

This function is a coroutine.

Retrieves a Widget for the given guild ID.

Note

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

Parameters

guild_id (int) – The ID of the guild.

Raises
Returns

The guild’s widget.

Return type

Widget

for ... in get_all_channels()[source]

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

Note

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

Yields

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

for ... in get_all_members()[source]

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

Returns a channel or thread with the given ID.

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

Gets the cog instance requested.

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

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_emoji(id, /)[source]

Returns an emoji with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The custom emoji or None if not found.

Return type

Optional[Emoji]

get_global_command(id)[source]

Returns a global application command with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_global_command_named(name, cmd_type=None)[source]

Returns a global application command matching the given name.

Parameters
  • name (str) – The name to look for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild(id, /)[source]

Returns a guild with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The guild or None if not found.

Return type

Optional[Guild]

get_guild_application_commands(guild_id)[source]

Returns a list of all application commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of application commands.

Return type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command(guild_id, id)[source]

Returns a guild application command with the given guild ID and application command ID.

Parameters
  • guild_id (int) – The guild ID to search for.

  • id (int) – The command ID to search for.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command_named(guild_id, name, cmd_type=None)[source]

Returns a guild application command matching the given name.

Parameters
  • guild_id (int) – The guild ID to search for.

  • name (str) – The command name to search for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns

The application command.

Return type

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_message_commands(guild_id)[source]

Returns a list of all message commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of message commands.

Return type

List[APIMessageCommand]

get_guild_slash_commands(guild_id)[source]

Returns a list of all slash commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of slash commands.

Return type

List[APISlashCommand]

get_guild_user_commands(guild_id)[source]

Returns a list of all user commands in the guild with the given ID.

Parameters

guild_id (int) – The ID to search for.

Returns

The list of user commands.

Return type

List[APIUserCommand]

get_message(id)[source]

Gets the message with the given ID from the bot’s message cache.

Parameters

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

Returns

The corresponding message.

Return type

Optional[Message]

get_message_command(name)[source]

Gets an InvokableMessageCommand from the internal list of message commands.

Parameters

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

Returns

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

Return type

Optional[InvokableMessageCommand]

await get_or_fetch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters

user_id (int) – The ID to search for.

Returns

The user with the given ID

Return type

User

get_partial_messageable(id, *, type=None)[source]

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.

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

Returns

The partial messageable

Return type

PartialMessageable

get_slash_command(name)[source]

Works like Bot.get_command, but for slash commands.

If the name contains spaces, then it will assume that you are looking for a SubCommand or a SubCommandGroup. e.g: 'foo bar' will get the sub command group, or the sub command bar of the top-level slash command foo if found, otherwise None.

Parameters

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

Raises

TypeError – The name is not a string.

Returns

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

Return type

Optional[Union[InvokableSlashCommand, SubCommandGroup, SubCommand]]

get_stage_instance(id, /)[source]

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 returns stage instance or None if not found.

Return type

Optional[StageInstance]

get_sticker(id, /)[source]

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

Returns a user with the given ID.

Parameters

id (int) – The ID to search for.

Returns

The user or None if not found.

Return type

Optional[User]

get_user_command(name)[source]

Gets an InvokableUserCommand from the internal list of user commands.

Parameters

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

Returns

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

Return type

Optional[InvokableUserCommand]

await getch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters

user_id (int) – The ID to search for.

Returns

The user with the given ID

Return type

User

property global_application_commands[source]

The client’s global application commands.

Type

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property global_message_commands[source]

The client’s global message commands.

Type

List[APIMessageCommand]

property global_slash_commands[source]

The client’s global slash commands.

Type

List[APISlashCommand]

property global_user_commands[source]

The client’s global user commands.

Type

List[APIUserCommand]

property guilds[source]

The guilds that the connected client is a member of.

Type

List[Guild]

property intents[source]

The intents configured for this connection.

New in version 1.5.

Type

Intents

is_closed()[source]

Whether the websocket connection is closed.

Return type

bool

await is_owner(user)[source]

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.

Parameters

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

Returns

Whether the user is the owner.

Return type

bool

is_ready()[source]

Whether the client’s internal cache is ready for use.

Return type

bool

is_ws_ratelimited()[source]

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.

Return type

bool

property latency[source]

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

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

Type

float

load_extension(name, *, package=None)[source]

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.

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.

load_extensions(path)[source]

Loads all extensions in a directory.

New in version 2.4.

Parameters

path (str) – The path to search for extensions

await login(token)[source]

This function is a coroutine.

Logs in the client with the specified credentials.

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.

property message_commands[source]

A set of all message commands the bot has.

Type

Set[InvokableMessageCommand]

await on_error(event_method, *args, **kwargs)[source]

This function is a coroutine.

The default error handler provided by the client.

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

await on_message_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for message commands.

await on_slash_command_error(interaction, exception)[source]

This function is a coroutine.

The default slash command error handler provided by the bot.

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

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

await on_user_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for user commands.

property persistent_views[source]

A sequence of persistent views added to the client.

New in version 2.0.

Type

Sequence[View]

property private_channels[source]

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

List[abc.PrivateChannel]

await process_app_command_autocompletion(inter)[source]

This function is a coroutine.

This function processes the application command autocompletions. Without this coroutine, none of the autocompletions will be performed.

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

Parameters

inter (disnake.ApplicationCommandInteraction) – The interaction to process.

await process_application_commands(interaction)[source]

This function is a coroutine.

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

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

Parameters

interaction (disnake.ApplicationCommandInteraction) – The interaction to process commands for.

reload_extension(name, *, package=None)[source]

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_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Removes a global application command check from the bot.

This function is idempotent and will not raise an exception if the function is not in the global checks.

You must specify at least one of the bool parameters, otherwise the check won’t be removed.

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

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

  • slash_commands (bool) – Whether this check was for slash commands.

  • user_commands (bool) – Whether this check was for user commands.

  • message_commands (bool) – Whether this check was for message commands.

remove_cog(name)[source]

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.

Parameters

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

Returns

The cog that was removed. Returns None if not found.

Return type

Optional[Cog]

remove_listener(func, name=...)[source]

Removes a listener from the pool of listeners.

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

remove_message_command(name)[source]

Removes an InvokableMessageCommand from the internal list of message commands.

Parameters

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

Returns

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

Return type

Optional[InvokableMessageCommand]

remove_slash_command(name)[source]

Removes an InvokableSlashCommand from the internal list of slash commands.

Parameters

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

Returns

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

Return type

Optional[InvokableSlashCommand]

remove_user_command(name)[source]

Removes an InvokableUserCommand from the internal list of user commands.

Parameters

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

Returns

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

Return type

Optional[InvokableUserCommand]

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

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

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

Roughly Equivalent to:

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

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.

property slash_commands[source]

A set of all slash commands the bot has.

Type

Set[InvokableSlashCommand]

await start(token, *, reconnect=True)[source]

This function is a coroutine.

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

Raises

TypeError – An unexpected keyword argument was received.

property status[source]

The status being used upon logging on to Discord.

New in version 2.0.

Type

Status

property stickers[source]

The stickers that the connected client has.

New in version 2.0.

Type

List[GuildSticker]

unload_extension(name, *, package=None)[source]

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

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
property user[source]

Represents the connected client. None if not logged in.

Type

Optional[ClientUser]

property user_commands[source]

A set of all user commands the bot has.

Type

Set[InvokableUserCommand]

property users[source]

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

Type

List[User]

property voice_clients[source]

Represents a list of voice connections.

These are usually VoiceClient instances.

Type

List[VoiceProtocol]

wait_for(event, *, check=None, timeout=None)[source]

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

This function is a coroutine.

Waits until the first connect.

await wait_until_ready()[source]

This function is a coroutine.

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

AutoShardedInteractionBot

class disnake.ext.commands.AutoShardedInteractionBot(*, sync_commands=True, sync_commands_debug=False, sync_commands_on_cog_unload=True, test_guilds=None, **options)[source]

This is similar to InteractionBot except that it is inherited from disnake.AutoShardedClient instead.

Prefix Helpers

disnake.ext.commands.when_mentioned(bot, msg)[source]

A callable that implements a command prefix equivalent to being mentioned.

These are meant to be passed into the Bot.command_prefix attribute.

disnake.ext.commands.when_mentioned_or(*prefixes)[source]

A callable that implements when mentioned or other prefixes provided.

These are meant to be passed into the Bot.command_prefix attribute.

Example

bot = commands.Bot(command_prefix=commands.when_mentioned_or('!'))

Note

This callable returns another callable, so if this is done inside a custom callable, you must call the returned callable, for example:

async def get_prefix(bot, message):
    extras = await prefixes_for(message.guild) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

See also

when_mentioned()

Event Reference

These events function similar to the regular events, except they are custom to the command extension module.

disnake.ext.commands.on_command_error(ctx, error)

An error handler that is called when an error is raised inside a command either through user input error, check failure, or an error in your own code.

A default one is provided (Bot.on_command_error()).

Parameters
  • ctx (Context) – The invocation context.

  • error (CommandError derived) – The error that was raised.

disnake.ext.commands.on_slash_command_error(inter, error)

An error handler that is called when an error is raised inside a slash command either through user input error, check failure, or an error in your own code.

A default one is provided (Bot.on_slash_command_error()).

Parameters
disnake.ext.commands.on_user_command_error(inter, error)

An error handler that is called when an error is raised inside a user command either through check failure, or an error in your own code.

A default one is provided (Bot.on_user_command_error()).

Parameters
disnake.ext.commands.on_message_command_error(inter, error)

An error handler that is called when an error is raised inside a message command either through check failure, or an error in your own code.

A default one is provided (Bot.on_message_command_error()).

Parameters
disnake.ext.commands.on_command(ctx)

An event that is called when a command is found and is about to be invoked.

This event is called regardless of whether the command itself succeeds via error or completes.

Parameters

ctx (Context) – The invocation context.

disnake.ext.commands.on_slash_command(inter)

An event that is called when a slash command is found and is about to be invoked.

This event is called regardless of whether the slash command itself succeeds via error or completes.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this slash command.

disnake.ext.commands.on_user_command(inter)

An event that is called when a user command is found and is about to be invoked.

This event is called regardless of whether the user command itself succeeds via error or completes.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this user command.

disnake.ext.commands.on_message_command(inter)

An event that is called when a message command is found and is about to be invoked.

This event is called regardless of whether the message command itself succeeds via error or completes.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this message command.

disnake.ext.commands.on_command_completion(ctx)

An event that is called when a command has completed its invocation.

This event is called only if the command succeeded, i.e. all checks have passed and the user input it correctly.

Parameters

ctx (Context) – The invocation context.

disnake.ext.commands.on_slash_command_completion(inter)

An event that is called when a slash command has completed its invocation.

This event is called only if the slash command succeeded, i.e. all checks have passed and command handler ran successfully.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this slash command.

disnake.ext.commands.on_user_command_completion(inter)

An event that is called when a user command has completed its invocation.

This event is called only if the user command succeeded, i.e. all checks have passed and command handler ran successfully.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this user command.

disnake.ext.commands.on_message_command_completion(inter)

An event that is called when a message command has completed its invocation.

This event is called only if the message command succeeded, i.e. all checks have passed and command handler ran successfully.

Parameters

inter (ApplicationCommandInteraction) – The interaction that invoked this message command.

Commands

Decorators

@disnake.ext.commands.command(name=..., cls=..., **attrs)[source]

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.

@disnake.ext.commands.slash_command(*, name=None, description=None, dm_permission=None, default_member_permissions=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 (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

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

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    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.user_command(*, name=None, dm_permission=None, default_member_permissions=None, guild_ids=None, auto_sync=None, extras=None, **kwargs)[source]

A shortcut decorator that builds a user command.

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableUserCommand and returns it.

Return type

Callable[…, InvokableUserCommand]

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

A shortcut decorator that builds a message command.

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

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

    New in version 2.5.

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

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

  • 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 InvokableMessageCommand and then returns it.

Return type

Callable[…, InvokableMessageCommand]

@disnake.ext.commands.group(name=..., cls=..., **attrs)[source]

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.

Helper 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, **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) – The actual default value of the function parameter that should be passed instead of the ParamInfo instance.

  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

    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 (Union[List[OptionChoice], List[Union[str, int]], Dict[str, Union[str, int]]]) – A list of choices for this 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.

Raises

TypeError – Unexpected keyword arguments were provided.

Returns

An instance with the option info.

Return type

ParamInfo

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 (Union[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.inject(function)[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.

@disnake.ext.commands.register_injection(function)[source]

A decorator to register a global injection.

New in version 2.3.

@disnake.ext.commands.converter_method(function)[source]

A decorator to register a method as the converter method.

New in version 2.3.

Application Command

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 that is executed when the command is called.

Type

coroutine

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

Optional[Tuple[int, …]]

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 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@after_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

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

Optional[Permissions]

add_check(func)[source]

Adds a check to the application command.

This is the non-decorator interface to 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

await invoke(inter, *args, **kwargs)[source]

This method isn’t really usable in this class, but it’s usable in subclasses.

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

Optional[str]

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

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 that is executed when the command is called.

Type

coroutine

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

Optional[Tuple[int, …]]

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]

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

A decorator that creates a subcommand under the base command.

Parameters
  • name (Optional[Union[str, Localized]]) –

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

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

    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 (Optional[Union[str, Localized]]) –

    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 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

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.

await invoke(inter)[source]

This method isn’t really usable in this class, but it’s usable in subclasses.

Slash Subcommand

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

option

API representation of this subcommand.

Type

Option

callback[source]

The coroutine that is executed when the subcommand is called.

Type

coroutine

cog

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

Type

Optional[Cog]

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 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

await invoke(inter, *args, **kwargs)[source]

This method isn’t really usable in this class, but it’s usable in subclasses.

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

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

option

API representation of this subcommand.

Type

Option

callback[source]

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

Type

coroutine

cog

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

Type

Optional[Cog]

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 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

ParamInfo

class disnake.ext.commands.ParamInfo(default=Ellipsis, *, name=None, description=None, converter=None, convert_default=False, autcomplete=None, choices=None, type=None, channel_types=None, lt=None, le=None, gt=None, ge=None, large=False)[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) – The actual default value for the corresponding function param.

  • name (Optional[Union[str, Localized]]) –

    The name of this slash command option.

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

    The description of this slash command option.

    Changed in version 2.5: Added support for localizations.

  • choices (Union[List[OptionChoice], List[Union[str, int]], Dict[str, Union[str, int]]]) – The list of choices of this slash command 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.

User Command

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 that is executed when the user command is called.

Type

coroutine

cog

The cog that this user 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 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

Optional[Tuple[int, …]]

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 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

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

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 that is executed when the message command is called.

Type

coroutine

cog

The cog that this message 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 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

Optional[Tuple[int, …]]

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 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) – The coroutine to register as the post-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

A decorator that registers a coroutine 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) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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

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

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

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.

Command

class disnake.ext.commands.Command(*args, **kwargs)[source]

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

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

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

New in version 2.0.

Type

dict

@after_invoke[source]

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.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

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.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@error[source]

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.

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

Adds a check to the command.

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

New in version 1.3.

Parameters

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

remove_check(func)[source]

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.

Parameters

func – The function to remove from the checks.

update(**kwargs)[source]

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

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.

copy()[source]

Creates a copy of this command.

Returns

A new instance of this command.

Return type

Command

property clean_params[source]

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

Useful for inspecting signature.

property full_parent_name[source]

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

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

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

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

Checks whether the command is currently on cooldown.

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

Resets the cooldown on this command.

Parameters

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

get_cooldown_retry_after(ctx)[source]

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

New in version 1.4.

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

Whether the command has an error handler registered.

New in version 1.7.

Return type

bool

property cog_name[source]

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

Type

Optional[str]

property short_doc[source]

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

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

Type

str

await can_run(ctx)[source]

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.

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

Whether the command can be invoked.

Return type

bool

Group

class disnake.ext.commands.Group(*args, **kwargs)[source]

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

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.

Parameters

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

Raises

TypeError – The coroutine passed is not actually a coroutine.

@before_invoke[source]

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.

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

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

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.

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

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

Creates a copy of this Group.

Returns

A new instance of this group.

Return type

Group

add_check(func)[source]

Adds a check to the command.

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

New in version 1.3.

Parameters

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

add_command(command)[source]

Adds a