Port LinePaginator from all bots.

docs/changelog.rst

@@ -4,6 +4,10 @@
 Changelog
 =========
 
+- :release:`10.6.0 <4th January 2024>`
+- :feature:`189` Add :obj:`pydis_core.utils.pagination.LinePaginator` which allows users to paginate over content using Embeds, with emoji reactions facilitating navigation.
+- :feature:`189` Add :obj:`pydis_core.utils.messages.reaction_check`, a predicate that dictates whether a user has the right to add a specific set of reactions based on certain criteria.
+
 - :release:`10.5.1 <14th December 2023>`
 - :bug:`200` Do not attempt to read response body if the HTTP response code is 204. Previously only :obj:`pydis_core.site_api.APIClient.delete` did this.
 

pydis_core/__init__.py

@@ -2,6 +2,7 @@
 
 from pydis_core import async_stats, exts, site_api, utils
 from pydis_core._bot import BotBase, StartupError
+from pydis_core.utils.pagination import EmptyPaginatorEmbedError, LinePaginator, PaginationEmojis
 
 __all__ = [
     async_stats,
@@ -10,6 +11,9 @@
     utils,
     site_api,
     StartupError,
+    LinePaginator,
+    PaginationEmojis,
+    EmptyPaginatorEmbedError
 ]
 
 __all__ = [module.__name__ for module in __all__]

pydis_core/utils/__init__.py

@@ -11,6 +11,8 @@
     interactions,
     logging,
     members,
+    messages,
+    pagination,
     paste_service,
     regex,
     scheduling,
@@ -45,6 +47,8 @@ def apply_monkey_patches() -> None:
     interactions,
     logging,
     members,
+    messages,
+    pagination,
     paste_service,
     regex,
     scheduling,

pydis_core/utils/messages.py

@@ -0,0 +1,47 @@
+from collections.abc import Sequence
+
+import discord
+
+from pydis_core.utils.logging import get_logger
+from pydis_core.utils.scheduling import create_task
+
+log = get_logger(__name__)
+
+
+def reaction_check(
+    reaction: discord.Reaction,
+    user: discord.abc.User,
+    *,
+    message_id: int,
+    allowed_emoji: Sequence[str],
+    allowed_users: Sequence[int],
+    allowed_roles: Sequence[int] | None = None,
+) -> bool:
+    """
+    Check if a reaction's emoji and author are allowed and the message is `message_id`.
+
+    If the user is not allowed, remove the reaction. Ignore reactions made by the bot.
+    If `allow_mods` is True, allow users with moderator roles even if they're not in `allowed_users`.
+    """
+    right_reaction = (
+        not user.bot
+        and reaction.message.id == message_id
+        and str(reaction.emoji) in allowed_emoji
+    )
+    if not right_reaction:
+        return False
+
+    allowed_roles = allowed_roles or []
+    has_sufficient_roles = any(role.id in allowed_roles for role in getattr(user, "roles", []))
+
+    if user.id in allowed_users or has_sufficient_roles:
+        log.trace(f"Allowed reaction {reaction} by {user} on {reaction.message.id}.")
+        return True
+
+    log.trace(f"Removing reaction {reaction} by {user} on {reaction.message.id}: disallowed user.")
+    create_task(
+        reaction.message.remove_reaction(reaction.emoji, user),
+        suppressed_exceptions=(discord.HTTPException,),
+        name=f"remove_reaction-{reaction}-{reaction.message.id}-{user}"
+    )
+    return False