pycascadeui 3.3.1__tar.gz → 3.3.2__tar.gz

{pycascadeui-3.3.1/pycascadeui.egg-info → pycascadeui-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.3.1
+Version: 3.3.2
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT
@@ -665,6 +665,7 @@ for row in rows:
 - Auto-defer with `respond()`, `open_modal()`, and `_safe_defer()` helpers
 - Interaction serialization so rapid clicks process sequentially
 - Refresh throttling via `refresh_cooldown_ms` and reactive 429 backoff
+- `edit_timeout` ceiling that cancels stalled Discord edits before they pin a view
 - Silent snowflake coercion at every public boundary
 - Class-attribute validation at subclass-definition time
 

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/README.md

@@ -622,6 +622,7 @@ for row in rows:
 - Auto-defer with `respond()`, `open_modal()`, and `_safe_defer()` helpers
 - Interaction serialization so rapid clicks process sequentially
 - Refresh throttling via `refresh_cooldown_ms` and reactive 429 backoff
+- `edit_timeout` ceiling that cancels stalled Discord edits before they pin a view
 - Silent snowflake coercion at every public boundary
 - Class-attribute validation at subclass-definition time
 

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/__init__.py

@@ -132,7 +132,7 @@ if "SQLiteBackend" in _persistence_all:
 # // ========================================( Script )======================================== // #
 
 
-__version__ = "3.3.1"
+__version__ = "3.3.2"
 
 # Export public API
 __all__ = [

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/views/_interaction.py

@@ -88,6 +88,22 @@ class _InteractionMixin:
                 if self.auto_defer and not interaction.response.is_done():
                     try:
                         await interaction.response.defer()
+                    except discord.HTTPException as e:
+                        # 40060 means Discord acknowledged a request the
+                        # acting-view fast path cancelled locally (cancellation
+                        # race) -- the interaction is already acked, so this is
+                        # benign and routine. Any other status is a genuine ack
+                        # failure the user saw as an interaction-failed toast.
+                        if e.code == 40060:
+                            logger.debug(
+                                f"Post-callback defer raced an existing ack in "
+                                f"{self.__class__.__name__} (40060)"
+                            )
+                        else:
+                            logger.warning(
+                                f"Post-callback defer failed in {self.__class__.__name__}: "
+                                f"status={e.status} code={e.code}"
+                            )
                     except Exception:
                         logger.debug(
                             f"Post-callback defer failed in {self.__class__.__name__} "
@@ -189,9 +205,24 @@ class _InteractionMixin:
         send operations. Prevents double-defer when auto-defer or
         ``serialize_interactions`` has already acknowledged the
         interaction before the callback runs.
+
+        The ack is bounded by ``auto_defer_delay``: this call runs inside
+        the interaction lock, and a Discord ack endpoint that stalls past
+        the ack window would pin the lock on a hung socket. A defer that
+        cannot land in time is useless anyway -- the auto-defer timer,
+        running outside the lock, is the backstop -- so the stall is
+        cancelled and swallowed rather than propagated.
         """
         if not interaction.response.is_done():
-            await interaction.response.defer()
+            try:
+                await asyncio.wait_for(
+                    interaction.response.defer(), timeout=max(0.5, self.auto_defer_delay)
+                )
+            except asyncio.TimeoutError:
+                logger.debug(
+                    f"Ack defer stalled past {self.auto_defer_delay}s in "
+                    f"{type(self).__name__}; auto-defer timer backstops the ack."
+                )
 
     # // ==================( Ephemeral Refresh )================== // #
 
@@ -341,11 +372,11 @@ class _InteractionMixin:
         # panel becomes a harmless orphan the user can dismiss.
         if self._message:
             try:
-                await self._message.delete()
-            except (discord.NotFound, discord.HTTPException):
+                await self._bounded(self._message.delete())
+            except (discord.NotFound, discord.HTTPException, asyncio.TimeoutError):
                 try:
-                    await self._message.edit(view=self)
-                except (discord.NotFound, discord.HTTPException):
+                    await self._bounded(self._message.edit(view=self))
+                except (discord.NotFound, discord.HTTPException, asyncio.TimeoutError):
                     pass
 
         await self.exit()

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/views/_navigation.py

@@ -380,13 +380,24 @@ class _NavigationMixin:
         new_view._check_placement()
 
         try:
-            msg = await current_interaction.edit_original_response(view=new_view, **edit_kwargs)
+            msg = await self._bounded(
+                current_interaction.edit_original_response(view=new_view, **edit_kwargs)
+            )
             # Preserve the parent's plain Message ref. The edit response
             # is an InteractionMessage / WebhookMessage bound to the
             # 15-minute interaction token; subsequent edits need the
             # channel endpoint, which the plain ref provides.
             if new_view._message is None:
                 new_view._message = msg
+        except asyncio.TimeoutError:
+            # Edit stalled past edit_timeout. The destination view is
+            # already registered with a fresh digest, so the next
+            # interaction re-renders it; re-attempting inline would stack
+            # a second wait on the same stalled endpoint.
+            logger.warning(
+                f"Navigation edit stalled past {self.edit_timeout}s in "
+                f"{type(self).__name__}; destination re-renders on next interaction."
+            )
         except discord.HTTPException:
             # Interaction token expired (15-min lifetime). Route the
             # channel-endpoint fallback through refresh() so it picks
@@ -405,9 +416,17 @@ class _NavigationMixin:
                 # Stack was empty -- pop() already stopped/unsubscribed this view,
                 # so remove the dead components from the message to avoid a broken UI
                 try:
-                    await interaction.edit_original_response(view=None)
-                except discord.HTTPException:
-                    pass
+                    await self._bounded(interaction.edit_original_response(view=None))
+                except asyncio.TimeoutError:
+                    logger.debug(
+                        f"Back-navigation clear stalled past {self.edit_timeout}s "
+                        f"in {type(self).__name__}."
+                    )
+                except discord.HTTPException as e:
+                    logger.debug(
+                        f"Back-navigation clear failed in {type(self).__name__}: "
+                        f"status={e.status} code={e.code}"
+                    )
             # When prev_view is non-None, pop() routed through _apply_navigation_edit
             # which already swapped the message to the restored view.
 

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/views/base.py

@@ -195,6 +195,20 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
     # Discord returns an escalated rate-limit.
     refresh_cooldown_ms: Optional[int] = None
 
+    # Subclass config: edit timeout ceiling
+    # discord.py issues HTTP edits with no total timeout (aiohttp defaults to
+    # total=None), so a connection that stalls without a response would pin
+    # the awaiting code -- and, on the interaction-locked refresh/navigation
+    # paths, the view itself -- until the socket drops. This ceiling bounds
+    # every live-view and teardown edit through ``_bounded``: a stall is
+    # cancelled after this many seconds and the view recovers on the next
+    # interaction. The default clears realistic attachment uploads while
+    # still capping a true hang. ``None`` disables the ceiling (unbounded
+    # awaits, matching discord.py's own default). The acting-view fast path
+    # keeps its own tighter bound, which protects the 3s ack deadline rather
+    # than guarding against a hang.
+    edit_timeout: Optional[float] = 60.0
+
     # Subclass config: interaction serialization
     # When True, rapid button clicks are processed one at a time to prevent
     # racing message edits that cause "This interaction failed" errors.
@@ -283,6 +297,8 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
     )
     # Attributes that must be a positive float/int.
     _POSITIVE_NUMBER_ATTRS: ClassVar[tuple] = ("auto_defer_delay",)
+    # Attributes that must be a positive float/int or None (None = disabled).
+    _OPTIONAL_POSITIVE_NUMBER_ATTRS: ClassVar[tuple] = ("edit_timeout",)
     # Attributes that must be a bool.
     _BOOL_ATTRS: ClassVar[tuple] = (
         "owner_only",
@@ -338,6 +354,14 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
                 raise ValueError(f"{cls.__name__}.{name} must be a positive number, got {value!r}")
             return
+        if name in cls._OPTIONAL_POSITIVE_NUMBER_ATTRS:
+            if value is None:
+                return
+            if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
+                raise ValueError(
+                    f"{cls.__name__}.{name} must be a positive number or None, got {value!r}"
+                )
+            return
         if name in cls._BOOL_ATTRS:
             if not isinstance(value, bool):
                 raise ValueError(
@@ -426,6 +450,9 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
         for attr in cls._POSITIVE_NUMBER_ATTRS:
             if attr in own:
                 cls._validate_attribute_value(attr, own[attr])
+        for attr in cls._OPTIONAL_POSITIVE_NUMBER_ATTRS:
+            if attr in own:
+                cls._validate_attribute_value(attr, own[attr])
         for attr in cls._BOOL_ATTRS:
             if attr in own:
                 cls._validate_attribute_value(attr, own[attr])
@@ -1465,9 +1492,14 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
 
         if self._message:
             try:
-                await self._message.edit(view=self)
+                await self._bounded(self._message.edit(view=self))
             except discord.NotFound:
                 pass  # Message was already deleted
+            except asyncio.TimeoutError:
+                logger.warning(
+                    f"Timed out disabling components on timeout for "
+                    f"{type(self).__name__}; continuing teardown."
+                )
             except Exception as e:
                 hint = ""
                 if self._ephemeral:
@@ -1664,6 +1696,9 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             # value. Disqualified cases (modal interactions, cross-view
             # message mismatch, already-deferred response, missing message
             # ref) fall through to the existing webhook/channel paths.
+            # Ephemeral acting views take the ack-first branch instead: a
+            # webhook-only edit runs too slowly to double as the ack without
+            # risking the 3s deadline.
             #
             # The fast path couples ack to edit in one HTTP call. A slow
             # edit response from Discord (latency spike, ephemeral backend
@@ -1677,13 +1712,14 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             # done" and the fall-through paths behave as if the fast path
             # was never attempted.
             interaction = _CURRENT_INTERACTION.get()
-            if (
+            acting = (
                 interaction is not None
                 and interaction.type == discord.InteractionType.component
                 and interaction.message is not None
                 and interaction.message.id == self._message.id
                 and not interaction.response.is_done()
-            ):
+            )
+            if acting and not self._ephemeral:
                 fast_path_timeout = max(0.5, self.auto_defer_delay - 1.0)
                 try:
                     await asyncio.wait_for(
@@ -1723,6 +1759,18 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
                     # Any other HTTP error falls through to the channel path
                     # so a transient failure on the interaction endpoint does
                     # not lose the edit entirely.
+            elif acting and self._ephemeral:
+                # Ephemeral messages edit only through the interaction webhook,
+                # which runs slower than a channel PATCH. The edit-as-ack fast
+                # path couples the ack to that edit, so a slow webhook response
+                # starves the 3s ack deadline: the panel misses its ack (the
+                # interaction-failed toast) and loses the edit (a frozen body).
+                # Acknowledge first with a deferred update, then fall through to
+                # the webhook edit below. self._message is the
+                # InteractionMessage/WebhookMessage, whose .edit() routes through
+                # the webhook and stays valid for the token's 15-minute life with
+                # no 3s deadline on the edit itself.
+                await self._safe_defer(interaction)
 
             # Interaction-response messages ignore embed edits via the channel
             # endpoint (PATCH /channels/{id}/messages/{id}).  When the caller
@@ -1731,12 +1779,19 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             # update embeds.  Falls back to the plain Message on token expiry.
             if ("embed" in kwargs or "embeds" in kwargs) and self._webhook_message:
                 try:
-                    await self._webhook_message.edit(view=self, **kwargs)
+                    await self._bounded(self._webhook_message.edit(view=self, **kwargs))
                     self._last_tree_digest = self._compute_tree_digest()
                     if perf_on:
                         store._record_edit()
                     self._stamp_cooldown()
                     return
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        f"Webhook edit stalled past {self.edit_timeout}s in "
+                        f"{type(self).__name__}; the next refresh re-ships."
+                    )
+                    self._last_tree_digest = None
+                    return
                 except discord.HTTPException as e:
                     if self._handle_rate_limit(e):
                         return
@@ -1744,13 +1799,19 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
                     self._webhook_message = None
 
             try:
-                await self._message.edit(view=self, **kwargs)
+                await self._bounded(self._message.edit(view=self, **kwargs))
                 self._last_tree_digest = self._compute_tree_digest()
                 if perf_on:
                     store._record_edit()
                 self._stamp_cooldown()
             except discord.NotFound:
                 pass
+            except asyncio.TimeoutError:
+                logger.warning(
+                    f"Edit stalled past {self.edit_timeout}s in {type(self).__name__}; "
+                    f"the next refresh re-ships."
+                )
+                self._last_tree_digest = None
             except discord.HTTPException as e:
                 if not self._handle_rate_limit(e):
                     raise
@@ -1780,6 +1841,20 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
         self._refresh_not_before = time.monotonic() + retry
         return True
 
+    async def _bounded(self, coro):
+        """Await a Discord HTTP coroutine under the ``edit_timeout`` ceiling.
+
+        ``asyncio.wait_for`` cancels the request when it stalls past
+        ``edit_timeout`` seconds; aiohttp closes the connection on
+        cancellation, so a hung socket cannot pin the awaiting code.
+        ``edit_timeout = None`` awaits the coroutine directly with no
+        ceiling. Raises ``asyncio.TimeoutError`` on stall so the caller
+        can release the interaction lock and recover on the next edit.
+        """
+        if self.edit_timeout is None:
+            return await coro
+        return await asyncio.wait_for(coro, self.edit_timeout)
+
     def _check_placement(self) -> None:
         """Run the V2 placement validator on this view if enabled.
 
@@ -2413,19 +2488,27 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
         if self._message:
             try:
                 if delete_message:
-                    await self._message.delete()
+                    await self._bounded(self._message.delete())
                 elif self._is_layout():
                     # V2 messages ARE their components -- edit(view=None) would
                     # produce an empty message (error 50006).  Freeze instead.
                     self._freeze_components()
-                    await self._message.edit(view=self)
+                    await self._bounded(self._message.edit(view=self))
                 else:
-                    await self._message.edit(view=None)
+                    await self._bounded(self._message.edit(view=None))
             except discord.NotFound:
                 # Expected lifecycle: user dismissed the ephemeral, an
                 # admin deleted the message, or the channel was deleted.
                 # Nothing left to clean up on Discord's side.
                 pass
+            except asyncio.TimeoutError:
+                # Visual cleanup stalled past edit_timeout. State teardown
+                # already ran above, so the view is gone regardless of the
+                # stale message on screen.
+                logger.warning(
+                    f"Exit cleanup edit stalled past {self.edit_timeout}s for "
+                    f"{type(self).__name__}; view torn down regardless."
+                )
             except discord.HTTPException as e:
                 if self._ephemeral and getattr(e, "status", None) == 401:
                     # Expected lifecycle for ephemerals past the 15-minute

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/views/layout.py

@@ -1,6 +1,8 @@
 # // ========================================( Modules )======================================== // #
 
 
+import asyncio
+import logging
 from typing import Any, Dict, Optional, Sequence
 
 import discord
@@ -9,6 +11,8 @@ from discord.ui import ActionRow, Item, LayoutView
 from ..components.base import StatefulButton
 from .base import _StatefulMixin
 
+logger = logging.getLogger(__name__)
+
 # // ========================================( Classes )======================================== // #
 
 
@@ -98,9 +102,17 @@ class StatefulLayoutView(_StatefulMixin, LayoutView):
                 # an empty message.  Freeze instead.
                 try:
                     self._freeze_components()
-                    await interaction.edit_original_response(view=self)
-                except discord.HTTPException:
-                    pass
+                    await self._bounded(interaction.edit_original_response(view=self))
+                except asyncio.TimeoutError:
+                    logger.debug(
+                        f"Back-navigation freeze stalled past {self.edit_timeout}s "
+                        f"in {type(self).__name__}."
+                    )
+                except discord.HTTPException as e:
+                    logger.debug(
+                        f"Back-navigation freeze failed in {type(self).__name__}: "
+                        f"status={e.status} code={e.code}"
+                    )
             # When prev_view is non-None, pop() routed through _apply_navigation_edit
             # which already swapped the message to the restored view.
 

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/cascadeui/views/persistent.py

@@ -1,6 +1,7 @@
 # // ========================================( Modules )======================================== // #
 
 
+import asyncio
 import logging
 import re
 from typing import Dict
@@ -107,7 +108,7 @@ class _PersistentMixin:
         V2 calls ``delete()`` because V2 messages ARE their components  --
         ``edit(view=None)`` would produce an empty message (Discord error 50006).
         """
-        await old_message.edit(view=None)
+        await self._bounded(old_message.edit(view=None))
 
     async def _register_persistent(self, message) -> None:
         """Perform duplicate-key cleanup and dispatch PERSISTENT_VIEW_REGISTERED.
@@ -154,7 +155,12 @@ class _PersistentMixin:
                                 f"Cleaned up previous message {old_msg_id} for "
                                 f"persistence_key '{self.persistence_key}'"
                             )
-                    except (discord.NotFound, discord.Forbidden, discord.HTTPException):
+                    except (
+                        discord.NotFound,
+                        discord.Forbidden,
+                        discord.HTTPException,
+                        asyncio.TimeoutError,
+                    ):
                         pass  # Old message already gone, nothing to clean up
                     except Exception as e:
                         logger.debug(
@@ -296,4 +302,4 @@ class PersistentLayoutView(_PersistentMixin, StatefulLayoutView):
 
     async def _cleanup_orphan_message(self, old_message):
         """V2 messages ARE their components -- delete instead of edit."""
-        await old_message.delete()
+        await self._bounded(old_message.delete())

{pycascadeui-3.3.1 → pycascadeui-3.3.2/pycascadeui.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.3.1
+Version: 3.3.2
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT
@@ -665,6 +665,7 @@ for row in rows:
 - Auto-defer with `respond()`, `open_modal()`, and `_safe_defer()` helpers
 - Interaction serialization so rapid clicks process sequentially
 - Refresh throttling via `refresh_cooldown_ms` and reactive 429 backoff
+- `edit_timeout` ceiling that cancels stalled Discord edits before they pin a view
 - Silent snowflake coercion at every public boundary
 - Class-attribute validation at subclass-definition time
 

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pycascadeui"
-version = "3.3.1"
+version = "3.3.2"
 description = "Redux-inspired UI framework for discord.py"
 readme = "README.md"
 license = "MIT"

{pycascadeui-3.3.1 → pycascadeui-3.3.2}/tests/test_auto_defer.py

@@ -1,8 +1,11 @@
 """Tests for auto-defer safety net on StatefulView."""
 
 import asyncio
+import logging
+import time
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import discord
 import pytest
 from helpers import make_interaction as _make_interaction
 
@@ -19,6 +22,23 @@ def _make_item(callback):
     return item
 
 
+def _http_error(status, code):
+    """Build a ``discord.HTTPException`` carrying a specific status/code.
+
+    The post-callback defer classifies errors by ``code`` (40060 is the
+    benign already-acknowledged race), so tests need to control it directly.
+    """
+
+    class _Err(discord.HTTPException):
+        def __init__(self):
+            Exception.__init__(self, str(status))
+            self.status = status
+            self.code = code
+            self.retry_after = 0
+
+    return _Err()
+
+
 # // ========================================( Timer Fires )======================================== // #
 
 
@@ -149,6 +169,55 @@ class TestPostCallbackDefer:
 
         interaction.response.defer.assert_not_called()
 
+    async def test_post_defer_40060_race_logged_at_debug(self, caplog):
+        """A 40060 (already acknowledged) on the post-callback defer is the
+        benign cancellation race the acting-view fast path can produce.
+        Logged at debug, never warning, so a successful fast-path edit does
+        not spam warnings on every interaction.
+        """
+        view = StatefulView(interaction=_make_interaction())
+        view.auto_defer_delay = 10
+        view.owner_only = False
+
+        interaction = _make_interaction(is_done=False)
+        interaction.response.defer = AsyncMock(side_effect=_http_error(400, 40060))
+
+        async def silent_callback(inter):
+            pass
+
+        item = _make_item(silent_callback)
+        with caplog.at_level(logging.DEBUG, logger="cascadeui.views._interaction"):
+            await view._scheduled_task(item, interaction)
+
+        assert any(
+            rec.levelno == logging.DEBUG and "40060" in rec.getMessage() for rec in caplog.records
+        )
+        assert not any(rec.levelno >= logging.WARNING for rec in caplog.records)
+
+    async def test_post_defer_genuine_failure_logged_at_warning(self, caplog):
+        """A non-40060 HTTP failure is a real ack failure -- the user saw an
+        interaction-failed toast -- so it surfaces at warning with the
+        status and code instead of vanishing at debug.
+        """
+        view = StatefulView(interaction=_make_interaction())
+        view.auto_defer_delay = 10
+        view.owner_only = False
+
+        interaction = _make_interaction(is_done=False)
+        interaction.response.defer = AsyncMock(side_effect=_http_error(404, 10062))
+
+        async def silent_callback(inter):
+            pass
+
+        item = _make_item(silent_callback)
+        with caplog.at_level(logging.WARNING, logger="cascadeui.views._interaction"):
+            await view._scheduled_task(item, interaction)
+
+        assert any(
+            rec.levelno == logging.WARNING and "status=404" in rec.getMessage()
+            for rec in caplog.records
+        )
+
 
 # // ========================================( Timer Skipped )======================================== // #
 
@@ -232,6 +301,28 @@ class TestAutoDeferErrorHandling:
         # Timer should not crash
         await view._auto_defer_timer(interaction)
 
+    async def test_safe_defer_bounds_a_stalled_ack(self):
+        """``_safe_defer`` cancels a stalled defer at ``auto_defer_delay`` and
+        swallows the timeout, so a hung Discord ack endpoint cannot pin the
+        interaction lock on the socket lifetime.
+        """
+        view = StatefulView(interaction=_make_interaction())
+        view.auto_defer_delay = 0.05
+        view.owner_only = False
+
+        interaction = _make_interaction(is_done=False)
+
+        async def stall(*args, **kwargs):
+            await asyncio.sleep(60)
+
+        interaction.response.defer = AsyncMock(side_effect=stall)
+
+        before = time.monotonic()
+        await view._safe_defer(interaction)  # must return, not hang
+        elapsed = time.monotonic() - before
+
+        assert elapsed < 2.0  # bounded by auto_defer_delay, not the 60s stall
+
     async def test_callback_error_still_triggers_on_error(self):
         """When the callback raises, on_error is called even with auto-defer active."""
         view = StatefulView(interaction=_make_interaction())