Commands¶

discord_http.commands module¶

class discord_http.commands.Choice(key, value)¶

Bases: Generic[ChoiceT]

Makes it possible to access both the name and value of a choice.

Defaults to a string type

Paramaters¶

key:: The key of the choice from your dict.
value:: The value of your choice (the one that is shown to public)

key: ChoiceT¶: The key of the choice (the internal value sent to the command).

value: ChoiceT¶: The value of the choice (the label shown to the user).

type: CommandOptionType¶: The option type of the choice, inferred from the key type.

Parameters:

key (ChoiceT)
value (ChoiceT)

class discord_http.commands.Cog(*args, **kwargs)¶

Bases: object

Represents a cog, a collection of commands, listeners, and interactions.

async cog_load() → None¶

Called before the cog is loaded.

Return type:: None

async cog_unload() → None¶

Called before the cog is unloaded.

Return type:: None

class discord_http.commands.Command(command, name, description=None, guild_ids=None, guild_install=True, user_install=False, cmd_type=ApplicationCommandType.chat_input, parent=None)¶

Bases: object

Represents a Discord command.

Parameters:

command (Callable)
name (str)
description (str | None)
guild_ids (list[Snowflake | int] | None)
guild_install (bool)
user_install (bool)
cmd_type (ApplicationCommandType)
parent (SubGroup | None)

id: int | None¶: The ID of the command, None if it’s not registered yet.

command: Callable¶: The function that is called when the command is invoked.

cog: Cog | None¶: The cog this command belongs to, None if it does not belong to a cog.

type: int¶: The type of the command, either 1 for chat input, 2 for user context menu, or 3 for message context menu.

name: str¶: The name of the command.

parent: SubGroup | None¶: The parent subcommand group of this command, if it is a subcommand.

guild_install: bool¶: Whether this command should be installed in guilds or not.

user_install: bool¶: Whether this command should be installed for users or not.

list_autocompletes: dict[str, Callable]¶: A mapping of option names to their autocomplete functions.

guild_ids: list[Snowflake | int]¶: A list of guild IDs this command is in, empty if it’s a global command.

cooldown: CooldownCache | None¶: The cooldown rule of the command, if any.

description: str | None¶: The description of the command, only applicable for chat input commands.

options: list[dict]¶: The options of the command, only applicable for chat input commands.

property mention: str¶: A mentionable string for the command.

mention_sub(suffix) → str¶

Returns a mentionable string for a subcommand.

Parameters:: suffix (str) – The subcommand name.
Return type:: str
Returns:: The mentionable string.

async run(context, *args, **kwargs) → BaseResponse¶

Runs the command.

Parameters:

context (Context) – The context of the command.
*args – The arguments of the command.
**kwargs – The keyword arguments of the command.

Return type:

BaseResponse

Returns:

The return type of the command, used by backend.py

Raises:

UserMissingPermissions – User that ran the command is missing permissions.
BotMissingPermissions – Bot is missing permissions.

async run_autocomplete(context, name, current) → dict¶

Runs the autocomplete.

Parameters:

context (Context) – Context object for the command
name (str) – Name of the option
current (str) – Current value of the option

Return type:

dict

Returns:

The return type of the command, used by backend.py

Raises:

TypeError – Autocomplete must return an AutocompleteResponse object

to_dict() → dict¶

Converts the Discord command to a dict.

Return type:: dict

autocomplete(name) → Callable[[Callable], Callable]¶

Decorator to set an option as an autocomplete.

The function must at the end, return a Response.send_autocomplete() object.

Example usage

@commands.command()
async def ping(ctx, options: str):
    return ctx.response.send_message(f"You chose {options}")

@ping.autocomplete("options")
async def search_autocomplete(ctx, current: str):
    return ctx.response.send_autocomplete({
        "key": "Value shown to user",
        "feeling_lucky_tm": "I'm feeling lucky!"
    })

Parameters:: name (str) – Name of the option to set as an autocomplete.
Return type:: Callable[[Callable], Callable]

class discord_http.commands.Converter(*args, **kwargs)¶

Bases: Protocol[ConverterT]

The base class of converting strings to whatever you desire.

Instead of needing to implement checks inside the command, you can use this to convert the value on runtime, both in sync and async mode.

async convert(ctx, value) → ConverterT¶

The function where you implement the logic of converting the value into whatever you need to be outputted in command.

Parameters:

ctx (Context) – Context of the bot
value (str) – The value returned by the argument in command

Return type:

TypeVar(ConverterT, covariant=True)

Returns:

Your converted value

class discord_http.commands.Interaction(func, custom_id, *, regex=False)¶

Bases: object

Represents a Discord interaction, usually from a component or modal.

Parameters:

func (Callable)
custom_id (str)
regex (bool)

func: Callable¶: The function that is called when the interaction is invoked.

custom_id: str¶: The custom ID of the interaction, used to match with incoming interactions.

regex: bool¶: Whether the custom ID is a regex pattern or not.

cog: Cog | None¶: The cog this interaction belongs to, None if it does not belong to a cog.

match(custom_id) → bool¶

Matches the custom ID with the interaction.

Will always return False if the interaction is not a regex.

Parameters:: custom_id (str) – The custom ID to match.
Return type:: bool
Returns:: Whether the custom ID matched or not.

async run(context) → BaseResponse¶

Runs the interaction.

Parameters:: context (Context) – The context of the interaction.
Return type:: BaseResponse
Returns:: The return type of the interaction, used by backend.py
Raises:: TypeError – Interaction must be a Response object

class discord_http.commands.Listener(*, name, coro)¶

Bases: object

Represents a Discord event listener.

Parameters:

name (str)
coro (Callable)

name: str¶: The name of the event to listen to, e.g. “on_message_create”.

coro: Callable¶: The coroutine function that is called when the event is triggered.

cog: Cog | None¶: The cog this listener belongs to, None if it does not belong to a cog.

async run(*args, **kwargs) → None¶

Runs the listener.

Return type:: None

class discord_http.commands.LocaleContainer(key, name, description=None)¶

Bases: object

Represents a container for localized names and descriptions.

Parameters:

key (str)
name (str)
description (str | None)

key: str¶: The key of the option this localization is for, or “_” for the command itself.

name: str¶: The localized name.

description: str¶: The localized description.

class discord_http.commands.PartialCommand(data)¶

Bases: PartialBase

Represents a partial command, usually from an event.

Parameters:: data (dict)

name: str¶: The name of the command.

guild_id: int | None¶: The ID of the guild this command is in, or None if it’s a global command.

property created_at: datetime¶: The datetime of the snowflake.

id: int¶: The ID of the snowflake.

discord_http.commands.Range¶: alias of Annotated

class discord_http.commands.SubCommand(func, *, name, description=None, guild_install=True, user_install=False, guild_ids=None, parent=None)¶

Bases: Command

Represents a subcommand, a command that is part of a subcommand group.

Parameters:

func (Callable)
name (str)
description (str | None)
guild_install (bool)
user_install (bool)
guild_ids (list[Snowflake | int] | None)
parent (SubGroup | None )

autocomplete(name) → Callable[[Callable], Callable]¶

Decorator to set an option as an autocomplete.

The function must at the end, return a Response.send_autocomplete() object.

Example usage

@commands.command()
async def ping(ctx, options: str):
    return ctx.response.send_message(f"You chose {options}")

@ping.autocomplete("options")
async def search_autocomplete(ctx, current: str):
    return ctx.response.send_autocomplete({
        "key": "Value shown to user",
        "feeling_lucky_tm": "I'm feeling lucky!"
    })

Parameters:: name (str) – Name of the option to set as an autocomplete.
Return type:: Callable[[Callable], Callable]

property mention: str¶: A mentionable string for the command.

mention_sub(suffix) → str¶

Returns a mentionable string for a subcommand.

Parameters:: suffix (str) – The subcommand name.
Return type:: str
Returns:: The mentionable string.

async run(context, *args, **kwargs) → BaseResponse¶

Runs the command.

Parameters:

context (Context) – The context of the command.
*args – The arguments of the command.
**kwargs – The keyword arguments of the command.

Return type:

BaseResponse

Returns:

The return type of the command, used by backend.py

Raises:

UserMissingPermissions – User that ran the command is missing permissions.
BotMissingPermissions – Bot is missing permissions.

async run_autocomplete(context, name, current) → dict¶

Runs the autocomplete.

Parameters:

context (Context) – Context object for the command
name (str) – Name of the option
current (str) – Current value of the option

Return type:

dict

Returns:

The return type of the command, used by backend.py

Raises:

TypeError – Autocomplete must return an AutocompleteResponse object

to_dict() → dict¶

Converts the Discord command to a dict.

Return type:: dict

id: int | None¶: The ID of the command, None if it’s not registered yet.

command: Callable¶: The function that is called when the command is invoked.

cog: Cog | None¶: The cog this command belongs to, None if it does not belong to a cog.

type: int¶: The type of the command, either 1 for chat input, 2 for user context menu, or 3 for message context menu.

name: str¶: The name of the command.

description: str | None¶: The description of the command, only applicable for chat input commands.

options: list[dict]¶: The options of the command, only applicable for chat input commands.

parent: SubGroup | None¶: The parent subcommand group of this command, if it is a subcommand.

guild_install: bool¶: Whether this command should be installed in guilds or not.

user_install: bool¶: Whether this command should be installed for users or not.

list_autocompletes: dict[str, Callable]¶: A mapping of option names to their autocomplete functions.

guild_ids: list[Snowflake | int]¶: A list of guild IDs this command is in, empty if it’s a global command.

cooldown: CooldownCache | None¶: The cooldown rule of the command, if any.

class discord_http.commands.SubGroup(*, name, description=None, guild_ids=None, guild_install=True, user_install=False, parent=None)¶

Bases: Command

Represents a subcommand group, a collection of subcommands.

Parameters:

name (str)
description (str | None)
guild_ids (list[Snowflake | int] | None)
guild_install (bool)
user_install (bool)
parent (SubGroup | None)

name: str¶: The name of the subcommand group.

description: str¶: The description of the subcommand group.

guild_ids: list[Snowflake | int]¶: A list of guild IDs this subcommand group is in, empty if it’s a global subcommand group.

type: int¶: The type of the subcommand group, always 1 (chat input).

cog: Cog | None¶: The cog this subcommand group belongs to, None if it does not belong to a cog.

subcommands: dict[str, SubCommand | SubGroup]¶: A mapping of subcommand names to their respective SubCommand or SubGroup objects.

guild_install: bool¶: Whether this subcommand group should be installed in guilds or not.

user_install: bool¶: Whether this subcommand group should be installed for users or not.

parent: SubGroup | None¶: The parent subcommand group of this subcommand group, if it is a nested subcommand group.

cooldown: CooldownCache | None¶: The cooldown of this subcommand group, if any.

command(name=None, *, description=None, guild_ids=None, guild_install=True, user_install=False) → Callable[[Callable], SubCommand]¶

Decorator to add a subcommand to a subcommand group.

Parameters:

name (str | None) – Name of the command (defaults to the function name)
description (str | None) – Description of the command (defaults to the function docstring)
guild_ids (list[Snowflake | int] | None) – List of guild IDs to register the command in
user_install (bool) – Whether the command can be installed by users or not
guild_install (bool) – Whether the command can be installed by guilds or not

Return type:

Callable[[Callable], SubCommand]

group(name=None, *, description=None) → Callable[[Callable], SubGroup]¶

Decorator to add a subcommand group to a subcommand group.

Parameters:

name (str | None) – Name of the subcommand group (defaults to the function name)
description (str | None) – Description of the subcommand group (defaults to the function docstring)

Return type:

Callable[[Callable], SubGroup]

add_group(name) → SubGroup¶

Adds a subcommand group to a subcommand group.

Parameters:: name (str) – Name of the subcommand group
Return type:: SubGroup
Returns:: The subcommand group

property options: list[dict]¶: The options of the subcommand group.

autocomplete(name) → Callable[[Callable], Callable]¶

Decorator to set an option as an autocomplete.

The function must at the end, return a Response.send_autocomplete() object.

Example usage

@commands.command()
async def ping(ctx, options: str):
    return ctx.response.send_message(f"You chose {options}")

@ping.autocomplete("options")
async def search_autocomplete(ctx, current: str):
    return ctx.response.send_autocomplete({
        "key": "Value shown to user",
        "feeling_lucky_tm": "I'm feeling lucky!"
    })

Parameters:: name (str) – Name of the option to set as an autocomplete.
Return type:: Callable[[Callable], Callable]

property mention: str¶: A mentionable string for the command.

mention_sub(suffix) → str¶

Returns a mentionable string for a subcommand.

Parameters:: suffix (str) – The subcommand name.
Return type:: str
Returns:: The mentionable string.

async run(context, *args, **kwargs) → BaseResponse¶

Runs the command.

Parameters:

context (Context) – The context of the command.
*args – The arguments of the command.
**kwargs – The keyword arguments of the command.

Return type:

BaseResponse

Returns:

The return type of the command, used by backend.py

Raises:

UserMissingPermissions – User that ran the command is missing permissions.
BotMissingPermissions – Bot is missing permissions.

async run_autocomplete(context, name, current) → dict¶

Runs the autocomplete.

Parameters:

context (Context) – Context object for the command
name (str) – Name of the option
current (str) – Current value of the option

Return type:

dict

Returns:

The return type of the command, used by backend.py

Raises:

TypeError – Autocomplete must return an AutocompleteResponse object

to_dict() → dict¶

Converts the Discord command to a dict.

Return type:: dict

id: int | None¶: The ID of the command, None if it’s not registered yet.

list_autocompletes: dict[str, Callable]¶: A mapping of option names to their autocomplete functions.

Commands decorators¶

discord_http.commands.command(name=None, *, description=None, guild_ids=None, guild_install=True, user_install=False) → Callable[[Callable], Command]¶

Decorator to register a command.

Parameters:

name (str | None) – Name of the command (defaults to the function name)
description (str | None) – Description of the command (defaults to the function docstring)
guild_ids (list[Snowflake | int] | None) – List of guild IDs to register the command in
user_install (bool) – Whether the command can be installed by users or not
guild_install (bool) – Whether the command can be installed by guilds or not

Return type:

Callable[[Callable], Command]

discord_http.commands.user_command(name=None, *, guild_ids=None, guild_install=True, user_install=False) → Callable[[Callable], Command]¶

Decorator to register a user command.

Example usage

@user_command()
async def content(ctx, user: Union[Member, User]):
    return ctx.response.send_message(f"Target: {user.name}")

Parameters:

name (str | None) – Name of the command (defaults to the function name)
guild_ids (list[Snowflake | int] | None) – List of guild IDs to register the command in
user_install (bool) – Whether the command can be installed by users or not
guild_install (bool) – Whether the command can be installed by guilds or not

Return type:

Callable[[Callable], Command]

discord_http.commands.message_command(name=None, *, guild_ids=None, guild_install=True, user_install=False) → Callable[[Callable], Command]¶

Decorator to register a message command.

Example usage

@message_command()
async def content(ctx, msg: Message):
    return ctx.response.send_message(f"Content: {msg.content}")

Parameters:

name (str | None) – Name of the command (defaults to the function name)
guild_ids (list[Snowflake | int] | None) – List of guild IDs to register the command in
user_install (bool) – Whether the command can be installed by users or not
guild_install (bool) – Whether the command can be installed by guilds or not

Return type:

Callable[[Callable], Command]

discord_http.commands.group(name=None, *, description=None, guild_ids=None, guild_install=True, user_install=False) → Callable[[Callable], SubGroup]¶

Decorator to register a command group.

Parameters:

name (str | None) – Name of the command group (defaults to the function name)
description (str | None) – Description of the command group (defaults to the function docstring)
guild_ids (list[Snowflake | int] | None) – List of guild IDs to register the command group in
user_install (bool) – Whether the command group can be installed by users or not
guild_install (bool) – Whether the command group can be installed by guilds or not

Return type:

Callable[[Callable], SubGroup]

discord_http.commands.locales(translations) → Callable[[Callable], Callable]¶

Decorator to set translations for a command.

_ = Reserved for the root command name and description.

Example usage:

@commands.command(name="ping")
@commands.locales({
    # Norwegian
    "no": {
        "_": ("ping", "Sender en 'pong' melding")
        "funny": ("morsomt", "Morsomt svar")
    }
})
async def ping(ctx, funny: str):
    return ctx.response.send_message(f"pong {funny}")

Parameters:: translations (dict[Literal['id', 'da', 'de', 'en-GB', 'en-US', 'es-ES', 'fr', 'es-419', 'hr', 'it', 'lt', 'hu', 'nl', 'no', 'pl', 'pt-BR', 'ro', 'fi', 'sv-SE', 'vi', 'tr', 'cs', 'el', 'bg', 'ru', 'uk', 'hi', 'th', 'zh-CN', 'ja', 'zh-TW', 'ko'], dict[str, list[str] | tuple[str] | tuple[str, str]]]) – The translations for the command name, description, and options.
Return type:: Callable[[Callable], Callable]

discord_http.commands.describe(**kwargs) → Callable¶

Decorator to set descriptions for a command.

Example usage:

@commands.command()
@commands.describe(user="User to ping")
async def ping(ctx, user: Member):
    return ctx.response.send_message(f"Pinged {user.mention}")

Return type:: Callable
Parameters:: kwargs (str)

discord_http.commands.allow_contexts(*, guild=True, bot_dm=True, private_dm=True) → Callable¶

Decorator to set the places you are allowed to use the command.

Can only be used if the Command has user_install set to True.

Parameters:

guild (bool) – Weather the command can be used in guilds.
bot_dm (bool) – Weather the command can be used in bot DMs.
private_dm (bool) – Weather the command can be used in private DMs.

Return type:

Callable

discord_http.commands.cooldown(rate, per, *, type=None) → Callable[[Callable], Callable]¶

Decorator to set a cooldown for a command.

Example usage

@commands.command()
@commands.cooldown(1, 5.0)
async def ping(ctx):
    return ctx.response.send_message("Pong!")

Parameters:

rate (int) – The number of times the command can be used within the cooldown period
per (float) – The cooldown period in seconds
type (BucketType | None) – The bucket type to use for the cooldown If not set, it will be using default, which is a global cooldown

Return type:

Callable[[Callable], Callable]

discord_http.commands.choices(**kwargs) → Callable¶

Decorator to set choices for a command.

Example usage:

@commands.command()
@commands.choices(
    options={
        "opt1": "Choice 1",
        "opt2": "Choice 2",
        ...
    }
)
async def ping(ctx, options: Choice[str]):
    return ctx.response.send_message(f"You chose {choice.value}")

Return type:: Callable
Parameters:: kwargs (dict[str | int | float, str | int | float])

discord_http.commands.guild_only() → Callable¶

Decorator to set a command as guild only.

This is a alias to two particular functions: - commands.allow_contexts(guild=True, bot_dm=False, private_dm=False) - commands.check(…) (which checks for Context.guild to be available)

Return type:: Callable

discord_http.commands.is_nsfw() → Callable¶

Decorator to set a command as NSFW.

Return type:: Callable

discord_http.commands.default_permissions(*args) → Callable¶

Decorator to set default permissions for a command.

Return type:: Callable
Parameters:: args (Permissions | str)

discord_http.commands.has_permissions(*args) → Callable¶

Decorator to set permissions for a command.

Example usage:

@commands.command()
@commands.has_permissions("manage_messages")
async def ban(ctx, user: Member):
    ...

Return type:: Callable
Parameters:: args (Permissions | str)

discord_http.commands.bot_has_permissions(*args) → Callable¶

Decorator to set permissions for a command.

Example usage:

@commands.command()
@commands.bot_has_permissions("embed_links")
async def cat(ctx):
    ...

Return type:: Callable
Parameters:: args (Permissions | str)

discord_http.commands.check(predicate) → Callable¶

Decorator to set a check for a command.

Example usage:

def is_owner(ctx):
    return ctx.author.id == 123456789

@commands.command()
@commands.check(is_owner)
async def foo(ctx):
    ...

Return type:: Callable
Parameters:: predicate (Callable)

discord_http.commands.interaction(custom_id, *, regex=False) → Callable¶

Decorator to register an interaction.

This supports the usage of regex to match multiple custom IDs.

Parameters:

custom_id (str) – The custom ID of the interaction. (can be partial, aka. regex)
regex (bool) – Whether the custom_id is a regex or not

Return type:

Callable

discord_http.commands.listener(name=None) → Callable¶

Decorator to register a listener.

Parameters:

name (str | None) – Name of the listener (defaults to the function name)

Raises:

TypeError –

If name was not a string - If the listener was not a coroutine function

Return type:

Callable