Merge pull request #895 from krittick/ext-pages-stop-remove

[ext.pages] Add disable/cancel methods to `Paginator` class

Author: krittick

discord/ext/pages/pagination.py

@@ -80,7 +80,7 @@ def __init__(
         )
         self.button_type = button_type
         self.label = label if label or emoji else button_type.capitalize()
-        self.emoji = emoji
+        self.emoji: Union[str, discord.Emoji, discord.PartialEmoji] = emoji
         self.style = style
         self.disabled = disabled
         self.loop_label = self.label if not loop_label else loop_label
@@ -170,18 +170,20 @@ def __init__(
     ):
         self.label = label
         self.description = description
-        self.emoji = emoji
-        self.pages = pages
+        self.emoji: Union[str, discord.Emoji, discord.PartialEmoji] = emoji
+        self.pages: Union[
+            List[str], List[Union[List[discord.Embed], discord.Embed]]
+        ] = pages
         self.show_disabled = show_disabled
         self.show_indicator = show_indicator
         self.author_check = author_check
         self.disable_on_timeout = disable_on_timeout
         self.use_default_buttons = use_default_buttons
         self.default_button_row = default_button_row
         self.loop_pages = loop_pages
-        self.custom_view = custom_view
-        self.timeout = timeout
-        self.custom_buttons = custom_buttons
+        self.custom_view: discord.ui.View = custom_view
+        self.timeout: float = timeout
+        self.custom_buttons: List = custom_buttons
 
 
 class Paginator(discord.ui.View):
@@ -252,27 +254,31 @@ def __init__(
         custom_buttons: Optional[List[PaginatorButton]] = None,
     ) -> None:
         super().__init__(timeout=timeout)
-        self.timeout = timeout
-        self.pages = pages
+        self.timeout: float = timeout
+        self.pages: Union[
+            List[PageGroup], List[str], List[Union[List[discord.Embed], discord.Embed]]
+        ] = pages
         self.current_page = 0
         self.menu: Optional[PaginatorMenu] = None
         self.show_menu = show_menu
         self.page_groups: Optional[List[PageGroup]] = None
 
         if all(isinstance(pg, PageGroup) for pg in pages):
             self.page_groups = self.pages if show_menu else None
-            self.pages = self.page_groups[0].pages
+            self.pages: Union[
+                List[str], List[Union[List[discord.Embed], discord.Embed]]
+            ] = self.page_groups[0].pages
 
         self.page_count = len(self.pages) - 1
         self.buttons = {}
-        self.custom_buttons = custom_buttons
+        self.custom_buttons: List = custom_buttons
         self.show_disabled = show_disabled
         self.show_indicator = show_indicator
         self.disable_on_timeout = disable_on_timeout
         self.use_default_buttons = use_default_buttons
         self.default_button_row = default_button_row
         self.loop_pages = loop_pages
-        self.custom_view = custom_view
+        self.custom_view: discord.ui.View = custom_view
         self.message: Union[discord.Message, discord.WebhookMessage, None] = None
 
         if self.custom_buttons and not self.use_default_buttons:
@@ -333,7 +339,9 @@ async def update(
         """
 
         # Update pages and reset current_page to 0 (default)
-        self.pages = pages if pages is not None else self.pages
+        self.pages: Union[
+            List[PageGroup], List[str], List[Union[List[discord.Embed], discord.Embed]]
+        ] = (pages if pages is not None else self.pages)
         self.page_count = len(self.pages) - 1
         self.current_page = 0
         # Apply config changes, if specified
@@ -360,8 +368,8 @@ async def update(
             else self.default_button_row
         )
         self.loop_pages = loop_pages if loop_pages is not None else self.loop_pages
-        self.custom_view = None if custom_view is None else custom_view
-        self.timeout = timeout if timeout is not None else self.timeout
+        self.custom_view: discord.ui.View = None if custom_view is None else custom_view
+        self.timeout: float = timeout if timeout is not None else self.timeout
         if custom_buttons and not self.use_default_buttons:
             self.buttons = {}
             for button in custom_buttons:
@@ -379,6 +387,61 @@ async def on_timeout(self) -> None:
                 item.disabled = True
             await self.message.edit(view=self)
 
+    async def disable(
+        self,
+        include_custom: bool = False,
+        page: Optional[Union[str, Union[List[discord.Embed], discord.Embed]]] = None,
+    ) -> None:
+        """Stops the paginator, disabling all of its components.
+
+        Parameters
+        ----------
+        include_custom: :class:`bool`
+            Whether to disable components added via custom views.
+        page: Optional[Union[:class:`str`, Union[List[:class:`discord.Embed`], :class:`discord.Embed`]]]
+            The page content to show after disabling the paginator.
+        """
+        page = self.get_page_content(page)
+        for item in self.children:
+            if item not in self.custom_view.children or include_custom:
+                item.disabled = True
+        if page:
+            await self.message.edit(
+                content=page if isinstance(page, str) else None,
+                embeds=[] if isinstance(page, str) else page,
+                view=self,
+            )
+        else:
+            await self.message.edit(view=self)
+
+    async def cancel(
+        self,
+        include_custom: bool = False,
+        page: Optional[Union[str, Union[List[discord.Embed], discord.Embed]]] = None,
+    ) -> None:
+        """Cancels the paginator, removing all of its components from the message.
+
+        Parameters
+        ----------
+        include_custom: :class:`bool`
+            Whether to remove components added via custom views.
+        page: Optional[Union[:class:`str`, Union[List[:class:`discord.Embed`], :class:`discord.Embed`]]]
+            The page content to show after canceling the paginator.
+        """
+        items = self.children.copy()
+        page = self.get_page_content(page)
+        for item in items:
+            if item not in self.custom_view.children or include_custom:
+                self.remove_item(item)
+        if page:
+            await self.message.edit(
+                content=page if isinstance(page, str) else None,
+                embeds=[] if isinstance(page, str) else page,
+                view=self,
+            )
+        else:
+            await self.message.edit(view=self)
+
     async def goto_page(self, page_number=0) -> discord.Message:
         """Updates the paginator message to show the specified page number.
 
@@ -559,7 +622,6 @@ def update_buttons(self) -> Dict:
         if self.custom_view:
             for item in self.custom_view.children:
                 self.add_item(item)
-
         return self.buttons
 
     @staticmethod

examples/views/paginator.py

@@ -182,6 +182,26 @@ async def pagetest_custom_view(self, ctx: discord.ApplicationContext):
         paginator = pages.Paginator(pages=self.get_pages(), custom_view=view)
         await paginator.respond(ctx.interaction, ephemeral=False)
 
+    @pagetest.command(name="disable")
+    async def pagetest_disable(self, ctx: discord.ApplicationContext):
+        """Demonstrates disabling the paginator buttons and showing a custom page when disabled."""
+        paginator = pages.Paginator(pages=self.get_pages())
+        await paginator.respond(ctx.interaction, ephemeral=False)
+        await ctx.respond("Disabling paginator in 5 seconds...")
+        await asyncio.sleep(5)
+        disable_page = discord.Embed(title="Paginator Disabled!", description="This page is only shown when the paginator is disabled.")
+        await paginator.disable(page=disable_page)
+
+    @pagetest.command(name="cancel")
+    async def pagetest_cancel(self, ctx: discord.ApplicationContext):
+        """Demonstrates canceling (stopping) the paginator and showing a custom page when cancelled."""
+        paginator = pages.Paginator(pages=self.get_pages())
+        await paginator.respond(ctx.interaction, ephemeral=False)
+        await ctx.respond("Canceling paginator in 5 seconds...")
+        await asyncio.sleep(5)
+        cancel_page = discord.Embed(title="Paginator Cancelled!", description="This page is only shown when the paginator is cancelled.")
+        await paginator.cancel(page=cancel_page)
+
     @pagetest.command(name="groups")
     async def pagetest_groups(self, ctx: discord.ApplicationContext):
         """Demonstrates using page groups to switch between different sets of pages."""