Select Support (#243)

Add select support to context, and tweak docs, select helpers

Author: LordOfPolls

discord_slash/context.py

@@ -23,13 +23,16 @@ class InteractionContext:
     :ivar bot: discord.py client.
     :ivar _http: :class:`.http.SlashCommandRequest` of the client.
     :ivar _logger: Logger instance.
+    :ivar data: The raw data of the interaction.
+    :ivar values: The values sent with the interaction. Currently for selects.
     :ivar deferred: Whether the command is current deferred (loading state)
     :ivar _deferred_hidden: Internal var to check that state stays the same
     :ivar responded: Whether you have responded with a message to the interaction.
     :ivar guild_id: Guild ID of the command message. If the command was invoked in DM, then it is ``None``
     :ivar author_id: User ID representing author of the command message.
     :ivar channel_id: Channel ID representing channel of the command message.
     :ivar author: User or Member instance of the command invoke.
+
     """
 
     def __init__(
@@ -47,6 +50,8 @@ def __init__(
         self._logger = logger
         self.deferred = False
         self.responded = False
+        self.data = _json["data"]
+        self.values = _json["data"]["values"] if "values" in _json["data"] else None
         self._deferred_hidden = False  # To check if the patch to the deferred response matches
         self.guild_id = int(_json["guild_id"]) if "guild_id" in _json.keys() else None
         self.author_id = int(
@@ -283,7 +288,7 @@ class ComponentContext(InteractionContext):
     :ivar component: Component data retrieved from the message. Not available if the origin message was ephemeral.
     :ivar origin_message: The origin message of the component. Not available if the origin message was ephemeral.
     :ivar origin_message_id: The ID of the origin message.
-
+    :ivar selected_options: The options selected (only for selects)
     """
 
     def __init__(
@@ -309,6 +314,8 @@ def __init__(
             )
             self.component = self.origin_message.get_component(self.custom_id)
 
+        self.selected_options = _json["data"]["values"] if self.component_type == 3 else None
+
     async def defer(self, hidden: bool = False, edit_origin: bool = False):
         """
         'Defers' the response, showing a loading state to the user

discord_slash/utils/manage_components.py

@@ -156,17 +156,21 @@ def create_select_option(
     """
     Creates an option for select components.
 
-    .. warning::
-        Currently, select components are not available for public use, nor do they have official documentation. The parameters will not be documented at this time.
-
-    :param label: The label of the option.
-    :param value: The value that the bot will recieve when this option is selected.
+    :param label: The user-facing name of the option that will be displayed in discord client.
+    :param value: The value that the bot will receive when this option is selected.
     :param emoji: The emoji of the option.
-    :param description: A description of the option.
+    :param description: An additional description of the option.
     :param default: Whether or not this is the default option.
     """
     emoji = emoji_to_dict(emoji)
 
+    if not len(label) or len(label) > 25:
+        raise IncorrectFormat("Label length should be between 1 and 25.")
+    if not len(value) or len(value) > 100:
+        raise IncorrectFormat("Value length should be between 1 and 100.")
+    if description is not None and len(description) > 50:
+        raise IncorrectFormat("Description length must be 50 or lower.")
+
     return {
         "label": label,
         "value": value,
@@ -186,9 +190,11 @@ def create_select(
     """
     Creates a select (dropdown) component for use with the ``components`` field. Must be inside an ActionRow to be used (see :meth:`create_actionrow`).
 
-
-    .. warning::
-        Currently, select components are not available for public use, nor do they have official documentation. The parameters will not be documented at this time.
+    :param options: The choices the user can pick from
+    :param custom_id: A custom identifier, like buttons
+    :param placeholder: Custom placeholder text if nothing is selected
+    :param min_values: The minimum number of items that **must** be chosen
+    :param max_values: The maximum number of items that **can** be chosen
     """
     if not len(options) or len(options) > 25:
         raise IncorrectFormat("Options length should be between 1 and 25.")

docs/components.rst

@@ -99,3 +99,28 @@ How do I know which button was pressed?
 _______________________________________
 
 Each button gets a ``custom_id`` (which is always a string), this is a unique identifier of which button is being pressed. You can specify what the ID is when you define your button, if you don't; a random one will be generated. When handling the event, simply check the custom_id, and handle accordingly.
+
+What about selects / Dropdowns?
+_______________________________
+
+Yep we support those too. You use them much the same as buttons:
+
+.. code-block:: python
+
+    from discord_slash.utils.manage_components import create_select, create_select_option
+
+    select = create_select(
+        options=[# the options in your dropdown
+            create_select_option("Lab Coat", value="coat", emoji="🥼"),
+            create_select_option("Test Tube", value="tube", emoji="🧪"),
+            create_select_option("Petri Dish", value="dish", emoji="🧫"),
+        ],
+        placeholder="Choose your option",  # the placeholder text to show when no options have been chosen
+        min_values=1,  # the minimum number of options a user must select
+        max_values=2,  # the maximum number of options a user can select
+    )
+
+    @bot.event
+    async def on_component(ctx: ComponentContext):
+        # ctx.selected_options is a list of all the values the user selected
+        await ctx.send(content=f"You selected {ctx.selected_options}")