fix: cache button renders on single page; cache_button edit swallows deleted/expired message (v0.1.7)

update_buttons gated the cache button behind the nav row, so a single-page
paginator with a non-empty cache never showed it despite the README promising
otherwise; the cache button now renders whenever self.cache is truthy,
independent of nav, and start() keeps the view alive for that case too.

cache_button's post-sleep message.edit was unguarded, so a message deleted or
expired during cache_sleep raised out of the callback; it now mirrors
on_timeout's NotFound/Forbidden swallow and HTTPException log.

also compresses the module and method docstrings (no behavior change).

Signed-off-by: disqualifier <dev@disqualifier.me>

.gitignore

@@ -1,5 +1,5 @@
 # claude
-CLAUDE.md
+.claude/
 
 # python
 __pycache__/

README.md

@@ -9,26 +9,31 @@ 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.0
+dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.7
 ```
 
 Direct:
 
 ```bash
-pip install "dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.0"
+pip install "dpy_paginator @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_paginator.git@v0.1.7"
 ```
 
 Requires `discord.py` (pulled transitively).
 
+Drop the `@v0.1.7` suffix from the line above to install the latest unpinned.
+
 ## Basic usage
 
+The paginator class is `DPYPaginator`. It is also exported as `ButtonPaginator` (a
+back-compat alias) — both names refer to the same class, so either import works.
+
 Plain pages — just navigation:
 
 ```python
-from dpy_paginator import ButtonPaginator
+from dpy_paginator import DPYPaginator      # or: from dpy_paginator import ButtonPaginator
 
 pages = [discord.Embed(title=f"Page {i}") for i in range(5)]
-await ButtonPaginator(pages, author_id=ctx.author.id).start(ctx)
+await DPYPaginator(pages, author_id=ctx.author.id).start(ctx)
 ```
 
 `start()` accepts an `Interaction` or any `Messageable` (a `Context`, channel, etc.).
@@ -39,7 +44,7 @@ Navigation uses plain Unicode by default — no setup, no emoji upload required.
 `emojis=` to override with custom application/guild emojis the bot can use:
 
 ```python
-ButtonPaginator(pages, emojis={
+DPYPaginator(pages, emojis={
     "previous": "<:icon_back:123...>",
     "next": "<:icon_next:123...>",
     "cache": "<:icon_cache:123...>",
@@ -52,7 +57,15 @@ Unset keys fall back to the Unicode defaults.
 
 A page may be a `str`, `discord.Embed`, `discord.File`/`Attachment`, a sequence of
 those, or a `dict`. A dict page can carry `content`, `embed`/`embeds`,
-`file`/`files`, and a `buttons` list of custom button configs.
+`file`/`files`, and a `buttons` list of custom button configs. Both `file` and
+`files` accept a `discord.Attachment` and convert it via `to_file()` automatically —
+you never need to convert an attachment before passing it in.
+
+File pages are safe to navigate back to. discord.py closes a `discord.File`'s
+underlying handle after every send/edit, so the paginator never resends your File
+object directly — it rebuilds a fresh `discord.File` from the same source (path or
+buffer) on every render, so `pages` can hold a `discord.File` once and be paged
+back and forth indefinitely.
 
 ## Custom per-page buttons
 
@@ -81,7 +94,7 @@ for session in sessions:
         ],
     })
 
-paginator = ButtonPaginator(
+paginator = DPYPaginator(
     pages, cache=None, timeout=900, delete_message_after=True,
     mentions_allowed=discord.AllowedMentions.none(), ephemeral=True,
     page_text="Session {} of {}",
@@ -97,6 +110,8 @@ echoes its `data`.
 ## Cache button (mention priming)
 
 Discord clients render `<@id>` as a raw id until the user object is cached locally.
+Omit `cache` (or pass `None` / `[]`) and the button never appears; a non-empty cache
+must have one entry per page or construction raises.
 The cache button fixes that: pass `cache=[...]` with one entry per page, where each
 entry is a string of the user mentions on that page (`"<@111> <@222> <@333>"`).
 
@@ -112,11 +127,16 @@ for group in groups:
     pages.append(build_embed(group))
     cache.append(" ".join(f"<@{uid}>" for uid in group["user_ids"]))
 
-await ButtonPaginator(pages, cache=cache, cache_sleep=1.0).start(ctx)
+await DPYPaginator(pages, cache=cache, cache_sleep=1.0).start(ctx)
 ```
 
 Omit `cache` or pass `None`/`[]` and the button never appears. When set, `cache`
-must have one entry per rendered page.
+must have one entry per rendered page — a shorter `cache` raises `ValueError` at
+construction rather than failing with an `IndexError` mid-navigation.
+
+The cache button renders whenever `cache` is truthy, even on a single page (no
+navigation row) — it doesn't depend on there being more than one page to flip
+through.
 
 ## Constructor options
 
@@ -138,4 +158,4 @@ in an embed). It may be sync or async.
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag in `requirements.txt`.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dpy_paginator"
-version = "0.1.0"
+version = "0.1.7"
 description = "Button-navigated paginator for discord.py — config-free, injectable emojis, installable."
 requires-python = ">=3.10"
 dependencies = [

src/dpy_paginator/__init__.py

@@ -1,3 +1,3 @@
-from .dpy_paginator import ButtonPaginator, JumpToPageModal, DEFAULT_EMOJIS, Page
+from .dpy_paginator import DPYPaginator, ButtonPaginator, JumpToPageModal, DEFAULT_EMOJIS, Page
 
-__all__ = ["ButtonPaginator", "JumpToPageModal", "DEFAULT_EMOJIS", "Page"]
+__all__ = ["DPYPaginator", "ButtonPaginator", "JumpToPageModal", "DEFAULT_EMOJIS", "Page"]

src/dpy_paginator/dpy_paginator.py

@@ -5,23 +5,25 @@ 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.
 
-    from dpy_paginator import ButtonPaginator
+    from dpy_paginator import DPYPaginator      # or ButtonPaginator, an alias
 
     pages = [discord.Embed(title=f"Page {i}") for i in range(5)]
-    await ButtonPaginator(pages, author_id=ctx.author.id).start(ctx)
+    await DPYPaginator(pages, author_id=ctx.author.id).start(ctx)
 
-emojis: navigation uses plain unicode by default (no setup). pass emojis= to
+emojis: unicode by default; override via emojis={"previous"/"next"/"cache": ...}.
-override with custom application/guild emojis the bot can use:
 
-    ButtonPaginator(pages, emojis={
+page types: str, discord.Embed, discord.File/Attachment, a sequence of those, or a
-        "previous": "<:icon_back:123...>",
+dict carrying 'content'/'embed(s)'/'file(s)' plus a 'buttons' list of custom button
-        "next": "<:icon_next:123...>",
+configs (see README). both 'file' and 'files' accept a discord.Attachment and
-        "cache": "<:icon_cache:123...>",
+convert it via to_file() automatically.
-    })
 
-page types: a page may be a str, a discord.Embed, a discord.File/Attachment,
+file pages: discord.py closes a discord.File's handle after every send/edit, so a
-a sequence of those, or a dict. a dict page can carry 'content'/'embed(s)'/
+fresh discord.File is rebuilt from the same source on every render (including the
-'file(s)' plus a 'buttons' list of custom button configs (see README).
+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.
 """
@@ -29,6 +31,7 @@ config-free: no host config import; everything is passed at construction.
 from __future__ import annotations
 
 import asyncio
+import logging
 from typing import (
     Any,
     Dict,
@@ -69,6 +72,8 @@ DEFAULT_EMOJIS = {
     "cache": "\U0001f5c2\ufe0f",  # 🗂️
 }
 
+log = logging.getLogger(__name__)
+
 PageT_co = TypeVar("PageT_co", bound=Page, covariant=True)
 
 
@@ -94,7 +99,7 @@ class _CustomButton(discord.ui.Button):
 class JumpToPageModal(discord.ui.Modal, title="Jump to Page"):
     """modal that lets a user jump to a specific page"""
 
-    def __init__(self, paginator: "ButtonPaginator"):
+    def __init__(self, paginator: "DPYPaginator"):
         super().__init__()
         self.paginator = paginator
         self.page_number = discord.ui.TextInput(
@@ -122,8 +127,12 @@ class JumpToPageModal(discord.ui.Modal, title="Jump to Page"):
             )
 
 
-class ButtonPaginator(Generic[PageT_co], discord.ui.View):
+class DPYPaginator(Generic[PageT_co], discord.ui.View):
-    """button-navigated paginator supporting mixed page content and custom buttons"""
+    """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.
+    """
 
     message: Optional[Union[discord.Message, discord.WebhookMessage]] = None
 
@@ -159,6 +168,10 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
             cache_sleep: seconds to wait after priming before refreshing the view
         """
         super().__init__(timeout=timeout)
+        if not pages:
+            raise ValueError("DPYPaginator requires at least one page")
+        if per_page < 1:
+            raise ValueError("per_page must be >= 1")
         self.author_id: Optional[int] = author_id
         self.delete_message_after: bool = delete_message_after
         self.mentions_allowed = mentions_allowed or discord.AllowedMentions.all()
@@ -174,7 +187,12 @@ class ButtonPaginator(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)
-        self._page_kwargs: Dict[str, Any] = self._fresh_kwargs()
+        # 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; "
+                "cache needs one entry per page"
+            )
 
     def _fresh_kwargs(self) -> Dict[str, Any]:
         """a clean page-kwargs dict"""
@@ -193,7 +211,7 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
 
     async def interaction_check(self, interaction: Interaction) -> bool:
         """restrict interaction to author_id when set"""
-        if not self.author_id or self.author_id == interaction.user.id:
+        if self.author_id is None or self.author_id == interaction.user.id:
             return True
         await interaction.response.send_message("You cannot interact with this menu.", ephemeral=True)
         return False
@@ -202,7 +220,7 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
         """return the content for a page index, wrapping out-of-range to 0"""
         if page_number < 0 or page_number >= self.max_pages:
             self.current_page = 0
-            return self.pages[self.current_page]
+            return self.get_page(0)
         if self.per_page == 1:
             return self.pages[page_number]
         base = page_number * self.per_page
@@ -217,19 +235,42 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
     async def get_page_kwargs(
         self, page: Union[PageT_co, Sequence[PageT_co]], skip_formatting: bool = False
     ) -> Dict[str, Any]:
-        """build the send/edit kwargs for a page, extracting any custom buttons"""
+        """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.
+        """
+        kwargs, buttons = await self._get_page_kwargs(page, skip_formatting=skip_formatting)
+        self.current_page_buttons = buttons
+        return kwargs
+
+    async def _get_page_kwargs(
+        self,
+        page: Union[PageT_co, Sequence[PageT_co]],
+        skip_formatting: bool = False,
+        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.
+        """
+        if kwargs is None:
+            kwargs = self._fresh_kwargs()
+        if buttons is None:
+            buttons = []
+
         if not skip_formatting:
-            self._page_kwargs = self._fresh_kwargs()
             formatted_page = await discord.utils.maybe_coroutine(self.format_page, page)
         else:
             formatted_page = page
 
-        self.current_page_buttons = []
-
         if isinstance(formatted_page, dict):
             formatted_page = dict(formatted_page)
             for config in formatted_page.pop("buttons", []):
-                self.current_page_buttons.append(
+                buttons.append(
                     _CustomButton(
                         label=config.get("label", "Button"),
                         style=config.get("style", discord.ButtonStyle.gray),
@@ -243,46 +284,64 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
 
             for key, value in formatted_page.items():
                 if key == "embeds" and isinstance(value, list):
-                    self._page_kwargs["embeds"].extend(value)
+                    kwargs["embeds"].extend(value)
                 elif key == "embed" and isinstance(value, discord.Embed):
-                    self._page_kwargs["embeds"].append(value)
+                    kwargs["embeds"].append(value)
                 elif key == "files" and isinstance(value, list):
-                    self._page_kwargs["files"].extend(value)
+                    for item in value:
+                        if isinstance(item, discord.Attachment):
+                            item = await item.to_file()
+                        kwargs["files"].append(item)
                 elif key == "file" and isinstance(value, (discord.File, discord.Attachment)):
                     if isinstance(value, discord.Attachment):
                         value = await value.to_file()
-                    self._page_kwargs["files"].append(value)
+                    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
+                    raise ValueError(
+                        f"page key {key!r} has unexpected type {type(value).__name__}"
+                    )
                 else:
-                    self._page_kwargs[key] = value
+                    kwargs[key] = value
         elif isinstance(formatted_page, str):
-            content = self._page_kwargs["content"]
+            content = kwargs["content"]
-            self._page_kwargs["content"] = (
+            kwargs["content"] = (
                 formatted_page if content is None else f"{content}\n{formatted_page}"
             )
         elif isinstance(formatted_page, discord.Embed):
-            self._page_kwargs["embeds"].append(formatted_page)
+            kwargs["embeds"].append(formatted_page)
         elif isinstance(formatted_page, (discord.File, discord.Attachment)):
             if isinstance(formatted_page, discord.Attachment):
                 formatted_page = await formatted_page.to_file()
-            self._page_kwargs["files"].append(formatted_page)
+            kwargs["files"].append(formatted_page)
         elif isinstance(formatted_page, (tuple, list)):
             for item in formatted_page:
-                await self.get_page_kwargs(item, skip_formatting=True)
+                await self._get_page_kwargs(item, skip_formatting=True, kwargs=kwargs, buttons=buttons)
         else:
             raise TypeError("page content must be str, discord.Embed, file/attachment, sequence, or dict")
 
-        return self._page_kwargs
+        return kwargs, buttons
 
-    def update_buttons(self) -> None:
+    def update_buttons(self, nav: bool = True) -> None:
-        """rebuild the action row for the current page state"""
+        """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.
+        """
         self.clear_items()
 
-        self.previous_page.emoji = self.emojis["previous"]
+        nav = nav and self.max_pages >= 2
-        self.previous_page.disabled = self.current_page <= 0
-        self.add_item(self.previous_page)
 
-        self.jump_button.label = self.page_text.format(self.current_page + 1, self.max_pages)
+        if nav:
-        self.add_item(self.jump_button)
+            self.previous_page.emoji = self.emojis["previous"]
+            self.previous_page.disabled = self.current_page <= 0
+            self.add_item(self.previous_page)
+
+            self.jump_button.label = self.page_text.format(self.current_page + 1, self.max_pages)
+            self.add_item(self.jump_button)
 
         for button in self.current_page_buttons:
             self.add_item(button)
@@ -291,9 +350,10 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
             self.cache_button.emoji = self.emojis["cache"]
             self.add_item(self.cache_button)
 
-        self.next_page.emoji = self.emojis["next"]
+        if nav:
-        self.next_page.disabled = self.current_page >= self.max_pages - 1
+            self.next_page.emoji = self.emojis["next"]
-        self.add_item(self.next_page)
+            self.next_page.disabled = self.current_page >= self.max_pages - 1
+            self.add_item(self.next_page)
 
     async def _build_render_kwargs(self) -> Dict[str, Any]:
         """build the edit-ready kwargs for the current page (buttons + attachments)"""
@@ -325,13 +385,14 @@ class ButtonPaginator(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
 
-        discord clients render <@id> as a raw id until the user object is cached.
+        this is a mention-cache primer, not a data cache: discord clients render
-        this posts the page's mentions in a throwaway ephemeral message so the client
+        <@id> as a raw id until the user is cached, so this posts the page's
-        resolves them, waits cache_sleep seconds, then re-edits the message so the
+        mentions in a throwaway ephemeral message (allowed_mentions=none() — tags
-        mentions display as names — no manual page-flip needed.
+        render, no ping fires) to force resolution, waits cache_sleep seconds, then
+        re-edits the message so mentions display as names.
 
-        allowed_mentions is none() on purpose: the <@id> tags still render (which is
+        expected discord failures (deleted message, no permission) are swallowed
-        what primes the cache) but no actual ping/notification fires.
+        like on_timeout — an expired/deleted message must not raise here.
         """
         await interaction.response.send_message(
             content=self.cache[self.current_page],
@@ -342,7 +403,12 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
         await asyncio.sleep(self.cache_sleep)
         kwargs = await self._build_render_kwargs()
         if self.message:
-            await self.message.edit(**kwargs)
+            try:
+                await self.message.edit(**kwargs)
+            except (discord.NotFound, discord.Forbidden):
+                pass
+            except discord.HTTPException:
+                log.warning("paginator cache_button: failed to refresh message", exc_info=True)
 
     @discord.ui.button(style=discord.ButtonStyle.blurple)
     async def next_page(self, interaction: Interaction, _: discord.ui.Button[Self]) -> None:
@@ -351,33 +417,87 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
         await self.update_page(interaction)
 
     def reset_files(self, page_kwargs: Dict[str, Any]) -> None:
-        """rewind file pointers so they can be sent again"""
+        """swap in a fresh discord.File per render so a re-render never reuses a sent one
-        for file in page_kwargs.get("files", []):
+
-            file.reset()
+        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.
+        """
+        files = page_kwargs.get("files")
+        if not files:
+            return
+        page_kwargs["files"] = [self._fresh_file(file) for file in files]
+
+    @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.
+        """
+        if file._owner:
+            source = file.fp.name
+        else:
+            source = file.fp
+            source.seek(file._original_pos)
+        return discord.File(
+            source,
+            filename=file.filename,
+            spoiler=file.spoiler,
+            description=file.description,
+        )
 
     async def start(
         self, obj: Union[Interaction, Messageable], **send_kwargs: Any
     ) -> 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
         self.update_buttons()
 
-        if self.max_pages < 2:
+        if self.max_pages < 2 and not self.current_page_buttons and not self.cache:
             self.stop()
             kwargs.pop("view", None)
 
         self.reset_files(kwargs)
-        send_kwargs["ephemeral"] = self.ephemeral
 
         if isinstance(obj, discord.Interaction):
+            # ephemeral is an interaction-response concept; only these paths accept it
             if obj.response.is_done():
-                self.message = await obj.followup.send(**kwargs, **send_kwargs)
+                self.message = await obj.followup.send(**kwargs, ephemeral=self.ephemeral, **send_kwargs)
             else:
-                await obj.response.send_message(**kwargs, **send_kwargs)
+                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
             self.message = await obj.send(**kwargs, **send_kwargs)
         else:
             raise TypeError(f"expected Interaction or Messageable, got {obj.__class__.__name__}")
 
         return self.message
+
+    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.
+        """
+        if not self.delete_message_after or self.message is None:
+            return
+        try:
+            await self.message.delete()
+        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
+            log.warning("paginator on_timeout: failed to delete message", exc_info=True)
+
+
+# back-compat alias: the class was originally named ButtonPaginator; DPYPaginator is
+# the canonical name (matching the package), both refer to the same class
+ButtonPaginator = DPYPaginator