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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-events-lib
-Version: 0.2.0
+Version: 0.3.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
@@ -110,13 +110,11 @@ 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']
     )
@@ -133,22 +131,23 @@ if __name__ == '__main__':
 The SQLAlchemyEvents class accepts the following parameters:
 ```python
 SQLAlchemyEvents(
-    base,
     engine,
     autodiscover_paths,
-    logger=None
+    logger=None,
+    verbose=True
 )
 ```
 
 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. 
+`@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

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

@@ -88,13 +88,11 @@ 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']
     )
@@ -111,22 +109,23 @@ if __name__ == '__main__':
 The SQLAlchemyEvents class accepts the following parameters:
 ```python
 SQLAlchemyEvents(
-    base,
     engine,
     autodiscover_paths,
-    logger=None
+    logger=None,
+    verbose=True
 )
 ```
 
 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. 
+`@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

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

@@ -10,7 +10,7 @@ where = ["src"]
 
 [project]
 name = "sqlalchemy-events-lib"
-version = "0.2.0"
+version = "0.3.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 = [

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events/__init__.py

@@ -11,4 +11,4 @@ __all__ = [
     'with_events',
     'SaEvent'
 ]
-__version__ = '0.2.0'
+__version__ = '0.3.0'

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events/core.py

@@ -1,16 +1,19 @@
 import asyncio
 import logging
+from collections import defaultdict
 from pathlib import Path
-from typing import Optional, Type, Union
+from typing import Optional, Union
 import inspect
 
 from sqlalchemy import Engine
 from sqlalchemy.ext.asyncio import AsyncEngine
 from sqlalchemy.orm import DeclarativeBase
 
+from .default_logger import DefaultLogger
 from .discovery import autodiscover
 from .events import SaEventStrategy, sa_events_strategy
 from .registry import get_event_handlers
+from .types import Handler
 from .utils import dialect_resolver
 
 
@@ -18,19 +21,35 @@ class SQLAlchemyEvents:
 
     def __init__(
         self,
-        base: Type[DeclarativeBase],
         engine: Union[AsyncEngine, Engine],
-        autodiscover_paths: list[str],
-        logger: Optional[logging.Logger] = None
+        autodiscover_paths: list[str | Path],
+        logger: Optional[logging.Logger] = None,
+        verbose: bool = True
     ) -> None:
-        self.base = base
         self.engine = engine
         self.autodiscover_paths = autodiscover_paths
-        self.logger = logger
+        self.logger = logger or DefaultLogger() if verbose else None
+        self.verbose = verbose
         asyncio.create_task(self.__init())
 
     async def __init(self) -> None:
-        if not await self.__find_handlers():
+        if not isinstance(self.engine, (AsyncEngine, Engine)):
+            raise RuntimeError(
+                '[SQLAlchemyEvents] \'engine\' must be an instance of '
+                'sqlalchemy.Engine or sqlalchemy.ext.asyncio.AsyncEngine.'
+            )
+
+        if not self.autodiscover_paths:
+            if self.verbose:
+                self.logger.warning(
+                    '[SQLAlchemyEvents] No autodiscover paths specified. '
+                    'Please provide at least one module path (e.g., \'app.handlers\') '
+                    'in \'autodiscover_paths\' during initialization.'
+                )
+            return
+
+        handlers = await self.__find_handlers()
+        if not handlers:
             return
 
         dialect = dialect_resolver(self.engine)
@@ -38,13 +57,13 @@ class SQLAlchemyEvents:
         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)
+        await self.__start_listen(event_strategy, handlers)
 
     async def __find_handlers(self):
         autodiscover(self.autodiscover_paths)
         handlers = get_event_handlers()
         if not handlers:
-            if self.logger:
+            if self.verbose:
                 self.logger.info('[SQLAlchemyEvents] No handlers found')
             return
         res_handlers = []
@@ -53,6 +72,7 @@ class SQLAlchemyEvents:
 
         filtered_handlers = []
         handler_paths = set()
+        handlers_qty = defaultdict(int)
         for handler in res_handlers:
             file_path = inspect.getsourcefile(handler.func) or inspect.getfile(handler.func)
 
@@ -64,13 +84,28 @@ class SQLAlchemyEvents:
 
             handler_paths.add(handler_path)
             filtered_handlers.append(handler)
-            if self.logger:
-                self.logger.info(f'[SQLAlchemyEvents] Registered handler {handler.func.__name__} '
-                                 f'from {file_func.parent.name}/{file_name}')
+            handlers_qty[f'{file_func.parent.name}/{file_name}'] += 1
+
+        if self.verbose:
+            for path, qty in handlers_qty.items():
+                self.logger.info(f'[SQLAlchemyEvents] Registered {qty} {'handler' if qty == 1 else 'handlers'} '
+                                 f'from \'{path}\'')
 
         return filtered_handlers
 
-    async def __start_listen(self, event_strategy: SaEventStrategy):
+    async def __start_listen(self, event_strategy: SaEventStrategy, handlers: list[Handler]):
+        base = None
+        try:
+            model = handlers[0].args['model']
+            for cls in model.__mro__:
+                if issubclass(cls, DeclarativeBase) and cls is not DeclarativeBase:
+                    base = cls
+
+            if not base:
+                raise Exception
+        except Exception:
+            raise RuntimeError('[SQLAlchemyEvents] No Base found in Registered handlers')
+
         if isinstance(self.engine, AsyncEngine):
             async with self.engine.connect() as conn:
                 raw_conn = await conn.get_raw_connection()
@@ -80,11 +115,11 @@ class SQLAlchemyEvents:
                     raise RuntimeError('[SQLAlchemyEvents] Driver does not support LISTEN/NOTIFY')
 
                 await event_strategy.init_triggers(
-                    model_list=self.base.__subclasses__(),
+                    model_list=base.__subclasses__(),
                     conn=conn,
                     logger=self.logger
                 )
-            if self.logger:
+            if self.verbose:
                 self.logger.info('[SQLAlchemyEvents] Start listening')
             await driver_conn.add_listener('sqlalchemy_events', event_strategy.callback.handle)
             return
@@ -103,11 +138,11 @@ class SQLAlchemyEvents:
             if not asyncio.iscoroutine(result):
                 raise RuntimeError(sync_engine_error)
             await event_strategy.init_triggers(
-                model_list=self.base.__subclasses__(),
+                model_list=base.__subclasses__(),
                 conn=conn,
                 logger=self.logger
             )
-            if self.logger:
+            if self.verbose:
                 self.logger.info('[SQLAlchemyEvents] Start listening')
             await result
 
@@ -120,6 +155,6 @@ class SQLAlchemyEvents:
             try:
                 await driver_conn.wait_for_notify()
             except Exception as e:
-                if self.logger:
+                if self.verbose:
                     self.logger.error(f'[SQLAlchemyEvents] listener crashed: {e}')
                 await asyncio.sleep(1)

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events/decorators.py

@@ -2,6 +2,10 @@ from .types import SaEvent
 
 
 def with_events(events: list[SaEvent]):
+    for e in events:
+        if not isinstance(e, SaEvent):
+            raise RuntimeError(f'Event must be a SaEvent instance, not {type(e)}')
+
     def wrapper(cls):
         cls.__events__ = set(events)
 

sqlalchemy_events_lib-0.3.0/src/sqlalchemy_events/default_logger.py

@@ -0,0 +1,25 @@
+import logging
+
+
+class DefaultLogger:
+    def __init__(self) -> None:
+        self.__logger = logging.getLogger()
+        self.__logger.setLevel(logging.INFO)
+
+        if not self.__logger.handlers:
+            formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
+            console_handler = logging.StreamHandler()
+            console_handler.setFormatter(formatter)
+            self.__logger.addHandler(console_handler)
+
+    def info(self, message: str) -> None:
+        self.__logger.info(message)
+
+    def error(self, message: str, exc_info: bool = True) -> None:
+        self.__logger.error(message, exc_info=exc_info)
+
+    def warning(self, message: str) -> None:
+        self.__logger.warning(message)
+
+    def debug(self, message: str) -> None:
+        self.__logger.debug(message)

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events/discovery.py

@@ -1,5 +1,6 @@
 import importlib
 import pkgutil
+from pathlib import Path
 from types import ModuleType
 from typing import Iterable, List
 
@@ -8,6 +9,11 @@ def autodiscover(paths: Iterable[str]) -> List[ModuleType]:
     modules: List[ModuleType] = []
 
     for path in paths:
+        if isinstance(path, Path):
+            path = str(path)
+            path = path.replace('\\', '.')
+
+        path = path.strip('/').replace('/', '.').lstrip('.')
         module = importlib.import_module(path)
         modules.append(module)
 

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events/handlers.py

@@ -10,6 +10,9 @@ from .types import Handler
 
 
 def __inner(func: Callable, sa_event: SaEvent, model: Type[DeclarativeBase]):
+    if not isinstance(model, type) or not issubclass(model, DeclarativeBase):
+        raise RuntimeError('Model must inherit from DeclarativeBase')
+
     event_handlers = get_event_handlers()
     trig_name = f'sa_{model.__tablename__}_{sa_event.lower()}_notify'
     func_path = inspect.getsourcefile(func) or inspect.getfile(func)

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-events-lib
-Version: 0.2.0
+Version: 0.3.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
@@ -110,13 +110,11 @@ 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']
     )
@@ -133,22 +131,23 @@ if __name__ == '__main__':
 The SQLAlchemyEvents class accepts the following parameters:
 ```python
 SQLAlchemyEvents(
-    base,
     engine,
     autodiscover_paths,
-    logger=None
+    logger=None,
+    verbose=True
 )
 ```
 
 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. 
+`@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

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/sqlalchemy_events_lib.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/sqlalchemy_events/__init__.py
 src/sqlalchemy_events/core.py
 src/sqlalchemy_events/decorators.py
+src/sqlalchemy_events/default_logger.py
 src/sqlalchemy_events/discovery.py
 src/sqlalchemy_events/events.py
 src/sqlalchemy_events/exceptions.py

{sqlalchemy_events_lib-0.2.0 → sqlalchemy_events_lib-0.3.0}/src/tests/conftest.py

@@ -33,7 +33,6 @@ async def prepared_db(engine):
             await conn.run_sync(Base.metadata.create_all)
 
         SQLAlchemyEvents(
-            base=Base,
             engine=engine,
             autodiscover_paths=['tests']
         )