feat: General enhancements for views

CHANGELOG.md

@@ -12,6 +12,19 @@ These changes are available on the `master` branch, but have not yet been releas
 
 ### Added
 
+- Added `replace_item` to `DesignerView`, `Section`, `Container`, `ActionRow`, &
+  `MediaGallery` ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+- Added `index`, `before`, and `after` to `add_item` functions
+  ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+- Added arbitrary kwarg support to `get_item` functions
+  ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+- Added `Message.get_view`
+  ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+- Added `from_dict`, `add_label`, & `add_text` to `DesignerModal`
+  ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+- Added `read`, `save`, and `to_file` to `UnfurledMediaItem`
+  ([#3093](https://github.com/Pycord-Development/pycord/pull/3093))
+
 ### Changed
 
 ### Fixed

discord/asset.py

@@ -28,6 +28,7 @@
 import io
 import os
 from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlparse
 
 import yarl
 
@@ -122,6 +123,12 @@ async def save(
             with open(fp, "wb") as f:
                 return f.write(data)
 
+    @property
+    def cdn_name(self) -> str | None:
+        """Attempts to return the filename within this asset's URL, if present."""
+        parsed = urlparse(self.url)
+        return os.path.basename(parsed.path)
+
 
 class Asset(AssetMixin):
     """Represents a CDN asset on Discord.

discord/components.py

@@ -25,7 +25,10 @@
 
 from __future__ import annotations
 
+import io
+from os import PathLike, path
 from typing import TYPE_CHECKING, Any, ClassVar, Iterator, TypeVar, overload
+from urllib.parse import urlparse
 
 from .asset import AssetMixin
 from .colour import Colour
@@ -38,6 +41,7 @@
     SeparatorSpacingSize,
     try_enum,
 )
+from .file import File
 from .flags import AttachmentFlags
 from .partial_emoji import PartialEmoji, _EmojiTag
 from .utils import MISSING, find, get_slots
@@ -956,6 +960,138 @@ def url(self, value: str) -> None:
             value if value and value.startswith("attachment://") else None
         )
 
+    @property
+    def resolved_name(self) -> str | None:
+        """Attempts to return the filename within this media's URL, if present."""
+        if self.url.startswith("attachment://"):
+            return self.url.replace("attachment://", "")
+        else:
+            parsed = urlparse(self.url)
+            return path.basename(parsed.path)
+
+    async def save(
+        self,
+        fp: io.BufferedIOBase | PathLike,
+        *,
+        seek_begin: bool = True,
+    ) -> int:
+        """|coro|
+
+        Saves this media into a file-like object.
+
+        Parameters
+        ----------
+        fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]
+            The file-like object to save this media to or the filename
+            to use. If a filename is passed then a file is created with that
+            filename and used instead.
+        seek_begin: :class:`bool`
+            Whether to seek to the beginning of the file after saving is
+            successfully done.
+
+        Returns
+        -------
+        :class:`int`
+            The number of bytes written.
+
+        Raises
+        ------
+        HTTPException
+            Saving the media failed.
+        NotFound
+            The media was deleted.
+        ValueError
+            You attempted to download from a local ``attachment://`` URL.
+        """
+        data = await self.read()
+
+        if isinstance(fp, io.BufferedIOBase):
+            written = fp.write(data)
+            if seek_begin:
+                fp.seek(0)
+            return written
+        else:
+            with open(fp, "wb") as f:
+                return f.write(data)
+
+    async def read(self) -> bytes:
+        """|coro|
+
+        Retrieves the content of this media as a :class:`bytes` object.
+
+        Returns
+        -------
+        :class:`bytes`
+            The contents of the media.
+
+        Raises
+        ------
+        HTTPException
+            Downloading the media failed.
+        Forbidden
+            You do not have permissions to access this media.
+        NotFound
+            The media was deleted.
+        ValueError
+            You attempted to download from a local ``attachment://`` URL.
+        """
+        if self.url.startswith("attachment://"):
+            raise ValueError("cannot download a local media URL.")
+        if not self._state:
+            raise RuntimeError("can only read when media is received from Discord.")
+        return await self._state.http.get_from_cdn(self.url)
+
+    async def to_file(
+        self,
+        filename: str | None = None,
+        *,
+        description: str | None = None,
+        spoiler: bool = False,
+    ) -> File:
+        """|coro|
+
+        Converts the media into a :class:`discord.File` suitable for sending via
+        :meth:`abc.Messageable.send`.
+
+        Parameters
+        ----------
+        filename: :class:`str`
+            The name to initialize this file with. Defaults to :attr:`resolved_name` if available.
+        description: Optional[:class:`str`]
+            The description of this file.
+        spoiler: :class:`bool`
+            Whether the file is a spoiler.
+
+        Returns
+        -------
+        :class:`File`
+            The media as a file suitable for sending.
+
+        Raises
+        ------
+        HTTPException
+            Downloading the media failed.
+        Forbidden
+            You do not have permissions to access this media
+        NotFound
+            The media was deleted.
+        ValueError
+            You attempted to download from a local ``attachment://`` URL.
+        """
+        name = filename or self.resolved_name
+        if not name:
+            raise ValueError(
+                "no resolved_name available, please provide filename manually."
+            )
+
+        data = await self.read()
+        return File(
+            io.BytesIO(data),
+            filename=name,
+            spoiler=spoiler,
+            description=description,
+        )
+
     @classmethod
     def from_dict(cls, data: UnfurledMediaItemPayload, state=None) -> UnfurledMediaItem:
         r = cls(data.get("url"))
@@ -1050,6 +1186,9 @@ def __init__(self, url, *, description=None, spoiler=False):
         self.description: str | None = description
         self.spoiler: bool = spoiler
 
+    def __repr__(self) -> str:
+        return f"<MediaGalleryItem url={self.url!r} spoiler={self.spoiler!r}>"
+
     @property
     def url(self) -> str:
         return self.media.url
@@ -1347,7 +1486,7 @@ class Label(Component):
 
     def __init__(self, data: LabelComponentPayload):
         self.type: ComponentType = try_enum(ComponentType, data["type"])
-        self.id: int = data["id"]
+        self.id: int = data.get("id")
         self.component: Component = _component_factory(data["component"])
         self.label: str = data["label"]
         self.description: str | None = data.get("description")

discord/ext/pages/pagination.py

@@ -27,6 +27,8 @@
 import contextlib
 from typing import List
 
+from typing_extensions import Self
+
 import discord
 from discord.errors import DiscordException
 from discord.ext.bridge import BridgeContext
@@ -916,6 +918,12 @@ def update_custom_view(self, custom_view: discord.ui.View):
         for item in custom_view.children:
             self.add_item(item)
 
+    def clear_items(self) -> Self:
+        # Necessary override due to behavior of Item.parent, see #3057
+        self.children.clear()
+        self._View__weights.clear()
+        return self
+
     def get_page_group_content(self, page_group: PageGroup) -> list[Page]:
         """Returns a converted list of `Page` objects for the given page group based on the content of its pages."""
         return [self.get_page_content(page) for page in page_group.pages]

discord/message.py

@@ -93,7 +93,7 @@
     from .types.snowflake import SnowflakeList
     from .types.threads import ThreadArchiveDuration
     from .types.user import User as UserPayload
-    from .ui.view import BaseView
+    from .ui.view import BaseView, DesignerView
     from .user import User
 
     MR = TypeVar("MR", bound="MessageReference")
@@ -2345,6 +2345,35 @@ def get_component(self, id: str | int) -> Component | None:
                     return component
         return None
 
+    def get_view(
+        self, cls: BaseView | None = None, force: bool = False
+    ) -> DesignerView | BaseView | None:
+        """Retrieve this message's view from the ViewStore. If there is no stored view, a new view will be returned if :attr:`components` is not empty.
+
+        Parameters
+        ----------
+        cls
+            The class that will be used to generate the new view.
+            By default, this is :class:`discord.ui.DesignerView`. Should a custom
+            class be provided, it must inherit from :class:`discord.ui.BaseView`
+            and properly implement ``from_message``.
+        force: :class:`bool`
+            When set to ``True``, this will ignore the ViewStore and forcibly create a new view.
+
+        Returns
+        -------
+        Optional[Union[:class:`discord.ui.DesignerView`, :class:`discord.ui.BaseView`]]
+            The view belonging to this message, if it exists or there are components available to create a new view.
+        """
+        v = self._state.get_message_view(self.id) if not force else None
+        if not v and self.components:
+            if not cls:
+                from .ui.view import DesignerView
+
+                cls = DesignerView
+            v = cls.from_message(self)
+        return v
+
 
 class PartialMessage(Hashable):
     """Represents a partial message to aid with working messages when only

discord/state.py

@@ -418,6 +418,9 @@ def store_view(self, view: BaseView, message_id: int | None = None) -> None:
     def purge_message_view(self, message_id: int) -> None:
         self._view_store.remove_message_view(message_id)
 
+    def get_message_view(self, message_id: int) -> BaseView | None:
+        return self._view_store.get_message_view(message_id)
+
     def store_modal(self, modal: BaseModal, message_id: int) -> None:
         self._modal_store.add_modal(modal, message_id)
 

discord/types/components.py

@@ -47,6 +47,12 @@ class BaseComponent(TypedDict):
     id: NotRequired[int]
 
 
+class Modal(TypedDict):
+    custom_id: str
+    title: str
+    components: list[AllowedModalComponents]
+
+
 class ActionRow(BaseComponent):
     type: Literal[1]
     components: list[AllowedActionRowComponents]
@@ -254,3 +260,9 @@ class CheckboxComponent(BaseComponent):
     CheckboxComponent,
     CheckboxGroupComponent,
 ]
+
+AllowedModalComponents = Union[
+    ActionRow,
+    LabelComponent,
+    TextDisplayComponent,
+]