feat: support format_page returning list of embeds

docs/ext/menus/reaction_menus.rst

@@ -131,5 +131,6 @@ For the sake of example, here’s a basic list source that is paginated:
         await pages.start(ctx)
 
 The :meth:`PageSource.format_page` can return either a :class:`str` for content,
-:class:`nextcord.Embed` for an embed, or a :class:`dict` to pass into the kwargs
+:class:`nextcord.Embed` for an embed, :class:`List[nextcord.Embed]` for
+sending multiple embeds, or a :class:`dict` to pass into the kwargs
 of :meth:`nextcord.Message.edit`.

nextcord/ext/menus/constants.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, Union
+from typing import Dict, List, Union
 
 import nextcord
 
@@ -15,7 +15,7 @@
 SendKwargsType = Dict[str, Union[str, nextcord.Embed, nextcord.ui.View, None]]
 
 # type definition for possible page formats
-PageFormatType = Union[str, nextcord.Embed, SendKwargsType]
+PageFormatType = Union[str, nextcord.Embed, List[nextcord.Embed], SendKwargsType]
 
 # type definition for emoji parameters
 EmojiType = Union[str, nextcord.Emoji, nextcord.PartialEmoji]

nextcord/ext/menus/menu_pages.py

@@ -77,16 +77,32 @@ async def _get_kwargs_from_page(self, page: List[Any]) -> SendKwargsType:
         """|coro|
 
         Calls :meth:`PageSource.format_page` and returns a dict of send kwargs
+
+        Raises
+        --------
+        TypeError
+            The return value of :meth:`PageSource.format_page` was not a
+            :class:`str`, :class:`nextcord.Embed`, :class:`List[nextcord.Embed]`,
+            or :class:`dict`.
         """
         value: PageFormatType = await nextcord.utils.maybe_coroutine(
             self._source.format_page, self, page
         )
         if isinstance(value, dict):
             return value
         elif isinstance(value, str):
-            return {"content": value, "embed": None}
+            return {"content": value}
         elif isinstance(value, nextcord.Embed):
-            return {"embed": value, "content": None}
+            return {"embed": value}
+        elif isinstance(value, list) and all(
+            isinstance(v, nextcord.Embed) for v in value
+        ):
+            return {"embeds": value}
+        raise TypeError(
+            "Expected {0!r} not {1.__class__!r}.".format(
+                (dict, str, nextcord.Embed, List[nextcord.Embed]), value
+            )
+        )
 
     async def show_page(self, page_number: int):
         """|coro|
@@ -323,6 +339,13 @@ async def show_page(self, page_number: int):
     async def _get_kwargs_from_page(self, page: List[Any]) -> SendKwargsType:
         """|coro|
         Calls :meth:`PageSource.format_page` and returns a dict of send kwargs
+
+        Raises
+        --------
+        TypeError
+            The return value of :meth:`PageSource.format_page` was not a
+            :class:`str`, :class:`nextcord.Embed`, :class:`List[nextcord.Embed]`,
+            or :class:`dict`.
         """
         kwargs = await super()._get_kwargs_from_page(page)
         # add view to kwargs if it's not already there

nextcord/ext/menus/page_source.py

@@ -112,18 +112,22 @@ async def format_page(self, menu: Menu, page: Any) -> PageFormatType:
 
         This method must return one of the following types.
 
-        If this method returns a ``str`` then it is interpreted as returning
+        If this method returns a :class:`str` then it is interpreted as returning
         the ``content`` keyword argument in :meth:`nextcord.Message.edit`
         and :meth:`nextcord.abc.Messageable.send`.
 
         If this method returns a :class:`nextcord.Embed` then it is interpreted
         as returning the ``embed`` keyword argument in :meth:`nextcord.Message.edit`
         and :meth:`nextcord.abc.Messageable.send`.
 
-        If this method returns a ``dict`` then it is interpreted as the
+        If this method returns a :class:`List[nextcord.Embed]` then it is interpreted
+        as returning the ``embeds`` keyword argument in :meth:`nextcord.Message.edit`
+        and :meth:`nextcord.abc.Messageable.send`.
+
+        If this method returns a :class:`dict` then it is interpreted as the
         keyword-arguments that are used in both :meth:`nextcord.Message.edit`
-        and :meth:`nextcord.abc.Messageable.send`. The two of interest are
-        ``embed`` and ``content``.
+        and :meth:`nextcord.abc.Messageable.send`. A few of interest are:
+        ``content``, ``embed``, ``embeds``, ``file``, ``files``.
 
         Parameters
         ------------