API Reference

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

Bots

Bot

Attributes
Methods
class disnake.ext.commands.Bot(command_prefix=None, help_command=<default-help-command>, description=None, *, strip_after_prefix=False, **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.

Parameters:

  • test_guilds (List[int]) –

    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.

  • command_sync_flags (CommandSyncFlags) –

    The command sync flags for the session. This is a way of controlling when and how application commands will be synced with the Discord API. If not given, defaults to CommandSyncFlags.default().

    New in version 2.7.

  • sync_commands (bool) –

    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.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_on_cog_unload (bool) –

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

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_debug (bool) –

    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.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • localization_provider (LocalizationProtocol) –

    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.

  • strict_localization (bool) –

    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.

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.

If the prefix is None, the bot won’t listen to any prefixes, and prefix commands will not be processed. If you don’t need prefix commands, consider using InteractionBot or AutoShardedInteractionBot instead, which are drop-in replacements, just without prefix command support.

This can be provided as a parameter at creation.

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.

This can be provided as a parameter at creation.

Type:

bool

description

The content prefixed into the default help message.

This can be provided as a parameter at creation.

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.

This can be provided as a parameter at creation.

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

This can be provided as a parameter at creation.

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.

This can be provided as a parameter at creation.

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.

This can be provided as a parameter at creation.

New in version 1.7.

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

This can be provided as a parameter at creation.

New in version 2.1.

Type:

bool

i18n

An implementation of LocalizationProtocol used for localization of application commands.

New in version 2.5.

Type:

LocalizationProtocol

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

  • nsfw (bool) –

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

    New in version 2.8.

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

  • nsfw (bool) –

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

    New in version 2.8.

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

  • nsfw (bool) –

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

    New in version 2.8.

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

# in yet another file
@bot.listen(Event.message)
async def another_message(message):
    print('three')

Would print one, two and three in an unspecified order.

Raises:

TypeError – The function being listened to is not a coroutine or a string or an Event was not passed as the name.

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 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 (Union[str, Event]) – The name of the event to listen for. Defaults to func.__name__.

Example

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

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')
bot.add_listener(another_message, Event.message)
Raises:

TypeError – The function is not a coroutine or a string or an Event was not passed as the name.

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

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

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:

TypeError – 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 command_sync_flags[source]

The command sync flags configured for this bot.

New in version 2.7.

Type:

CommandSyncFlags

property commands[source]

A unique set of commands without aliases that are registered.

Type:

Set[Command]

await connect(*, reconnect=True, ignore_session_start_limit=False)[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.

Changed in version 2.6: Added usage of SessionStartLimit when connecting to the API. Added the ignore_session_start_limit parameter.

Parameters:

  • reconnect (bool) – Whether reconnecting should be attempted, 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).

  • ignore_session_start_limit (bool) –

    Whether the API provided session start limit should be ignored when connecting to the API.

    New in version 2.6.

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.

  • SessionStartLimitReached – If the client doesn’t have enough connects remaining in the current 24-hour window and ignore_session_start_limit is False this will be raised rather than connecting to the gateawy and Discord resetting the token. However, if ignore_session_start_limit is True, the client will connect regardless and this exception will not be raised.

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.

See guild_builder() for a more comprehensive alternative.

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

Changed in version 2.5: Removed the region parameter.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

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]

await edit_role_connection_metadata(records)[source]

This function is a coroutine.

Edits the ApplicationRoleConnectionMetadata records for the application.

An application can have up to 5 metadata records.

Warning

This will overwrite all existing metadata records. Consider fetching them first, and constructing the new list of metadata records based off of the returned list.

New in version 2.8.

Parameters:

records (Sequence[ApplicationRoleConnectionMetadata]) – The new metadata records.

Raises:

HTTPException – Editing the metadata records failed.

Returns:

The list of newly edited metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

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

This function is a coroutine.

Retrieves the ApplicationRoleConnectionMetadata records for the application.

New in version 2.8.

Raises:

HTTPException – Retrieving the metadata records failed.

Returns:

The list of metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

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

Mapping[str, List[Callable]]: A read-only mapping of event names to listeners.

Note

To add or remove a listener you should use add_listener() and remove_listener().

New in version 2.9.

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.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[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.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

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

guild_builder(name)[source]

Creates a builder object that can be used to create more complex guilds.

This is a more comprehensive alternative to create_guild(). See GuildBuilder for details and examples.

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

New in version 2.8.

Parameters:

name (str) – The name of the guild.

Returns:

The guild builder object for configuring and creating a new guild.

Return type:

GuildBuilder

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_gateway_error(event, data, shard_id, exc, /)[source]

This function is a coroutine.

The default gateway 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_gateway_error() for more details.

New in version 2.6.

Note

Unlike on_error(), the exception is available as the exc parameter and cannot be obtained through sys.exc_info().

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 (Union[str, Event]) – The name of the event we want to remove. Defaults to func.__name__.

Raises:

TypeError – The name passed was not a string or an Event.

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, ignore_session_start_limit=False)[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}!')

# using events enums:
@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(Event.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 (Union[str, Event]) – The event name, similar to the event reference, but without the on_ prefix, to wait for. It’s recommended to use Event.

  • 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, *, strip_after_prefix=False, **options)[source]

Similar to Bot, except that it is inherited from disnake.AutoShardedClient instead.

InteractionBot

Attributes
Methods
class disnake.ext.commands.InteractionBot(*, command_sync_flags=None, sync_commands=..., sync_commands_debug=..., sync_commands_on_cog_unload=..., 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.

Parameters:

  • test_guilds (List[int]) –

    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.

  • command_sync_flags (CommandSyncFlags) –

    The command sync flags for the session. This is a way of controlling when and how application commands will be synced with the Discord API. If not given, defaults to CommandSyncFlags.default().

    New in version 2.7.

  • sync_commands (bool) –

    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.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_on_cog_unload (bool) –

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

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_debug (bool) –

    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.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • localization_provider (LocalizationProtocol) –

    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.

  • strict_localization (bool) –

    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.

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

This can be provided as a parameter at creation.

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.

This can be provided as a parameter at creation.

Type:

Optional[Collection[int]]

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

This can be provided as a parameter at creation.

New in version 2.1.

Type:

bool

i18n

An implementation of LocalizationProtocol used for localization of application commands.

New in version 2.5.

Type:

LocalizationProtocol

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

  • nsfw (bool) –

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

    New in version 2.8.

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

  • nsfw (bool) –

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

    New in version 2.8.

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

  • nsfw (bool) –

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

    New in version 2.8.

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

# in yet another file
@bot.listen(Event.message)
async def another_message(message):
    print('three')

Would print one, two and three in an unspecified order.

Raises:

TypeError – The function being listened to is not a coroutine or a string or an Event was not passed as the name.

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 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 (Union[str, Event]) – The name of the event to listen for. Defaults to func.__name__.

Example

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

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')
bot.add_listener(another_message, Event.message)
Raises:

TypeError – The function is not a coroutine or a string or an Event was not passed as the name.

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.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

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:

TypeError – 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 command_sync_flags[source]

The command sync flags configured for this bot.

New in version 2.7.

Type:

CommandSyncFlags

await connect(*, reconnect=True, ignore_session_start_limit=False)[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.

Changed in version 2.6: Added usage of SessionStartLimit when connecting to the API. Added the ignore_session_start_limit parameter.

Parameters:

  • reconnect (bool) – Whether reconnecting should be attempted, 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).

  • ignore_session_start_limit (bool) –

    Whether the API provided session start limit should be ignored when connecting to the API.

    New in version 2.6.

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.

  • SessionStartLimitReached – If the client doesn’t have enough connects remaining in the current 24-hour window and ignore_session_start_limit is False this will be raised rather than connecting to the gateawy and Discord resetting the token. However, if ignore_session_start_limit is True, the client will connect regardless and this exception will not be raised.

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.

See guild_builder() for a more comprehensive alternative.

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

Changed in version 2.5: Removed the region parameter.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

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]

await edit_role_connection_metadata(records)[source]

This function is a coroutine.

Edits the ApplicationRoleConnectionMetadata records for the application.

An application can have up to 5 metadata records.

Warning

This will overwrite all existing metadata records. Consider fetching them first, and constructing the new list of metadata records based off of the returned list.

New in version 2.8.

Parameters:

records (Sequence[ApplicationRoleConnectionMetadata]) – The new metadata records.

Raises:

HTTPException – Editing the metadata records failed.

Returns:

The list of newly edited metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

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

This function is a coroutine.

Retrieves the ApplicationRoleConnectionMetadata records for the application.

New in version 2.8.

Raises:

HTTPException – Retrieving the metadata records failed.

Returns:

The list of metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

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

Mapping[str, List[Callable]]: A read-only mapping of event names to listeners.

Note

To add or remove a listener you should use add_listener() and remove_listener().

New in version 2.9.

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.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[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.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

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

guild_builder(name)[source]

Creates a builder object that can be used to create more complex guilds.

This is a more comprehensive alternative to create_guild(). See GuildBuilder for details and examples.

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

New in version 2.8.

Parameters:

name (str) – The name of the guild.

Returns:

The guild builder object for configuring and creating a new guild.

Return type:

GuildBuilder

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_gateway_error(event, data, shard_id, exc, /)[source]

This function is a coroutine.

The default gateway 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_gateway_error() for more details.

New in version 2.6.

Note

Unlike on_error(), the exception is available as the exc parameter and cannot be obtained through sys.exc_info().

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 (Union[str, Event]) – The name of the event we want to remove. Defaults to func.__name__.

Raises:

TypeError – The name passed was not a string or an Event.

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, ignore_session_start_limit=False)[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}!')

# using events enums:
@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(Event.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 (Union[str, Event]) – The event name, similar to the event reference, but without the on_ prefix, to wait for. It’s recommended to use Event.

  • 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(*, command_sync_flags=None, sync_commands=..., sync_commands_debug=..., sync_commands_on_cog_unload=..., test_guilds=None, **options)[source]

Similar to InteractionBot, except that it is inherited from disnake.AutoShardedClient instead.

Command Sync

CommandSyncFlags

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

Controls the library’s application command syncing policy.

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

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

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

New in version 2.7.

x == y

Checks if two CommandSyncFlags instances are equal.

x != y

Checks if two CommandSyncFlags instances are not equal.

x <= y

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

x >= y

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

x < y

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

x > y

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

x | y, x |= y

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

x & y, x &= y

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

x ^ y, x ^= y

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

~x

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

hash(x)

Return the flag’s hash.

iter(x)

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

Additionally supported are a few operations on class attributes.

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

Returns a CommandSyncFlags instance with all provided flags enabled.

~CommandSyncFlags.y

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

value

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

Type:

int

classmethod all()[source]

A factory method that creates a CommandSyncFlags with everything enabled.

classmethod none()[source]

A factory method that creates a CommandSyncFlags with everything disabled.

classmethod default()[source]

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

The default is all flags enabled except for sync_commands_debug.

sync_commands

Whether to sync global and guild app commands.

This controls the sync_global_commands and sync_guild_commands attributes.

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

Type:

bool

sync_commands_debug

Whether or not to show app command sync debug messages.

Type:

bool

sync_on_cog_actions

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

Type:

bool

allow_command_deletion

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

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

Type:

bool

sync_global_commands

Whether to sync global commands.

Type:

bool

sync_guild_commands

Whether to sync per-guild commands.

Type:

bool

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, nsfw=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.

  • nsfw (bool) –

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

    New in version 2.8.

  • 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, nsfw=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.

  • nsfw (bool) –

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

    New in version 2.8.

  • 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, nsfw=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.

  • nsfw (bool) –

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

    New in version 2.8.

  • 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, min_length=None, max_length=None, **kwargs)[source]

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

See Parameters for more info.

Parameters:

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

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

  • min_length (int) –

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

    New in version 2.6.

  • max_length (int) –

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

    New in version 2.6.

Raises:

TypeError – Unexpected keyword arguments were provided.

Returns:

An instance with the option info.

Note

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

Return type:

ParamInfo

disnake.ext.commands.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.converter_method(function)[source]

A decorator to register a method as the converter method.

New in version 2.3.

Application Command

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

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

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

The following classes implement this ABC:

name

The name of the command.

Type:

str

qualified_name

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

Type:

str

body

An object being registered in the API.

Type:

ApplicationCommand

callback[source]

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

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

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

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

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

name

The name of the command.

Type:

str

qualified_name

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

Type:

str

body

An object being registered in the API.

Type:

SlashCommand

callback[source]

The coroutine 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]

parent

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

New in version 2.6.

Type:

None

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

A decorator that creates a subcommand under the base command.

Parameters:

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

property root_parent[source]

This is for consistency with SubCommand and SubCommandGroup.

New in version 2.6.

Type:

None

property parents[source]

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

New in version 2.6.

Type:

Tuple[()]

autocomplete(option_name)[source]

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

Parameters:

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

Slash Subcommand

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

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

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

name

The name of the subcommand.

Type:

str

qualified_name

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

Type:

str

parent

The parent command or group this subcommand belongs to.

New in version 2.6.

Type:

Union[InvokableSlashCommand, SubCommandGroup]

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.

property root_parent[source]

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

New in version 2.6.

Type:

InvokableSlashCommand

property parents[source]

Union[Tuple[InvokableSlashCommand], Tuple[SubCommandGroup, InvokableSlashCommand]]: Returns all parents of this subcommand.

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

New in version 2.6.

autocomplete(option_name)[source]

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

Parameters:

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

Slash Subcommand Group

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

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

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

name

The name of the group.

Type:

str

qualified_name

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

Type:

str

parent

The parent command this group belongs to.

New in version 2.6.

Type:

InvokableSlashCommand

option

API representation of this subcommand.

Type:

Option

callback[source]

The coroutine 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.

property ro