# discord-ext-pager
[](https://pypi.org/project/discord-ext-pager/)
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.
[discord-ext-pager]: https://pypi.org/project/discord-ext-pager/
[discord-ext-menus]: https://github.com/Rapptz/discord-ext-menus
While the `PaginatorView` can be instantiated and used by itself, page formatting
is handled by subclassing one of the `PageSource` base classes:
```py
from typing import List
from discord.ext.pager import ListPageSource, PageSource, PaginatorView
class EmbedListPageSource(ListPageSource):
"""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)
```
A navigation select menu for sub-pages can be added by overriding the
`get_page_options()` method to return a list of `PageOption` objects:
```py
from typing import List
from discord.ext.pager import ListPageSource, PageOption, PageSource, PaginatorView
class MessageSource(PageSource):
"""A page source that simply displays a string in the message content."""
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):
return {"content": page, "embed": None}
class MessageNavigator(ListPageSource):
"""A list of messages that the user can select to view."""
def get_page_options(self, view: PaginatorView, page: List[MessageSource]):
# PageOption() takes the same arguments as discord.SelectOption
# plus a source= argument
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)
```
Once 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:
[](https://github.com/thegamecracks/thegamebot/blob/04d9909877685acd24654a911b1853e2143fc316/bot/cogs/tags/__init__.py#L123-L162)
[](https://github.com/thegamecracks/thegamebot/blob/04d9909877685acd24654a911b1853e2143fc316/bot/cogs/helpcommand.py#L26-L249)
Raw data
{
"_id": null,
"home_page": null,
"name": "discord-ext-pager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "discord, discord.py, paginator, view",
"author": "thegamecracks",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5b/37/08da90eb98ef1f2d37a76d7c9528ac86dd029dc1d77621b7b0f365e10ae5/discord_ext_pager-1.1.4.tar.gz",
"platform": null,
"description": "# discord-ext-pager\n\n[](https://pypi.org/project/discord-ext-pager/)\n\nA simple view-based paginator library for discord.py 2.0. Works with Python 3.8+.\n\n## Usage\n\n[discord-ext-pager] is available on PyPI, and as such can be installed using pip.\n\nUsers of Danny's [discord-ext-menus] will find some familiarity\nin this library. Provided are the following classes:\n\n- PaginatorView:\n The view class that manages pagination and navigation.\n- PageSource:\n The base class for sources the paginator view can accept.\n- ListPageSource:\n The base class for formatting a list of items.\n- AsyncIteratorPageSource:\n The base class for formatting an asynchronous iterator of items.\n- PageOption:\n A subclass of `discord.SelectOption` used for presenting navigation options.\n- StopAction:\n An enum for customizing PaginatorView's stop button behaviour.\n- TimeoutAction:\n An enum for customizing PaginatorView's timeout behaviour.\n\n[discord-ext-pager]: https://pypi.org/project/discord-ext-pager/\n[discord-ext-menus]: https://github.com/Rapptz/discord-ext-menus\n\nWhile the `PaginatorView` can be instantiated and used by itself, page formatting\nis handled by subclassing one of the `PageSource` base classes:\n\n```py\nfrom typing import List\nfrom discord.ext.pager import ListPageSource, PageSource, PaginatorView\n\nclass EmbedListPageSource(ListPageSource):\n \"\"\"Takes a list of items and formats it in an embed.\"\"\"\n\n def format_page(self, view: PaginatorView, page: List[object]):\n index = self.current_index * self.page_size\n description = \"\\n\".join(\n f\"{i}. {x}\"\n for i, x in enumerate(page, start=index + 1)\n )\n return discord.Embed(description=description)\n\n# Anywhere a channel or interaction is available:\nfruits = [\"\ud83c\udf4e Apple\", \"\ud83c\udf4a Orange\", \"\ud83c\udf4b Lemon\"]\nsource = EmbedListPageSource(fruits, page_size=2)\nview = PaginatorView(sources=source, timeout=180)\nawait view.start(interaction)\n```\n\nA navigation select menu for sub-pages can be added by overriding the\n`get_page_options()` method to return a list of `PageOption` objects:\n\n```py\nfrom typing import List\nfrom discord.ext.pager import ListPageSource, PageOption, PageSource, PaginatorView\n\nclass MessageSource(PageSource):\n \"\"\"A page source that simply displays a string in the message content.\"\"\"\n\n def __init__(self, message: str):\n super().__init__(current_index=0)\n self.message = message\n\n def get_page(self, index: int):\n return self.message\n\n def format_page(self, view: PaginatorView, page: str):\n return {\"content\": page, \"embed\": None}\n\nclass MessageNavigator(ListPageSource):\n \"\"\"A list of messages that the user can select to view.\"\"\"\n\n def get_page_options(self, view: PaginatorView, page: List[MessageSource]):\n # PageOption() takes the same arguments as discord.SelectOption\n # plus a source= argument\n return [PageOption(source=source, label=source.message) for source in page]\n\n def format_page(self, view: PaginatorView, page: List[MessageSource]):\n description = \"\\n\".join(source.message for source in page)\n embed = discord.Embed(description=description)\n return {\"content\": None, \"embed\": embed}\n\nhands = \"\ud83d\udc48\ud83d\udc49\ud83d\udc46\ud83d\udc47\ud83e\udef5\ud83e\udd1e\ud83e\udef0\ud83e\udd18\ud83e\udd19\ud83e\udd1b\ud83e\udd1c\u270a\ud83d\udc4a\ud83d\udc4b\ud83d\udc4f\ud83d\ude4c\"\nsource = MessageNavigator([MessageSource(s) for s in hands], page_size=5)\nview = PaginatorView(sources=source)\nawait view.start(ctx)\n```\n\nOnce an option is selected, the `PageSource` contained within that option\nis appended to `PaginatorView.sources`, causing that source to be displayed.\nAnother button is automatically provided for users to back out to the last\npage source. This can be manually triggered by passing a list of page sources\nto the `PaginatorView(sources=)` argument.\n\n## Examples\n\nClick on an example below to see its source code:\n\n[](https://github.com/thegamecracks/thegamebot/blob/04d9909877685acd24654a911b1853e2143fc316/bot/cogs/tags/__init__.py#L123-L162)\n\n[](https://github.com/thegamecracks/thegamebot/blob/04d9909877685acd24654a911b1853e2143fc316/bot/cogs/helpcommand.py#L26-L249)\n",
"bugtrack_url": null,
"license": null,
"summary": "A view-based paginator library for discord.py 2.0",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/thegamecracks/discord-ext-pager"
},
"split_keywords": [
"discord",
" discord.py",
" paginator",
" view"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb351ebb5e267fe95a821623b4671ccdde685c9468ce021257ba467d75d05ec4",
"md5": "e23afbf883d79a1ca006e88697f88273",
"sha256": "ddd3e819bbc010c0621d650afddcd7dc1fe793978621e5e827ab4714b782c9f9"
},
"downloads": -1,
"filename": "discord_ext_pager-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e23afbf883d79a1ca006e88697f88273",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13819,
"upload_time": "2025-10-29T05:17:36",
"upload_time_iso_8601": "2025-10-29T05:17:36.670694Z",
"url": "https://files.pythonhosted.org/packages/bb/35/1ebb5e267fe95a821623b4671ccdde685c9468ce021257ba467d75d05ec4/discord_ext_pager-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b3708da90eb98ef1f2d37a76d7c9528ac86dd029dc1d77621b7b0f365e10ae5",
"md5": "251300830126dd85fffba138a22c5284",
"sha256": "8dda9cef67d7894374272d6568d5477cb3df4e12f9676831f28ba542560c0726"
},
"downloads": -1,
"filename": "discord_ext_pager-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "251300830126dd85fffba138a22c5284",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12148,
"upload_time": "2025-10-29T05:17:38",
"upload_time_iso_8601": "2025-10-29T05:17:38.070921Z",
"url": "https://files.pythonhosted.org/packages/5b/37/08da90eb98ef1f2d37a76d7c9528ac86dd029dc1d77621b7b0f365e10ae5/discord_ext_pager-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 05:17:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thegamecracks",
"github_project": "discord-ext-pager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "discord-ext-pager"
}
JSON
