Contents:

discord_slash.client module¶

class discord_slash.client.SlashCommand(client: Union[discord.client.Client, discord.ext.commands.bot.Bot], sync_commands: bool = False, debug_guild: Optional[int] = None, delete_from_unused_guilds: bool = False, sync_on_cog_reload: bool = False, override_type: bool = False, application_id: Optional[int] = None)¶

Bases: object

Slash command handler class.

Parameters

client (Union[discord.Client, discord.ext.commands.Bot]) – discord.py Client or Bot instance.
sync_commands (bool) – Whether to sync commands automatically. Default False.
debug_guild (int) – Guild ID of guild to use for testing commands. Prevents setting global commands in favor of guild commands, which update instantly
delete_from_unused_guilds (bool) – If the bot should make a request to set no commands for guilds that haven’t got any commands registered in :class:SlashCommand. Default False.
sync_on_cog_reload (bool) – Whether to sync commands on cog reload. Default False.
override_type (bool) – Whether to override checking type of the client and try register event.
application_id (int) – The application id of the bot, required only when the application id and bot id are different. (old bots)

Note

If sync_on_cog_reload is enabled, command syncing will be triggered when discord.ext.commands.Bot.reload_extension() is triggered.

Variables

_discord – Discord client of this client.
commands – Dictionary of the registered commands via slash() decorator.
menu_commands – Dictionary of the registered context menus via the context_menu() decorator.
req – http.SlashCommandRequest of this client.
logger – Logger of this client.
sync_commands – Whether to sync commands automatically.
sync_on_cog_reload – Whether to sync commands on cog reload.
has_listener – Whether discord client has listener add function.

get_cog_commands(cog: discord.ext.commands.cog.Cog)¶

Gets slash command from discord.ext.commands.Cog.

Note

Since version 1.0.9, this gets called automatically during cog initialization.

Parameters: cog (discord.ext.commands.Cog) – Cog that has slash commands.

remove_cog_commands(cog)¶

Removes slash command from discord.ext.commands.Cog.

Note

Since version 1.0.9, this gets called automatically during cog de-initialization.

Parameters: cog (discord.ext.commands.Cog) – Cog that has slash commands.

async to_dict()¶

Converts all commands currently registered to SlashCommand to a dictionary. Returns a dictionary in the format:

{
    "global" : [], # list of global commands
    "guild" : {
        0000: [] # list of commands in the guild 0000
    }
}

Commands are in the format specified by discord here

async sync_all_commands(delete_from_unused_guilds=False, delete_perms_from_unused_guilds=False)¶

Matches commands registered on Discord to commands registered here. Deletes any commands on Discord but not here, and registers any not on Discord. This is done with a put request. A PUT request will only be made if there are changes detected. If sync_commands is True, then this will be automatically called.

Parameters

delete_from_unused_guilds – If the bot should make a request to set no commands for guilds that haven’t got any commands registered in :class:SlashCommand
delete_perms_from_unused_guilds – If the bot should make a request to clear permissions for guilds that haven’t got any permissions registered in :class:SlashCommand

add_slash_command(cmd, name: Optional[str] = None, description: Optional[str] = None, guild_ids: Optional[List[int]] = None, options: Optional[list] = None, default_permission: bool = True, permissions: Optional[Dict[int, list]] = None, connector: Optional[dict] = None, has_subcommands: bool = False)¶

Registers slash command to SlashCommand.

Warning

Just using this won’t register slash command to Discord API. To register it, check utils.manage_commands.add_slash_command() or simply enable sync_commands.

Parameters

cmd (Coroutine) – Command Coroutine.
name (str) – Name of the slash command. Default name of the coroutine.
description (str) – Description of the slash command. Defaults to command docstring or None.
guild_ids (List[int]) – List of Guild ID of where the command will be used. Default None, which will be global command.
options (list) – Options of the slash command. This will affect auto_convert and command data at Discord API. Default None.
default_permission (bool) – Sets if users have permission to run slash command by default, when no permissions are set. Default True.
permissions (dict) – Dictionary of permissions of the slash command. Key being target guild_id and value being a list of permissions to apply. Default None.
connector (dict) – Kwargs connector for the command. Default None.
has_subcommands (bool) – Whether it has subcommand. Default False.

add_context_menu(cmd, name: str, _type: int, guild_ids: Optional[list] = None)¶

Creates a new context menu command.

Parameters

cmd (Coroutine) – Command Coroutine.
name (str) – The name of the command
_type (int) – The context menu type.

add_subcommand(cmd, base, subcommand_group=None, name=None, description: Optional[str] = None, base_description: Optional[str] = None, base_default_permission: bool = True, base_permissions: Optional[Dict[int, list]] = None, subcommand_group_description: Optional[str] = None, guild_ids: Optional[List[int]] = None, options: Optional[list] = None, connector: Optional[dict] = None)¶

Registers subcommand to SlashCommand.

Parameters

cmd (Coroutine) – Subcommand Coroutine.
base (str) – Name of the base command.
subcommand_group (str) – Name of the subcommand group, if any. Default None which represents there is no sub group.
name (str) – Name of the subcommand. Default name of the coroutine.
description (str) – Description of the subcommand. Defaults to command docstring or None.
base_description (str) – Description of the base command. Default None.
base_default_permission (bool) – Sets if users have permission to run base command by default, when no permissions are set. Default True.
base_permissions (dict) – Dictionary of permissions of the slash command. Key being target guild_id and value being a list of permissions to apply. Default None.
subcommand_group_description (str) – Description of the subcommand_group. Default None.
guild_ids (List[int]) – List of guild ID of where the command will be used. Default None, which will be global command.
options (list) – Options of the subcommand. This will affect auto_convert and command data at Discord API. Default None.
connector (dict) – Kwargs connector for the command. Default None.

slash(*, name: Optional[str] = None, description: Optional[str] = None, guild_ids: Optional[List[int]] = None, options: Optional[List[dict]] = None, default_permission: bool = True, permissions: Optional[dict] = None, connector: Optional[dict] = None)¶

Decorator that registers coroutine as a slash command.

All decorator args must be passed as keyword-only args.

1 arg for command coroutine is required for ctx(model.SlashContext), and if your slash command has some args, then those args are also required.

All args must be passed as keyword-args.

Note

If you don’t pass options but has extra args, then it will automatically generate options. However, it is not recommended to use it since descriptions will be “No Description.” or the command’s description.

Warning

Unlike discord.py’s command, *args, keyword-only args, converters, etc. are not supported or behave differently.

Example:

@slash.slash(name="ping")
async def _slash(ctx): # Normal usage.
    await ctx.send(content=f"Pong! (`{round(bot.latency*1000)}`ms)")


@slash.slash(name="pick")
async def _pick(ctx, choice1, choice2): # Command with 1 or more args.
    await ctx.send(content=str(random.choice([choice1, choice2])))

To format the connector, follow this example.

{
    "example-arg": "example_arg",
    "시간": "hour"
    # Formatting connector is required for
    # using other than english for option parameter name
    # for in case.
}

Set discord UI’s parameter name as key, and set command coroutine’s arg name as value.

Parameters

name (str) – Name of the slash command. Default name of the coroutine.
description (str) – Description of the slash command. Default None.
guild_ids (List[int]) – List of Guild ID of where the command will be used. Default None, which will be global command.
options (List[dict]) – Options of the slash command. This will affect auto_convert and command data at Discord API. Default None.
default_permission (bool) – Sets if users have permission to run slash command by default, when no permissions are set. Default True.
permissions (dict) – Permission requirements of the slash command. Default None.
connector (dict) – Kwargs connector for the command. Default None.

subcommand(*, base, subcommand_group=None, name=None, description: Optional[str] = None, base_description: Optional[str] = None, base_desc: Optional[str] = None, base_default_permission: bool = True, base_permissions: Optional[dict] = None, subcommand_group_description: Optional[str] = None, sub_group_desc: Optional[str] = None, guild_ids: Optional[List[int]] = None, options: Optional[List[dict]] = None, connector: Optional[dict] = None)¶

Decorator that registers subcommand.

Unlike discord.py, you don’t need base command.

All args must be passed as keyword-args.

Note

Warning

Unlike discord.py’s command, *args, keyword-only args, converters, etc. are not supported or behave differently.

Example:

# /group say <str>
@slash.subcommand(base="group", name="say")
async def _group_say(ctx, _str):
    await ctx.send(content=_str)

# /group kick user <user>
@slash.subcommand(base="group",
                  subcommand_group="kick",
                  name="user")
async def _group_kick_user(ctx, user):
    ...

Parameters

base (str) – Name of the base command.
subcommand_group (str) – Name of the subcommand group, if any. Default None which represents there is no sub group.
name (str) – Name of the subcommand. Default name of the coroutine.
description (str) – Description of the subcommand. Default None.
base_description (str) – Description of the base command. Default None.
base_desc – Alias of base_description.
base_default_permission (bool) – Sets if users have permission to run slash command by default, when no permissions are set. Default True.
permissions (dict) – Permission requirements of the slash command. Default None.
subcommand_group_description (str) – Description of the subcommand_group. Default None.
sub_group_desc – Alias of subcommand_group_description.
guild_ids (List[int]) – List of guild ID of where the command will be used. Default None, which will be global command.
options (List[dict]) – Options of the subcommand. This will affect auto_convert and command data at Discord API. Default None.
connector (dict) – Kwargs connector for the command. Default None.

permission(guild_id: int, permissions: list)¶

Decorator that add permissions. This will set the permissions for a single guild, you can use it more than once for each command.

Parameters

guild_id (int) – ID of the guild for the permissions.
permissions (list) – List of permissions to be set for the specified guild.

context_menu(*, target: int, name: str, guild_ids: Optional[list] = None)¶

Decorator that adds context menu commands.

Parameters

target (int) – The type of menu.
name (str) – A name to register as the command in the menu.
guild_ids (list) – A list of guild IDs to register the command under. Defaults to None.

add_component_callback(callback: Coroutine, *, messages: Optional[Union[int, discord.message.Message, list]] = None, components: Optional[Union[str, dict, list]] = None, use_callback_name=True, component_type: Optional[int] = None)¶

Adds a coroutine callback to a component. Callback can be made to only accept component interactions from a specific messages and/or custom_ids of components.

Parameters

callback (Coroutine) – The coroutine to be called when the component is interacted with. Must accept a single argument with the type context.ComponentContext.
messages (Union[discord.Message, int, list]) – If specified, only interactions from the message given will be accepted. Can be a message object to check for, or the message ID or list of previous two. Empty list will mean that no interactions are accepted.
components (Union[str, dict, list]) – If specified, only interactions with custom_id of given components will be accepted. Defaults to the name of callback if use_callback_name=True. Can be a custom ID (str) or component dict (actionrow or button) or list of previous two.
use_callback_name (bool) – Whether the custom_id defaults to the name of callback if unspecified. If False, either messages or components must be specified.
component_type (Optional[int]) – The type of the component to avoid collisions with other component types. See model.ComponentType.

Raises

.error.DuplicateCustomID, .error.IncorrectFormat

extend_component_callback(callback_obj: discord_slash.model.ComponentCallbackObject, message_id: Optional[int] = None, custom_id: Optional[str] = None)¶

Registers existing callback object (model.ComponentCallbackObject) for specific combination of message_id, custom_id, component_type.

Parameters

callback_obj (model.ComponentCallbackObject) – callback object.
message_id (Optional[.model]) – If specified, only removes the callback for the specific message ID.
custom_id (Optional[str]) – The custom_id of the component.

Raises

.error.DuplicateCustomID, .error.IncorrectFormat

get_component_callback(message_id: Optional[int] = None, custom_id: Optional[str] = None, component_type: Optional[int] = None)¶

Returns component callback (or None if not found) for specific combination of message_id, custom_id, component_type.

Parameters

message_id (Optional[.model]) – If specified, only removes the callback for the specific message ID.
custom_id (Optional[str]) – The custom_id of the component.
component_type (Optional[int]) – The type of the component. See model.ComponentType.

Returns

Optional[model.ComponentCallbackObject]

remove_component_callback(message_id: Optional[int] = None, custom_id: Optional[str] = None, component_type: Optional[int] = None)¶

Removes a component callback from specific combination of message_id, custom_id, component_type.

Parameters

message_id (Optional[int]) – If specified, only removes the callback for the specific message ID.
custom_id (Optional[str]) – The custom_id of the component.
component_type (Optional[int]) – The type of the component. See model.ComponentType.

Raises

.error.IncorrectFormat

remove_component_callback_obj(callback_obj: discord_slash.model.ComponentCallbackObject)¶

Removes a component callback from all related message_id, custom_id listeners.

Parameters: callback_obj (model.ComponentCallbackObject) – callback object.
Raises: .error.IncorrectFormat

component_callback(*, messages: Optional[Union[int, discord.message.Message, list]] = None, components: Optional[Union[str, dict, list]] = None, use_callback_name=True, component_type: Optional[int] = None)¶

Decorator that registers a coroutine as a component callback. Adds a coroutine callback to a component. Callback can be made to only accept component interactions from a specific messages and/or custom_ids of components.

Parameters

messages (Union[discord.Message, int, list]) – If specified, only interactions from the message given will be accepted. Can be a message object to check for, or the message ID or list of previous two. Empty list will mean that no interactions are accepted.
components (Union[str, dict, list]) – If specified, only interactions with custom_id of given components will be accepted. Defaults to the name of callback if use_callback_name=True. Can be a custom ID (str) or component dict (actionrow or button) or list of previous two.
use_callback_name (bool) – Whether the custom_id defaults to the name of callback if unspecified. If False, either messages or components must be specified.
component_type (Optional[int]) – The type of the component to avoid collisions with other component types. See model.ComponentType.

Raises

.error.DuplicateCustomID, .error.IncorrectFormat

async process_options(guild: discord.guild.Guild, options: list, connector: dict, temporary_auto_convert: Optional[dict] = None) → dict¶

Processes Role, User, and Channel option types to discord.py’s models.

Parameters

guild (discord.Guild) – Guild of the command message.
options (list) – Dict of options.
connector – Kwarg connector.
temporary_auto_convert – Temporary parameter, use this if options doesn’t have type keyword.

Returns

Union[list, dict]

async invoke_command(func, ctx, args)¶

Invokes command.

Parameters

func – Command coroutine.
ctx – Context.
args – Args. Can be list or dict.

async invoke_component_callback(func, ctx)¶

Invokes component callback.

Parameters

func – Component callback object.
ctx – Context.

async on_socket_response(msg)¶

This event listener is automatically registered at initialization of this class.

Warning

DO NOT MANUALLY REGISTER, OVERRIDE, OR WHATEVER ACTION TO THIS COROUTINE UNLESS YOU KNOW WHAT YOU ARE DOING.

Parameters: msg – Gateway message.

async handle_subcommand(ctx: discord_slash.context.SlashContext, data: dict)¶

Coroutine for handling subcommand.

Warning

Do not manually call this.

Parameters

ctx – model.SlashContext instance.
data – Gateway message.

async on_slash_command_error(ctx, ex)¶

Handles Exception occurred from invoking command.

Example of adding event:

@client.event
async def on_slash_command_error(ctx, ex):
    ...

Example of adding listener:

@bot.listen()
async def on_slash_command_error(ctx, ex):
    ...

Parameters

ctx (model.SlashContext) – Context of the command.
ex (Exception) – Exception from the command invoke.

Returns

async on_component_callback_error(ctx, ex)¶

Handles Exception occurred from invoking component callback.

Example of adding event:

@client.event
async def on_component_callback_error(ctx, ex):
    ...

Example of adding listener:

@bot.listen()
async def on_component_callback_error(ctx, ex):
    ...

Parameters

ctx (model.ComponentContext) – Context of the callback.
ex (Exception) – Exception from the command invoke.

Returns