Autocomplete¶
You can use autocomplete to suggest options for your users while they are typing a command. To do this, flag the option as an Autocomplete option, then define an autocomplete handler to return the autocomplete results.
Marking an option as autocomplete¶
If you’re using type hints to define your options, you can use the
Autocomplete
class to “wrap” the type of your option, like so:
@discord.command()
def autocomplete_example(ctx, country: Autocomplete(str), city: Autocomplete(str)):
return f"You selected **{city}, {country}**!"
Note that even though this is a type annotation, these are parenthesis, not brackets. This is due to a limitation in Python.
Alternatively, if you’re using the options=[]
parameter, you can set
autocomplete=True
on the Option
objects.
@discord.command(
options=[
Option(
name="message",
type=str,
description="The message to repeat",
required=True,
autocomplete=True,
),
]
)
def repeat_many(ctx, message: string):
return f"You said, {message}!"
Defining an autocomplete handler¶
Autocomplete handlers are functions that take in Option
objects and
return a list of autocomplete options. You can either provide a
AutocompleteResult
object directly, or one will be generated for
you.
There are two ways to register an autocomplete handler. The simplest is to make use of the Command.autocomplete()
decorator, like so:
@discord.command()
def more_autocomplete(ctx, value: Autocomplete(int)):
return f"Your number is **{value}**."
@more_autocomplete.autocomplete()
def more_autocomplete_handler(ctx, value=None):
# Note that even though this option is an int,
# the autocomplete handler still gets passed a str.
try:
value = int(value.value)
except ValueError:
return []
return [i for i in range(value, value + 10)]
Note
Make sure the arguments to your function are optional! If a user isn’t finished typing a response, then some of the options might not be provided.
You can also use DiscordInteractionsBlueprint.add_autocomplete_handler()
and provide the name of the function you wish to autocomplete.
@discord.command()
def autocomplete_example(ctx, country: Autocomplete(str), city: Autocomplete(str)):
return f"You selected **{city}, {country}**!"
COUNTRIES = ["Germany", "Canada", "United States", "United Kingdom"]
CITIES = {
"Germany": ["Berlin", "Munich", "Frankfurt"],
"Canada": ["Toronto", "Montreal", "Vancouver"],
"United States": ["New York", "Chicago", "Los Angeles"],
"United Kingdom": ["London", "Manchester", "Liverpool"],
}
def autocomplete_handler(ctx, country=None, city=None):
if country.focused:
return [c for c in COUNTRIES if c.lower().startswith(country.value.lower())]
elif city.focused:
if country.value in CITIES:
return CITIES[country.value]
else:
return []
discord.add_autocomplete_handler(autocomplete_handler, "autocomplete_example")
In your autocomplete handler, you’ll receive Option
objects. Each one
will have a value
attribute, containing what the user is currently typing,
as well as a focused
attribute, which will be True
for the option that
the user is currently typing in.
Full API¶
- class flask_discord_interactions.AutocompleteResult(choices=[])¶
Represents the result of an autocomplete handler.
- Parameters:
choices – A dict mapping the displayed name of each choice to its value passed to your command.
- encode()¶
Return this result as a complete interaction response.
- Returns:
str – The encoded JSON object.
str – The mimetype of the response (
application/json
).
- static from_return_value(value: Union[dict, list, AutocompleteResult])¶
Converts the return value of an autocomplete handler to an AutocompleteResult.
- Parameters:
value – The return value of an autocomplete handler.
- Returns:
The AutocompleteResult that corresponds to the return value.
- Return type: