feat: components v2

changelog/1294.feature.rst

@@ -0,0 +1,14 @@
+Add support for :ddocs:`components v2 <components/reference>` (`example <https://github.com/DisnakeDev/disnake/blob/master/examples/components_v2.py>`_):
+- These components allow you to have more control over the layout of your messages, and are used instead of the classic ``content`` and ``embeds`` fields.
+- New top-level components:
+    - :class:`ui.Section`: Displays an accessory (:class:`ui.Thumbnail` or :class:`ui.Button`) alongside some text.
+    - :class:`ui.TextDisplay`: Text component, similar to the ``content`` field of messages.
+    - :class:`ui.MediaGallery`: A gallery/mosaic of up to 10 :class:`MediaGalleryItem`\s.
+    - :class:`ui.File`: Display an uploaded file as an attachment.
+    - :class:`ui.Separator`: A spacer/separator adding vertical padding.
+    - :class:`ui.Container`: Contains other components, visually similar to :class:`Embed`\s.
+    - Each component has a corresponding new :class:`ComponentType`.
+- New :attr:`MessageFlags.is_components_v2` flag. This is set automatically when sending v2 components, and cannot be reverted once set.
+- New :func:`ui.walk_components` and :func:`ui.components_from_message` utility functions.
+- All ``ui.*`` components now inherit from a common :class:`ui.UIComponent` base class.
+- Components now have an :attr:`~ui.UIComponent.id` attribute, which is a unique (per-message) optional numeric identifier.

disnake/abc.py

@@ -84,7 +84,7 @@
         PermissionOverwrite as PermissionOverwritePayload,
     )
     from .types.threads import PartialForumTag as PartialForumTagPayload
-    from .ui.action_row import Components, MessageUIComponent
+    from .ui._types import MessageComponents
     from .ui.view import View
     from .user import ClientUser
     from .voice_region import VoiceRegion
@@ -1442,7 +1442,7 @@ async def send(
         reference: Union[Message, MessageReference, PartialMessage] = ...,
         mention_author: bool = ...,
         view: View = ...,
-        components: Components[MessageUIComponent] = ...,
+        components: MessageComponents = ...,
         poll: Poll = ...,
     ) -> Message: ...
 
@@ -1463,7 +1463,7 @@ async def send(
         reference: Union[Message, MessageReference, PartialMessage] = ...,
         mention_author: bool = ...,
         view: View = ...,
-        components: Components[MessageUIComponent] = ...,
+        components: MessageComponents = ...,
         poll: Poll = ...,
     ) -> Message: ...
 
@@ -1484,7 +1484,7 @@ async def send(
         reference: Union[Message, MessageReference, PartialMessage] = ...,
         mention_author: bool = ...,
         view: View = ...,
-        components: Components[MessageUIComponent] = ...,
+        components: MessageComponents = ...,
         poll: Poll = ...,
     ) -> Message: ...
 
@@ -1505,7 +1505,7 @@ async def send(
         reference: Union[Message, MessageReference, PartialMessage] = ...,
         mention_author: bool = ...,
         view: View = ...,
-        components: Components[MessageUIComponent] = ...,
+        components: MessageComponents = ...,
         poll: Poll = ...,
     ) -> Message: ...
 
@@ -1527,7 +1527,7 @@ async def send(
         reference: Optional[Union[Message, MessageReference, PartialMessage]] = None,
         mention_author: Optional[bool] = None,
         view: Optional[View] = None,
-        components: Optional[Components[MessageUIComponent]] = None,
+        components: Optional[MessageComponents] = None,
         poll: Optional[Poll] = None,
     ):
         """|coro|
@@ -1540,8 +1540,8 @@ async def send(
         ``stickers``, ``components``, ``poll`` or ``view`` must be provided.
 
         To upload a single file, the ``file`` parameter should be used with a
-        single :class:`.File` object. To upload multiple files, the ``files``
-        parameter should be used with a :class:`list` of :class:`.File` objects.
+        single :class:`~disnake.File` object. To upload multiple files, the ``files``
+        parameter should be used with a :class:`list` of :class:`~disnake.File` objects.
         **Specifying both parameters will lead to an exception**.
 
         To upload a single embed, the ``embed`` parameter should be used with a
@@ -1567,9 +1567,9 @@ async def send(
 
             .. versionadded:: 2.0
 
-        file: :class:`.File`
+        file: :class:`~disnake.File`
             The file to upload. This cannot be mixed with the ``files`` parameter.
-        files: List[:class:`.File`]
+        files: List[:class:`~disnake.File`]
             A list of files to upload. Must be a maximum of 10.
             This cannot be mixed with the ``file`` parameter.
         stickers: Sequence[Union[:class:`.GuildSticker`, :class:`.StandardSticker`, :class:`.StickerItem`]]
@@ -1623,6 +1623,11 @@ async def send(
 
             .. versionadded:: 2.4
 
+            .. note::
+                Passing v2 components here automatically sets the :attr:`~.MessageFlags.is_components_v2` flag.
+                Setting this flag cannot be reverted. Note that this also disables the
+                ``content``, ``embeds``, ``stickers``, and ``poll`` fields.
+
         suppress_embeds: :class:`bool`
             Whether to suppress embeds for the message. This hides
             all the embeds from the UI if set to ``True``.
@@ -1631,8 +1636,8 @@ async def send(
 
         flags: :class:`.MessageFlags`
             The flags to set for this message.
-            Only :attr:`~.MessageFlags.suppress_embeds` and :attr:`~.MessageFlags.suppress_notifications`
-            are supported.
+            Only :attr:`~.MessageFlags.suppress_embeds`, :attr:`~.MessageFlags.suppress_notifications`,
+            and :attr:`~.MessageFlags.is_components_v2` are supported.
 
             If parameter ``suppress_embeds`` is provided,
             that will override the setting of :attr:`.MessageFlags.suppress_embeds`.
@@ -1657,7 +1662,8 @@ async def send(
             or the ``reference`` object is not a :class:`.Message`,
             :class:`.MessageReference` or :class:`.PartialMessage`.
         ValueError
-            The ``files`` or ``embeds`` list is too large.
+            The ``files`` or ``embeds`` list is too large, or
+            you tried to send v2 components together with ``content``, ``embeds``, ``stickers``, or ``poll``.
 
         Returns
         -------
@@ -1721,19 +1727,28 @@ async def send(
                     "reference parameter must be Message, MessageReference, or PartialMessage"
                 ) from None
 
+        is_v2 = False
         if view is not None and components is not None:
             raise TypeError("cannot pass both view and components parameter to send()")
         elif view:
             if not hasattr(view, "__discord_ui_view__"):
                 raise TypeError(f"view parameter must be View not {view.__class__!r}")
             components_payload = view.to_components()
         elif components:
-            from .ui.action_row import components_to_dict
+            from .ui.action_row import normalize_components_to_dict
 
-            components_payload = components_to_dict(components)
+            components_payload, is_v2 = normalize_components_to_dict(components)
         else:
             components_payload = None
 
+        # set cv2 flag automatically
+        if is_v2:
+            flags = MessageFlags._from_value(0 if flags is None else flags.value)
+            flags.is_components_v2 = True
+        # components v2 cannot be used with other content fields
+        if flags and flags.is_components_v2 and (content or embeds or stickers or poll):
+            raise ValueError("Cannot use v2 components with content, embeds, stickers, or polls")
+
         flags_payload = None
         if suppress_embeds is not None:
             flags = MessageFlags._from_value(0 if flags is None else flags.value)

disnake/channel.py

@@ -96,7 +96,7 @@
     from .types.soundboard import PartialSoundboardSound as PartialSoundboardSoundPayload
     from .types.threads import ThreadArchiveDurationLiteral
     from .types.voice import VoiceChannelEffect as VoiceChannelEffectPayload
-    from .ui.action_row import Components, MessageUIComponent
+    from .ui._types import MessageComponents
     from .ui.view import View
     from .user import BaseUser, ClientUser, User
     from .voice_region import VoiceRegion
@@ -3522,7 +3522,7 @@ async def create_thread(
         stickers: Sequence[Union[GuildSticker, StandardSticker, StickerItem]] = ...,
         allowed_mentions: AllowedMentions = ...,
         view: View = ...,
-        components: Components = ...,
+        components: MessageComponents = ...,
         reason: Optional[str] = None,
     ) -> ThreadWithMessage: ...
 
@@ -3542,7 +3542,7 @@ async def create_thread(
         stickers: Sequence[Union[GuildSticker, StandardSticker, StickerItem]] = ...,
         allowed_mentions: AllowedMentions = ...,
         view: View = ...,
-        components: Components = ...,
+        components: MessageComponents = ...,
         reason: Optional[str] = None,
     ) -> ThreadWithMessage: ...
 
@@ -3562,7 +3562,7 @@ async def create_thread(
         stickers: Sequence[Union[GuildSticker, StandardSticker, StickerItem]] = ...,
         allowed_mentions: AllowedMentions = ...,
         view: View = ...,
-        components: Components = ...,
+        components: MessageComponents = ...,
         reason: Optional[str] = None,
     ) -> ThreadWithMessage: ...
 
@@ -3582,7 +3582,7 @@ async def create_thread(
         stickers: Sequence[Union[GuildSticker, StandardSticker, StickerItem]] = ...,
         allowed_mentions: AllowedMentions = ...,
         view: View = ...,
-        components: Components = ...,
+        components: MessageComponents = ...,
         reason: Optional[str] = None,
     ) -> ThreadWithMessage: ...
 
@@ -3603,7 +3603,7 @@ async def create_thread(
         stickers: Sequence[Union[GuildSticker, StandardSticker, StickerItem]] = MISSING,
         allowed_mentions: AllowedMentions = MISSING,
         view: View = MISSING,
-        components: Components[MessageUIComponent] = MISSING,
+        components: MessageComponents = MISSING,
         reason: Optional[str] = None,
     ) -> ThreadWithMessage:
         """|coro|
@@ -3656,16 +3656,17 @@ async def create_thread(
             all the embeds from the UI if set to ``True``.
         flags: :class:`MessageFlags`
             The flags to set for this message.
-            Only :attr:`~MessageFlags.suppress_embeds` is supported.
+            Only :attr:`~MessageFlags.suppress_embeds` and :attr:`~MessageFlags.is_components_v2`
+            are supported.
 
             If parameter ``suppress_embeds`` is provided,
             that will override the setting of :attr:`MessageFlags.suppress_embeds`.
 
             .. versionadded:: 2.9
 
-        file: :class:`.File`
+        file: :class:`~disnake.File`
             The file to upload. This cannot be mixed with the ``files`` parameter.
-        files: List[:class:`.File`]
+        files: List[:class:`~disnake.File`]
             A list of files to upload. Must be a maximum of 10.
             This cannot be mixed with the ``file`` parameter.
         stickers: Sequence[Union[:class:`.GuildSticker`, :class:`.StandardSticker`, :class:`.StickerItem`]]
@@ -3681,6 +3682,12 @@ async def create_thread(
             A Discord UI View to add to the message. This cannot be mixed with ``components``.
         components: |components_type|
             A list of components to include in the message. This cannot be mixed with ``view``.
+
+            .. note::
+                Passing v2 components here automatically sets the :attr:`~MessageFlags.is_components_v2` flag.
+                Setting this flag cannot be reverted. Note that this also disables the
+                ``content``, ``embeds``, and ``stickers`` fields.
+
         reason: Optional[:class:`str`]
             The reason for creating the thread. Shows up on the audit log.
 
@@ -3693,11 +3700,11 @@ async def create_thread(
         TypeError
             Specified both ``file`` and ``files``,
             or you specified both ``embed`` and ``embeds``,
-            or you specified both ``view`` and ``components``.
+            or you specified both ``view`` and ``components``,
             or you have passed an object that is not :class:`File` to ``file`` or ``files``.
         ValueError
-            Specified more than 10 embeds,
-            or more than 10 files.
+            Specified more than 10 embeds, or more than 10 files, or
+            you tried to send v2 components together with ``content``, ``embeds``, or ``stickers``.
 
         Returns
         -------