sqlnotify 0.1.0__py3-none-any.whl

sqlnotify/__init__.py

@@ -0,0 +1,14 @@
+from importlib.metadata import version
+
+from .constants import PACKAGE_NAME
+from .notifiers import Notifier
+from .types import ChangeEvent, FilterOnParams, Operation
+
+__version__ = version(PACKAGE_NAME)
+
+__all__ = [
+    "ChangeEvent",
+    "FilterOnParams",
+    "Notifier",
+    "Operation",
+]

sqlnotify/adapters/asgi.py

@@ -0,0 +1,40 @@
+from contextlib import asynccontextmanager
+
+from ..notifiers.notifier import Notifier
+
+
+@asynccontextmanager
+async def sqlnotify_lifespan(notifier: Notifier):
+    """
+    Lifespan context manager for FastAPI.
+
+    Automatically detects whether the notifier is using an async or sync engine
+    and uses the appropriate methods (astart/astop for async, start/stop for sync).
+
+    Examples:
+
+        from fastapi import FastAPI # Or any ASGI framework that supports lifespan events
+        from contextlib import asynccontextmanager
+
+        notifier = Notifier(...)
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            async with sqlnotify_lifespan(notifier):
+                yield
+
+        app = FastAPI(lifespan=lifespan)
+    """
+
+    if notifier.async_mode:
+        await notifier.astart()
+        try:
+            yield
+        finally:
+            await notifier.astop()
+    else:
+        notifier.start()
+        try:
+            yield
+        finally:
+            notifier.stop()

sqlnotify/constants.py

@@ -0,0 +1,9 @@
+PACKAGE_NAME = "sqlnotify"
+
+MAX_SQLNOTIFY_PAYLOAD_BYTES = 7999  # PostgreSQL NOTIFY payload limit (8000 - 1 for terminator)
+
+MAX_SQLNOTIFY_IDENTIFER_BYTES = 63  # PostgreSQL identifier limit (63 bytes)
+
+MAX_SQLNOTIFY_EXTRA_COLUMNS = 5  # Limit extra columns to help stay within payload size limit, but this is not a hard limit since column data size can vary greatly
+
+MAX_SQLNOTIFY_EVENT_RETRIES = 3  # Max retries for any event in sqlnotify

sqlnotify/dialects/__init__.py

@@ -0,0 +1,12 @@
+from .base import BaseDialect
+from .postgresql import PostgreSQLDialect
+from .sqlite import SQLiteDialect
+from .utils import detect_dialect_name, get_dialect_for_engine
+
+__all__ = [
+    "BaseDialect",
+    "PostgreSQLDialect",
+    "SQLiteDialect",
+    "get_dialect_for_engine",
+    "detect_dialect_name",
+]

sqlnotify/dialects/base.py

@@ -0,0 +1,183 @@
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from ..watcher import Watcher
+
+
+class BaseDialect(ABC):
+    """
+    Abstract base class for database dialect implementations
+    """
+
+    def __init__(
+        self,
+        async_engine: AsyncEngine | None,
+        sync_engine: Engine | None,
+        logger: logging.Logger | None = None,
+        revoke_on_model_change: bool = True,
+    ):
+        self._async_engine = async_engine
+        self._sync_engine = sync_engine
+        self._logger = logger
+        self._listen_conn: Any | None = None
+        self.revoke_on_model_change = revoke_on_model_change
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Return the dialect name (e.g., 'postgresql', 'mysql', 'sqlite')
+        """
+        pass
+
+    @abstractmethod
+    async def table_exists_async(self, schema: str, table: str) -> bool:
+        """
+        Check if a table exists in the database asynchronously
+        """
+        pass
+
+    @abstractmethod
+    def table_exists_sync(self, schema: str, table: str) -> bool:
+        """
+        Check if a table exists in the database synchronously
+        """
+        pass
+
+    @abstractmethod
+    async def create_trigger_async(self, watcher: Watcher) -> None:
+        """
+        Create database trigger asynchronously
+        """
+        pass
+
+    @abstractmethod
+    def create_trigger_sync(self, watcher: Watcher) -> None:
+        """
+        Create database trigger synchronously
+        """
+        pass
+
+    @abstractmethod
+    async def listen_async(
+        self,
+        watchers: list[Watcher],
+        running_check: Callable[[], bool],
+        handle_notification: Callable[[str, str], Any],
+        database_url: str,
+        listener_ready: Any | None = None,
+    ) -> None:
+        """
+        Listen for database notifications asynchronously
+        """
+        pass
+
+    @abstractmethod
+    async def cleanup_async(self, watchers: list[Watcher]) -> None:
+        """
+        Remove all triggers and functions asynchronously
+        """
+        pass
+
+    @abstractmethod
+    def cleanup_sync(self, watchers: list[Watcher]) -> None:
+        """
+        Remove all triggers and functions synchronously
+        """
+        pass
+
+    @abstractmethod
+    async def notify_async(
+        self,
+        watcher: Watcher,
+        payload: dict[str, Any],
+        use_overflow_table: bool = False,
+    ) -> None:
+        """
+        Send a notification asynchronously
+
+        Args:
+            watcher (Watcher): The watcher configuration
+            payload (dict[str, Any]): The payload dict to send
+            use_overflow_table (bool): If True, use overflow table for large payloads
+        """
+        pass
+
+    @abstractmethod
+    def notify_sync(
+        self,
+        watcher: Watcher,
+        payload: dict[str, Any],
+        use_overflow_table: bool = False,
+    ) -> None:
+        """
+        Send a notification synchronously
+
+        Args:
+            watcher (Watcher): The watcher configuration
+            payload (dict[str, Any]): The payload dict to send
+            use_overflow_table (bool): If True, use overflow table for large payloads
+        """
+        pass
+
+    @abstractmethod
+    async def store_overflow_async(self, watcher: Watcher, payload_str: str) -> str:
+        """
+        Store large payload in overflow table asynchronously
+        """
+        pass
+
+    @abstractmethod
+    def store_overflow_sync(self, watcher: Watcher, payload_str: str) -> str:
+        """
+        Store large payload in overflow table synchronously
+        """
+        pass
+
+    @abstractmethod
+    async def fetch_overflow_async(self, watcher: Watcher, overflow_id: int) -> dict[str, Any] | None:
+        """
+        Fetch and consume overflow payload asynchronously
+        """
+        pass
+
+    @abstractmethod
+    def fetch_overflow_sync(self, watcher: Watcher, overflow_id: int) -> dict[str, Any] | None:
+        """
+        Fetch and consume overflow payload synchronously
+        """
+        pass
+
+    @abstractmethod
+    def build_watcher_sql(self, watcher: Watcher) -> tuple[str, str]:
+        """
+        Build SQL for trigger and function creation
+        """
+        pass
+
+    @abstractmethod
+    def create_overflow_table_sql(self, schema: str) -> str:
+        """
+        Generate SQL to create overflow table
+        """
+        pass
+
+    async def stop_listening(self) -> None:
+        """
+        Clean up listening connection
+        """
+
+        if self._listen_conn is not None:
+            try:
+                await self._listen_conn.close()
+                self._listen_conn = None
+                if self._logger:
+                    self._logger.debug("Closed listen connection")
+            except Exception as e:
+                if self._logger:
+                    self._logger.debug(f"Error closing listen connection: {str(e)}")