Skip to main content

A view-based paginator library for discord.py 2.0

Project description

discord-ext-pager

PyPI

A simple view-based paginator library for discord.py 2.0. Works with Python 3.8+.

Usage

discord-ext-pager is available on PyPI, and as such can be installed using pip.

Users of Danny's discord-ext-menus will find some familiarity in this library. Provided are the following classes:

  • PaginatorView: The view class that manages pagination and navigation.
  • PageSource: The base class for sources the paginator view can accept.
  • ListPageSource: The base class for formatting a list of items.
  • AsyncIteratorPageSource: The base class for formatting an asynchronous iterator of items.
  • PageOption: A subclass of discord.SelectOption used for presenting navigation options.
  • StopAction: An enum for customizing PaginatorView's stop button behaviour.
  • TimeoutAction: An enum for customizing PaginatorView's timeout behaviour.

The PaginatorView can be instantiated and used by itself, but page formatting is handled by subclassing one of the PageSource base classes.

from typing import List
from discord.ext.pager import ListPageSource, PageSource, PaginatorView

class EmbedListPageSource(ListPageSource[object, PageSource, PaginatorView]):
    #                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    #            These type parameters denote the page item type,
    #            source type for page options (demonstrated later),
    #            and view type. Only needed for static typing.
    """Takes a list of items and formats it in an embed."""

    def format_page(self, view: PaginatorView, page: List[object]):
        index = self.current_index * self.page_size
        description = "\n".join(
            f"{i}. {x}"
            for i, x in enumerate(page, start=index + 1)
        )
        return discord.Embed(description=description)

# Anywhere a channel or interaction is available:
fruits = ["🍎 Apple", "🍊 Orange", "🍋 Lemon"]
source = EmbedListPageSource(fruits, page_size=2)
view = PaginatorView(sources=source, timeout=180)
await view.start(interaction)

If the navigation select menu is desired, the get_page_options() method should be overridden to return a list of PageOption objects for the user to select from:

from typing import List
from discord.ext.pager import ListPageSource, PageOption, PageSource, PaginatorView

class MessageSource(PageSource[str, PageSource, PaginatorView]):
    """A single page for displaying a string."""

    def __init__(self, message: str):
        super().__init__(current_index=0)
        self.message = message

    def get_page(self, index: int):
        return self.message

    def format_page(self, view: PaginatorView, page: str):
        # If we don't specify both content and embed, either will
        # persist as the user clicks between options
        return {"content": page, "embed": None}

class MessageNavigator(ListPageSource[MessageSource, MessageSource, PaginatorView]):
    """A list of messages for the user to select from."""

    def get_page_options(self, view: PaginatorView, page: List[MessageSource]):
        # PageOption() takes the same arguments as discord.SelectOption,
        # except that source= is also required
        return [PageOption(source=source, label=source.message) for source in page]

    def format_page(self, view: PaginatorView, page: List[MessageSource]):
        description = "\n".join(source.message for source in page)
        embed = discord.Embed(description=description)
        return {"content": None, "embed": embed}

hands = "👈👉👆👇🫵🤞🫰🤘🤙🤛🤜✊👊👋👏🙌"
source = MessageNavigator([MessageSource(s) for s in hands], page_size=5)
view = PaginatorView(sources=source)
await view.start(ctx)

When an option is selected, the PageSource contained within that option is appended to PaginatorView.sources, causing that source to be displayed. Another button is automatically provided for users to back out to the last page source. This can be manually triggered by passing a list of page sources to the PaginatorView(sources=) argument.

Examples

Click on an example below to see its source code:

Tag leaderboard

Help command

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

discord-ext-pager-1.1.3.tar.gz (14.9 kB view details)

Uploaded Source

Built Distribution

discord_ext_pager-1.1.3-py3-none-any.whl (13.5 kB view details)

Uploaded Python 3

File details

Details for the file discord-ext-pager-1.1.3.tar.gz.

File metadata

  • Download URL: discord-ext-pager-1.1.3.tar.gz
  • Upload date:
  • Size: 14.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.6

File hashes

Hashes for discord-ext-pager-1.1.3.tar.gz
Algorithm Hash digest
SHA256 75add7c3a11ab3e0a700d381083fde9f15933dce5ba9d6e151fb48e7cc838879
MD5 26aea9983c860b1ac929d1667d134720
BLAKE2b-256 962ea93bb4defd6ee0b90ac6831408561b6f0731710995909af74fce9259fef9

See more details on using hashes here.

File details

Details for the file discord_ext_pager-1.1.3-py3-none-any.whl.

File metadata

File hashes

Hashes for discord_ext_pager-1.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 af95256386f9ae7947554320e0381a2bac20f754a40388bd4b90495cddd7c4d2
MD5 1e99f9f2a7089f12003f9ac6b537ab47
BLAKE2b-256 fa06d07ec77392d7acb98255df05f5f8d0f9b60c73b3abdfba680c7990808536

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page