rethink-public/dpy_paginator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: compress prose/module docstrings, em-dash->hyphen (de-bloat wave 1)

Browse Source 
Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
dsql
2026-07-03 00:13:45 -04:00
parent 8addecd64f
commit 4e4cd0687b
3 changed files with 38 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -3
View File
@@ -9,18 +9,18 @@ buttons) behind previous / jump / next navigation, with an optional cache button
`requirements.txt`:
```
dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.7
dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.8
```
Direct:
```bash
pip install "dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.7"
pip install "dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.8"
```
Requires `discord.py` (pulled transitively).
Drop the `@v0.1.7` suffix from the line above to install the latest unpinned.
Drop the `@v0.1.8` suffix from the line above to install the latest unpinned.
## Basic usage
pyproject.toml
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "dpy_paginator"
version = "0.1.7"
version = "0.1.8"
description = "Button-navigated paginator for discord.py — config-free, injectable emojis, installable."
requires-python = ">=3.10"
dependencies = [
src/dpy_paginator/dpy_paginator.py
+34 -68
View File
@@ -3,29 +3,14 @@ button paginator for discord.py
a discord.ui.View that paginates mixed content (strings, embeds, files,
attachments, or dicts of mixed content with custom buttons) behind
previous / jump / next navigation, with an optional cache button.
previous / jump / next navigation, with an optional cache button. config-free;
everything is passed at construction. see README for page-type and button-config
details.
from dpy_paginator import DPYPaginator # or ButtonPaginator, an alias
pages = [discord.Embed(title=f"Page {i}") for i in range(5)]
await DPYPaginator(pages, author_id=ctx.author.id).start(ctx)
emojis: unicode by default; override via emojis={"previous"/"next"/"cache": ...}.
page types: str, discord.Embed, discord.File/Attachment, a sequence of those, or a
dict carrying 'content'/'embed(s)'/'file(s)' plus a 'buttons' list of custom button
configs (see README). both 'file' and 'files' accept a discord.Attachment and
convert it via to_file() automatically.
file pages: discord.py closes a discord.File's handle after every send/edit, so a
fresh discord.File is rebuilt from the same source on every render (including the
first) instead of resending the consumer's object.
concurrency: get_page_kwargs builds each page's kwargs/buttons in local state and
only publishes them once the whole page is fully assembled, so near-simultaneous
interactions (e.g. rapid button clicks) never interleave into a shared render.
config-free: no host config import; everything is passed at construction.
file pages get a fresh discord.File rebuilt from the same source on every render,
since discord.py closes a File's handle after each send/edit. get_page_kwargs
builds each page's kwargs/buttons in local state and only publishes once fully
assembled, so concurrent interactions never interleave into a shared render.
"""
from __future__ import annotations
@@ -128,11 +113,7 @@ class JumpToPageModal(discord.ui.Modal, title="Jump to Page"):
class DPYPaginator(Generic[PageT_co], discord.ui.View):
"""button-navigated paginator supporting mixed page content and custom buttons
also importable as `ButtonPaginator` (a back-compat alias defined below); both
names refer to this same class.
"""
"""button-navigated paginator supporting mixed page content and custom buttons"""
message: Optional[Union[discord.Message, discord.WebhookMessage]] = None
@@ -187,7 +168,6 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
total_pages, left_over = divmod(len(self.pages), self.per_page)
self.max_pages: int = total_pages + (1 if left_over else 0)
# falsy cache (None/[]) disables the cache button; non-empty needs one entry per page
if cache and len(cache) < self.max_pages:
raise ValueError(
f"cache has {len(cache)} entries but there are {self.max_pages} pages; "
@@ -237,9 +217,9 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
) -> Dict[str, Any]:
"""build the send/edit kwargs for a page, extracting any custom buttons
builds into local state (see _get_page_kwargs) and publishes
self.current_page_buttons only once the page is fully assembled, so an
interleaved concurrent call never observes a partially-built page.
concurrency-safe: publishes self.current_page_buttons only once the page
is fully assembled, so an interleaved concurrent call never observes a
partially-built page.
"""
kwargs, buttons = await self._get_page_kwargs(page, skip_formatting=skip_formatting)
self.current_page_buttons = buttons
@@ -252,11 +232,9 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
kwargs: Optional[Dict[str, Any]] = None,
buttons: Optional[List[discord.ui.Button]] = None,
) -> Tuple[Dict[str, Any], List[discord.ui.Button]]:
"""recursive worker: builds kwargs/buttons in locals threaded through recursion
instance attributes are never touched mid-build, so concurrent interactions
each hold their own state until get_page_kwargs publishes the result.
"""
"""recursive worker: builds kwargs/buttons in locals, never touching instance
attributes mid-build, so concurrent calls hold their own state until
get_page_kwargs publishes the result"""
if kwargs is None:
kwargs = self._fresh_kwargs()
if buttons is None:
@@ -297,8 +275,7 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
value = await value.to_file()
kwargs["files"].append(value)
elif key in ("embed", "embeds", "file", "files"):
# wrong-typed value would otherwise collide with base embeds=[]/files=[]
# and raise an opaque TypeError from inside discord.py — reject it here
# wrong-typed value would collide with base embeds=[]/files=[]; reject early
raise ValueError(
f"page key {key!r} has unexpected type {type(value).__name__}"
)
@@ -327,9 +304,8 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
"""rebuild the action row for the current page state
nav=False (or a single page, max_pages < 2) drops prev/jump/next but keeps
the page's custom buttons and the cache button — cache renders whenever
self.cache is truthy, independent of the nav row, so a single-page result
with a cache still gets its cache button.
custom and cache buttons; the cache button renders independent of nav
whenever self.cache is truthy.
"""
self.clear_items()
@@ -385,14 +361,11 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
async def cache_button(self, interaction: discord.Interaction, _: discord.ui.Button) -> None:
"""prime the viewer's client mention cache, then refresh the current view
this is a mention-cache primer, not a data cache: discord clients render
<@id> as a raw id until the user is cached, so this posts the page's
mentions in a throwaway ephemeral message (allowed_mentions=none() — tags
render, no ping fires) to force resolution, waits cache_sleep seconds, then
re-edits the message so mentions display as names.
expected discord failures (deleted message, no permission) are swallowed
like on_timeout — an expired/deleted message must not raise here.
a mention-cache primer, not a data cache: posts the page's mentions in a
throwaway ephemeral message (allowed_mentions=none(), tags render but no
ping fires) to force client resolution, waits cache_sleep seconds, then
re-edits so mentions display as names. expected discord failures (deleted
message, no permission) are swallowed, like on_timeout.
"""
await interaction.response.send_message(
content=self.cache[self.current_page],
@@ -419,9 +392,8 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
def reset_files(self, page_kwargs: Dict[str, Any]) -> None:
"""swap in a fresh discord.File per render so a re-render never reuses a sent one
discord.py closes a File's fp after every send/edit, making it single-use;
file.reset() raises once a path-backed File is actually closed, so rebuild a
new discord.File from the same source instead — cheap, and safe either way.
discord.py closes a File's fp after every send/edit; file.reset() raises
once a path-backed File is actually closed, so rebuild from source instead.
"""
files = page_kwargs.get("files")
if not files:
@@ -430,13 +402,9 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
@staticmethod
def _fresh_file(file: discord.File) -> discord.File:
"""build a new discord.File from an existing one's source
a path-backed File (_owner=True) is reopened from fp.name, which stays
readable after discord.py closes the handle. a buffer-backed File
(_owner=False) is never closed by discord.py, so its buffer is rewound and
reused directly.
"""
"""build a new discord.File from an existing one's source: a path-backed
File (_owner=True) reopens from fp.name; a buffer-backed File (_owner=False)
is never closed by discord.py, so its buffer is rewound and reused"""
if file._owner:
source = file.fp.name
else:
@@ -454,9 +422,8 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
) -> Optional[Union[discord.Message, discord.WebhookMessage]]:
"""send the first page; obj is an Interaction or a Messageable"""
kwargs = await self.get_page_kwargs(self.get_page(self.current_page))
# single page (max_pages < 2): update_buttons already drops the nav row but
# keeps custom/cache buttons — so a single page with either still renders
# them (live callbacks); only drop the view entirely if neither is present
# single page: update_buttons drops nav but keeps custom/cache buttons live;
# only drop the view entirely below if neither is present
self.update_buttons()
if self.max_pages < 2 and not self.current_page_buttons and not self.cache:
@@ -466,14 +433,14 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
self.reset_files(kwargs)
if isinstance(obj, discord.Interaction):
# ephemeral is an interaction-response concept; only these paths accept it
# ephemeral only applies to interaction-response paths
if obj.response.is_done():
self.message = await obj.followup.send(**kwargs, ephemeral=self.ephemeral, **send_kwargs)
else:
await obj.response.send_message(**kwargs, ephemeral=self.ephemeral, **send_kwargs)
self.message = await obj.original_response()
elif isinstance(obj, Messageable):
# Messageable.send (a raw channel) has no ephemeral param — never pass it
# a raw channel's send has no ephemeral param; never pass it
self.message = await obj.send(**kwargs, **send_kwargs)
else:
raise TypeError(f"expected Interaction or Messageable, got {obj.__class__.__name__}")
@@ -483,8 +450,8 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
async def on_timeout(self) -> None:
"""delete the message on timeout when delete_message_after is set
only the expected discord failures (already deleted, or no permission) are
swallowed; an unexpected error surfaces rather than being silently dropped.
only expected discord failures (already deleted, no permission) are
swallowed; unexpected errors surface.
"""
if not self.delete_message_after or self.message is None:
return
@@ -493,8 +460,7 @@ class DPYPaginator(Generic[PageT_co], discord.ui.View):
except (discord.NotFound, discord.Forbidden):
pass
except discord.HTTPException:
# fire-and-forget task; a transient failure must not surface as an
# unretrieved-task traceback on a best-effort cleanup
# best-effort cleanup task; log rather than raise into an unretrieved task
log.warning("paginator on_timeout: failed to delete message", exc_info=True)