Pycord-Development · NeloBlivion · Dec 23, 2025 · Dec 23, 2025 · Dec 23, 2025 · Dec 23, 2025
@@ -12,6 +12,8 @@ These changes are available on the `master` branch, but have not yet been releas
 
 ### Added
 
+- Added `replace_item` to `DesignerView`, `Section`, `Container`, `ActionRow`, &
+  `MediaGallery` ([#3032](https://github.com/Pycord-Development/pycord/pull/3032))
 - Added support for community invites.
   ([#3044](https://github.com/Pycord-Development/pycord/pull/3044))
 - Added `Member.colours` and `Member.colors` properties.

@@ -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
@@ -914,6 +916,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]

@@ -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,31 @@ def get_component(self, id: str | int) -> Component | None:
                     return component
         return None
 
+    def get_view(self, cls: BaseView | None = None) -> 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``.
+
+        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 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

@@ -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:
+        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)
 

@@ -179,6 +179,36 @@ def remove_item(self, item: ViewItem | str | int) -> Self:
             pass
         return self
 
+    def replace_item(
+        self, original_item: ViewItem | str | int, new_item: ViewItem
+    ) -> Self:
+        """Directly replace an item in this row.
+        If an :class:`int` is provided, the item will be replaced by ``id``, otherwise by  ``custom_id``.
+
+        Parameters
+        ----------
+        original_item: Union[:class:`ViewItem`, :class:`int`, :class:`str`]
+            The item, item ``id``, or item ``custom_id`` to replace in the row.
+        new_item: :class:`ViewItem`
+            The new item to insert into the row.
+        """
+
+        if not isinstance(new_item, (Select, Button)):
+            raise TypeError(f"expected Select or Button, not {new_item.__class__!r}")
+
+        if isinstance(original_item, (str, int)):
+            original_item = self.get_item(original_item)
+        if not original_item:
+            raise ValueError(f"Could not find original_item in row.")
+        try:
+            i = self.children.index(original_item)
+            new_item.parent = self
+            self.children[i] = new_item
+            original_item.parent = None
+        except ValueError:
+            raise ValueError(f"Could not find original_item in row.")
+        return self
+
     def get_item(self, id: str | int) -> ViewItem | None:
         """Get an item from this action row. Roughly equivalent to `utils.get(row.children, ...)`.
         If an ``int`` is provided, the item will be retrieved by ``id``, otherwise by ``custom_id``.

@@ -195,6 +195,36 @@ def remove_item(self, item: ViewItem | str | int) -> Self:
             pass
         return self
 
+    def replace_item(
+        self, original_item: ViewItem | str | int, new_item: ViewItem
+    ) -> Self:
+        """Directly replace an item in this container.
+        If an :class:`int` is provided, the item will be replaced by ``id``, otherwise by  ``custom_id``.
+
+        Parameters
+        ----------
+        original_item: Union[:class:`ViewItem`, :class:`int`, :class:`str`]
+            The item, item ``id``, or item ``custom_id`` to replace in the container.
+        new_item: :class:`ViewItem`
+            The new item to insert into the container.
+        """
+
+        if isinstance(original_item, (str, int)):
+            original_item = self.get_item(original_item)
+        if not original_item:
+            raise ValueError(f"Could not find original_item in container.")
+        try:
+            if original_item.parent is self:
+                i = self.items.index(original_item)
+                new_item.parent = self
+                self.items[i] = new_item
+                original_item.parent = None
+            else:
+                original_item.parent.replace_item(original_item, new_item)
+        except ValueError:
+            raise ValueError(f"Could not find original_item in container.")
+        return self
+
     def get_item(self, id: str | int) -> ViewItem | None:
         """Get an item from this container. Roughly equivalent to `utils.get(container.items, ...)`.
         If an ``int`` is provided, the item will be retrieved by ``id``, otherwise by ``custom_id``.

@@ -27,6 +27,7 @@
 import asyncio
 import time
 from itertools import groupby
+from operator import attrgetter
 from typing import TYPE_CHECKING, Any, Callable
 
 from ..utils import find, get
@@ -115,30 +116,68 @@ def _dispatch_timeout(self):
     def to_components(self) -> list[dict[str, Any]]:
         return [item.to_component_dict() for item in self.children]
 
-    def get_item(self, custom_id: str | int) -> Item | None:
-        """Gets an item from this structure. Roughly equal to `utils.get(self.children, ...)`.
+    def get_item(self, custom_id: str | int | None = None, **attrs: Any) -> Item | None:
+        r"""Gets an item from this structure. Roughly equal to `utils.get(self.children, **attrs)`.
         If an :class:`int` is provided, the item will be retrieved by ``id``, otherwise by  ``custom_id``.
         This method will also search nested items.
+        If ``attrs`` are provided, it will check them by logical AND as done in :func:`~utils.get`.
+        To have a nested attribute search (i.e. search by ``x.y``) then pass in ``x__y`` as the keyword argument.
+
+        Examples
+        ---------
+
+        Basic usage:
+
+        .. code-block:: python3
+
+            container = my_view.get(1234)
+
+        Attribute matching:
+
+        .. code-block:: python3
+
+            button = my_view.get(label='Click me!', style=discord.ButtonStyle.danger)
 
         Parameters
         ----------
-        custom_id: Union[:class:`str`, :class:`int`]
+        custom_id: Optional[Union[:class:`str`, :class:`int`]]
             The id of the item to get
+        \*\*attrs
+            Keyword arguments that denote attributes to search with.
 
         Returns
         -------
         Optional[:class:`Item`]
-            The item with the matching ``custom_id`` or ``id`` if it exists.
+            The item with the matching ``custom_id``, ``id``, or ``attrs`` if it exists.
         """
-        if not custom_id:
+        if not (custom_id or attrs):
             return None
-        attr = "id" if isinstance(custom_id, int) else "custom_id"
-        child = find(lambda i: getattr(i, attr, None) == custom_id, self.children)
-        if not child:
+        child = None
+        if custom_id:
+            attr = "id" if isinstance(custom_id, int) else "custom_id"
+            child = find(lambda i: getattr(i, attr, None) == custom_id, self.children)
+            if not child:
+                for i in self.children:
+                    if hasattr(i, "get_item"):
+                        if child := i.get_item(custom_id):
+                            return child
+        elif attrs:
+            _all = all
+            attrget = attrgetter
             for i in self.children:
+                converted = [
+                    (attrget(attr.replace("__", ".")), value)
+                    for attr, value in attrs.items()
+                ]
+                try:
+                    if _all(pred(i) == value for pred, value in converted):
+                        return i
+                except:
+                    pass
                 if hasattr(i, "get_item"):
-                    if child := i.get_item(custom_id):
+                    if child := i.get_item(custom_id, **attrs):
                         return child
+
         return child
 
     def add_item(self, item: Item) -> Self:

@@ -168,6 +168,22 @@ def remove_item(self, index: int) -> Self:
             pass
         return self
 
+    def replace_item(self, index: int, new_item: MediaGalleryItem) -> Self:
+        """Directly replace an item in this gallery by index.
+
+        Parameters
+        ----------
+        original_item: :class:`int`
+            The index of the item to replace in this gallery.
+        new_item: :class:`MediaGalleryItem`
+            The new item to insert into the gallery.
+        """
+
+        if not isinstance(new_item, MediaGalleryItem):
+            raise TypeError(f"expected MediaGalleryItem not {new_item.__class__!r}")
+        self._underlying.items[index] = new_item
+        return self
+
     def to_component_dict(self) -> MediaGalleryComponentPayload:
         self._underlying = self._generate_underlying()
         return super().to_component_dict()

@@ -186,6 +186,39 @@ def remove_item(self, item: ViewItem | str | int) -> Self:
             pass
         return self
 
+    def replace_item(
+        self, original_item: ViewItem | str | int, new_item: ViewItem
+    ) -> Self:
+        """Directly replace an item in this section.
+        If an :class:`int` is provided, the item will be replaced by ``id``, otherwise by  ``custom_id``.
+
+        Parameters
+        ----------
+        original_item: Union[:class:`ViewItem`, :class:`int`, :class:`str`]
+            The item, item ``id``, or item ``custom_id`` to replace in the section.
+        new_item: :class:`ViewItem`
+            The new item to insert into the section.
+        """
+
+        if not isinstance(new_item, ViewItem):
+            raise TypeError(f"expected ViewItem not {new_item.__class__!r}")
+
+        if isinstance(original_item, (str, int)):
+            original_item = self.get_item(original_item)
+        if not original_item:
+            raise ValueError(f"Could not find original_item in section.")
+        try:
+            if original_item is self.accessory:
+                self.accessory = new_item
+            else:
+                i = self.items.index(original_item)
+                self.items[i] = new_item
+            original_item.parent = None
+            new_item.parent = self
+        except ValueError:
+            raise ValueError(f"Could not find original_item in section.")
+        return self
+
     def get_item(self, id: int | str) -> ViewItem | None:
         """Get an item from this section. Alias for `utils.get(section.walk_items(), ...)`.
         If an ``int`` is provided, it will be retrieved by ``id``, otherwise it will check the accessory's ``custom_id``.