discord_slash.client module

class discord_slash.client.SlashCommand(client: Union[discord.client.Client, discord.ext.commands.bot.Bot], sync_commands: bool = False, 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.

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

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

  • 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

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:

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

  • 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. :param guild_id: ID of the guild for the permissions. :type guild_id: int :param permissions: Permission requirements of the slash command. Default None. :type permissions: dict

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