chore: ignore .claude/ dir (CLAUDE.md now lives under .claude/)

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

.gitignore

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

README.md

@@ -9,17 +9,19 @@ 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.4
 ```
 
 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.4"
 ```
 
 Requires `discord.py` (pulled transitively).
 
+Drop the `@v0.1.4` suffix from the line above to install the latest unpinned.
+
 ## Basic usage
 
 Plain pages — just navigation:
@@ -97,6 +99,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>"`).
 
@@ -116,7 +120,8 @@ await ButtonPaginator(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.
 
 ## Constructor options
 
@@ -138,4 +143,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.4"
 description = "Button-navigated paginator for discord.py — config-free, injectable emojis, installable."
 requires-python = ">=3.10"
 dependencies = [

src/dpy_paginator/dpy_paginator.py

@@ -29,6 +29,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 +70,8 @@ DEFAULT_EMOJIS = {
     "cache": "\U0001f5c2\ufe0f",  # 🗂️
 }
 
+log = logging.getLogger(__name__)
+
 PageT_co = TypeVar("PageT_co", bound=Page, covariant=True)
 
 
@@ -159,6 +162,12 @@ 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("ButtonPaginator requires at least one page")
+        if per_page < 1:
+            # per_page <= 0 would ZeroDivisionError (==0) or yield a negative max_pages
+            # (<0) at the divmod below; fail loud like the other construction guards
+            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,6 +183,13 @@ 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)
+        # a falsy cache (None or []) disables the cache button (see the render path's
+        # `if self.cache:`); only a non-empty cache must have 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"
+            )
         self._page_kwargs: Dict[str, Any] = self._fresh_kwargs()
 
     def _fresh_kwargs(self) -> Dict[str, Any]:
@@ -193,7 +209,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 +218,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
@@ -252,6 +268,14 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
                     if isinstance(value, discord.Attachment):
                         value = await value.to_file()
                     self._page_kwargs["files"].append(value)
+                elif key in ("embed", "embeds", "file", "files"):
+                    # a wrong-typed embed/file would otherwise fall to the catch-all and
+                    # be forwarded verbatim, colliding with the base embeds=[]/files=[]
+                    # and raising an opaque TypeError from inside discord.py — reject it
+                    # here with a clear, paginator-side message
+                    raise ValueError(
+                        f"page key {key!r} has unexpected type {type(value).__name__}"
+                    )
                 else:
                     self._page_kwargs[key] = value
         elif isinstance(formatted_page, str):
@@ -273,10 +297,20 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
 
         return self._page_kwargs
 
-    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 rebuilds with only the page's custom buttons and no navigation
+        items (prev/jump/cache/next) — a single-page result that still carries
+        custom buttons keeps them (and their live callbacks) without a nav row.
+        the nav row is also suppressed for a single page (max_pages < 2) even when
+        nav is left at its default, so a re-render (update_page) never resurrects it.
+        """
         self.clear_items()
 
+        nav = nav and self.max_pages >= 2
+
+        if nav:
             self.previous_page.emoji = self.emojis["previous"]
             self.previous_page.disabled = self.current_page <= 0
             self.add_item(self.previous_page)
@@ -287,6 +321,7 @@ class ButtonPaginator(Generic[PageT_co], discord.ui.View):
         for button in self.current_page_buttons:
             self.add_item(button)
 
+        if nav:
             if self.cache:
                 self.cache_button.emoji = self.emojis["cache"]
                 self.add_item(self.cache_button)
@@ -360,24 +395,46 @@ class ButtonPaginator(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))
+        # update_buttons already suppresses the nav row for a single page (max_pages < 2),
+        # keeping only the page's custom buttons — so a single page with custom buttons
+        # renders them (live callbacks) with no nav row
         self.update_buttons()
 
-        if self.max_pages < 2:
+        if self.max_pages < 2 and not self.current_page_buttons:
+            # single page, no custom buttons: no interactive row at all, drop the view
             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:
+            # on_timeout runs as a fire-and-forget task; a transient delete 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)