pycascadeui 3.3.2__tar.gz → 3.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.3.2
+Version: 3.3.3
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT

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

@@ -12,6 +12,14 @@ import logging as _logging
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())
 
 from .components.base import DynamicPersistentButton, StatefulButton, StatefulSelect
+from .components.buttons import (
+    DangerButton,
+    LinkButton,
+    PrimaryButton,
+    SecondaryButton,
+    SuccessButton,
+    ToggleButton,
+)
 from .components.inputs import Checkbox, CheckboxGroup, FileUpload, Modal, RadioGroup, TextInput
 from .components.patterns import (
     ConfirmationButtons,
@@ -40,6 +48,13 @@ from .components.patterns import (
     toggle_button,
     toggle_section,
 )
+from .components.selects import (
+    ChannelSelect,
+    Dropdown,
+    MentionableSelect,
+    RoleSelect,
+    UserSelect,
+)
 from .components.types import EmojiInput, MediaInput
 from .components.v1_composition import CompositeComponent, get_component, register_component
 from .components.wrappers import with_confirmation, with_cooldown, with_loading_state
@@ -132,7 +147,7 @@ if "SQLiteBackend" in _persistence_all:
 # // ========================================( Script )======================================== // #
 
 
-__version__ = "3.3.2"
+__version__ = "3.3.3"
 
 # Export public API
 __all__ = [
@@ -179,6 +194,17 @@ __all__ = [
     "StatefulButton",
     "StatefulSelect",
     "DynamicPersistentButton",
+    "PrimaryButton",
+    "SecondaryButton",
+    "SuccessButton",
+    "DangerButton",
+    "LinkButton",
+    "ToggleButton",
+    "Dropdown",
+    "RoleSelect",
+    "ChannelSelect",
+    "UserSelect",
+    "MentionableSelect",
     "CompositeComponent",
     "ConfirmationButtons",
     "PaginationControls",

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/devtools.py

@@ -14,7 +14,6 @@ from discord.ui import ActionRow, TextDisplay
 from .components.base import StatefulButton, StatefulSelect
 from .components.patterns import action_section, alert, card, divider, gap, key_value
 from .exceptions import InstanceLimitError
-from .state.actions import ActionCreators
 from .state.computed import _SENTINEL as _SENTINEL_COMPUTED
 from .state.computed import ComputedValue, computed
 from .state.singleton import get_store
@@ -43,15 +42,15 @@ _LIST_DISPLAY_CAP = 15
 async def _cleanup_ghost_view(store, view_id: str) -> None:
     """Drop a ghost view (state row with no live instance) from the store.
 
-    Three-step mop-up: remove from the active-view registry, remove the
-    subscriber slot, dispatch VIEW_DESTROYED so the state-tree reducer
-    trims ``state["views"][view_id]`` and session membership. Used when
-    an instance dies without routing through ``exit()`` -- the state
-    row outlives the object and only the inspector can clean it.
+    Removes the subscriber slot, then tears the view down through the atomic
+    ``_destroy_view`` seam: VIEW_DESTROYED trims ``state["views"][view_id]``
+    and session membership, and the active-registry entry is cleared only
+    after state confirms the removal. Used when an instance dies without
+    routing through ``exit()`` -- the state row outlives the object and only
+    the inspector can clean it.
     """
-    store._unregister_view(view_id)
     store._unsubscribe(view_id)
-    await store.dispatch("VIEW_DESTROYED", ActionCreators.view_destroyed(view_id))
+    await store._destroy_view(view_id)
 
 
 # // ========================================( Computed Aggregations )======================================== // #
@@ -152,15 +151,33 @@ class InspectorView(TabLayoutView):
         notification and the Views tab's Channel / Msg columns stay null
         until the user manually refreshes.
         """
+        # Filter to the same rows the Views / Sessions tabs display (exclude
+        # every inspector, honor the guild scope) so a guild-scoped inspector
+        # does not rebuild on out-of-scope cross-guild activity.
         views = frozenset(
             (k, v.get("message_id"), v.get("channel_id"))
             for k, v in state.get("views", {}).items()
             if k != self.id
+            and v.get("type") != "InspectorView"
+            and self._in_scope(v.get("guild_id"))
+        )
+        view_rows = state.get("views", {})
+        inspector_sessions = {
+            v.get("session_id") for v in view_rows.values() if v.get("type") == "InspectorView"
+        }
+        inspector_sessions.add(self.session_id)
+        sessions = frozenset(
+            k
+            for k, v in state.get("sessions", {}).items()
+            if k not in inspector_sessions and self._in_scope(v.get("guild_id"))
         )
-        sessions = frozenset(k for k in state.get("sessions", {}) if k != self.session_id)
         return (views, sessions)
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, scope_guild_id=None, **kwargs):
+        # scope_guild_id: an int restricts the Views / Sessions tabs to that
+        # guild; None shows every guild. The /cascadeui inspect command
+        # defaults this to the executing guild.
+        self._scope_guild_id = scope_guild_id
         tabs = {
             "\U0001f4ca Overview": self.build_overview,
             "\U0001f441\ufe0f Views": self.build_views,
@@ -173,15 +190,46 @@ class InspectorView(TabLayoutView):
 
     # // ==================( Filtering )================== // #
 
+    def _in_scope(self, guild_id) -> bool:
+        """Whether a row's guild belongs to the inspector's scope.
+
+        A ``None`` scope is global -- every guild passes. A guildless row
+        (DM-originated, ``guild_id`` is ``None``) only passes the global scope.
+        """
+        return self._scope_guild_id is None or guild_id == self._scope_guild_id
+
     def _filtered_views(self):
-        """Return state views excluding the inspector's own entry."""
+        """State views, excluding every inspector and rows outside the scope.
+
+        Filtering by ``type`` rather than ``self.id`` drops other inspectors
+        open in other guilds too, not just this one -- they are observer-effect
+        noise wherever they appear.
+        """
         views = self.state_store.state.get("views", {})
-        return {k: v for k, v in views.items() if k != self.id}
+        return {
+            k: v
+            for k, v in views.items()
+            if k != self.id
+            and v.get("type") != "InspectorView"
+            and self._in_scope(v.get("guild_id"))
+        }
 
     def _filtered_sessions(self):
-        """Return state sessions excluding the inspector's own session."""
+        """State sessions, excluding inspector sessions and out-of-scope guilds."""
+        views = self.state_store.state.get("views", {})
+        # Drop this inspector's own session plus any session whose view is
+        # another inspector. self.session_id covers the common case where the
+        # inspector's own view row is not present in the probed state.
+        inspector_sessions = {
+            v.get("session_id") for v in views.values() if v.get("type") == "InspectorView"
+        }
+        inspector_sessions.add(self.session_id)
         sessions = self.state_store.state.get("sessions", {})
-        return {k: v for k, v in sessions.items() if k != self.session_id}
+        return {
+            k: v
+            for k, v in sessions.items()
+            if k not in inspector_sessions and self._in_scope(v.get("guild_id"))
+        }
 
     def _filtered_history(self):
         """Return action history excluding the inspector's own dispatches."""
@@ -242,30 +290,36 @@ class InspectorView(TabLayoutView):
         components = self._filtered_components()
         modals = self._filtered_modals()
 
-        # Total counts come from the module-level @computed aggregations; the
-        # inspector subtracts its own contribution only when registered.
-        # TabLayoutView.send() calls build_overview() before super().send()
-        # dispatches VIEW_CREATED / SESSION_CREATED, so on first render the
-        # inspector's own ids are not yet in state -- subtracting 1
-        # unconditionally would under-count every other view by one.
-        # Probing state membership picks the right subtraction every render.
-        state_views = store.state.get("views", {})
-        state_sessions = store.state.get("sessions", {})
-        self_view_present = self.id in state_views
-        self_session_present = self.session_id in state_sessions
-        view_count = max(0, store.computed["total_views"] - (1 if self_view_present else 0))
-        session_count = max(
-            0,
-            store.computed["total_sessions"] - (1 if self_session_present else 0),
-        )
+        # Scoped counts come from the filtered helpers so the Overview agrees
+        # with the Views / Sessions tabs -- both exclude inspectors and honor
+        # the guild scope.
+        view_count = len(self._filtered_views())
+        session_count = len(self._filtered_sessions())
 
+        scope_label = (
+            f"Guild `{self._scope_guild_id}`"
+            if self._scope_guild_id is not None
+            else "Global (all guilds)"
+        )
         stats = {
+            "Scope": scope_label,
             "Views": view_count,
             "Sessions": session_count,
             "Components": len(components),
         }
         if modals:
             stats["Modals"] = len(modals)
+        if self._scope_guild_id is not None:
+            # All-guilds totals from the @computed aggregates. TabLayoutView.send()
+            # builds this tab before VIEW_CREATED / SESSION_CREATED dispatch, so
+            # the inspector's own ids may not be in state yet -- probe membership
+            # to subtract its own contribution only once registered.
+            views_state = store.state.get("views", {})
+            sessions_state = store.state.get("sessions", {})
+            self_view = 1 if self.id in views_state else 0
+            self_session = 1 if self.session_id in sessions_state else 0
+            stats["Views (all guilds)"] = max(0, store.computed["total_views"] - self_view)
+            stats["Sessions (all guilds)"] = max(0, store.computed["total_sessions"] - self_session)
 
         overview = card(
             "## State Inspector",
@@ -1258,11 +1312,25 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
 
     # // ==================( View Commands )================== // #
 
+    @staticmethod
+    def _scope_guild(ctx: Context):
+        """Guild id the text commands scope to, or None in a DM (all guilds).
+
+        The listing and bulk-exit commands filter to this guild; None passes
+        every row.
+        """
+        return ctx.guild.id if ctx.guild else None
+
     @cascadeui_group.command(name="views", description="List active CascadeUI views.")
     async def list_views(self, ctx: Context) -> None:
-        """List all active views in the state store."""
+        """List active views in the executing guild."""
         store = get_store()
-        views = store.state.get("views", {})
+        gid = self._scope_guild(ctx)
+        views = {
+            k: v
+            for k, v in store.state.get("views", {}).items()
+            if gid is None or v.get("guild_id") == gid
+        }
         active = store.get_active_views()
 
         if not views:
@@ -1278,7 +1346,8 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
         if len(views) > _LIST_DISPLAY_CAP:
             lines.append(f"*...and {len(views) - _LIST_DISPLAY_CAP} more*")
 
-        header = f"**{len(views)} view(s)** ({len(active)} live)\n"
+        live = sum(1 for vid in views if vid in active)
+        header = f"**{len(views)} view(s)** ({live} live)\n"
         await ctx.send(header + "\n".join(lines), ephemeral=True)
 
     @cascadeui_group.command(name="exit", description="Exit a specific CascadeUI view by ID.")
@@ -1319,14 +1388,17 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
 
     @cascadeui_group.command(name="exitall", description="Exit all active CascadeUI views.")
     async def exit_all(self, ctx: Context) -> None:
-        """Exit all active views and clean ghost entries."""
+        """Exit active views in the executing guild and clean their ghosts."""
         store = get_store()
+        gid = self._scope_guild(ctx)
         views = dict(store.state.get("views", {}))
         active = dict(store.get_active_views())
         exited = 0
         failed = 0
 
         for view_id, view in list(active.items()):
+            if gid is not None and getattr(view, "guild_id", None) != gid:
+                continue
             try:
                 await view.exit()
                 exited += 1
@@ -1334,10 +1406,13 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
                 logger.debug("exit_all: view %s failed to exit cleanly: %s", view_id, exc)
                 failed += 1
 
-        for view_id in list(views.keys()):
-            if view_id not in active:
-                await _cleanup_ghost_view(store, view_id)
-                exited += 1
+        for view_id, view_data in list(views.items()):
+            if view_id in active:
+                continue
+            if gid is not None and view_data.get("guild_id") != gid:
+                continue
+            await _cleanup_ghost_view(store, view_id)
+            exited += 1
 
         suffix = f" ({failed} failed)" if failed else ""
         await ctx.send(f"Exited {exited} view(s){suffix}.", ephemeral=True)
@@ -1447,9 +1522,14 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
 
     @cascadeui_group.command(name="sessions", description="List active CascadeUI sessions.")
     async def list_sessions(self, ctx: Context) -> None:
-        """List all sessions in the state store."""
+        """List sessions in the executing guild."""
         store = get_store()
-        sessions = store.state.get("sessions", {})
+        gid = self._scope_guild(ctx)
+        sessions = {
+            k: v
+            for k, v in store.state.get("sessions", {}).items()
+            if gid is None or v.get("guild_id") == gid
+        }
 
         if not sessions:
             return await ctx.send("No active sessions.", ephemeral=True)
@@ -1499,19 +1579,40 @@ class DevToolsCog(commands.Cog, name="cascadeui_devtools"):
     # // ==================( Inspector Command )================== // #
 
     @cascadeui_group.command(name="inspect", description="Open the CascadeUI state inspector.")
-    async def inspect(self, ctx: Context) -> None:
+    async def inspect(self, ctx: Context, scope: str = None) -> None:
         """Open the visual state inspector.
 
         A tabbed V2 dashboard showing the live state tree, active views,
         sessions, action history, and store configuration with interactive
         controls for managing views, sessions, and state.
+
+        Scope defaults to the current guild. Pass ``global`` (or ``all``) to
+        inspect every guild, or a guild id to target a specific guild.
         """
+        scope_guild_id = self._resolve_inspect_scope(ctx, scope)
         try:
-            view = InspectorView(context=ctx)
+            view = InspectorView(context=ctx, scope_guild_id=scope_guild_id)
             await view.send()
         except InstanceLimitError:
             await ctx.send("Inspector already open.", ephemeral=True)
 
+    @staticmethod
+    def _resolve_inspect_scope(ctx: Context, scope: str = None):
+        """Map the optional scope argument to a guild id, or None for global.
+
+        No argument defaults to the executing guild (None in a DM). ``global``
+        or ``all`` widen to every guild. A numeric string targets that guild
+        id. Anything unrecognized falls back to the executing guild.
+        """
+        if scope is None:
+            return ctx.guild.id if ctx.guild else None
+        normalized = scope.strip().lower()
+        if normalized in ("global", "all"):
+            return None
+        if normalized.isdigit():
+            return int(normalized)
+        return ctx.guild.id if ctx.guild else None
+
     # // ==================( Registry Commands )================== // #
 
     @cascadeui_group.command(

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/persistence/manager.py

@@ -596,33 +596,20 @@ class PersistenceManager:
                 # subscriber + registry entry + undo-tracking row, all
                 # of which must go back before the next row is tried.
                 self._store._unsubscribe(view.id)
-                self._store._unregister_view(view.id)
                 self._store._undo_enabled_views.pop(view.id, None)
-                # If state registration succeeded before the failure,
-                # the SESSION_CREATED + VIEW_CREATED actions already
-                # landed in store state. Dispatch VIEW_DESTROYED to
-                # tear those down -- otherwise the session and view
-                # entries would persist as zombies for the rest of
-                # the process lifetime. ``reduce_view_destroyed``
-                # cleans up the session entry too when its members
-                # list empties.
                 if state_registered:
-                    # Late import: ``state.actions`` would not introduce
-                    # a circular dep, but the file's convention is to
-                    # late-import every state-domain symbol (matches the
-                    # ``PersistenceMiddleware`` import below).
-                    from ..state.actions import ActionCreators
-
-                    try:
-                        await self._store.dispatch(
-                            "VIEW_DESTROYED",
-                            ActionCreators.view_destroyed(view.id),
-                        )
-                    except Exception as cleanup_exc:
-                        logger.error(
-                            f"Rollback dispatch failed for {persistence_key!r}: " f"{cleanup_exc}",
-                            exc_info=True,
-                        )
+                    # State registration landed SESSION_CREATED + VIEW_CREATED,
+                    # so tear them down through the atomic seam: _destroy_view
+                    # dispatches VIEW_DESTROYED, then clears the active-registry
+                    # entry only after state confirms the removal. A failed
+                    # dispatch leaves both registries intact instead of
+                    # stranding a ghost; _destroy_view catches and logs the
+                    # dispatch failure internally. ``reduce_view_destroyed``
+                    # cleans up the session entry too when its members empty.
+                    await self._store._destroy_view(view.id)
+                else:
+                    # State never registered; just drop the active entry.
+                    self._store._unregister_view(view.id)
             return "failed"
 
     # // ========================================( Middleware install )======================================== // #

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/state/actions.py

@@ -3,7 +3,7 @@
 
 from typing import Any, Dict, List, Optional
 
-from .types import ComponentId, SessionId, UserId, ViewId
+from .types import ComponentId, GuildId, SessionId, UserId, ViewId
 
 # Type alias for action payloads
 ActionPayload = Dict[str, Any]
@@ -21,6 +21,7 @@ class ActionCreators:
         view_type: str,
         user_id: Optional[UserId] = None,
         session_id: Optional[SessionId] = None,
+        guild_id: GuildId = None,
         **props,
     ) -> ActionPayload:
         """Create a VIEW_CREATED action payload."""
@@ -29,6 +30,7 @@ class ActionCreators:
             "view_type": view_type,
             "user_id": user_id,
             "session_id": session_id,
+            "guild_id": guild_id,
             "props": props,
         }
 
@@ -44,10 +46,18 @@ class ActionCreators:
 
     @staticmethod
     def session_created(
-        session_id: SessionId, user_id: Optional[UserId] = None, **data
+        session_id: SessionId,
+        user_id: Optional[UserId] = None,
+        guild_id: GuildId = None,
+        **data,
     ) -> ActionPayload:
         """Create a SESSION_CREATED action payload."""
-        return {"session_id": session_id, "user_id": user_id, "shared_data": data}
+        return {
+            "session_id": session_id,
+            "user_id": user_id,
+            "guild_id": guild_id,
+            "shared_data": data,
+        }
 
     @staticmethod
     def session_updated(session_id: SessionId, **data) -> ActionPayload:

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/state/reducers.py

@@ -76,6 +76,7 @@ async def reduce_view_created(action: Action, state: StateData) -> StateData:
         "id": view_id,
         "type": payload.get("view_type"),
         "user_id": payload.get("user_id"),
+        "guild_id": payload.get("guild_id"),
         "session_id": payload.get("session_id"),
         "created_at": action["timestamp"],
         "updated_at": action["timestamp"],
@@ -182,6 +183,7 @@ async def reduce_session_created(action: Action, state: StateData) -> StateData:
     new_session = {
         "id": session_id,
         "user_id": payload.get("user_id"),
+        "guild_id": payload.get("guild_id"),
         "created_at": action["timestamp"],
         "updated_at": action["timestamp"],
         "members": [],

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/state/store.py

@@ -12,6 +12,7 @@ from typing import Any, Dict, Iterator, List, Mapping, Optional, Set, Tuple, Uni
 
 from ..utils.errors import with_error_boundary
 from ..utils.tasks import get_task_manager
+from .actions import ActionCreators
 from .slots import access_slot, read_slot
 from .types import Action, HookFn, MiddlewareFn, ReducerFn, SelectorFn, StateData, SubscriberFn
 
@@ -912,6 +913,57 @@ class StateStore:
                 if p_key is not None and p_key != scope_key:
                     self._remove_from_instance_index(view_id, view_type, p_key)
 
+    async def _destroy_view(self, view_id: str, *, source_id: Optional[str] = None) -> bool:
+        """Atomic view teardown: dispatch ``VIEW_DESTROYED``, then drop the active entry.
+
+        A live view occupies two registries: ``state["views"]`` (the Redux
+        source of truth, mutated only through the reducer) and ``_active_views``
+        (the sync instance-limit and inspector index). This method tears them
+        down in a fixed order. The async ``VIEW_DESTROYED`` dispatch removes the
+        ``state["views"]`` entry first; ``_unregister_view`` clears the
+        ``_active_views`` entry only once state confirms the view is gone.
+
+        The ordering keeps the two registries consistent under failure. A
+        raising middleware, a reducer error the dispatch chain logs and
+        absorbs, or a cancellation mid-dispatch all leave both registries
+        intact rather than producing the inspector-flagged divergence (a view
+        present in ``state["views"]`` but absent from ``_active_views``).
+        Over-retention is transient and self-heals on the next teardown or
+        restart.
+
+        Idempotent and safe under double-teardown. Returns ``True`` when the
+        view was fully removed, ``False`` when the state removal did not land
+        and the active-registry entry was retained.
+        """
+        try:
+            await self.dispatch(
+                "VIEW_DESTROYED", ActionCreators.view_destroyed(view_id), source_id=source_id
+            )
+        except Exception:
+            # Log and fall through to the post-dispatch state check below: if
+            # the reducer ran before the exception (state already clean), the
+            # finally clears the active entry and the check returns True; if not,
+            # the check returns False and retains both registries.
+            logger.exception(
+                f"VIEW_DESTROYED dispatch failed for {view_id}; "
+                f"checking whether the state entry was removed."
+            )
+        finally:
+            # Clear the active entry only once state confirms the removal. The
+            # finally clause also covers a cancellation mid-dispatch: when the
+            # reducer already removed the state entry before the await was
+            # cancelled, the active entry still gets cleared, so a cancelled
+            # teardown cannot leave the view stranded in _active_views.
+            if view_id not in self.state.get("views", {}):
+                self._unregister_view(view_id)
+        if view_id not in self.state.get("views", {}):
+            return True
+        logger.warning(
+            f"VIEW_DESTROYED did not remove {view_id} from state; "
+            f"retaining active-registry entry to avoid a ghost."
+        )
+        return False
+
     def _get_active_views(self, view_type: str, scope_key: str) -> list:
         """Return active view instances for a type+scope, oldest-first. Internal plumbing."""
         key = (view_type, scope_key)

{pycascadeui-3.3.2 → pycascadeui-3.3.3}/cascadeui/state/types.py

@@ -8,6 +8,7 @@ ViewId = str
 SessionId = str
 ComponentId = str
 UserId = Optional[int]
+GuildId = Optional[int]
 Timestamp = str
 
 # Simple action type