feat: add GuildSoundboardSound converter

disnake/ext/commands/converter.py

@@ -40,6 +40,7 @@
     EmojiNotFound,
     GuildNotFound,
     GuildScheduledEventNotFound,
+    GuildSoundboardSoundNotFound,
     GuildStickerNotFound,
     MemberNotFound,
     MessageNotFound,
@@ -82,6 +83,7 @@
     "EmojiConverter",
     "PartialEmojiConverter",
     "GuildStickerConverter",
+    "GuildSoundboardSoundConverter",
     "PermissionsConverter",
     "GuildScheduledEventConverter",
     "clean_content",
@@ -944,6 +946,43 @@ async def convert(self, ctx: AnyContext, argument: str) -> disnake.GuildSticker:
         return result
 
 
+class GuildSoundboardSoundConverter(IDConverter[disnake.GuildSoundboardSound]):
+    """Converts to a :class:`~disnake.GuildSoundboardSound`.
+
+    All lookups are done for the local guild first, if available. If that lookup
+    fails, then it checks the client's global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID
+    2. Lookup by name
+
+    .. versionadded:: 2.10
+    """
+
+    async def convert(self, ctx: AnyContext, argument: str) -> disnake.GuildSoundboardSound:
+        match = self._get_id_match(argument)
+        result = None
+        bot: disnake.Client = ctx.bot
+        guild = ctx.guild
+
+        if match is None:
+            # Try to get the sound by name. Try local guild first.
+            if guild:
+                result = _utils_get(guild.soundboard_sounds, name=argument)
+
+            if result is None:
+                result = _utils_get(bot.soundboard_sounds, name=argument)
+        else:
+            # Try to look up sound by id.
+            result = bot.get_soundboard_sound(int(match.group(1)))
+
+        if result is None:
+            raise GuildSoundboardSoundNotFound(argument)
+
+        return result
+
+
 class PermissionsConverter(Converter[disnake.Permissions]):
     """Converts to a :class:`~disnake.Permissions`.
 
@@ -1212,6 +1251,7 @@ def is_generic_type(tp: Any, *, _GenericAlias: Type = _GenericAlias) -> bool:
     disnake.Thread: ThreadConverter,
     disnake.abc.GuildChannel: GuildChannelConverter,
     disnake.GuildSticker: GuildStickerConverter,
+    disnake.GuildSoundboardSound: GuildSoundboardSoundConverter,
     disnake.Permissions: PermissionsConverter,
     disnake.GuildScheduledEvent: GuildScheduledEventConverter,
 }

disnake/ext/commands/errors.py

@@ -49,6 +49,7 @@
     "BadInviteArgument",
     "EmojiNotFound",
     "GuildStickerNotFound",
+    "GuildSoundboardSoundNotFound",
     "GuildScheduledEventNotFound",
     "PartialEmojiConversionFailure",
     "BadBoolArgument",
@@ -499,6 +500,24 @@ def __init__(self, argument: str) -> None:
         super().__init__(f'Sticker "{argument}" not found.')
 
 
+class GuildSoundboardSoundNotFound(BadArgument):
+    """Exception raised when the bot can not find the soundboard sound.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.10
+
+    Attributes
+    ----------
+    argument: :class:`str`
+        The soundboard sound supplied by the caller that was not found
+    """
+
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'Soundboard sound "{argument}" not found.')
+
+
 class GuildScheduledEventNotFound(BadArgument):
     """Exception raised when the bot cannot find the scheduled event.
 

docs/ext/commands/api/converters.rst

@@ -78,6 +78,9 @@ Classes
 .. autoclass:: GuildStickerConverter
     :members:
 
+.. autoclass:: GuildSoundboardSoundConverter
+    :members:
+
 .. autoclass:: PermissionsConverter
     :members:
 

docs/ext/commands/api/exceptions.rst

@@ -120,6 +120,9 @@ Exceptions
 .. autoexception:: GuildStickerNotFound
     :members:
 
+.. autoexception:: GuildSoundboardSoundNotFound
+    :members:
+
 .. autoexception:: GuildScheduledEventNotFound
     :members:
 
@@ -213,6 +216,7 @@ Exception Hierarchy
                     - :exc:`EmojiNotFound`
                     - :exc:`PartialEmojiConversionFailure`
                     - :exc:`GuildStickerNotFound`
+                    - :exc:`GuildSoundboardSoundNotFound`
                     - :exc:`GuildScheduledEventNotFound`
                     - :exc:`BadBoolArgument`
                     - :exc:`LargeIntConversionFailure`

docs/ext/commands/commands.rst

@@ -399,6 +399,7 @@ A lot of Discord models work out of the gate as a parameter:
 - :class:`GuildSticker` (since v2.0)
 - :class:`Permissions` (since v2.3)
 - :class:`GuildScheduledEvent` (since v2.5)
+- :class:`GuildSoundboardSound` (since v2.10)
 
 Having any of these set as the converter will intelligently convert the argument to the appropriate target type you
 specify.
@@ -455,6 +456,8 @@ converter is given below:
 +------------------------------+--------------------------------------------------------+
 | :class:`GuildScheduledEvent` | :class:`~ext.commands.GuildScheduledEventConverter`    |
 +------------------------------+--------------------------------------------------------+
+| :class:`GuildSoundboardSound`| :class:`~ext.commands.GuildSoundboardSoundConverter`   |
++------------------------------+--------------------------------------------------------+
 
 By providing the converter it allows us to use them as building blocks for another converter: