Options¶
Discord allows Slash Commands to receive a variety of different option types. Each option has a name, description, and type.
To specify options with Flask-Discord-Interactions, you can use type annotations. This syntax should feel familiar to users of Discord.py.
@discord.command(annotations={"message": "The message to repeat"})
def repeat(ctx, message: str = "Hello!"):
"Repeat the message (and escape mentions)"
return Message(
f"{ctx.author.display_name} says {message}!",
allowed_mentions={"parse": []},
)
The annotations parameter is used to provide a description for each option
(they default to “no description”). See DiscordInteractions.command()
for more information about the decorator.
Primitives¶
You can use str, int, float, or bool for string, integer,
number, and boolean options.
@discord.command()
def add_one(ctx, number: int):
return Message(str(number + 1), ephemeral=True)
@discord.command()
def and_gate(ctx, a: bool, b: bool):
return f"{a} AND {b} is {a and b}"
Discord Models¶
For User, Channel, Role and Attachment options, you can receive an object with context information about the option:
@discord.command()
def has_role(ctx, user: Member, role: Role):
if role.id in user.roles:
return f"Yes, user {user.display_name} has role {role.name}."
else:
return f"No, user {user.display_name} does not have role {role.name}."
Choices¶
To specify a list of choices the user can choose from, you can use Python’s
enum.Enum class.
class Animal(enum.Enum):
Dog = "dog"
Cat = "cat"
@discord.command(annotations={"choice": "Your favorite animal"})
def favorite(ctx, choice: Animal):
"What is your favorite animal?"
return f"{ctx.author.display_name} chooses {choice}!"
Note that you can use the same enum in multiple commands if they share the same choices:
@discord.command(annotations={"choice": "The animal you hate the most"})
def hate(ctx, choice: Animal):
"What is the animal you hate the most?"
return f"{ctx.author.display_name} hates {choice}s."
You can also use an enum.IntEnum to receive the value as an integer
instead of a string:
class BigNumber(enum.IntEnum):
thousand = 1_000
million = 1_000_000
billion = 1_000_000_000
trillion = 1_000_000_000_000
@discord.command(annotations={"number": "A big number"})
def big_number(ctx, number: BigNumber):
"Print out a large number"
return f"One more than the number is {number+1}."
Explicit Options¶
If all of this magic doesn’t fit your use case, there’s an escape hatch you can
use to have full control over the data sent to Discord. Pass a list of dict s
or Option objects to the options argument when registering a
command:
@discord.command(
options=[
Option(
name="message", type=str, description="The message to repeat", required=True
),
Option(
name="times",
type=int,
description="How many times to repeat the message",
required=True,
),
]
)
def repeat_many(ctx, message: str, times: int):
return " ".join([message] * times)
Full API¶
- class flask_discord_interactions.Option(name: str, type: int, description: str = 'No description', required: bool = False, options: Optional[list] = None, choices: Optional[list] = None, channel_types: Optional[list] = None, min_value: Optional[int] = None, max_value: Optional[int] = None, min_length: Optional[int] = None, max_length: Optional[int] = None, name_localizations: Optional[dict] = None, description_localizations: Optional[dict] = None, autocomplete: bool = False, value: Optional[Any] = None, focused: Optional[bool] = None)¶
Represents an option provided to a slash command.
- Parameters
name (str) – The name of the option.
name_localizations (Optional[dict]) – A dict of localizations for the name of the option.
type (int) – The type of the option. Provide either a value of
CommandOptionTypeor a type (e.g.str).description (str) – The description of the option. Defaults to “No description.”
description_localizations (Optional[dict]) – A dict of localizations for the description of the option.
required (bool) – Whether the option is required. Defaults to
False.options (Optional[list]) – A list of further options if the option is a subcommand or a subcommand group.
choices (Optional[list]) – A list of choices for the option.
channel_types (Optional[list]) – A list of
ChannelTypefor the option.min_value (Optional[int]) – The minimum value of the option if the option is numeric.
max_value (Optional[int]) – The maximum value of the option if the option is numeric.
min_length (Optional[int]) – Minimum allowed length for string type options.
max_value – Maximum allowed length for string type options.
autocomplete (bool) – Whether the option should be autocompleted. Defaults to
False. Set toTrueif you have an autocomplete handler for this command.value (Any) – Only present on incoming options passed to autocomplete objects. You shouldn’t set this yourself. Represents the value that the user is currently typing.
focused (Optional[bool]) – Only present on incoming options passed to autocomplete objects. True if the user is currently typing this option.
- dump()¶
Return this option as as a dict for registration with Discord.
- Returns
A dict representing this option.
- Return type
- class flask_discord_interactions.CommandOptionType¶
Represents the different option type integers.
- SUB_COMMAND = 1¶
- SUB_COMMAND_GROUP = 2¶
- STRING = 3¶
- INTEGER = 4¶
- BOOLEAN = 5¶
- USER = 6¶
- CHANNEL = 7¶
- ROLE = 8¶
- MENTIONABLE = 9¶
- NUMBER = 10¶
- ATTACHMENT = 11¶
- class flask_discord_interactions.Channel(**kwargs)¶
Represents a Channel in Discord. This includes voice channels, text channels, and channel categories.
- class flask_discord_interactions.Attachment(id: Optional[str] = None, filename: Optional[str] = None, description: Optional[str] = None, content_type: Optional[str] = None, size: Optional[int] = None, url: Optional[str] = None, proxy_url: Optional[str] = None, height: Optional[int] = None, width: Optional[int] = None, ephemeral: Optional[bool] = None)¶
Represents an attachment .. attribute:: id
The id of the attachment
- type
Optional[str]
- class flask_discord_interactions.ChannelType¶
Represents the different
Channeltype integers.- GUILD_TEXT = 0¶
- DM = 1¶
- GUILD_VOICE = 2¶
- GROUP_DM = 3¶
- GUILD_CATEGORY = 4¶
- GUILD_NEWS = 5¶
- GUILD_STORE = 6¶
- ANNOUNCEMENT_THREAD = 10¶
- PUBLIC_THREAD = 11¶
- PRIVATE_THREAD = 12¶
- GUILD_STAGE_VOICE = 13¶
- GUILD_DIRECTORY = 14¶
- GUILD_FORUM = 15¶
- class flask_discord_interactions.User(**kwargs)¶
Represents a User (the identity of a Discord user, not tied to any specific guild).
- property avatar_url¶
The URL of the user’s profile picture.
- Returns
The URL of the user’s profile picture.
- Return type
- property display_name¶
The displayed name of the user (the username).
- Returns
The displayed name of the user.
- Return type
- class flask_discord_interactions.Member(**kwargs)¶
Bases:
UserRepresents a Member (a specific Discord
Userin one particular guild.)The timestamp that the user started Nitro boosting the guild at.
- Type
Optional[str]
- class flask_discord_interactions.Role(**kwargs)¶
Represents a Role in Discord.