pycascadeui 3.2.0__tar.gz → 3.3.0__tar.gz

{pycascadeui-3.2.0/pycascadeui.egg-info → pycascadeui-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycascadeui
-Version: 3.2.0
+Version: 3.3.0
 Summary: Redux-inspired UI framework for discord.py
 Author-email: HollowTheSilver <hollow@users.noreply.github.com>
 License-Expression: MIT
@@ -30,12 +30,15 @@ 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: testcontainers[postgres]>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"
 Requires-Dist: mkdocs-material>=9.0; extra == "docs"
 Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
 Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.19; extra == "sqlite"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30; extra == "postgres"
 Dynamic: license-file
 
 <p align="center">
@@ -149,7 +152,8 @@ pip install pycascadeui
 Optional dependencies:
 
 ```bash
-pip install pycascadeui[sqlite]
+pip install pycascadeui[sqlite]      # single-process persistence
+pip install pycascadeui[postgres]    # multi-process persistence with LISTEN/NOTIFY
 ```
 
 Requirements:
@@ -647,7 +651,7 @@ for row in rows:
 ### Components
 - Stateful buttons, selects, and modals with state integration
 - Select callbacks can opt into a `values` second parameter
-- V2 builders: `card()`, `stats_card()`, `action_section()`, `toggle_section()`, `image_section()`, `link_section()`, `confirm_section()`, `button_row()`, `cycle_button()`, `toggle_button()`, `tab_nav()`, `key_value()`, `alert()`, `progress_bar()`, `divider()`, `gap()`, `gallery()`
+- V2 builders: `card()`, `stats_card()`, `action_section()`, `toggle_section()`, `image_section()`, `link_section()`, `confirm_section()`, `button_row()`, `cycle_button()`, `toggle_button()`, `tab_nav()`, `key_value()`, `alert()`, `progress_bar()`, `divider()`, `gap()`, `gallery()`, `file_attachment()`
 - Grid helpers: `emoji_grid()` and `button_grid()`
 - Typed modal fields (`text`, `integer`, `float`, `date`) with per-field validation
 - Declarative `FormSchema` and `WizardSchema` base classes
@@ -674,7 +678,8 @@ for row in rows:
 ### Persistence
 - Persistent views that survive bot restarts with automatic message re-attachment
 - Opt-in per slot via `persistent_slots = (...)` (≈ `redux-persist`)
-- Built-in SQLite and in-memory backends; custom backends via capability-flag `Protocol`
+- Built-in SQLite, PostgreSQL, and in-memory backends; custom backends via capability-flag `Protocol`
+- Cross-process scoped invalidation through PostgreSQL `LISTEN`/`NOTIFY` (multi-worker bots)
 - Named scoped buckets via `scoped_slot` for per-subsystem persistence
 - Two-namespace model (`registry` and `application`) with per-namespace debounce and retry backoff
 - Undo and redo via snapshot-based state history (opt in with `enable_undo`)

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/README.md

@@ -109,7 +109,8 @@ pip install pycascadeui
 Optional dependencies:
 
 ```bash
-pip install pycascadeui[sqlite]
+pip install pycascadeui[sqlite]      # single-process persistence
+pip install pycascadeui[postgres]    # multi-process persistence with LISTEN/NOTIFY
 ```
 
 Requirements:
@@ -607,7 +608,7 @@ for row in rows:
 ### Components
 - Stateful buttons, selects, and modals with state integration
 - Select callbacks can opt into a `values` second parameter
-- V2 builders: `card()`, `stats_card()`, `action_section()`, `toggle_section()`, `image_section()`, `link_section()`, `confirm_section()`, `button_row()`, `cycle_button()`, `toggle_button()`, `tab_nav()`, `key_value()`, `alert()`, `progress_bar()`, `divider()`, `gap()`, `gallery()`
+- V2 builders: `card()`, `stats_card()`, `action_section()`, `toggle_section()`, `image_section()`, `link_section()`, `confirm_section()`, `button_row()`, `cycle_button()`, `toggle_button()`, `tab_nav()`, `key_value()`, `alert()`, `progress_bar()`, `divider()`, `gap()`, `gallery()`, `file_attachment()`
 - Grid helpers: `emoji_grid()` and `button_grid()`
 - Typed modal fields (`text`, `integer`, `float`, `date`) with per-field validation
 - Declarative `FormSchema` and `WizardSchema` base classes
@@ -634,7 +635,8 @@ for row in rows:
 ### Persistence
 - Persistent views that survive bot restarts with automatic message re-attachment
 - Opt-in per slot via `persistent_slots = (...)` (≈ `redux-persist`)
-- Built-in SQLite and in-memory backends; custom backends via capability-flag `Protocol`
+- Built-in SQLite, PostgreSQL, and in-memory backends; custom backends via capability-flag `Protocol`
+- Cross-process scoped invalidation through PostgreSQL `LISTEN`/`NOTIFY` (multi-worker bots)
 - Named scoped buckets via `scoped_slot` for per-subsystem persistence
 - Two-namespace model (`registry` and `application`) with per-namespace debounce and retry backoff
 - Undo and redo via snapshot-based state history (opt in with `enable_undo`)

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/__init__.py

@@ -28,6 +28,7 @@ from .components.patterns import (
     cycle_button,
     divider,
     emoji_grid,
+    file_attachment,
     gallery,
     gap,
     image_section,
@@ -39,7 +40,7 @@ from .components.patterns import (
     toggle_button,
     toggle_section,
 )
-from .components.types import EmojiInput
+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
 from .devtools import DevToolsCog, InspectorView
@@ -82,8 +83,9 @@ from .theming.core import Theme, get_default_theme, get_theme, register_theme, s
 from .theming.themes import dark_theme, default_theme, light_theme
 from .utils.decorators import cascade_component, cascade_reducer
 from .utils.errors import safe_execute, with_error_boundary, with_retry
-from .utils.helpers import slugify
+from .utils.fetch import fetch_as_file
 from .utils.logging import setup_logging
+from .utils.strings import slugify
 from .utils.tasks import get_task_manager
 from .validation import (
     ValidationResult,
@@ -130,7 +132,7 @@ if "SQLiteBackend" in _persistence_all:
 # // ========================================( Script )======================================== // #
 
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"
 
 # Export public API
 __all__ = [
@@ -197,6 +199,7 @@ __all__ = [
     "with_cooldown",
     # Type aliases
     "EmojiInput",
+    "MediaInput",
     # V2 Cards & Sections
     "card",
     "action_section",
@@ -220,6 +223,7 @@ __all__ = [
     "tab_nav",
     # V2 Media
     "gallery",
+    "file_attachment",
     # V2 Grids
     "EmojiGrid",
     "emoji_grid",
@@ -277,6 +281,7 @@ __all__ = [
     "cascade_reducer",
     "cascade_component",
     "slugify",
+    "fetch_as_file",
     # DevTools
     "InspectorView",
     "DevToolsCog",

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/components/__init__.py

@@ -23,6 +23,7 @@ from .patterns import (
     confirm_section,
     cycle_button,
     divider,
+    file_attachment,
     gallery,
     gap,
     image_section,
@@ -35,7 +36,7 @@ from .patterns import (
     toggle_section,
 )
 from .selects import ChannelSelect, Dropdown, MentionableSelect, RoleSelect, UserSelect
-from .types import EmojiInput
+from .types import EmojiInput, MediaInput
 from .v1_composition import CompositeComponent, get_component, register_component
 from .wrappers import with_confirmation, with_cooldown, with_loading_state
 
@@ -102,6 +103,8 @@ __all__ = [
     "tab_nav",
     # V2 media
     "gallery",
+    "file_attachment",
     # Type aliases
     "EmojiInput",
+    "MediaInput",
 ]

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/components/patterns/__init__.py

@@ -13,6 +13,7 @@ from .v2 import (
     cycle_button,
     divider,
     emoji_grid,
+    file_attachment,
     gallery,
     gap,
     image_section,
@@ -57,6 +58,7 @@ __all__ = [
     "tab_nav",
     # V2 media
     "gallery",
+    "file_attachment",
     # V2 grids
     "EmojiGrid",
     "emoji_grid",

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/components/patterns/v2.py

@@ -9,6 +9,7 @@ from discord.enums import SeparatorSpacing
 from discord.ui import (
     ActionRow,
     Container,
+    File,
     MediaGallery,
     Section,
     Separator,
@@ -17,11 +18,33 @@ from discord.ui import (
 )
 
 from ..base import StatefulButton
-from ..types import EmojiInput
+from ..types import EmojiInput, MediaInput
 
 # Discord content-length ceiling for a single TextDisplay component.
 _TEXTDISPLAY_MAX_CHARS = 4000
 
+
+def _coerce_media_ref(value: MediaInput) -> str:
+    """Resolve a ``MediaInput`` to the URL string Discord's API consumes.
+
+    Strings pass through unchanged. A :class:`discord.File` resolves to
+    its ``.uri`` (the ``"attachment://<filename>"`` reference built from
+    the normalized filename). The builder emits only the reference
+    string; the bytes travel separately through
+    ``view.send(files=[...])``.
+
+    Only the ``.uri`` is extracted -- the ``description`` and ``spoiler``
+    attributes of the source :class:`discord.File` are NOT forwarded.
+    Builders that wrap the reference in a component carrying those
+    fields (``image_section``, ``file_attachment``) accept them as
+    explicit kwargs, so the metadata is never silently lost on the
+    documented call paths.
+    """
+    if isinstance(value, discord.File):
+        return value.uri
+    return value
+
+
 # Regional indicator emoji for alpha axis preset (🇦 through 🇿, 26 glyphs).
 _ALPHA_LABELS = [chr(0x1F1E6 + i) for i in range(26)]
 
@@ -181,7 +204,7 @@ def toggle_section(
 def image_section(
     text: str,
     *,
-    url: str,
+    url: MediaInput,
     description: Optional[str] = None,
     spoiler: bool = False,
 ) -> Section:
@@ -192,7 +215,11 @@ def image_section(
 
     Args:
         text: Display text (supports markdown).
-        url: Image URL for the thumbnail.
+        url: Image reference for the thumbnail. Accepts either a URL
+            string (remote or ``attachment://`` form) or a
+            :class:`discord.File` instance whose ``.uri`` is used.
+            File-backed references require the same ``discord.File`` to
+            be passed via ``view.send(files=[...])``.
         description: Optional alt text for the thumbnail (up to 256 chars).
         spoiler: Whether the thumbnail is hidden behind a spoiler.
 
@@ -206,7 +233,7 @@ def image_section(
             url=member.display_avatar.url,
         )
     """
-    kwargs = {"media": url, "spoiler": spoiler}
+    kwargs = {"media": _coerce_media_ref(url), "spoiler": spoiler}
     if description is not None:
         kwargs["description"] = description
     return Section(
@@ -790,18 +817,22 @@ def tab_nav(
 
 
 def gallery(
-    *urls: str,
+    *media: MediaInput,
     descriptions: Optional[Sequence[Optional[str]]] = None,
 ) -> MediaGallery:
-    """Build a MediaGallery from image URLs.
+    """Build a MediaGallery from image references.
 
     Simplifies the ``MediaGallery(MediaGalleryItem(...), ...)`` nesting
-    into a flat call with URLs.
+    into a flat call.
 
     Args:
-        *urls: Image URLs (up to 10).
+        *media: Image references (up to 10). Each accepts either a URL
+            string (remote or ``attachment://`` form) or a
+            :class:`discord.File` instance whose ``.uri`` is used.
+            File-backed references require the same ``discord.File``
+            objects to be passed via ``view.send(files=[...])``.
         descriptions: Optional sequence of descriptions matching each
-            URL positionally. Use ``None`` for items without a
+            reference positionally. Use ``None`` for items without a
             description.
 
     Returns:
@@ -815,23 +846,69 @@ def gallery(
             descriptions=["First image", None],
         )
     """
-    if descriptions is not None and len(descriptions) != len(urls):
+    if not media:
+        raise ValueError(
+            "gallery: at least one media reference is required. Discord "
+            "rejects empty MediaGallery components with HTTP 400 (1-10 "
+            "items required)."
+        )
+    if len(media) > 10:
+        raise ValueError(
+            f"gallery: too many media references ({len(media)}). Discord "
+            f"caps MediaGallery at 10 items. Split into multiple gallery() "
+            f"calls."
+        )
+    if descriptions is not None and len(descriptions) != len(media):
         raise ValueError(
             f"gallery: descriptions length ({len(descriptions)}) must match "
-            f"urls length ({len(urls)}). Pad with None for URLs that should "
-            f"have no description."
+            f"media length ({len(media)}). Pad with None for references that "
+            f"should have no description."
         )
 
     items = []
-    for i, url in enumerate(urls):
+    for i, ref in enumerate(media):
         desc = descriptions[i] if descriptions is not None else None
-        kwargs = {"media": url}
+        kwargs = {"media": _coerce_media_ref(ref)}
         if desc is not None:
             kwargs["description"] = desc
         items.append(MediaGalleryItem(**kwargs))
     return MediaGallery(*items)
 
 
+def file_attachment(
+    url: MediaInput,
+    *,
+    spoiler: bool = False,
+) -> File:
+    """Build a File component for attachment display.
+
+    Completes the V2 media family alongside ``gallery()``. Discord
+    renders the file as a downloadable card inline with the rest of the
+    V2 content.
+
+    Args:
+        url: File reference. Accepts either a remote URL, the
+            ``attachment://<filename>`` form, or a
+            :class:`discord.File` instance whose ``.uri`` is used. When
+            a file-backed reference is supplied, the same
+            ``discord.File`` must travel via ``view.send(files=[...])``.
+        spoiler: Whether to flag the file as a spoiler.
+
+    Returns:
+        A ``File`` component ready to be added to a Container or
+        ``StatefulLayoutView``.
+
+    Example::
+
+        card(
+            "## Quarterly Report",
+            file_attachment("attachment://q1_2026.pdf"),
+            "Released April 15.",
+        )
+    """
+    return File(media=_coerce_media_ref(url), spoiler=spoiler)
+
+
 # // ========================================( Grids )======================================== // #
 
 

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/components/types.py

@@ -23,3 +23,21 @@ A live :class:`discord.Emoji` (returned by ``bot.get_emoji`` or
 ``bot.fetch_application_emoji``) and a :class:`discord.PartialEmoji`
 instance are also accepted directly.
 """
+
+
+MediaInput = Union[str, discord.File]
+"""Anything CascadeUI accepts where a media reference is required.
+
+Mirrors the union accepted by :class:`discord.ui.MediaGallery`,
+:class:`discord.ui.Thumbnail`, and :class:`discord.ui.File`. Two forms:
+
+* A URL string -- either an arbitrary remote URL
+  (``"https://cdn.example.com/img.png"``) or the
+  ``"attachment://<filename>"`` reference scheme for files uploaded
+  alongside the same message.
+* A :class:`discord.File` instance, in which case the underlying
+  ``.uri`` (``"attachment://<filename>"``) is used. The same file
+  object must also be passed via ``view.send(files=[...])`` (or
+  ``refresh(attachments=[...])`` for in-place swaps) so the bytes
+  travel with the message.
+"""

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/persistence/__init__.py

@@ -29,3 +29,8 @@ if "SQLiteBackend" in _backends_all:
     from .backends import SQLiteBackend  # noqa: F401
 
     __all__.append("SQLiteBackend")
+
+if "PostgresBackend" in _backends_all:
+    from .backends import PostgresBackend  # noqa: F401
+
+    __all__.append("PostgresBackend")

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/persistence/backends/__init__.py

@@ -17,3 +17,12 @@ try:
 except ImportError as _e:
     if "aiosqlite" not in str(_e):
         _logger.warning(f"Failed to import SQLiteBackend: {_e}")
+
+# Optional backend -- imported lazily to avoid a hard dependency on asyncpg
+try:
+    from .postgres import PostgresBackend
+
+    __all__.append("PostgresBackend")
+except ImportError as _e:
+    if "asyncpg" not in str(_e):
+        _logger.warning(f"Failed to import PostgresBackend: {_e}")

{pycascadeui-3.2.0 → pycascadeui-3.3.0}/cascadeui/persistence/backends/memory.py

@@ -45,9 +45,17 @@ class InMemoryBackend:
     """
 
     capabilities: ClassVar[Capability] = (
-        Capability.KV | Capability.RELATIONAL | Capability.TTL_INDEX | Capability.SCHEMA_META
+        Capability.KV
+        | Capability.RELATIONAL
+        | Capability.TTL_INDEX
+        | Capability.SCHEMA_META
+        # Capability.RAW_SQL deliberately omitted -- in-memory storage
+        # has no SQL engine to escape to. Code paths that require raw SQL
+        # must check `Capability.RAW_SQL in backend.capabilities` first.
     )
 
+    placeholder_style: ClassVar[str] = "n/a"
+
     def __init__(self) -> None:
         self._kv: dict[str, dict[str, bytes]] = {}
         self._rows: dict[str, list[dict[str, Any]]] = {}
@@ -155,3 +163,34 @@ class InMemoryBackend:
 
     async def set_schema_version(self, table: str, version: int) -> None:
         self._schema_versions[table] = version
+
+    # // ========================================( Raw SQL opt-out stubs )======================================== // #
+
+    # Capability.RAW_SQL is deliberately not declared on this backend --
+    # in-memory storage has no SQL engine to escape to. The five methods
+    # below raise NotImplementedError with a clear remediation message
+    # rather than producing AttributeError, so callers who reach for the
+    # escape hatch against InMemoryBackend get a directed error pointing
+    # them at SQLiteBackend or PostgresBackend.
+
+    _RAW_SQL_ERROR: ClassVar[str] = (
+        "InMemoryBackend does not support Capability.RAW_SQL. "
+        "Use SQLiteBackend or PostgresBackend for raw-SQL operations, "
+        "or check `Capability.RAW_SQL in backend.capabilities` before "
+        "reaching for the escape hatch."
+    )
+
+    async def execute(self, sql: str, *params: Any) -> int:
+        raise NotImplementedError(self._RAW_SQL_ERROR)
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        raise NotImplementedError(self._RAW_SQL_ERROR)
+
+    async def executemany(self, sql: str, params_list: list[tuple]) -> int:
+        raise NotImplementedError(self._RAW_SQL_ERROR)
+
+    async def fetch_one(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        raise NotImplementedError(self._RAW_SQL_ERROR)
+
+    def transaction(self) -> Any:
+        raise NotImplementedError(self._RAW_SQL_ERROR)