From 1b676df69b9a52fad0c9f87b2bf23d67c62a1056 Mon Sep 17 00:00:00 2001 From: DA-344 <108473820+DA-344@users.noreply.github.com> Date: Sun, 18 May 2025 12:11:01 +0200 Subject: [PATCH] chore: Improve documentation on MediaGallery(Item) and ui.File --- discord/components.py | 8 +-- discord/ui/file.py | 2 +- discord/ui/media_gallery.py | 97 +++++++++++++++++++++++++++++++------ 3 files changed, 87 insertions(+), 20 deletions(-) diff --git a/discord/components.py b/discord/components.py index 22c3d714c..4f69a80dc 100644 --- a/discord/components.py +++ b/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://`` 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 - using the ``attachment://file-name.extension`` format. + file uploaded as an attachment in the message, which can be accessed + using the ``attachment://`` format, or an arbitrary url. description: Optional[:class:`str`] The description to show within this item. Up to 256 characters. Defaults to ``None``. diff --git a/discord/ui/file.py b/discord/ui/file.py index 5d9014e72..09d557a89 100644 --- a/discord/ui/file.py +++ b/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://`` format. spoiler: :class:`bool` Whether to flag this file as a spoiler. Defaults to ``False``. row: Optional[:class:`int`] diff --git a/discord/ui/media_gallery.py b/discord/ui/media_gallery.py index bbecc9649..e7346bf69 100644 --- a/discord/ui/media_gallery.py +++ b/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://`` 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: - """Removes an item from the gallery. + def insert_item_at( + 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` - The item to remove from the gallery. + index: :class:`int` + 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://`` 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: - self._underlying.items.remove(item) - except ValueError: - pass + 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.insert(index, item) return self - def insert_item_at(self, index: int, item: MediaGalleryItem) -> Self: - """Inserts an item before a specified index to the gallery. + def remove_item(self, item: MediaGalleryItem) -> Self: + """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: