sqlalchemy-events-lib 0.1.0__tar.gz → 0.2.0__tar.gz

{sqlalchemy_events_lib-0.1.0 → sqlalchemy_events_lib-0.2.0}/PKG-INFO

@@ -1,179 +1,200 @@
-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
+Metadata-Version: 2.4
+Name: sqlalchemy-events-lib
+Version: 0.2.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
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+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 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 models import Base
+from session import engine
+
+
+async def main():
+    SQLAlchemyEvents(
+        base=Base,
+        engine=engine,
+        autodiscover_paths=['services']
+    )
+    while True:
+        await asyncio.sleep(9999)
+
+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_insert_handler`, `@sa_update_handler`, `@sa_delete_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/UPDATE/DELETE FROM {table} → DATABASE trigger fires →
+NOTIFY → Python listener receives event →
+handler is executed
+
+## License
+
+MIT

{sqlalchemy_events_lib-0.1.0 → sqlalchemy_events_lib-0.2.0}/README.md

@@ -39,16 +39,35 @@ class UserModel(Base):
 ___
 
 
-### Define event handlers using decorator `@sa_event_handler`  
+### 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_event_handler
+from sqlalchemy_events import sa_insert_handler
 
-@sa_event_handler.on_insert(UserModel)
+@sa_insert_handler(UserModel)
 async def handle_user_insert():
-    print("User inserted!")
+    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  
@@ -74,17 +93,13 @@ from session import engine
 
 
 async def main():
-    asyncio.create_task(
-        SQLAlchemyEvents(
-            base=Base,
-            engine=engine,
-            autodiscover_paths=['services']
-        ).init()
+    SQLAlchemyEvents(
+        base=Base,
+        engine=engine,
+        autodiscover_paths=['services']
     )
-    try:
+    while True:
         await asyncio.sleep(9999)
-    except:
-        pass
 
 if __name__ == '__main__':
     asyncio.run(main())
@@ -107,7 +122,10 @@ 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"]`
+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"]`
 
 ### Important:
 
@@ -127,13 +145,13 @@ If provided, the library will log internal lifecycle events such as:
 ```python
 import logging
 
-logger = logging.getLogger("sqlalchemy_events")
+logger = logging.getLogger('sqlalchemy_events')
 logger.setLevel(logging.INFO)
 
 SQLAlchemyEvents(
     base=Base,
     engine=engine,
-    autodiscover_paths=["services"],
+    autodiscover_paths=['services'],
     logger=logger
 )
 ```
@@ -151,7 +169,7 @@ SQLAlchemyEvents(
 * Ensure handlers are imported via autodiscover_paths, otherwise they will not be registered
 
 ## Example flow
-INSERT INTO {table} → DATABASE trigger fires →
+INSERT INTO/UPDATE/DELETE FROM {table} → DATABASE trigger fires →
 NOTIFY → Python listener receives event →
 handler is executed
 

{sqlalchemy_events_lib-0.1.0 → sqlalchemy_events_lib-0.2.0}/pyproject.toml

@@ -1,35 +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.1.0"
-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.urls]
-Homepage = "https://github.com/NormanwOw/SQLAlchemy-Events"
-Repository = "https://github.com/NormanwOw/SQLAlchemy-Events"
-Issues = "https://github.com/NormanwOw/SQLAlchemy-Events/issues"
+[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.2.0"
+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.1.0 → sqlalchemy_events_lib-0.2.0}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlalchemy_events_lib-0.2.0/src/sqlalchemy_events/__init__.py

@@ -0,0 +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.2.0'

sqlalchemy_events_lib-0.2.0/src/sqlalchemy_events/callbacks_strategies/postgres_callback.py

@@ -0,0 +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,
+                    )
+                )
+
+        await asyncio.gather(*tasks)