Write autocomplete by-example page

tandemdude · Aug 8, 2024 · a5db168 · a5db168
1 parent 3aeea5a
commit a5db168
Showing 1 changed file with 75 additions and 0 deletions.
diff --git a/docs/source/by-examples/080_autocomplete.md b/docs/source/by-examples/080_autocomplete.md
@@ -1,2 +1,77 @@
 (autocomplete)=
 # Autocomplete
+
+Autocomplete is a Discord feature that allows your bot to suggest values for an option dynamically based on the content
+already entered by the user within the option being autocompleted, as well as other options already filled in.
+
+:::{note}
+Only options of type `string`, `integer`, or `number` can be autocompleted.
+:::
+
+Lightbulb implements autocomplete by allowing you to specify an 'autocomplete callback' function that will be
+called for every autocomplete interaction sent when that option is focused.
+
+## Callback Specification
+
+An autocomplete callback is an **asynchronous** function that takes an instance of 
+{obj}`~lightbulb.context.AutocompleteContext` as its first argument - any return value will be discarded.
+
+:::{important}
+Dependency injection **is not** enabled on autocomplete callbacks by default - if you need
+dependency injection in your callback you should add the `@lightbulb.with_di` decorator to the function.
+:::
+
+Within an autocomplete callback, you are required to call the {meth}`~lightbulb.context.AutocompleteContext.respond`
+method **exactly once**. This is what actually submits the autocompletion suggestions to Discord. For details
+about the acceptable values you can pass to `respond()`, see the method's documentation.
+
+## Implementation
+
+To make an option autocomplete-able, you simply pass the callback function into the `autocomplete` argument
+of the respective option function.
+
+For example using a `string` option:
+
+```python
+class Command(
+    lightbulb.SlashCommand,
+    ...
+):
+    option = lightbulb.string(..., autocomplete=your_autocomplete_callback)
+
+    ...
+```
+
+## Full Example Command
+
+The below example is a command with a single autocomplete-able string option that simply recommends 10 random
+strings that are prefixed with the characters the user has already input.
+
+```python
+import string
+import random
+
+import lightbulb
+
+ALL_CHARS = string.ascii_letters + string.digits
+
+
+async def autocomplete_callback(ctx: lightbulb.AutocompleteContext[str]) -> None:
+    current_value: str = ctx.focused.value or ""
+    values_to_recommend = [
+        current_value + "".join(random.choices(ALL_CHARS, k=5)) for _ in range(10)
+    ]
+    await ctx.respond(values_to_recommend)
+
+
+class RandomCharacters(
+    lightbulb.SlashCommand,
+    name="randomchars",
+    description="autocomplete demo command"
+):
+    text = lightbulb.string("text", "autocompleted option", autocomplete=autocomplete_callback)
+
+    @lightbulb.invoke
+    async def invoke(self, ctx: lightbulb.Context) -> None:
+        await ctx.respond(self.text)
+```