Merge pull request #589 from krittick/ext-menus

Dorukyum · web-flow · commit dec067617b56 · 2021-12-20T20:31:19.000+03:00
Rename ext.menus to ext.pages, fix docs and typing
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -17,7 +17,7 @@ body:
         - The core library
         - discord.ext.commands
         - discord.ext.tasks
-        - discord.ext.menus
+        - discord.ext.pages
         - The documentation
     validations:
       required: true
diff --git a/discord/ext/pages/__init__.py b/discord/ext/pages/__init__.py
@@ -1,5 +1,5 @@
 """
-discord.ext.menus
+discord.ext.pages
 ~~~~~~~~~~~~~~~~~~~~~
 An extension module to provide useful menu options.
 
diff --git a/discord/ext/pages/pagination.py b/discord/ext/pages/pagination.py
@@ -34,12 +34,11 @@ class PaginatorButton(discord.ui.Button):
 
     Parameters
     ----------
-
     button_type: :class:`str`
         The type of button being created.
         Must be one of ``first``, ``prev``, ``next``, or ``last``.
     paginator: :class:`Paginator`
-        The Paginator class where this button will be used
+        The paginator class where this button will be used.
     """
 
     def __init__(self, label, emoji, style, disabled, button_type, paginator):
@@ -69,30 +68,30 @@ class Paginator(discord.ui.View):
     Attributes
     ----------
     current_page: :class:`int`
-        Zero-indexed value showing the current page number
+        A zero-indexed value showing the current page number.
     page_count: :class:`int`
-        Zero-indexed value showing the total number of pages
+        A zero-indexed value showing the total number of pages.
     buttons: Dict[:class:`str`, Dict[:class:`str`, Union[:class:`~PaginatorButton`, :class:`bool`]]]
-        Dictionary containing the :class:`~PaginatorButton` objects included in this Paginator
+        A dictionary containing the :class:`~PaginatorButton` objects included in this paginator.
     user: Optional[Union[:class:`~discord.User`, :class:`~discord.Member`]]
-        The user or member that invoked the Paginator.
+        The user or member that invoked the paginator.
     message: Union[:class:`~discord.Message`, :class:`~discord.WebhookMessage`]
-        The message sent from the Paginator.
+        The message the paginator is attached to.
 
     Parameters
     ----------
     pages: Union[List[:class:`str`], List[:class:`discord.Embed`]]
-        Your list of strings or embeds to paginate
+        The list of strings and/or embeds to paginate.
     show_disabled: :class:`bool`
-        Choose whether or not to show disabled buttons
+        Whether to show disabled buttons.
     show_indicator: :class:`bool`
-        Choose whether to show the page indicator
+        Whether to show the page indicator.
     author_check: :class:`bool`
-        Choose whether or not only the original user of the command can change pages
+        Whether only the original user of the command can change pages.
     disable_on_timeout: :class:`bool`
-        Should the buttons be disabled when the pagintator view times out?
+        Whether the buttons get disabled when the pagintator view times out.
     custom_view: Optional[:class:`discord.ui.View`]
-        A custom view whose items are appended below the pagination buttons
+        A custom view whose items are appended below the pagination buttons.
     """
 
     def __init__(
@@ -104,7 +103,7 @@ def __init__(
         disable_on_timeout=True,
         custom_view: Optional[discord.ui.View] = None,
         timeout: Optional[float] = 180.0,
-    ):
+    ) -> None:
         super().__init__(timeout=timeout)
         self.timeout = timeout
         self.pages = pages
@@ -114,7 +113,7 @@ def __init__(
         self.show_indicator = show_indicator
         self.disable_on_timeout = disable_on_timeout
         self.custom_view = custom_view
-        self.message: Union[discord.Message, discord.WebhookMessage]
+        self.message: Union[discord.Message, discord.WebhookMessage, None] = None
         self.buttons = {
             "first": {
                 "object": PaginatorButton(
@@ -182,7 +181,7 @@ async def on_timeout(self) -> None:
                 item.disabled = True
             await self.message.edit(view=self)
 
-    async def goto_page(self, interaction: discord.Interaction, page_number=0):
+    async def goto_page(self, interaction: discord.Interaction, page_number=0) -> None:
         """Updates the interaction response message to show the specified page number.
 
         Parameters
@@ -195,47 +194,43 @@ async def goto_page(self, interaction: discord.Interaction, page_number=0):
             .. note::
 
                 Page numbers are zero-indexed when referenced internally, but appear as one-indexed when shown to the user.
-
-        Returns
-        ---------
-        :class:`~Paginator`
-            The Paginator class
         """
         self.update_buttons()
         page = self.pages[page_number]
         await interaction.response.edit_message(
             content=page if isinstance(page, str) else None, embed=page if isinstance(page, discord.Embed) else None, view=self
         )
 
-    async def interaction_check(self, interaction):
+    async def interaction_check(self, interaction: discord.Interaction) -> bool:
         if self.usercheck:
             return self.user == interaction.user
         return True
 
     def customize_button(
         self, button_name: str = None, button_label: str = None, button_emoji=None, button_style: discord.ButtonStyle = discord.ButtonStyle.gray
-    ) -> Union[PaginatorButton, bool]:
+    ) -> PaginatorButton:
         """Allows you to easily customize the various pagination buttons.
 
         Parameters
         ----------
         button_name: :class:`str`
-            Name of the button to customize
+            The name of the button to customize.
+            Must be one of ``first``, ``prev``, ``next``, or ``last``.
         button_label: :class:`str`
-            Label to display on the button
+            The label to display on the button.
         button_emoji:
-            Emoji to display on the button
+            The emoji to display on the button.
         button_style: :class:`~discord.ButtonStyle`
-            ButtonStyle to use for the button
+            The ButtonStyle to use for the button.
 
         Returns
         -------
         :class:`~PaginatorButton`
-            The button that was customized
+            The button that was customized.
         """
 
         if button_name not in self.buttons.keys():
-            return False
+            raise ValueError(f"no button named {button_name} was found in this view.")
         button: PaginatorButton = self.buttons[button_name]["object"]
         button.label = button_label
         button.emoji = button_emoji
@@ -248,7 +243,7 @@ def update_buttons(self) -> Dict:
         Returns
         -------
         Dict[:class:`str`, Dict[:class:`str`, Union[:class:`~PaginatorButton`, :class:`bool`]]]
-            The dictionary of buttons that was updated.
+            The dictionary of buttons that were updated.
         """
         for key, button in self.buttons.items():
             if key == "first":
@@ -294,7 +289,7 @@ def update_buttons(self) -> Dict:
 
         return self.buttons
 
-    async def send(self, messageable: abc.Messageable, ephemeral: bool = False):
+    async def send(self, messageable: abc.Messageable, ephemeral: bool = False) -> Union[discord.Message, discord.WebhookMessage]:
         """Sends a message with the paginated items.
 
 
@@ -308,7 +303,7 @@ async def send(self, messageable: abc.Messageable, ephemeral: bool = False):
         Returns
         --------
         Union[:class:`~discord.Message`, :class:`~discord.WebhookMessage`]
-            The message that was sent with the Paginator.
+            The message that was sent with the paginator.
         """
 
         if not isinstance(messageable, abc.Messageable):
@@ -354,7 +349,7 @@ async def respond(self, interaction: discord.Interaction, ephemeral: bool = Fals
         Returns
         --------
         :class:`~discord.Interaction`
-            The message sent with the paginator
+            The message sent with the paginator.
         """
         page = self.pages[0]
         self.user = interaction.user
diff --git a/docs/ext/menus/index.rst b/docs/ext/menus/index.rst
diff --git a/docs/ext/pages/index.rst b/docs/ext/pages/index.rst
@@ -0,0 +1,80 @@
+.. _discord_ext_pages:
+
+``discord.ext.pages`` -- An extension module to provide useful pagination options
+===========================================================================
+
+.. versionadded:: 2.0
+
+This module provides an easy pagination system with buttons.
+
+Example usage in a cog:
+
+.. code-block:: python3
+
+    import discord
+    from discord.commands import slash_command
+    from discord.ext import commands, pages
+
+
+    class PageTest(commands.Cog):
+        def __init__(self, bot):
+            self.bot = bot
+
+            self.pages = [
+                "Page One",  # string (text)
+                discord.Embed(title="Page Two"),  # rich embed
+                discord.Embed(title="Page Three"),  # another rich embed
+            ]
+            self.pages[1].set_image(url="https://c.tenor.com/pPKOYQpTO8AAAAAM/monkey-developer.gif")
+            self.pages[2].add_field(name="Example Field", value="Example Value", inline=False)
+            self.pages[2].add_field(name="Another Example Field", value="Another Example Value", inline=False)
+
+        def get_pages(self):
+            return self.pages
+
+        @slash_command(name="pagetest")
+        async def pagetest(self, ctx):
+            await ctx.defer()
+            # initializing the paginator
+            paginator = menus.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True)
+
+            # customising buttons
+            paginator.customize_button("next", button_label=">", button_style=discord.ButtonStyle.green)
+            paginator.customize_button("prev", button_label="<", button_style=discord.ButtonStyle.green)
+            paginator.customize_button("first", button_label="<<", button_style=discord.ButtonStyle.blurple)
+            paginator.customize_button("last", button_label=">>", button_style=discord.ButtonStyle.blurple)
+
+            # start paginating
+            await paginator.send(ctx, ephemeral=False)
+
+        # using a custom view
+        @slash_command(name="pagetest_custom")
+        async def pagetest_custom(self, ctx):
+            await ctx.defer()
+            view = discord.ui.View()
+            view.add_item(discord.ui.Button(label="Test Button, Does Nothing", row=1))
+            view.add_item(
+                discord.ui.Select(
+                    placeholder="Test Select Menu, Does Nothing",
+                    options=[discord.SelectOption(label="Example Option", value="Example Value", description="This menu does nothing!")],
+                )
+            )
+            paginator = menus.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True, custom_view=view)
+            await paginator.send(ctx, ephemeral=False)
+
+
+    def setup(bot):
+        bot.add_cog(PageTest(bot))
+
+.. _discord_ext_pages_api:
+
+API Reference
+-------------
+
+.. attributetable:: discord.ext.pages.Paginator
+
+.. autoclass:: discord.ext.pages.Paginator
+    :members:
+
+.. autoclass:: discord.ext.pages.PaginatorButton
+    :members:
diff --git a/examples/views/paginator.py b/examples/views/paginator.py
@@ -1,6 +1,8 @@
+# Docs: https://docs.pycord.dev/en/master/ext/pages/index.html
+
 import discord
 from discord.commands import slash_command
-from discord.ext import commands, menus
+from discord.ext import commands, pages
 
 
 class PageTest(commands.Cog):
@@ -22,12 +24,12 @@ def get_pages(self):
     @slash_command(name="pagetest")
     async def pagetest(self, ctx):
         await ctx.defer()
-        pages = menus.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True)
-        pages.customize_button("next", button_label=">", button_style=discord.ButtonStyle.green)
-        pages.customize_button("prev", button_label="<", button_style=discord.ButtonStyle.green)
-        pages.customize_button("first", button_label="<<", button_style=discord.ButtonStyle.blurple)
-        pages.customize_button("last", button_label=">>", button_style=discord.ButtonStyle.blurple)
-        await pages.send(ctx, ephemeral=False)
+        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True)
+        paginator.customize_button("next", button_label=">", button_style=discord.ButtonStyle.green)
+        paginator.customize_button("prev", button_label="<", button_style=discord.ButtonStyle.green)
+        paginator.customize_button("first", button_label="<<", button_style=discord.ButtonStyle.blurple)
+        paginator.customize_button("last", button_label=">>", button_style=discord.ButtonStyle.blurple)
+        await paginator.send(ctx, ephemeral=False)
 
     @slash_command(name="pagetest_custom")
     async def pagetest_custom(self, ctx):
@@ -40,8 +42,8 @@ async def pagetest_custom(self, ctx):
                 options=[discord.SelectOption(label="Example Option", value="Example Value", description="This menu does nothing!")],
             )
         )
-        pages = menus.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True, custom_view=view)
-        await pages.send(ctx, ephemeral=False)
+        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True, custom_view=view)
+        await paginator.send(ctx, ephemeral=False)
 
 
 def setup(bot):
