sqlalchemy-events-lib 0.3.2__tar.gz → 0.3.4__tar.gz

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/LICENSE

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

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-events-lib
-Version: 0.3.2
+Version: 0.3.4
 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

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/README.md

@@ -1,186 +1,186 @@
-# 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 decorators `@sa_insert_handler`, `@sa_update_handler`, `@sa_delete_handler`
-services/handlers.py
-```python
-from models import UserModel
-from sqlalchemy_events import sa_insert_handler
-
-@sa_insert_handler(UserModel)
-async def handle_user_insert():
-    print('User inserted!')
-```
-
-**Optional Argument**: `rows`
-Handlers can optionally accept a rows argument.
-
-If the parameter is declared in the function signature, it will automatically receive a list of affected `row` IDs.
-
-```python
-from models import UserModel
-from sqlalchemy_events import sa_insert_handler
-
-@sa_insert_handler(UserModel)
-async def handle_user_insert(rows: list[DB_ID]):
-    print('Users inserted!', rows)
-```
-**Output:**
-```
-Users inserted! ['3310aa38-f555-4c05-a57f-5acae32a0a7b', '6aeba1b0-8e80-4369-8adf-cf967ab7ba7a']
-```
-
-___
- 
-### 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 session import engine
-
-
-async def main():
-    sa_events = SQLAlchemyEvents(
-        engine=engine,
-        autodiscover_paths=['services']
-    )
-    await sa_events()
-    while True:
-        await asyncio.sleep(9999)
-
-if __name__ == '__main__':
-    asyncio.run(main())
-```
-
-## Configuration
-### SQLAlchemyEvents
-
-The SQLAlchemyEvents class accepts the following parameters:
-```python
-SQLAlchemyEvents(
-    engine,
-    autodiscover_paths,
-    logger=None,
-    verbose=True
-)
-```
-
-Parameters:
-* **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_insert_handler`, `@sa_update_handler`, `@sa_delete_handler` are executed.  
-**Example:**  
-`autodiscover_paths=["services", "app.handlers"]`
-
-* **verbose** - Enables detailed logging output. When set to True, the library will log additional informational and warning messages to help with debugging and configuration.
-
-### 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
-import asyncio
-from sqlalchemy_events import SQLAlchemyEvents
-from session import engine
-
-logger = logging.getLogger('sqlalchemy_events')
-logger.setLevel(logging.INFO)
-
-async def main():
-    sa_events = SQLAlchemyEvents(
-        engine=engine,
-        autodiscover_paths=['services'],
-        logger=logger
-    )
-    await sa_events()
-    while True:
-        await asyncio.sleep(9999)
-
-if __name__ == '__main__':
-    asyncio.run(main())
-```
-
-## 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/UPDATE/DELETE FROM {table} → DATABASE trigger fires →
-NOTIFY → Python listener receives event →
-handler is executed
-
-## License
-
+# 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 decorators `@sa_insert_handler`, `@sa_update_handler`, `@sa_delete_handler`
+services/handlers.py
+```python
+from models import UserModel
+from sqlalchemy_events import sa_insert_handler
+
+@sa_insert_handler(UserModel)
+async def handle_user_insert():
+    print('User inserted!')
+```
+
+**Optional Argument**: `rows`
+Handlers can optionally accept a rows argument.
+
+If the parameter is declared in the function signature, it will automatically receive a list of affected `row` IDs.
+
+```python
+from models import UserModel
+from sqlalchemy_events import sa_insert_handler
+
+@sa_insert_handler(UserModel)
+async def handle_user_insert(rows: list[DB_ID]):
+    print('Users inserted!', rows)
+```
+**Output:**
+```
+Users inserted! ['3310aa38-f555-4c05-a57f-5acae32a0a7b', '6aeba1b0-8e80-4369-8adf-cf967ab7ba7a']
+```
+
+___
+ 
+### 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 session import engine
+
+
+async def main():
+    sa_events = SQLAlchemyEvents(
+        engine=engine,
+        autodiscover_paths=['services']
+    )
+    await sa_events()
+    while True:
+        await asyncio.sleep(9999)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Configuration
+### SQLAlchemyEvents
+
+The SQLAlchemyEvents class accepts the following parameters:
+```python
+SQLAlchemyEvents(
+    engine,
+    autodiscover_paths,
+    logger=None,
+    verbose=True
+)
+```
+
+Parameters:
+* **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_insert_handler`, `@sa_update_handler`, `@sa_delete_handler` are executed.  
+**Example:**  
+`autodiscover_paths=["services", "app.handlers"]`
+
+* **verbose** - Enables detailed logging output. When set to True, the library will log additional informational and warning messages to help with debugging and configuration.
+
+### 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
+import asyncio
+from sqlalchemy_events import SQLAlchemyEvents
+from session import engine
+
+logger = logging.getLogger('sqlalchemy_events')
+logger.setLevel(logging.INFO)
+
+async def main():
+    sa_events = SQLAlchemyEvents(
+        engine=engine,
+        autodiscover_paths=['services'],
+        logger=logger
+    )
+    await sa_events()
+    while True:
+        await asyncio.sleep(9999)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## 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/UPDATE/DELETE FROM {table} → DATABASE trigger fires →
+NOTIFY → Python listener receives event →
+handler is executed
+
+## License
+
 MIT

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/pyproject.toml

@@ -1,45 +1,45 @@
-[build-system]
-requires = ["setuptools>=68", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools]
-package-dir = {"" = "src"}
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[project]
-name = "sqlalchemy-events-lib"
-version = "0.3.2"
-description = "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."
-requires-python = ">=3.12"
-authors = [
-    {name = "Alexey Kostarev", email = "normjkeeewm@gmail.com"}
-]
-dependencies = [
-    "sqlalchemy>=2.0.49",
-]
-readme = {file = "README.md", content-type = "text/markdown"}
-license = {text = "MIT"}
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-keywords = []
-[project.optional-dependencies]
-test = [
-    "pytest",
-    "pytest-asyncio",
-]
-
-[project.urls]
-Homepage = "https://github.com/NormanwOw/SQLAlchemy-Events"
-Repository = "https://github.com/NormanwOw/SQLAlchemy-Events"
-Issues = "https://github.com/NormanwOw/SQLAlchemy-Events/issues"
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["src/tests"]
-pythonpath = ["src"]
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project]
+name = "sqlalchemy-events-lib"
+version = "0.3.4"
+description = "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."
+requires-python = ">=3.12"
+authors = [
+    {name = "Alexey Kostarev", email = "normjkeeewm@gmail.com"}
+]
+dependencies = [
+    "sqlalchemy>=2.0.49",
+]
+readme = {file = "README.md", content-type = "text/markdown"}
+license = {text = "MIT"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = []
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-asyncio",
+]
+
+[project.urls]
+Homepage = "https://github.com/NormanwOw/SQLAlchemy-Events"
+Repository = "https://github.com/NormanwOw/SQLAlchemy-Events"
+Issues = "https://github.com/NormanwOw/SQLAlchemy-Events/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["src/tests"]
+pythonpath = ["src"]

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/src/sqlalchemy_events/__init__.py

@@ -1,14 +1,14 @@
-from .core import SQLAlchemyEvents
-from .decorators import with_events
-from .handlers import sa_insert_handler, sa_update_handler, sa_delete_handler
-from .types import SaEvent
-
-__all__ = [
-    'SQLAlchemyEvents',
-    'sa_insert_handler',
-    'sa_update_handler',
-    'sa_delete_handler',
-    'with_events',
-    'SaEvent'
-]
-__version__ = '0.3.2'
+from .core import SQLAlchemyEvents
+from .decorators import with_events
+from .handlers import sa_insert_handler, sa_update_handler, sa_delete_handler
+from .types import SaEvent
+
+__all__ = [
+    'SQLAlchemyEvents',
+    'sa_insert_handler',
+    'sa_update_handler',
+    'sa_delete_handler',
+    'with_events',
+    'SaEvent'
+]
+__version__ = '0.3.4'

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/src/sqlalchemy_events/callbacks_strategies/base.py

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

{sqlalchemy_events_lib-0.3.2 → sqlalchemy_events_lib-0.3.4}/src/sqlalchemy_events/callbacks_strategies/postgres_callback.py

@@ -1,69 +1,69 @@
-import asyncio
-import json
-import inspect
-import signal
-import sys
-
-from .base import SaEventsCallbacksStrategy
-from ..registry import get_event_handlers
-from ..types import Handler
-from ..utils import _process_pool
-
-
-signal.signal(signal.SIGINT, lambda sig, frame: sys.exit(0))
-
-
-class PostgresCallback(SaEventsCallbacksStrategy):
-
-    def __init__(self) -> None:
-        self.__handlers = get_event_handlers()
-
-    async def handle(self, *args, **kwargs):
-        data = json.loads(args[3] or '{}')
-        trigger = data['op']
-        rows = data['rows']
-        trig_name = f'sa_{data['table']}_{trigger}_notify'
-        handlers: list[Handler] = self.__handlers.get(trig_name, [])
-        if not handlers:
-            return
-
-        loop = asyncio.get_running_loop()
-        tasks = []
-
-        for handler in handlers:
-            func = handler.func
-            sig = inspect.signature(func)
-
-            params = list(sig.parameters.values())
-            rows_index = None
-
-            for i, p in enumerate(params):
-                if p.name == 'rows':
-                    rows_index = i
-                    break
-
-            def build_args():
-                args = []
-                kwargs = {}
-
-                if rows_index is not None:
-                    if not any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in params):
-                        args.insert(rows_index, rows)
-                    else:
-                        kwargs['rows'] = rows
-                return args, kwargs
-
-            args, kwargs = build_args()
-
-            if asyncio.iscoroutinefunction(func):
-                tasks.append(func(*args, **kwargs))
-            else:
-                tasks.append(
-                    loop.run_in_executor(
-                        _process_pool,
-                        func,
-                        *args,
-                    )
-                )
-
+import asyncio
+import json
+import inspect
+import signal
+import sys
+
+from .base import SaEventsCallbacksStrategy
+from ..registry import get_event_handlers
+from ..types import Handler
+from ..utils import _process_pool
+
+
+signal.signal(signal.SIGINT, lambda sig, frame: sys.exit(0))
+
+
+class PostgresCallback(SaEventsCallbacksStrategy):
+
+    def __init__(self) -> None:
+        self.__handlers = get_event_handlers()
+
+    async def handle(self, *args, **kwargs):
+        data = json.loads(args[3] or '{}')
+        trigger = data['op']
+        rows = data['rows']
+        trig_name = f'sa_{data['table']}_{trigger}_notify'
+        handlers: list[Handler] = self.__handlers.get(trig_name, [])
+        if not handlers:
+            return
+
+        loop = asyncio.get_running_loop()
+        tasks = []
+
+        for handler in handlers:
+            func = handler.func
+            sig = inspect.signature(func)
+
+            params = list(sig.parameters.values())
+            rows_index = None
+
+            for i, p in enumerate(params):
+                if p.name == 'rows':
+                    rows_index = i
+                    break
+
+            def build_args():
+                args = []
+                kwargs = {}
+
+                if rows_index is not None:
+                    if not any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in params):
+                        args.insert(rows_index, rows)
+                    else:
+                        kwargs['rows'] = rows
+                return args, kwargs
+
+            args, kwargs = build_args()
+
+            if asyncio.iscoroutinefunction(func):
+                tasks.append(func(*args, **kwargs))
+            else:
+                tasks.append(
+                    loop.run_in_executor(
+                        _process_pool,
+                        func,
+                        *args,
+                    )
+                )
+
         return await asyncio.gather(*tasks)