sqlalchemy-events-lib 0.1.0__py3-none-any.whl

sqlalchemy_events/__init__.py

@@ -0,0 +1,8 @@
+from .core import SQLAlchemyEvents
+from .decorators import with_events
+from .enums import SaEvent
+from .handler import sa_event_handler
+
+__all__ = ['SQLAlchemyEvents', 'sa_event_handler', 'with_events', 'SaEvent']
+__version__ = '0.1.0'
+

sqlalchemy_events/callbacks_strategies/base.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+
+class SaEventsCallbacksStrategy(ABC):
+
+    @abstractmethod
+    async def handle(self, *args, **kwargs):
+        raise NotImplementedError

sqlalchemy_events/callbacks_strategies/postgres_callback.py

@@ -0,0 +1,28 @@
+import asyncio
+import json
+
+from .base import SaEventsCallbacksStrategy
+from ..registry import get_event_handlers
+
+
+class PostgresCallback(SaEventsCallbacksStrategy):
+
+    def __init__(self) -> None:
+        self.__handlers = get_event_handlers()
+
+    async def handle(self, *args, **kwargs):
+        data = json.loads(args[3] or '{}')
+        trig_name = data.get('trigger')
+
+        if not trig_name:
+            return
+
+        handlers = self.__handlers.get(trig_name, [])
+        if not handlers:
+            return
+
+        for handler in handlers:
+            if asyncio.iscoroutinefunction(handler):
+                await handler()
+            else:
+                handler()

sqlalchemy_events/core.py

@@ -0,0 +1,103 @@
+import asyncio
+import logging
+from pathlib import Path
+from typing import Optional, Type, Union
+import inspect
+
+from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy.orm import DeclarativeBase
+
+from .discovery import autodiscover
+from .events import SaEventStrategy, sa_events_strategy
+from .registry import get_event_handlers
+from .utils import dialect_resolver
+
+
+class SQLAlchemyEvents:
+
+    def __init__(
+        self,
+        base: Type[DeclarativeBase],
+        engine: Union[AsyncEngine, Engine],
+        autodiscover_paths: list[str],
+        logger: Optional[logging.Logger] = None
+    ) -> None:
+        self.base = base
+        self.engine = engine
+        self.autodiscover_paths = autodiscover_paths
+        self.logger = logger
+
+    async def init(self) -> None:
+        if not await self.__find_handlers():
+            return
+
+        dialect = dialect_resolver(self.engine)
+        event_strategy = sa_events_strategy.get(dialect)
+        if not event_strategy:
+            raise RuntimeError(f'[SQLAlchemyEvents] Unsupported database {dialect}. '
+                               f'This library supports only {', '.join(sa_events_strategy.keys())}')
+        await self.__start_listen(event_strategy)
+
+    async def __find_handlers(self):
+        autodiscover(self.autodiscover_paths)
+        handlers = get_event_handlers()
+        if not handlers:
+            self.logger.info('[SQLAlchemyEvents] No handlers found')
+            return
+        res_handlers = []
+        for handlers_list in handlers.values():
+            res_handlers.extend(handlers_list)
+        for handler in res_handlers:
+            file_path = inspect.getsourcefile(handler) or inspect.getfile(handler)
+            file_func = Path(file_path)
+            file_name = file_func.name
+            self.logger.info(f'[SQLAlchemyEvents] Registered handler {handler.__name__} '
+                             f'from {file_func.parent.name}/{file_name}')
+
+        return res_handlers
+
+    async def __start_listen(self, event_strategy: SaEventStrategy):
+        if isinstance(self.engine, AsyncEngine):
+            async with self.engine.connect() as conn:
+                raw_conn = await conn.get_raw_connection()
+                driver_conn = raw_conn.driver_connection
+
+                if not hasattr(driver_conn, 'add_listener'):
+                    raise RuntimeError('[SQLAlchemyEvents] Driver does not support LISTEN/NOTIFY')
+
+                await event_strategy.init_triggers(
+                    model_list=self.base.__subclasses__(),
+                    conn=conn,
+                    logger=self.logger
+                )
+                if self.logger:
+                    self.logger.info('[SQLAlchemyEvents] Start listening')
+                await driver_conn.add_listener('sqlalchemy_events', event_strategy.callback.handle)
+            return
+
+        elif isinstance(self.engine, Engine):
+            sync_engine_error = ('[SQLAlchemyEvents] Sync Engine driver does not support async LISTEN/NOTIFY. '
+                                 'Use AsyncEngine with asyncpg or psycopg[async]')
+            with self.engine.connect() as conn:
+                raw_conn = conn.connection
+                driver_conn = getattr(raw_conn, 'driver_connection', raw_conn)
+
+                if not hasattr(driver_conn, 'add_listener'):
+                    raise RuntimeError(sync_engine_error)
+                result = driver_conn.add_listener('sqlalchemy_events', event_strategy.callback.handle)
+
+                if not asyncio.iscoroutine(result):
+                    raise RuntimeError(sync_engine_error)
+                await event_strategy.init_triggers(
+                    model_list=self.base.__subclasses__(),
+                    conn=conn,
+                    logger=self.logger
+                )
+                if self.logger:
+                    self.logger.info('[SQLAlchemyEvents] Start listening')
+                await result
+
+            return
+
+        raise TypeError('[SQLAlchemyEvents] engine must be AsyncEngine or Engine')

sqlalchemy_events/decorators.py

@@ -0,0 +1,14 @@
+from .enums import SaEvent
+
+
+def with_events(events: list[SaEvent]):
+    def wrapper(cls):
+        cls.__events__ = set(events)
+
+        class Events:
+            for e in events:
+                locals()[e.name] = e.value
+
+        cls.events = Events
+        return cls
+    return wrapper

sqlalchemy_events/discovery.py

@@ -0,0 +1,24 @@
+import importlib
+import pkgutil
+from types import ModuleType
+from typing import Iterable, List
+
+
+def autodiscover(paths: Iterable[str]) -> List[ModuleType]:
+    modules: List[ModuleType] = []
+
+    for path in paths:
+        module = importlib.import_module(path)
+        modules.append(module)
+
+        if not hasattr(module, '__path__'):
+            continue
+
+        for _, module_name, _ in pkgutil.walk_packages(
+            module.__path__,
+            module.__name__ + '.',
+        ):
+            submodule = importlib.import_module(module_name)
+            modules.append(submodule)
+
+    return modules

sqlalchemy_events/enums.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class SaEvent(StrEnum):
+    INSERT = 'INSERT'
+    UPDATE = 'UPDATE'
+    DELETE = 'DELETE'
+
+
+class Dialect(StrEnum):
+    POSTGRESQL = 'postgresql'
+    SQLITE = 'sqlite'
+    MYSQL = 'mysql'
+    MSSQL = 'mssql'
+    ORACLE = 'oracle'

sqlalchemy_events/events.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+
+from .callbacks_strategies.base import SaEventsCallbacksStrategy
+from .callbacks_strategies.postgres_callback import PostgresCallback
+from .enums import Dialect, SaEvent
+from .init_triggers_strategies.base import InitTriggersStrategy
+from .init_triggers_strategies.postgres_init_triggers import PostgresInitTriggers
+
+
+class SaEvents:
+
+    def __init__(self, events: list[SaEvent]):
+        self.events = events
+        for e in events:
+            setattr(self, e.name, e)
+
+    def __iter__(self):
+        return iter(self.__dict__.values())
+
+    def __len__(self):
+        return len(self.events)
+
+
+@dataclass(frozen=True)
+class SaEventStrategy:
+    init_triggers: InitTriggersStrategy
+    callback: SaEventsCallbacksStrategy
+
+
+sa_events_strategy: dict[Dialect, SaEventStrategy] = {
+    Dialect.POSTGRESQL: SaEventStrategy(
+        init_triggers=PostgresInitTriggers(),
+        callback=PostgresCallback()
+    )
+}

sqlalchemy_events/exceptions.py

@@ -0,0 +1 @@
+class InvalidModelEventError(ValueError): ...

sqlalchemy_events/handler.py

@@ -0,0 +1,38 @@
+from typing import Callable, Type
+from sqlalchemy.orm import DeclarativeBase
+
+from .enums import SaEvent
+from .registry import get_event_handlers
+
+
+class SaEventHandler:
+
+    def __init__(self):
+        self.__handlers = get_event_handlers()
+
+    def __sa_event_handler(self, model: Type[DeclarativeBase], event: SaEvent):
+        if event not in getattr(model, '__events__', set()):
+            raise ValueError(
+                f'[SQLAlchemyEvents] Event {event} is not registered for model {model.__name__}'
+            )
+
+        def decorator(func: Callable):
+            trig_name = f'sa_{model.__tablename__}_{event.lower()}_notify'
+
+            self.__handlers.setdefault(trig_name, []).append(func)
+
+            return func
+
+        return decorator
+
+    def on_insert(self, model: Type[DeclarativeBase]):
+        return self.__sa_event_handler(model, SaEvent.INSERT)
+
+    def on_update(self, model: Type[DeclarativeBase]):
+        return self.__sa_event_handler(model, SaEvent.UPDATE)
+
+    def on_delete(self, model: Type[DeclarativeBase]):
+        return self.__sa_event_handler(model, SaEvent.DELETE)
+
+
+sa_event_handler = SaEventHandler()

sqlalchemy_events/init_triggers_strategies/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Type
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class InitTriggersStrategy(ABC):
+
+    @abstractmethod
+    async def __call__(self, model_list: list[Type[DeclarativeBase]], conn, logger):
+        raise NotImplementedError
+
+

sqlalchemy_events/init_triggers_strategies/postgres_init_triggers.py

@@ -0,0 +1,89 @@
+from typing import Type
+
+from sqlalchemy import text
+from sqlalchemy.orm import DeclarativeBase
+
+from ..enums import SaEvent
+from .base import InitTriggersStrategy
+
+
+class PostgresInitTriggers(InitTriggersStrategy):
+
+    async def __call__(self, model_list: list[Type[DeclarativeBase]], conn, logger):
+        await conn.execute(
+            text("""
+                 CREATE OR REPLACE FUNCTION sqlalchemy_events() 
+                 RETURNS trigger AS $$ 
+                 BEGIN PERFORM pg_notify(
+                    'sqlalchemy_events', json_build_object(
+                    'table', TG_TABLE_NAME, 'event', TG_OP, 'trigger', TG_NAME
+                 )::text); 
+                 RETURN NEW; END; $$ LANGUAGE plpgsql;
+                 """)
+        )
+
+        for cls in model_list:
+            events = getattr(cls, '__events__', None)
+
+            if not events or not all(isinstance(e, SaEvent) for e in events):
+                continue
+
+            table_name = cls.__tablename__
+
+            existing_triggers = set()
+
+            table_exists = await conn.scalar(
+                text("""
+                     SELECT EXISTS (SELECT 1
+                                    FROM pg_class
+                                    WHERE relname = :tbl
+                                      AND relkind = 'r')
+                     """),
+                {'tbl': table_name},
+            )
+            if not table_exists:
+                if logger:
+                    logger.warning(f"[SQLAlchemyEvents] {cls.__name__} has "
+                                   f"{'event' if len(events) == 1 else 'events'} {', '.join(events)}, "
+                                   f"but relation '{table_name}' does not exist")
+                continue
+
+            if table_exists:
+                tg_sql = text("""
+                              SELECT tgname
+                              FROM pg_trigger
+                              WHERE tgrelid = to_regclass(:tbl)
+                                AND NOT tgisinternal
+                              """)
+
+                for row in await conn.execute(tg_sql, {'tbl': table_name}):
+                    existing_triggers.add(row[0])
+
+            added_events = []
+            for event in sorted(events):
+                l_event = event.lower()
+                trig_name = f'sa_{table_name}_{l_event}_notify'
+
+                if trig_name in existing_triggers:
+                    continue
+
+                added_events.append(event)
+                await conn.execute(
+                    text(f"DROP TRIGGER IF EXISTS {trig_name} ON {table_name};")
+                )
+
+                await conn.execute(
+                    text(f"""
+                         CREATE TRIGGER {trig_name}
+                         AFTER {event} ON {table_name}
+                         FOR EACH ROW EXECUTE FUNCTION sqlalchemy_events();
+                         """)
+                )
+
+            if added_events and logger:
+                logger.info(
+                    f"Detected added {'event' if len(added_events) == 1 else 'events'} "
+                    f"{', '.join(added_events)} for table '{table_name}'"
+                )
+
+        await conn.commit()

sqlalchemy_events/registry.py

@@ -0,0 +1,15 @@
+import sys
+
+_GLOBAL_KEY = 'sqlalchemy_events._global_registry'
+
+if _GLOBAL_KEY not in sys.modules:
+    class _Registry:
+        handlers = {}
+
+    sys.modules[_GLOBAL_KEY] = _Registry()
+
+_registry = sys.modules[_GLOBAL_KEY]
+
+
+def get_event_handlers():
+    return _registry.handlers

sqlalchemy_events/utils.py

@@ -0,0 +1,25 @@
+from typing import Union
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .enums import Dialect
+
+
+def dialect_resolver(engine: Union[AsyncEngine, Engine]) -> Dialect:
+    if isinstance(engine, AsyncEngine):
+        dialect_name = engine.sync_engine.dialect.name.lower()
+    else:
+        dialect_name = engine.dialect.name.lower()
+
+    if dialect_name.startswith('postgres'):
+        return Dialect.POSTGRESQL
+    elif dialect_name.startswith('sqlite'):
+        return Dialect.SQLITE
+    elif dialect_name.startswith('mysql'):
+        return Dialect.MYSQL
+    elif dialect_name in ('mssql', 'sqlserver'):
+        return Dialect.MSSQL
+    elif dialect_name.startswith('oracle'):
+        return Dialect.ORACLE
+
+    raise ValueError(f'Unsupported dialect: {dialect_name}')

sqlalchemy_events_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-events-lib
+Version: 0.1.0
+Summary: Event-driven extension for SQLAlchemy that enables listening to database CUD events. This library allows you to react to database changes in real time using a clean, declarative API.
+Author-email: Alexey Kostarev <normjkeeewm@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/NormanwOw/SQLAlchemy-Events
+Project-URL: Repository, https://github.com/NormanwOw/SQLAlchemy-Events
+Project-URL: Issues, https://github.com/NormanwOw/SQLAlchemy-Events/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.49
+Dynamic: license-file
+
+# SQLAlchemy Events
+
+## About  
+Event-driven extension for SQLAlchemy that enables listening to database CUD events.
+This library allows you to react to database changes in real time using a clean, declarative API.
+* **Currently supports PostgreSQL only**
+
+
+## Installation
+
+```bash
+$ pip install sqlalchemy-events-lib
+```
+## Quick start
+
+
+### Define models with enabled event tracking using **`@with_events`**  
+models.py
+```python
+import uuid
+
+from sqlalchemy import UUID
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from sqlalchemy_events import with_events, SaEvent
+
+
+class Base(DeclarativeBase):
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID, nullable=False, primary_key=True, default=uuid.uuid4
+    )
+
+@with_events([SaEvent.INSERT, SaEvent.UPDATE, SaEvent.DELETE])
+class UserModel(Base):
+    __tablename__ = 'users'
+
+    name: Mapped[str] = mapped_column()
+```
+___
+
+
+### Define event handlers using decorator `@sa_event_handler`  
+services/handlers.py
+```python
+from models import UserModel
+from sqlalchemy_events import sa_event_handler
+
+@sa_event_handler.on_insert(UserModel)
+async def handle_user_insert():
+    print("User inserted!")
+```
+___
+ 
+### Configure SQLAlchemy async engine  
+session.py
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+from config import DATABASE_URL
+
+engine = create_async_engine(DATABASE_URL)
+async_session = async_sessionmaker(engine, expire_on_commit=False, autoflush=False)
+
+```
+___
+ 
+### Initialize event system and start listening  
+main.py 
+```python
+import asyncio
+from sqlalchemy_events import SQLAlchemyEvents
+from models import Base
+from session import engine
+
+
+async def main():
+    asyncio.create_task(
+        SQLAlchemyEvents(
+            base=Base,
+            engine=engine,
+            autodiscover_paths=['services']
+        ).init()
+    )
+    try:
+        await asyncio.sleep(9999)
+    except:
+        pass
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Configuration
+### SQLAlchemyEvents
+
+The SQLAlchemyEvents class accepts the following parameters:
+```python
+SQLAlchemyEvents(
+    base,
+    engine,
+    autodiscover_paths,
+    logger=None
+)
+```
+
+Parameters:
+* **base** - SQLAlchemy declarative base class used to discover mapped models.
+* **engine** - SQLAlchemy Engine or AsyncEngine instance.
+* **autodiscover_paths** - List of Python module paths where event handlers are defined.
+These modules are automatically imported so that decorators such as `@sa_event_handler` are executed. Example:`autodiscover_paths=["services", "app.handlers"]`
+
+### Important:
+
+All modules containing event handlers must be imported through autodiscover
+This ensures decorator registration is executed at startup
+
+### logger (optional)
+A standard Python logging.Logger instance.
+
+If provided, the library will log internal lifecycle events such as:
+
+* successful initialization
+* listener startup
+* trigger setup
+
+**Example:**
+```python
+import logging
+
+logger = logging.getLogger("sqlalchemy_events")
+logger.setLevel(logging.INFO)
+
+SQLAlchemyEvents(
+    base=Base,
+    engine=engine,
+    autodiscover_paths=["services"],
+    logger=logger
+)
+```
+
+## How it works
+1. autodiscover_paths modules are imported at startup
+2. Decorators register event handlers into a global registry
+3. Triggers send events via LISTEN/NOTIFY
+4. The library receives notifications and dispatches them to registered handlers
+
+## Notes
+* Handlers can be both async and regular functions
+* Only models registered with @with_events will emit events
+* Currently supports LISTEN/NOTIFY
+* Ensure handlers are imported via autodiscover_paths, otherwise they will not be registered
+
+## Example flow
+INSERT INTO {table} → DATABASE trigger fires →
+NOTIFY → Python listener receives event →
+handler is executed
+
+## License
+
+MIT

sqlalchemy_events_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+sqlalchemy_events/__init__.py,sha256=XTsL2UXIGOeR1t23L_BWmV3avg9BpVTjLQHcU9iKzr4,245
+sqlalchemy_events/core.py,sha256=EsR7rxCiCup66Xx8DVMyGr9cvLMRkfV8wG7wvPbbziA,4165
+sqlalchemy_events/decorators.py,sha256=uNIHMaReqUCB_y_ndkaYa2YLQj4KZ6EGDuhzsWMaBFE,302
+sqlalchemy_events/discovery.py,sha256=NjiLWxdVvlM8LWdhLRXtNHvLDDxrtQ-Upuy1Ha-2zRM,633
+sqlalchemy_events/enums.py,sha256=NC-yvTJ1xB_RdPg0uI-z8-C0EQKQLSn9l2om5Lo46_4,270
+sqlalchemy_events/events.py,sha256=F1CEQI3vmaJpfxP2bCqATersNFx_TB6sbHLFz6GfsbA,983
+sqlalchemy_events/exceptions.py,sha256=CRUdzA-V1gAQYGITwwwRJhauosG6iwjVAMG0QCB48gA,45
+sqlalchemy_events/handler.py,sha256=mP04ykFUAKJ3651LWjg8JfBozOFh_y3VFv4OMuONQPQ,1187
+sqlalchemy_events/registry.py,sha256=8a9yqk0oC0DzHOQ26fh6o9T9cZCWnOPz1vQdJnkzYDs,295
+sqlalchemy_events/utils.py,sha256=bWDCouY-FJmK359q_DBSOXfeo1YdyyypPmZCyocEExM,834
+sqlalchemy_events/callbacks_strategies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlalchemy_events/callbacks_strategies/base.py,sha256=FLnRvmpnAE99qyGx5dXH3Egtn7cvkuhbC64IwJCrkvw,182
+sqlalchemy_events/callbacks_strategies/postgres_callback.py,sha256=87_bT25xoTDEKdp6ASYot4bBIDDCY6BYlVntoevzn5Y,710
+sqlalchemy_events/init_triggers_strategies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlalchemy_events/init_triggers_strategies/base.py,sha256=nuUL_HTJW1Shf7RSD0-PjDabNHoCtZffcS33e6doGuE,294
+sqlalchemy_events/init_triggers_strategies/postgres_init_triggers.py,sha256=gv873n5tCyrih397hmfJVdj4PCnoCn4MZJvRDmWinLg,3266
+sqlalchemy_events_lib-0.1.0.dist-info/licenses/LICENSE,sha256=-4dAsEvyIMLC8pS68pJqK6ks5sRpNrtBzTBxltHcaCE,132
+sqlalchemy_events_lib-0.1.0.dist-info/METADATA,sha256=CUHfeoAQRy_5T6rLC72RWhkewOFrZwvAkBYqZz2GBuk,4883
+sqlalchemy_events_lib-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sqlalchemy_events_lib-0.1.0.dist-info/top_level.txt,sha256=fYKcnbBujkHy1oF2GEJJyxGw0Kr0-ZwLbU35PDbrE3w,18
+sqlalchemy_events_lib-0.1.0.dist-info/RECORD,,

sqlalchemy_events_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlalchemy_events_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 Alexey Kostarev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

sqlalchemy_events_lib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlalchemy_events