chore: Improve documentation on MediaGallery(Item) and ui.File

discord/components.py

@@ -905,7 +905,9 @@ class UnfurledMediaItem(AssetMixin):
     Parameters
     ----------
     url: :class:`str`
-        The URL of this media item.
+        The URL of this media item. This can be an arbitrary url or a reference to a local
+        file uploaded as an attachment within the message, which can be accessed with the
+        ``attachment://<filename>`` format.
 
     Attributes
     ----------
@@ -990,8 +992,8 @@ class MediaGalleryItem:
     ----------
     media: Union[:class:`str`, :class:`UnfurledMediaItem`]
         The media item data. This can be a string representing a local
-        file uploaded as an attachment in the message, that can be accessed
+        file uploaded as an attachment in the message, which can be accessed
-        using the ``attachment://file-name.extension`` format.
+        using the ``attachment://<filename>`` format, or an arbitrary url.
     description: Optional[:class:`str`]
         The description to show within this item. Up to 256 characters. Defaults
         to ``None``.

discord/ui/file.py

@@ -63,7 +63,7 @@ class File(Item[V]):
     media: Union[:class:`str`, :class:`.UnfurledMediaItem`]
         This file's media. If this is a string it must point to a local
         file uploaded within the parent view of this item, and must
-        meet the ``attachment://filename.extension`` structure.
+        meet the ``attachment://<filename>`` format.
     spoiler: :class:`bool`
         Whether to flag this file as a spoiler. Defaults to ``False``.
     row: Optional[:class:`int`]

discord/ui/media_gallery.py

@@ -23,13 +23,14 @@ DEALINGS IN THE SOFTWARE.
 """
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, List, Literal, Optional, TypeVar
+from typing import TYPE_CHECKING, List, Literal, Optional, TypeVar, Union
 
 from .item import Item
 from ..enums import ComponentType
 from ..components import (
     MediaGalleryItem,
     MediaGalleryComponent,
+    UnfurledMediaItem,
 )
 
 if TYPE_CHECKING:
@@ -100,12 +101,49 @@ class MediaGallery(Item[V]):
     def _is_v2(self) -> bool:
         return True
 
-    def add_item(self, item: MediaGalleryItem) -> Self:
+    def add_item(
+        self,
+        *,
+        media: Union[str, UnfurledMediaItem],
+        description: Optional[str] = None,
+        spoiler: bool = False,
+    ) -> Self:
         """Adds an item to this gallery.
 
         This function returns the class instance to allow for fluent-style
         chaining.
 
+        Parameters
+        ----------
+        media: Union[:class:`str`, :class:`.UnfurledMediaItem`]
+            The media item data. This can be a string representing a local
+            file uploaded as an attachment in the message, which can be accessed
+            using the ``attachment://<filename>`` format, or an arbitrary url.
+        description: Optional[:class:`str`]
+            The description to show within this item. Up to 256 characters. Defaults
+            to ``None``.
+        spoiler: :class:`bool`
+            Whether this item should be flagged as a spoiler. Defaults to ``False``.
+
+        Raises
+        ------
+        ValueError
+            Maximum number of items has been exceeded (10).
+        """
+
+        if len(self._underlying.items) >= 10:
+            raise ValueError('maximum number of items has been exceeded')
+
+        item = MediaGalleryItem(media, description=description, spoiler=spoiler)
+        self._underlying.items.append(item)
+        return self
+
+    def append_item(self, item: MediaGalleryItem) -> Self:
+        """Appends an item to this gallery.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
         Parameters
         ----------
         item: :class:`.MediaGalleryItem`
@@ -128,39 +166,66 @@ class MediaGallery(Item[V]):
         self._underlying.items.append(item)
         return self
 
-    def remove_item(self, item: MediaGalleryItem) -> Self:
+    def insert_item_at(
-        """Removes an item from the gallery.
+        self,
+        index: int,
+        *,
+        media: Union[str, UnfurledMediaItem],
+        description: Optional[str] = None,
+        spoiler: bool = False,
+    ) -> Self:
+        """Inserts an item before a specified index to the media gallery.
 
         This function returns the class instance to allow for fluent-style
         chaining.
 
         Parameters
         ----------
-        item: :class:`.MediaGalleryItem`
+        index: :class:`int`
-            The item to remove from the gallery.
+            The index of where to insert the field.
+        media: Union[:class:`str`, :class:`.UnfurledMediaItem`]
+            The media item data. This can be a string representing a local
+            file uploaded as an attachment in the message, which can be accessed
+            using the ``attachment://<filename>`` format, or an arbitrary url.
+        description: Optional[:class:`str`]
+            The description to show within this item. Up to 256 characters. Defaults
+            to ``None``.
+        spoiler: :class:`bool`
+            Whether this item should be flagged as a spoiler. Defaults to ``False``.
+
+        Raises
+        ------
+        ValueError
+            Maximum number of items has been exceeded (10).
         """
 
-        try:
+        if len(self._underlying.items) >= 10:
-            self._underlying.items.remove(item)
+            raise ValueError('maximum number of items has been exceeded')
-        except ValueError:
+
-            pass
+        item = MediaGalleryItem(
+            media,
+            description=description,
+            spoiler=spoiler,
+        )
+        self._underlying.items.insert(index, item)
         return self
 
-    def insert_item_at(self, index: int, item: MediaGalleryItem) -> Self:
+    def remove_item(self, item: MediaGalleryItem) -> Self:
-        """Inserts an item before a specified index to the gallery.
+        """Removes an item from the gallery.
 
         This function returns the class instance to allow for fluent-style
         chaining.
 
         Parameters
         ----------
-        index: :class:`int`
-            The index of where to insert the item.
         item: :class:`.MediaGalleryItem`
-            The item to insert.
+            The item to remove from the gallery.
         """
 
-        self._underlying.items.insert(index, item)
+        try:
+            self._underlying.items.remove(item)
+        except ValueError:
+            pass
         return self
 
     def clear_items(self) -> Self: