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 CommandOptionType or 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 ChannelType for 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 to True if 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:: dict

classmethod from_data(data: dict)¶: Load this option from incoming Interaction data.

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.

id¶

The unique ID (snowflake) of the channel.

Type:: str

name¶

The name of the channel.

Type:: str

permissions¶

The permissions integer of the invoking user in that channel.

Type:: int

type¶

The type of channel.

Type:: int

nsfw¶

Whether the channel is age restricted or not.

Type:: Optional[bool]

parent_id¶

Category this channel belongs to.

Type:: Optional[bool]

thread_metadata¶

Thread-specific fields not needed by other channels.

Type:: Optional[dict]

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]

filename¶

Name of the attached file

Type:: Optional[str]

description¶

Optional description of the file. Used for screen readers

Type:: Optional[str]

content_type¶

The media type of the file

Type:: Optional[str]

size¶

Size of the attached file in bytes

Type:: Optional[int]

url¶

Url to fetch the file

Type:: Optional[str]

proxy_url¶

Url to fetch the file from the discord media proxy

Type:: Optional[str]

height¶

Optinal height if the file is an image

Type:: Optional[int]

width¶

Optinal width if the file is an image

Type:: Optional[int]

ephemeral¶

Set to true on ephemeral messages and when getting attachment as command option values

Type:: Optional[bool]

class flask_discord_interactions.ChannelType¶

Represents the different Channel type 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).

id¶

The ID (snowflake) of the user.

Type:: str

username¶

The Discord username of the user.

Type:: str

discriminator¶

The code following the # after the username.

Type:: str

public_flags¶

Miscellaneous information about the user.

Type:: Optional[int]

avatar_hash¶

The unique hash identifying the profile picture of the user.

Type:: Optional[str]

bot¶

Whether the user is a bot account.

Type:: Optional[bool]

system¶

Whether the user is a Discord system account.

Type:: Optional[bool]

property avatar_url¶

The URL of the user’s profile picture.

Returns:: The URL of the user’s profile picture.
Return type:: str

property display_name¶

The displayed name of the user (the username).

Returns:: The displayed name of the user.
Return type:: str

classmethod from_dict(data)¶

Construct the dataclass from a dictionary, skipping any keys in the dictionary that do not correspond to fields of the class.

Parameters:: data (dict) – A dictionary of fields to set on the dataclass.

class flask_discord_interactions.Member(**kwargs)¶

Bases: User

Represents a Member (a specific Discord User in one particular guild.)

deaf¶

Whether the user has been server deafened.

Type:: bool

mute¶

Whether the user has been server muted.

Type:: bool

joined_at¶

The timestamp that the user joined the guild at.

Type:: str

avatar¶

The member’s guild avatar hash

Type:: Optional[str]

nick¶

The guild nickname of the user.

Type:: Optional[str]

roles¶

An array of role IDs that the user has.

Type:: Optional[List[str]]

premium_since¶

The timestamp that the user started Nitro boosting the guild at.

Type:: Optional[str]

permissions¶

The permissions integer of the user.

Type:: Optional[int]

communication_disabled_until¶

Timestamp when the member’s timeout will expire (if existing)

Type:: Optional[str]

pending¶

Whether the user has passed the membership requirements of a guild.

Type:: Optional[bool]

property display_name¶

The displayed name of the user (their nickname, or if none exists, their username).

Returns:: The displayed name of the user.
Return type:: str

class flask_discord_interactions.Role(**kwargs)¶

Represents a Role in Discord.

id¶

The unique ID (snowflake) of the role.

Type:: str

name¶

The name of the role.

Type:: str

color¶

The color given to the role.

Type:: int

hoist¶

Whether the role is displayed separately in the member list.

Type:: bool

position¶

The position of the role in the roles list.

Type:: int

permissions¶

The permissions integer of the role.

Type:: str

managed¶

Whether the role is managed by an integration (bot).

Type:: bool

mentionable¶

Whether the role can be mentioned by all users.

Type:: bool

tags¶

Miscellaneous information about the role.

Type:: Optional[dict]

icon¶

Hash of the role’s icon

Type:: Optional[str]

unicode_emoji¶

Unicode emoji of the role (alternative to icons)

Type:: Optional[str]

Options¶

Primitives¶

Discord Models¶

Choices¶

Explicit Options¶

Full API¶

Flask-Discord-Interactions

Navigation

Related Topics