Browse Source

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

pull/10166/head
DA-344 1 week ago
parent
commit
1b676df69b
  1. 8
      discord/components.py
  2. 2
      discord/ui/file.py
  3. 97
      discord/ui/media_gallery.py

8
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
using the ``attachment://file-name.extension`` format.
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``.

2
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`]

97
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:
"""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://<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:
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:

Loading…
Cancel
Save