From de8a7238f8cd282ba291b88875fd9177f95280ed Mon Sep 17 00:00:00 2001 From: DA-344 <108473820+DA-344@users.noreply.github.com> Date: Sun, 2 Mar 2025 14:04:45 +0100 Subject: [PATCH] chore: docs and some changes --- discord/components.py | 2 + discord/ui/__init__.py | 6 ++ discord/ui/container.py | 4 +- discord/ui/file.py | 2 +- discord/ui/media_gallery.py | 2 +- discord/ui/section.py | 2 + discord/ui/separator.py | 11 ++- discord/ui/text_display.py | 8 ++ discord/ui/thumbnail.py | 2 +- discord/ui/view.py | 26 ++++- docs/api.rst | 29 ++++-- docs/interactions/api.rst | 188 +++++++++++++++++++++++++++++++++++- 12 files changed, 268 insertions(+), 14 deletions(-) diff --git a/discord/components.py b/discord/components.py index f13646910..cb1a50976 100644 --- a/discord/components.py +++ b/discord/components.py @@ -91,6 +91,8 @@ __all__ = ( 'SelectDefaultValue', 'SectionComponent', 'ThumbnailComponent', + 'UnfurledMediaItem', + 'MediaGalleryItem', 'MediaGalleryComponent', 'FileComponent', 'SectionComponent', diff --git a/discord/ui/__init__.py b/discord/ui/__init__.py index 029717cb5..62a78634c 100644 --- a/discord/ui/__init__.py +++ b/discord/ui/__init__.py @@ -17,3 +17,9 @@ from .select import * from .text_input import * from .dynamic import * from .container import * +from .file import * +from .media_gallery import * +from .section import * +from .separator import * +from .text_display import * +from .thumbnail import * diff --git a/discord/ui/container.py b/discord/ui/container.py index a98b0d965..978781dd8 100644 --- a/discord/ui/container.py +++ b/discord/ui/container.py @@ -51,9 +51,9 @@ class Container(View, Item[V]): children: List[:class:`Item`] The initial children or :class:`View`s of this container. Can have up to 10 items. - accent_colour: Optional[:class:`~discord.Colour`] + accent_colour: Optional[:class:`.Colour`] The colour of the container. Defaults to ``None``. - accent_color: Optional[:class:`~discord.Color`] + accent_color: Optional[:class:`.Color`] The color of the container. Defaults to ``None``. spoiler: :class:`bool` Whether to flag this container as a spoiler. Defaults diff --git a/discord/ui/file.py b/discord/ui/file.py index b4285a654..fabf5b0f3 100644 --- a/discord/ui/file.py +++ b/discord/ui/file.py @@ -46,7 +46,7 @@ class File(Item[V]): Parameters ---------- - media: Union[:class:`str`, :class:`UnfurledMediaItem`] + media: Union[:class:`str`, :class:`.UnfurledMediaItem`] This file's media. If this is a string itmust point to a local file uploaded within the parent view of this item, and must meet the ``attachment://file-name.extension`` structure. diff --git a/discord/ui/media_gallery.py b/discord/ui/media_gallery.py index fa20af740..93638d7f6 100644 --- a/discord/ui/media_gallery.py +++ b/discord/ui/media_gallery.py @@ -51,7 +51,7 @@ class MediaGallery(Item[V]): Parameters ---------- - items: List[:class:`MediaGalleryItem`] + items: List[:class:`.MediaGalleryItem`] The initial items of this gallery. row: Optional[:class:`int`] The relative row this media gallery belongs to. By default diff --git a/discord/ui/section.py b/discord/ui/section.py index 4da36f86f..fece9b053 100644 --- a/discord/ui/section.py +++ b/discord/ui/section.py @@ -78,6 +78,8 @@ class Section(Item[V]): ] self.accessory: Optional[Item[Any]] = accessory + self.row = row + @property def type(self) -> Literal[ComponentType.section]: return ComponentType.section diff --git a/discord/ui/separator.py b/discord/ui/separator.py index c275fad82..cc49adecb 100644 --- a/discord/ui/separator.py +++ b/discord/ui/separator.py @@ -30,6 +30,8 @@ from ..components import SeparatorComponent from ..enums import SeparatorSize, ComponentType if TYPE_CHECKING: + from typing_extensions import Self + from .view import View V = TypeVar('V', bound='View', covariant=True) @@ -47,7 +49,7 @@ class Separator(Item[V]): visible: :class:`bool` Whether this separator is visible. On the client side this is whether a divider line should be shown or not. - spacing: :class:`SeparatorSize` + spacing: :class:`discord.SeparatorSize` The spacing of this separator. row: Optional[:class:`int`] The relative row this separator belongs to. By default @@ -108,3 +110,10 @@ class Separator(Item[V]): def to_component_dict(self): return self._underlying.to_dict() + + @classmethod + def from_component(cls, component: SeparatorComponent) -> Self: + return cls( + visible=component.visible, + spacing=component.spacing, + ) diff --git a/discord/ui/text_display.py b/discord/ui/text_display.py index a51d60493..9a70bd247 100644 --- a/discord/ui/text_display.py +++ b/discord/ui/text_display.py @@ -30,6 +30,8 @@ from ..components import TextDisplay as TextDisplayComponent from ..enums import ComponentType if TYPE_CHECKING: + from typing_extensions import Self + from .view import View V = TypeVar('V', bound='View', covariant=True) @@ -77,3 +79,9 @@ class TextDisplay(Item[V]): def _is_v2(self) -> bool: return True + + @classmethod + def from_component(cls, component: TextDisplayComponent) -> Self: + return cls( + content=component.content, + ) diff --git a/discord/ui/thumbnail.py b/discord/ui/thumbnail.py index fe1d96221..ce178fb4c 100644 --- a/discord/ui/thumbnail.py +++ b/discord/ui/thumbnail.py @@ -48,7 +48,7 @@ class Thumbnail(Item[V]): Parameters ---------- - media: Union[:class:`str`, :class:`UnfurledMediaItem`] + media: Union[:class:`str`, :class:`.UnfurledMediaItem`] The media of the thumbnail. This can be a string that points to a local attachment uploaded within this item. URLs must match the ``attachment://file-name.extension`` structure. diff --git a/discord/ui/view.py b/discord/ui/view.py index 08714bf3a..92ec768fa 100644 --- a/discord/ui/view.py +++ b/discord/ui/view.py @@ -45,6 +45,7 @@ from ..components import ( MediaGalleryComponent, FileComponent, SeparatorComponent, + ThumbnailComponent, ) # fmt: off @@ -86,7 +87,30 @@ def _component_to_item(component: Component) -> Item: from .select import BaseSelect return BaseSelect.from_component(component) - # TODO: convert V2 Components into Item's + if isinstance(component, SectionComponent): + from .section import Section + + return Section.from_component(component) + if isinstance(component, TextDisplayComponent): + from .text_display import TextDisplay + + return TextDisplay.from_component(component) + if isinstance(component, MediaGalleryComponent): + from .media_gallery import MediaGallery + + return MediaGallery.from_component(component) + if isinstance(component, FileComponent): + from .file import File + + return File.from_component(component) + if isinstance(component, SeparatorComponent): + from .separator import Separator + + return Separator.from_component(component) + if isinstance(component, ThumbnailComponent): + from .thumbnail import Thumbnail + + return Thumbnail.from_component(component) return Item.from_component(component) diff --git a/docs/api.rst b/docs/api.rst index 934335c5a..07e04ca77 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5427,8 +5427,6 @@ PollAnswer .. autoclass:: PollAnswer() :members: -.. _discord_api_data: - MessageSnapshot ~~~~~~~~~~~~~~~~~ @@ -5445,6 +5443,16 @@ ClientStatus .. autoclass:: ClientStatus() :members: +CallMessage +~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: CallMessage + +.. autoclass:: CallMessage() + :members: + +.. _discord_api_data: + Data Classes -------------- @@ -5748,12 +5756,21 @@ PollMedia .. autoclass:: PollMedia :members: -CallMessage -~~~~~~~~~~~~~~~~~~~ +UnfurledMediaItem +~~~~~~~~~~~~~~~~~ -.. attributetable:: CallMessage +.. attributetable:: UnfurledMediaItem -.. autoclass:: CallMessage() +.. autoclass:: UnfurledMediaItem + :members: + + +MediaGalleryItem +~~~~~~~~~~~~~~~~ + +.. attributetable:: MediaGalleryItem + +.. autoclass:: MediaGalleryItem :members: diff --git a/docs/interactions/api.rst b/docs/interactions/api.rst index feab66907..df2d7418d 100644 --- a/docs/interactions/api.rst +++ b/docs/interactions/api.rst @@ -113,6 +113,77 @@ TextInput :members: :inherited-members: + +SectionComponent +~~~~~~~~~~~~~~~~ + +.. attributetable:: SectionComponent + +.. autoclass:: SectionComponent() + :members: + :inherited-members: + + +ThumbnailComponent +~~~~~~~~~~~~~~~~~~ + +.. attributetable:: ThumbnailComponent + +.. autoclass:: ThumbnailComponent() + :members: + :inherited-members: + + +TextDisplay +~~~~~~~~~~~ + +.. attributetable:: TextDisplay + +.. autoclass:: TextDisplay() + :members: + :inherited-members: + + +MediaGalleryComponent +~~~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: MediaGalleryComponent + +.. autoclass:: MediaGalleryComponent() + :members: + :inherited-members: + + +FileComponent +~~~~~~~~~~~~~ + +.. attributetable:: FileComponent + +.. autoclass:: FileComponent() + :members: + :inherited-members: + + +SeparatorComponent +~~~~~~~~~~~~~~~~~~ + +.. attributetable:: SeparatorComponent + +.. autoclass:: SeparatorComponent() + :members: + :inherited-members: + + +Container +~~~~~~~~~ + +.. attributetable:: Container + +.. autoclass:: Container() + :members: + :inherited-members: + + AppCommand ~~~~~~~~~~~ @@ -299,7 +370,7 @@ Enumerations .. attribute:: action_row - Represents the group component which holds different components in a row. + Represents a component which holds different components in a row. .. attribute:: button @@ -329,6 +400,38 @@ Enumerations Represents a select in which both users and roles can be selected. + .. attribute:: channel_select + + Represents a channel select component. + + .. attribute:: section + + Represents a component which holds different components in a section. + + .. attribute:: text_display + + Represents a text display component. + + .. attribute:: thumbnail + + Represents a thumbnail component. + + .. attribute:: media_gallery + + Represents a media gallery component. + + .. attribute:: file + + Represents a file component. + + .. attribute:: separator + + Represents a separator component. + + .. attribute:: container + + Represents a component which holds different components in a container. + .. class:: ButtonStyle Represents the style of the button component. @@ -463,6 +566,19 @@ Enumerations The permission is for a user. +.. class:: SeparatorSize + + The separator's size type. + + .. versionadded:: 2.6 + + .. attribute:: small + + A small separator. + .. attribute:: large + + A large separator. + .. _discord_ui_kit: Bot UI Kit @@ -582,6 +698,76 @@ TextInput :members: :inherited-members: + +Container +~~~~~~~~~ + +.. attributetable:: discord.ui.Container + +.. autoclass:: discord.ui.Container + :members: + :inherited-members: + + +File +~~~~ + +.. attributetable:: discord.ui.File + +.. autoclass:: discord.ui.File + :members: + :inherited-members: + + +MediaGallery +~~~~~~~~~~~~ + +.. attributetable:: discord.ui.MediaGallery + +.. autoclass:: discord.ui.MediaGallery + :members: + :inherited-members: + + +Section +~~~~~~~ + +.. attributetable:: discord.ui.Section + +.. autoclass:: discord.ui.Section + :members: + :inherited-members: + + +Separator +~~~~~~~~~ + +.. attributetable:: discord.ui.Separator + +.. autoclass:: discord.ui.Separator + :members: + :inherited-members: + + +TextDisplay +~~~~~~~~~~~ + +.. attributetable:: discord.ui.TextDisplay + +.. autoclass:: discord.ui.TextDisplay + :members: + :inherited-members: + + +Thumbnail +~~~~~~~~~ + +.. attributetable:: discord.ui.Thumbnail + +.. autoclass:: discord.ui.Thumbnail + :members: + :inherited-members: + .. _discord_app_commands: Application Commands