sqlnotify 0.1.0__py3-none-any.whl

sqlnotify/dialects/utils.py

@@ -0,0 +1,74 @@
+import logging
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from ..exceptions import SQLNotifyUnSupportedDatabaseProviderError
+from .base import BaseDialect
+from .postgresql import PostgreSQLDialect
+from .sqlite import SQLiteDialect
+
+
+def detect_dialect_name(engine: AsyncEngine | Engine) -> str:
+    """
+    Detect the database dialect from an SQLAlchemy engine
+
+    Args:
+        engine (Union[AsyncEngine, Engine]): SQLAlchemy Engine or AsyncEngine
+
+    Returns:
+        str: The dialect name (e.g., 'postgresql', 'mysql', 'sqlite')
+    """
+
+    if isinstance(engine, AsyncEngine):
+        dialect_name = engine.dialect.name
+    else:
+        dialect_name = engine.dialect.name
+
+    return dialect_name
+
+
+def get_dialect_for_engine(
+    engine: AsyncEngine | Engine,
+    async_engine: AsyncEngine | None = None,
+    sync_engine: Engine | None = None,
+    logger: logging.Logger | None = None,
+    revoke_on_model_change: bool = True,
+) -> BaseDialect:
+    """
+    Get the appropriate dialect implementation for the given engine
+
+    Args:
+        engine (Union[AsyncEngine, Engine]): SQLAlchemy Engine or AsyncEngine
+        async_engine (Optional[AsyncEngine]): Async engine if available
+        sync_engine (Optional[Engine]): Sync engine if available
+        logger (Optional[logging.Logger]): Logger instance
+        revoke_on_model_change (bool): Whether to revoke triggers on model change
+
+    Returns:
+        BaseDialect: The appropriate dialect implementation
+
+    Raises:
+        SQLNotifyUnSupportedDatabaseProviderError: If the dialect is not supported
+    """
+
+    dialect_name = detect_dialect_name(engine)
+
+    if dialect_name == "postgresql":
+        return PostgreSQLDialect(
+            async_engine=async_engine,
+            sync_engine=sync_engine,
+            logger=logger,
+            revoke_on_model_change=revoke_on_model_change,
+        )
+    elif dialect_name == "sqlite":
+        return SQLiteDialect(
+            async_engine=async_engine,
+            sync_engine=sync_engine,
+            logger=logger,
+            revoke_on_model_change=revoke_on_model_change,
+        )
+
+    raise SQLNotifyUnSupportedDatabaseProviderError(
+        f"Database dialect '{dialect_name}' is not supported. " f"Currently supported dialects: PostgreSQL, SQLite."
+    )

sqlnotify/exceptions.py

@@ -0,0 +1,38 @@
+class SQLNotifyException(Exception):
+    """
+    Base exception for SQLNotify
+    """
+
+    pass
+
+
+class SQLNotifyConfigurationError(SQLNotifyException):
+    """
+    Raised when there is a configuration error in SQLNotify
+    """
+
+    pass
+
+
+class SQLNotifyPayloadSizeError(SQLNotifyException):
+    """
+    Raised when the maximum payload size for SQLNotify is exceeded
+    """
+
+    pass
+
+
+class SQLNotifyIdentifierSizeError(SQLNotifyException):
+    """
+    Raised when the maximum size of an identifier for SQLNotify is exceeded
+    """
+
+    pass
+
+
+class SQLNotifyUnSupportedDatabaseProviderError(SQLNotifyException):
+    """
+    Raised when an unsupported database provider is specified for SQLNotify
+    """
+
+    pass

sqlnotify/logger.py

@@ -0,0 +1,32 @@
+import logging
+
+from .constants import PACKAGE_NAME
+
+
+def get_logger(name: str = PACKAGE_NAME, enabled: bool = True) -> logging.Logger:
+    """
+    Get a logger for the SQLNotify package.
+
+    Args:
+        name (str): The name of the logger. Defaults to the package name.
+        enable (bool): If False, adds a NullHandler to disable logging. Defaults to True.
+
+    Returns:
+        logging.Logger: Configured logger instance
+    """
+
+    logger = logging.getLogger(name)
+
+    logger.handlers.clear()
+
+    if enabled:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    else:
+        logger.addHandler(logging.NullHandler())
+        logger.setLevel(logging.CRITICAL + 1)
+
+    return logger

sqlnotify/notifiers/__init__.py

@@ -0,0 +1,3 @@
+from .notifier import Notifier
+
+__all__ = ["Notifier"]

sqlnotify/notifiers/base.py

@@ -0,0 +1,240 @@
+import asyncio
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import Mapper
+from typing_extensions import Self
+
+from ..constants import MAX_SQLNOTIFY_EXTRA_COLUMNS, MAX_SQLNOTIFY_PAYLOAD_BYTES
+from ..exceptions import SQLNotifyConfigurationError
+from ..types import FilterOnParams, Operation
+from ..watcher import Watcher
+
+
+class BaseNotifier:
+    """
+    Base class for SQLNotify notifier
+
+    It basically acts as a constructor class for registration and validation of watchers and subscribers of the notifier, but does not implement the actual listening logic.
+
+    Raises:
+        SQLNotifyConfigurationError: If there are configuration issues with watchers or subscribers
+    """
+
+    def __init__(self):
+        self.watchers: list[Watcher] = []
+        self.subscribers: dict[str, list[Callable]] = {}
+        self._listening_task: asyncio.Task | None = None
+        self._running = False
+        self._logger = None
+        self._listener_ready: asyncio.Event | None = None
+
+    def watch(
+        self,
+        model: type,
+        operation: Operation,
+        extra_columns: list[str] | None = None,
+        trigger_columns: list[str] | None = None,
+        primary_keys: list[str] = ["id"],  # noqa: B006
+        channel_label: str | None = None,
+        use_overflow_table: bool = False,
+    ) -> Self:
+        """
+        Register a watcher for a model and operation
+
+        Args:
+            model (Type): SQLModel or SQLAlchemy model class
+            operation (Operation | str): Operation to watch (insert, update, delete)
+            extra_columns (Optional[List[str]]): Additional columns to include in notifications. If None (the default),
+                only the primary key(s) will be returned in the notification event.
+            trigger_columns (Optional[List[str]]): For UPDATE, only trigger on these columns
+            primary_keys (List[str]): List of primary key column names. Must be actual primary keys on the model. Defaults to ["id"]
+            channel_label (Optional[str]): Custom label for the watcher
+            use_overflow_table (bool): If True, large payloads are stored in overflow table
+
+        Returns:
+            Notifier: The Notifier instance
+
+        Raises:
+            SQLNotifyConfigurationError: If there are configuration issues with the watcher (e.g. invalid column names, primary keys not actually being primary keys, etc.)
+        """
+
+        model_columns = self._get_model_columns(model)
+        model_primary_keys = self._get_model_primary_keys(model)
+
+        if not primary_keys:
+            raise SQLNotifyConfigurationError(f"primary_keys cannot be empty for model '{model.__name__}'")
+
+        invalid_primary_keys = [pk for pk in primary_keys if pk not in model_columns]
+        if invalid_primary_keys:
+            raise SQLNotifyConfigurationError(
+                f"Primary key column(s) {invalid_primary_keys} not found on model '{model.__name__}'. "
+                f"Available columns: {sorted(model_columns)}"
+            )
+
+        not_actual_pks = [pk for pk in primary_keys if pk not in model_primary_keys]
+        if not_actual_pks:
+            raise SQLNotifyConfigurationError(
+                f"Column(s) {not_actual_pks} exist on model '{model.__name__}' but are not primary keys. "
+                f"Actual primary keys: {sorted(model_primary_keys) if model_primary_keys else 'None defined'}"
+            )
+
+        if extra_columns:
+            invalid_extra_cols = [col for col in extra_columns if col not in model_columns]
+            if invalid_extra_cols:
+                raise SQLNotifyConfigurationError(
+                    f"Extra column(s) {invalid_extra_cols} not found on model '{model.__name__}'. "
+                    f"Available columns: {sorted(model_columns)}"
+                )
+
+        if trigger_columns:
+            invalid_trigger_cols = [col for col in trigger_columns if col not in model_columns]
+            if invalid_trigger_cols:
+                raise SQLNotifyConfigurationError(
+                    f"Trigger column(s) {invalid_trigger_cols} not found on model '{model.__name__}'. "
+                    f"Available columns: {sorted(model_columns)}"
+                )
+
+        if extra_columns and len(extra_columns) > MAX_SQLNOTIFY_EXTRA_COLUMNS:
+            if self._logger:
+                self._logger.warning(
+                    f"SQLNotify Watcher for {model.__name__}.{operation} has {len(extra_columns)} extra_columns. "
+                    f"This may exceed SQLNotify {MAX_SQLNOTIFY_PAYLOAD_BYTES} byte limit. "
+                    f"Consider setting use_overflow_table=True or reducing extra_columns."
+                )
+
+        watcher = Watcher(
+            model=model,
+            operation=operation,
+            extra_columns=extra_columns,
+            trigger_columns=trigger_columns,
+            primary_keys=primary_keys,
+            channel_label=channel_label,
+            use_overflow_table=use_overflow_table,
+            logger=self._logger,
+        )
+
+        self.watchers.append(watcher)
+
+        return self
+
+    def subscribe(
+        self,
+        model: type | str,
+        operation: Operation,
+        filters: list[FilterOnParams] | None = None,
+    ):
+        """
+        Decorator to subscribe to change events
+
+        Args:
+            model (Union[Type, str]): Model class or class name as string to watch
+            operation (Operation | str): Operation to watch
+            filters (Optional[List[FilterOnParams]]): Optional list of column filters to watch specific records
+
+        Returns:
+            Callable: Decorator for subscriber function
+
+        Raises:
+            SQLNotifyConfigurationError: If model is not registered as a watcher for the specified operation,
+                                         or if filter column names don't exist on the model
+        """
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            if inspect.iscoroutinefunction(func):
+
+                @wraps(func)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    return await func(*args, **kwargs)
+
+                registered_func = async_wrapper
+            else:
+
+                @wraps(func)
+                def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    return func(*args, **kwargs)
+
+                registered_func = sync_wrapper
+
+            matching_watcher = None
+
+            for watcher in self.watchers:
+                watcher_matches = False
+
+                if isinstance(model, str):
+                    watcher_matches = watcher.model.__name__ == model and watcher.operation == operation
+                else:
+                    watcher_matches = watcher.model == model and watcher.operation == operation
+
+                if watcher_matches:
+                    matching_watcher = watcher
+                    break
+
+            if not matching_watcher:
+                raise SQLNotifyConfigurationError(
+                    f"Model {model if isinstance(model, str) else model.__name__} is not registered as a watcher for operation {operation}"
+                )
+
+            if filters:
+                model_columns = self._get_model_columns(matching_watcher.model)
+                for filter_param in filters:
+                    column_name = filter_param["column"]
+
+                    if column_name not in model_columns:
+                        raise SQLNotifyConfigurationError(
+                            f"Column '{column_name}' does not exist on model '{matching_watcher.model.__name__}'. "
+                            f"Available columns: {', '.join(model_columns)}"
+                        )
+
+            channel = matching_watcher.channel_name
+
+            if filters:
+                sorted_filters = sorted(filters, key=lambda f: f["column"])
+                filter_parts = [f"{f['column']}:{f['value']}" for f in sorted_filters]
+                channel = f"{channel}:{'|'.join(filter_parts)}"
+
+            if channel not in self.subscribers:
+                self.subscribers[channel] = []
+
+            self.subscribers[channel].append(registered_func)
+
+            return registered_func
+
+        return decorator
+
+    def _get_model_columns(self, model: type) -> set[str]:
+        """
+        Get all column names from a model.
+
+        Args:
+            model (Type): SQLModel or SQLAlchemy model class
+
+        Returns:
+            set[str]: Set of column names
+        """
+
+        try:
+            mapper: Mapper[Any] = sa_inspect(model)
+            return {c.key for c in mapper.column_attrs}
+        except Exception:
+            return set()
+
+    def _get_model_primary_keys(self, model: type) -> set[str]:
+        """
+        Get actual primary key column names from a model.
+
+        Args:
+            model (Type): SQLModel or SQLAlchemy model class
+
+        Returns:
+            set[str]: Set of primary key column names
+        """
+
+        try:
+            mapper: Mapper[Any] = sa_inspect(model)
+            return {column.name for column in mapper.primary_key}
+        except Exception:
+            return set()