diff --git a/README.md b/README.md index c3fc72b..527000d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/pyproject.toml b/pyproject.toml index acc180c..84767d7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 = [ diff --git a/src/dpy_paginator/dpy_paginator.py b/src/dpy_paginator/dpy_paginator.py index 698d533..1976871 100644 --- a/src/dpy_paginator/dpy_paginator.py +++ b/src/dpy_paginator/dpy_paginator.py @@ -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)