pycascadeui 3.12.2__tar.gz → 3.12.3__tar.gz

{pycascadeui-3.12.2/pycascadeui.egg-info → pycascadeui-3.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.12.2
+Version: 3.12.3
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT
@@ -28,8 +28,8 @@ Requires-Dist: discord.py>=2.7
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
-Requires-Dist: black>=26.3; extra == "dev"
-Requires-Dist: isort>=8.0; extra == "dev"
+Requires-Dist: black<27.0,>=26.3; extra == "dev"
+Requires-Dist: isort<9.0,>=8.0; extra == "dev"
 Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/cascadeui/__init__.py

@@ -184,7 +184,7 @@ if "PostgresBackend" in _persistence_all:
 # // ========================================( Script )======================================== // #
 
 
-__version__ = "3.12.2"
+__version__ = "3.12.3"
 
 # Export public API
 __all__ = [

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/cascadeui/persistence/manager.py

@@ -1396,6 +1396,14 @@ class PersistenceManager:
             # runs.
             view._message = message
 
+            # Fingerprint the tree the fresh __init__ just produced, before
+            # on_restore has had any chance to run. A teardown before that
+            # render reads this against the CURRENT tree: unchanged means
+            # nothing has touched it and there is nothing on screen to
+            # correct, changed means a teardown override composed real
+            # content (a farewell card) that has to ship regardless.
+            view._reattach_baseline_digest = view._compute_tree_digest()
+
             # ``is not None`` (not truthy) so a stored ``user_id=0`` still
             # restores -- Discord doesn't mint zero snowflakes, but tests
             # and edge-case fixtures do, and the cost of the explicit form

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/cascadeui/views/_navigation.py

@@ -623,6 +623,7 @@ class _NavigationMixin:
                 await self._ack_bounded(
                     current_interaction.response.edit_message(view=new_view, **direct_kwargs)
                 )
+                new_view._has_rendered = True
                 new_view._redrive_dynamic_items()
                 return True
             except asyncio.TimeoutError:
@@ -661,6 +662,7 @@ class _NavigationMixin:
             msg = await self._bounded(
                 current_interaction.edit_original_response(view=new_view, **direct_kwargs)
             )
+            new_view._has_rendered = True
             # 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

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/cascadeui/views/base.py

@@ -1143,6 +1143,23 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
         # ``None`` means no baseline has been recorded yet, so the
         # next refresh always runs through to the REST call.
         self._last_tree_digest: Optional[int] = None
+        # Distinct from the digest above: this is never reset back to False
+        # once a tree has landed on Discord, even when a stall or a send
+        # failure clears the digest to force the next refresh through
+        # unconditionally. The teardown freeze-edit gate reads this rather
+        # than "digest is not None", since that comparison would otherwise
+        # misread every one of those deliberate baseline-drops as "never
+        # rendered" and skip an edit that has real content to correct.
+        self._has_rendered: bool = False
+        # Stamped once, by the persistence reattach path only, with the
+        # digest of the tree a fresh __init__ produced -- before on_restore
+        # has had any chance to run. Lets the teardown gate tell "restored,
+        # never rendered, and nothing has touched the tree since" (matches
+        # this baseline, safe to skip) apart from "restored, never rendered,
+        # but a teardown override composed real content before delegating"
+        # (differs from this baseline, has to ship). Left None for every
+        # view that was never reattached, where _has_rendered alone governs.
+        self._reattach_baseline_digest: Optional[int] = None
         # Set by ``refresh`` when it swallowed a transport failure, so a
         # caller that needs the edit to have LANDED can tell that apart from
         # a refresh that returned normally. A repaint is content to retry on
@@ -1857,6 +1874,7 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             # embed content is outside the digest, which is fine -- the
             # digest only certifies the component tree, and refresh() only
             # short-circuits when the caller passes no kwargs.
+            self._has_rendered = True
             self._last_tree_digest = self._compute_tree_digest()
 
             await self._update_message_state(self._message)
@@ -2496,6 +2514,48 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
                 frozen += 1
         return frozen
 
+    def _freeze_edit_needed(self, froze: bool) -> bool:
+        """Whether a teardown freeze edit has something new to ship.
+
+        ``froze`` alone answers "did disabling components change anything",
+        which misses a caller that rebuilt the tree (a farewell card) before
+        tearing down -- the digest comparison is what catches that case.
+
+        The comparison is gated on ``_has_rendered`` rather than on
+        ``_last_tree_digest is not None``, because the digest is ``None``
+        for two different reasons and only one of them means "nothing on
+        screen": a view that has never landed a tree (restored from
+        persistence, its post-ready render still pending: ``self.children``
+        is whatever ``__init__`` produced, typically empty for a pattern
+        that builds its tree in ``on_load``, which Discord rejects with
+        error 50006), and a view that HAS rendered but had its digest
+        deliberately dropped so the next refresh ships unconditionally (a
+        stalled edit, a swallowed transport failure, a navigation landing
+        that never stamps a digest at all). Gating on the digest alone
+        would read the second case as "never measured" and skip an edit
+        that has real, possibly stale content to correct, silently
+        dropping a farewell card composed just before teardown -- the
+        exact defect this guard exists to catch.
+
+        A never-rendered view can still have something to ship: a teardown
+        override (``exit()``, ``on_timeout()``) that composes new content
+        before delegating to ``super()`` runs whether or not ``on_restore``
+        ever rendered first, and its farewell card is not the empty tree
+        this guard exists to withhold. ``_reattach_baseline_digest``, stamped
+        once at reattach with the digest of whatever a fresh ``__init__``
+        produced, tells the two apart: a tree that still matches it has
+        nothing on screen to correct (the original defect this method
+        fixes), a tree that no longer matches it was composed by something
+        real and has to ship.
+        """
+        if froze:
+            return True
+        if self._has_rendered:
+            return self._compute_tree_digest() != self._last_tree_digest
+        if self._reattach_baseline_digest is None:
+            return False
+        return self._compute_tree_digest() != self._reattach_baseline_digest
+
     def _dispatch_timeout(self):
         """Repair the dynamic-item registry at the actual discord.py choke point.
 
@@ -2534,14 +2594,8 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
         self.state_store._undo_enabled_views.pop(self.id, None)
         await self.state_store._destroy_view(self.id, source_id=self.id)
 
-        # Skip the edit only when it would ship what is already on screen: a
-        # component-less display view (or one already fully disabled) would
-        # otherwise send a no-op PATCH on every timeout. The tree is checked
-        # alongside the freeze because an override that rebuilds before
-        # delegating here has something to say even though nothing froze.
-        if self._message and (
-            self._freeze_components() or self._compute_tree_digest() != self._last_tree_digest
-        ):
+        # See _freeze_edit_needed for what "nothing to ship" covers here.
+        if self._message and self._freeze_edit_needed(self._freeze_components()):
             try:
                 await self._bounded(self._message.edit(**self._freeze_edit_kwargs()))
             except discord.NotFound:
@@ -3419,6 +3473,7 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
                         interaction.response.edit_message(view=self, **kwargs),
                         timeout=fast_path_timeout,
                     )
+                    self._has_rendered = True
                     self._last_tree_digest = self._compute_tree_digest()
                     if perf_on:
                         store._record_edit()
@@ -3477,6 +3532,7 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
             if ("embed" in kwargs or "embeds" in kwargs) and self._webhook_message:
                 try:
                     await self._bounded(self._webhook_message.edit(view=self, **kwargs))
+                    self._has_rendered = True
                     self._last_tree_digest = self._compute_tree_digest()
                     if perf_on:
                         store._record_edit()
@@ -3510,6 +3566,7 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
 
             try:
                 await self._bounded(self._message.edit(view=self, **kwargs))
+                self._has_rendered = True
                 self._last_tree_digest = self._compute_tree_digest()
                 if perf_on:
                     store._record_edit()
@@ -4790,15 +4847,8 @@ class _StatefulMixin(_InteractionMixin, _NavigationMixin):
                 elif self._is_layout():
                     # V2 messages ARE their components -- edit(view=None) would
                     # produce an empty message (error 50006). Freeze instead.
-                    # The edit is skipped only when it would ship what is
-                    # already on screen: nothing froze AND the tree still
-                    # matches the last render. Testing the freeze alone read
-                    # a caller who rebuilt the tree before exiting as having
-                    # nothing to say, so a farewell card composed in
-                    # on_timeout was dropped and the expired prompt kept its
-                    # live-looking buttons until someone pressed one.
-                    froze = self._freeze_components()
-                    if froze or self._compute_tree_digest() != self._last_tree_digest:
+                    # See _freeze_edit_needed for what "nothing to ship" covers.
+                    if self._freeze_edit_needed(self._freeze_components()):
                         await self._bounded(self._message.edit(**self._freeze_edit_kwargs()))
                 else:
                     await self._bounded(self._message.edit(view=None))

{pycascadeui-3.12.2 → pycascadeui-3.12.3/pycascadeui.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.12.2
+Version: 3.12.3
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT
@@ -28,8 +28,8 @@ Requires-Dist: discord.py>=2.7
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
-Requires-Dist: black>=26.3; extra == "dev"
-Requires-Dist: isort>=8.0; extra == "dev"
+Requires-Dist: black<27.0,>=26.3; extra == "dev"
+Requires-Dist: isort<9.0,>=8.0; extra == "dev"
 Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/pycascadeui.egg-info/requires.txt

@@ -3,8 +3,8 @@ discord.py>=2.7
 [dev]
 pytest>=7.0
 pytest-asyncio>=0.21
-black>=26.3
-isort>=8.0
+black<27.0,>=26.3
+isort<9.0,>=8.0
 testcontainers[postgres]>=4.0
 
 [docs]

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pycascadeui"
-version = "3.12.2"
+version = "3.12.3"
 description = "Redux-inspired UI framework for discord.py"
 readme = "README.md"
 license = "MIT"
@@ -38,8 +38,8 @@ dependencies = [
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
-    "black>=26.3",
-    "isort>=8.0",
+    "black>=26.3,<27.0",
+    "isort>=8.0,<9.0",
     "testcontainers[postgres]>=4.0",
 ]
 docs = [

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/tests/test_layout_view.py

@@ -5,7 +5,7 @@ import inspect
 import io
 import logging
 import time
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import aiohttp
 import discord
@@ -5678,6 +5678,114 @@ class TestRebuiltTreeShipsOnTeardown:
 
         message.edit.assert_awaited_once()
 
+    async def test_exit_skips_the_edit_for_a_view_that_never_rendered(self):
+        """A view reattached from persistence but not yet rendered has no
+        baseline on screen for this edit to correct.
+
+        No ``send()`` and no ``refresh()`` runs here, so ``_has_rendered``
+        stays at its ``__init__`` default of ``False`` -- matching a view
+        between reattach and its deferred post-ready render.
+        """
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+        message = self._wire(view)
+        assert view._has_rendered is False
+
+        await view.exit(delete_message=False)
+
+        message.edit.assert_not_called()
+
+    async def test_on_timeout_skips_the_edit_for_a_view_that_never_rendered(self):
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+        message = self._wire(view)
+        assert view._has_rendered is False
+
+        await view.on_timeout()
+
+        message.edit.assert_not_called()
+
+    async def test_exit_still_ships_a_rebuild_when_the_digest_was_never_stamped(self):
+        """``_last_tree_digest`` is ``None`` for more than one reason, and
+        only "never rendered" means "skip".
+
+        A push/pop navigation landing never stamps the destination's digest,
+        so a pushed view carries ``_has_rendered = True`` (content is
+        genuinely on screen) alongside ``_last_tree_digest = None`` for its
+        whole life until some later refresh happens to land. Gating the
+        teardown skip on the digest alone would misread that combination as
+        "never rendered" and drop a farewell card composed just before
+        teardown -- the exact defect the digest comparison exists to catch.
+        """
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+        view.add_item(ActionRow(StatefulButton(label="Accept")))
+        await view.send()
+        message = self._wire(view)
+
+        # Simulate the state a navigation landing leaves behind: rendered,
+        # but with no stamped digest.
+        view._last_tree_digest = None
+        view.clear_items()
+        view.add_item(card("Challenge expired."))
+
+        await view.exit(delete_message=False)
+
+        message.edit.assert_awaited_once()
+
+    async def test_on_timeout_still_ships_a_rebuild_when_the_digest_was_never_stamped(self):
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+        view.add_item(ActionRow(StatefulButton(label="Accept")))
+        await view.send()
+        message = self._wire(view)
+
+        view._last_tree_digest = None
+        view.clear_items()
+        view.add_item(card("Challenge expired."))
+
+        await view.on_timeout()
+
+        message.edit.assert_awaited_once()
+
+    async def test_has_rendered_survives_a_raising_digest_after_send(self):
+        """``_has_rendered`` means "the send landed", stamped before the
+        digest computation that follows it.
+
+        A user subclass's tree can raise inside ``_compute_tree_digest``
+        (a property read on a live item) after the send already reached
+        Discord. ``_send_pipeline`` swallows that raise and drops the
+        digest to ``None``, but the flag must not depend on the digest
+        computation succeeding -- otherwise a view Discord is genuinely
+        showing would read as never rendered at its next teardown.
+        """
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+
+        with patch.object(type(view), "_compute_tree_digest", side_effect=RuntimeError("boom")):
+            await view.send()
+
+        assert view._has_rendered is True
+        assert view._last_tree_digest is None
+
+        message = self._wire(view)
+        view.clear_items()
+        view.add_item(card("Challenge expired."))
+
+        await view.exit(delete_message=False)
+
+        message.edit.assert_awaited_once()
+
+    async def test_refresh_marks_the_view_as_rendered_without_a_prior_send(self):
+        """A view can land its first tree through ``refresh()`` rather than
+        ``send()`` -- a persistence-restored view's ``on_restore()`` calling
+        ``reload()``/``refresh()`` is the production shape this covers. The
+        flag has to flip there too, or a teardown right after would read a
+        genuinely rendered view as never rendered.
+        """
+        view = RenderableLayoutView(interaction=_make_interaction(), user_id=1, guild_id=2)
+        message = self._wire(view)
+        assert view._has_rendered is False
+
+        await view.refresh()
+
+        assert view._has_rendered is True
+
 
 class TestTimeoutWindowStillRenders:
     """A view inside its timeout window is intact, so its render has to ship.

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/tests/test_navigation.py

@@ -1097,11 +1097,14 @@ class TestNavigationFastPath:
         await root.send()
 
         nav = _make_interaction(user_id=1, guild_id=100, is_done=False)
-        await root.push(_Sub, interaction=nav)
+        dest = await root.push(_Sub, interaction=nav)
 
         # One round-trip: edit + ack together, no separate defer.
         nav.response.edit_message.assert_awaited_once()
         nav.response.defer.assert_not_called()
+        # The fast-path landing is a real render: a teardown right after
+        # must not read it as "never rendered" (see _freeze_edit_needed).
+        assert dest._has_rendered is True
 
     async def test_push_falls_back_to_deferred_edit_when_acked(self):
         class _Root(StatefulView):
@@ -1119,10 +1122,11 @@ class TestNavigationFastPath:
         nav.edit_original_response = AsyncMock(
             return_value=MagicMock(id=777, channel=MagicMock(id=666))
         )
-        await root.push(_Sub, interaction=nav)
+        dest = await root.push(_Sub, interaction=nav)
 
         nav.response.edit_message.assert_not_called()
         nav.edit_original_response.assert_awaited_once()
+        assert dest._has_rendered is True
 
     async def test_push_non_component_interaction_skips_fast_path(self):
         """A non-component interaction (e.g. a slash command) is ineligible for

{pycascadeui-3.12.2 → pycascadeui-3.12.3}/tests/test_persistence.py

@@ -1248,6 +1248,148 @@ class TestReattachOnBind:
         assert captured["view"].db == "POOL"
 
 
+class TestReattachBaselineDigest:
+    """``_reattach_one`` stamps ``_reattach_baseline_digest`` with the tree a
+    fresh ``__init__`` produced, so a teardown before ``on_restore`` ever
+    renders can tell "untouched since reattach" apart from "a teardown
+    override composed real content" -- the second case has to ship even
+    though the view itself was never rendered.
+    """
+
+    def _stub_seams(self, cls):
+        async def _fake_register(self):
+            pass
+
+        async def _fake_update(self, message):
+            pass
+
+        cls._register_state = _fake_register
+        cls._update_message_state = _fake_update
+        cls._validate_custom_ids = lambda self: None
+
+    async def _row(self, key, cls):
+        be = InMemoryBackend()
+        await be.initialize()
+        await be.row_upsert(
+            TABLE_PERSISTENT_VIEWS,
+            {
+                "persistence_key": key,
+                "view_class": cls.__qualname__,
+                "custom_id": None,
+                "message_id": 1,
+                "channel_id": 2,
+                "guild_id": None,
+                "user_id": None,
+                "session_id": None,
+                "init_kwargs": json.dumps({"persistence_key": key}),
+                "kwargs_schema_version": 1,
+                "schema_version": 1,
+                "created_at": 1,
+                "updated_at": 1,
+            },
+            ["persistence_key"],
+        )
+        mgr = PersistenceManager(store=get_store(), registry=RegistryPersistence(backend=be))
+        await mgr.rehydrate()
+        return mgr
+
+    async def _reattach(self, cls, key):
+        from cascadeui.views.persistent import PersistentLayoutView  # noqa: F401
+
+        self._stub_seams(cls)
+        mgr = await self._row(key, cls)
+
+        class _Msg:
+            id = 1
+
+            async def edit(self, **kwargs):
+                self.edited_with = kwargs
+
+            async def delete(self):
+                self.deleted = True
+
+        message = _Msg()
+
+        class _FakeBot:
+            def add_view(self, view, message_id):
+                pass
+
+        mgr._bot = _FakeBot()
+        restored_views = []
+        outcome = await mgr._reattach_one(
+            row=mgr._registry_rows[0],
+            view_cls=cls,
+            init_kwargs={"persistence_key": key},
+            message=message,
+            class_name=cls.__qualname__,
+            restored_views=restored_views,
+        )
+        assert outcome == "restored"
+        return restored_views[0], message
+
+    async def test_baseline_matches_a_fresh_non_empty_tree(self):
+        """The stamp is a fingerprint, not a sentinel: confirm it equals
+        the tree __init__ actually built, on the exact view instance
+        reattach constructed, and differs across two views whose trees
+        differ. Every empty V2 tree hashes to the same constant, so an
+        empty fixture here cannot tell a real computation from a
+        hardcoded one. __init__ has to build something.
+        """
+        from cascadeui.views.persistent import PersistentLayoutView
+
+        class _EmptyPanel(PersistentLayoutView):
+            pass
+
+        class _BuiltPanel(PersistentLayoutView):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+                self.add_item(discord.ui.TextDisplay("Loading..."))
+
+        empty_view, _ = await self._reattach(_EmptyPanel, "baseline:empty")
+        built_view, _ = await self._reattach(_BuiltPanel, "baseline:built")
+
+        assert built_view._reattach_baseline_digest is not None
+        assert built_view._reattach_baseline_digest == built_view._compute_tree_digest()
+        assert built_view._reattach_baseline_digest != empty_view._reattach_baseline_digest
+        assert built_view._has_rendered is False
+
+    async def test_untouched_restored_view_skips_the_teardown_edit(self):
+        """Nothing has changed the tree since reattach, so there is
+        nothing on screen for the teardown edit to correct -- the
+        original defect this stamp exists to keep fixed."""
+        from cascadeui.views.persistent import PersistentLayoutView
+
+        class _EmptyPanel(PersistentLayoutView):
+            pass
+
+        view, message = await self._reattach(_EmptyPanel, "baseline:untouched")
+
+        await view.exit(delete_message=False)
+
+        assert not hasattr(message, "edited_with")
+
+    async def test_farewell_card_composed_before_teardown_still_ships(self):
+        """A teardown override that composes new content before delegating
+        to ``super()`` runs whether or not ``on_restore`` ever rendered --
+        its farewell card is not the empty tree the skip exists for, and
+        has to reach the message even though ``_has_rendered`` is still
+        False."""
+        from cascadeui.components.patterns.v2 import card
+        from cascadeui.views.persistent import PersistentLayoutView
+
+        class _FarewellPanel(PersistentLayoutView):
+            async def exit(self, delete_message=None):
+                self.clear_items()
+                self.add_item(card("Session expired."))
+                return await super().exit(delete_message=delete_message)
+
+        view, message = await self._reattach(_FarewellPanel, "baseline:farewell")
+
+        await view.exit(delete_message=False)
+
+        assert hasattr(message, "edited_with")
+
+
 class TestSendTimeBind:
     """``_bind_from_context`` (the send-time seam) forwards ``on_bind`` when
     the construction context resolves a bot, and ``send()`` invokes it."""