surreal-orm-lite 0.3.0__tar.gz → 0.4.0__tar.gz

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-07
+
+### Added
+
+- **Model Signals**: Django-style event system for model lifecycle
+  - `Signal` class for pre/post event handlers
+  - `AroundSignal` class for context manager-style wrapping signals with `yield`
+  - `pre_save` / `post_save` - Fired before/after `save()` operations
+  - `pre_update` / `post_update` - Fired before/after `update()` and `merge()` operations
+  - `pre_delete` / `post_delete` - Fired before/after `delete()` operations
+  - `around_save` / `around_update` / `around_delete` - Wrap operations for timing, logging, etc.
+  - `connect(model_class)` decorator for registering handlers
+  - `disconnect(handler, model_class)` for removing handlers
+  - `clear()` for removing all handlers
+  - `has_handlers()` for checking if handlers are registered
+
+- `post_save` signal includes `created` flag to distinguish new records
+- `pre_update` / `post_update` signals include `update_fields` list
+- New test file `tests/test_signals.py` with unit and e2e tests
+
+### Changed
+
+- `save()`, `update()`, `merge()`, `delete()` now emit signals when handlers are registered
+- Internal `_do_save()` method extracted from `save()` for signal integration
+
 ## [0.3.0] - 2026-02-05
 
 ### Added

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.3.0
+Version: 0.4.0
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -191,6 +191,9 @@ results = await User.objects().query(
 | Custom primary keys   | ✅     |
 | HTTP connections      | ✅     |
 | WebSocket connections | ✅     |
+| Aggregations          | ✅     |
+| GROUP BY              | ✅     |
+| Model Signals         | ✅     |
 
 ### Supported Filter Lookups
 
@@ -201,6 +204,78 @@ results = await User.objects().query(
 - `startswith`, `istartswith`
 - `endswith`, `iendswith`
 
+### 5. Aggregations
+
+```python
+from surreal_orm_lite import Count, Sum, Avg, Min, Max
+
+# Simple aggregations
+count = await User.objects().count()
+total = await Order.objects().sum("amount")
+avg_age = await User.objects().avg("age")
+max_price = await Product.objects().max("price")
+min_price = await Product.objects().min("price")
+
+# Check existence
+has_admins = await User.objects().filter(role="admin").exists()
+
+# GROUP BY with annotations
+results = await User.objects().values("status").annotate(count=Count()).exec()
+# [{"status": "active", "count": 42}, {"status": "inactive", "count": 8}]
+
+# Raw SurrealQL queries
+results = await User.raw_query(
+    "SELECT * FROM User WHERE age > $min_age",
+    variables={"min_age": 18}
+)
+```
+
+### 6. Model Signals
+
+```python
+from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
+
+@post_save.connect(User)
+async def on_user_saved(sender, instance, created, **kwargs):
+    """Called after every User save."""
+    if created:
+        await send_welcome_email(instance.email)
+    await invalidate_cache(f"user:{instance.id}")
+
+@pre_delete.connect(User)
+async def on_user_deleting(sender, instance, **kwargs):
+    """Called before User deletion."""
+    await archive_user_data(instance.id)
+```
+
+**Available signals:**
+
+| Signal          | When                        | Extra kwargs     |
+| --------------- | --------------------------- | ---------------- |
+| `pre_save`      | Before `save()`             |                  |
+| `post_save`     | After `save()`              | `created`        |
+| `pre_update`    | Before `update()`/`merge()` | `update_fields`  |
+| `post_update`   | After `update()`/`merge()`  | `update_fields`  |
+| `pre_delete`    | Before `delete()`           |                  |
+| `post_delete`   | After `delete()`            |                  |
+| `around_save`   | Wraps `save()`              |                  |
+| `around_update` | Wraps `update()`/`merge()`  | `update_fields`  |
+| `around_delete` | Wraps `delete()`            |                  |
+
+**Around signals** use async generators to wrap operations:
+
+```python
+from surreal_orm_lite import around_save
+
+@around_save.connect(User)
+async def time_user_save(sender, instance, **kwargs):
+    import time
+    start = time.time()
+    yield  # save() executes here
+    duration = time.time() - start
+    print(f"Save took {duration:.3f}s")
+```
+
 ---
 
 ## Configuration Options

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/README.md

@@ -141,6 +141,9 @@ results = await User.objects().query(
 | Custom primary keys   | ✅     |
 | HTTP connections      | ✅     |
 | WebSocket connections | ✅     |
+| Aggregations          | ✅     |
+| GROUP BY              | ✅     |
+| Model Signals         | ✅     |
 
 ### Supported Filter Lookups
 
@@ -151,6 +154,78 @@ results = await User.objects().query(
 - `startswith`, `istartswith`
 - `endswith`, `iendswith`
 
+### 5. Aggregations
+
+```python
+from surreal_orm_lite import Count, Sum, Avg, Min, Max
+
+# Simple aggregations
+count = await User.objects().count()
+total = await Order.objects().sum("amount")
+avg_age = await User.objects().avg("age")
+max_price = await Product.objects().max("price")
+min_price = await Product.objects().min("price")
+
+# Check existence
+has_admins = await User.objects().filter(role="admin").exists()
+
+# GROUP BY with annotations
+results = await User.objects().values("status").annotate(count=Count()).exec()
+# [{"status": "active", "count": 42}, {"status": "inactive", "count": 8}]
+
+# Raw SurrealQL queries
+results = await User.raw_query(
+    "SELECT * FROM User WHERE age > $min_age",
+    variables={"min_age": 18}
+)
+```
+
+### 6. Model Signals
+
+```python
+from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
+
+@post_save.connect(User)
+async def on_user_saved(sender, instance, created, **kwargs):
+    """Called after every User save."""
+    if created:
+        await send_welcome_email(instance.email)
+    await invalidate_cache(f"user:{instance.id}")
+
+@pre_delete.connect(User)
+async def on_user_deleting(sender, instance, **kwargs):
+    """Called before User deletion."""
+    await archive_user_data(instance.id)
+```
+
+**Available signals:**
+
+| Signal          | When                        | Extra kwargs     |
+| --------------- | --------------------------- | ---------------- |
+| `pre_save`      | Before `save()`             |                  |
+| `post_save`     | After `save()`              | `created`        |
+| `pre_update`    | Before `update()`/`merge()` | `update_fields`  |
+| `post_update`   | After `update()`/`merge()`  | `update_fields`  |
+| `pre_delete`    | Before `delete()`           |                  |
+| `post_delete`   | After `delete()`            |                  |
+| `around_save`   | Wraps `save()`              |                  |
+| `around_update` | Wraps `update()`/`merge()`  | `update_fields`  |
+| `around_delete` | Wraps `delete()`            |                  |
+
+**Around signals** use async generators to wrap operations:
+
+```python
+from surreal_orm_lite import around_save
+
+@around_save.connect(User)
+async def time_user_save(sender, instance, **kwargs):
+    import time
+    start = time.time()
+    yield  # save() executes here
+    duration = time.time() - start
+    print(f"Save took {duration:.3f}s")
+```
+
 ---
 
 ## Configuration Options

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.3.0"
+version = "0.4.0"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/src/surreal_orm_lite/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
 from .connection_manager import SurrealDBConnectionManager
@@ -12,6 +12,19 @@ from .exceptions import (
 )
 from .model_base import BaseSurrealModel, SurrealConfigDict
 from .query_set import QuerySet
+from .signals import (
+    AroundSignal,
+    Signal,
+    around_delete,
+    around_save,
+    around_update,
+    post_delete,
+    post_save,
+    post_update,
+    pre_delete,
+    pre_save,
+    pre_update,
+)
 
 __all__ = [
     "__version__",
@@ -30,6 +43,18 @@ __all__ = [
     "Avg",
     "Min",
     "Max",
+    # Signals
+    "Signal",
+    "AroundSignal",
+    "pre_save",
+    "post_save",
+    "pre_update",
+    "post_update",
+    "pre_delete",
+    "post_delete",
+    "around_save",
+    "around_update",
+    "around_delete",
     # Exceptions
     "SurrealORMError",
     "SurrealDbError",

{surreal_orm_lite-0.3.0 → surreal_orm_lite-0.4.0}/src/surreal_orm_lite/model_base.py

@@ -7,6 +7,17 @@ from surrealdb import RecordID
 
 from .connection_manager import SurrealDBConnectionManager
 from .exceptions import SurrealDbError
+from .signals import (
+    around_delete,
+    around_save,
+    around_update,
+    post_delete,
+    post_save,
+    post_update,
+    pre_delete,
+    pre_save,
+    pre_update,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -52,7 +63,7 @@ class BaseSurrealModel(BaseModel):
         Get the ID of the model instance.
         """
         if hasattr(self, "id"):
-            id_value = self.id
+            id_value = self.id  # type: ignore[attr-defined]
             return str(id_value) if id_value is not None else None
 
         if hasattr(self, "model_config"):
@@ -111,9 +122,10 @@ class BaseSurrealModel(BaseModel):
                 if hasattr(self, key):
                     object.__setattr__(self, key, value)
 
-    async def save(self) -> Self:
+    async def _do_save(self) -> tuple[Self, bool]:
         """
-        Save the model instance to the database.
+        Internal save logic. Returns (self, created) where created indicates
+        whether a new record was created (always True for save).
         """
         client = await SurrealDBConnectionManager.get_client()
         data = self.model_dump(exclude={"id"})
@@ -122,13 +134,13 @@ class BaseSurrealModel(BaseModel):
 
         if id is not None:
             # Escape special characters in ID
-            escaped_id = f"`{id}`" if any(c in str(id) for c in "@#$%^&*()") else id
+            escaped_id = f"`{id}`" if any(c in str(id) for c in "@#$%^&*()-+=/\\! ") else id
             thing = f"{table}:{escaped_id}"
             result = await client.create(thing, data)
             # SDK 1.0.8 returns error message as string instead of raising exception
             if isinstance(result, str) and "already exists" in result:
                 raise SurrealDbError(f"There was a problem with the database: {result}")
-            return self
+            return self, True
 
         # Auto-generate the ID
         record = await client.create(table, data)  # pragma: no cover
@@ -150,38 +162,95 @@ class BaseSurrealModel(BaseModel):
                     value = str(value).split(":")[1]
                 if hasattr(self, key):
                     object.__setattr__(self, key, value)
-            return self
+            return self, True
 
         raise SurrealDbError("Can't save data, no record returned.")  # pragma: no cover
 
+    async def save(self) -> Self:
+        """
+        Save the model instance to the database.
+
+        Emits pre_save, post_save, and around_save signals.
+        """
+        sender = self.__class__
+        has_signals = pre_save.has_handlers(sender) or post_save.has_handlers(sender) or around_save.has_handlers(sender)
+
+        if not has_signals:
+            result, created = await self._do_save()
+            return result
+
+        await pre_save.send(sender, instance=self)
+
+        async with around_save.wrap(sender, instance=self):
+            result, created = await self._do_save()
+
+        await post_save.send(sender, instance=self, created=created)
+
+        return result
+
     async def update(self) -> Any:
         """
         Update the model instance to the database.
+
+        Emits pre_update, post_update, and around_update signals.
         """
         client = await SurrealDBConnectionManager.get_client()
+        sender = self.__class__
 
         data = self.model_dump(exclude={"id"})
         id = self.get_id()
         if id is not None:
             thing = f"{self.__class__.__name__}:{id}"
-            result = await client.update(thing, data)
+            update_fields = list(data.keys())
+            has_signals = (
+                pre_update.has_handlers(sender) or post_update.has_handlers(sender) or around_update.has_handlers(sender)
+            )
+
+            if not has_signals:
+                return await client.update(thing, data)
+
+            await pre_update.send(sender, instance=self, update_fields=update_fields)
+
+            async with around_update.wrap(sender, instance=self, update_fields=update_fields):
+                result = await client.update(thing, data)
+
+            await post_update.send(sender, instance=self, update_fields=update_fields)
+
             return result
         raise SurrealDbError("Can't update data, no id found.")
 
     async def merge(self, **data: Any) -> Any:
         """
-        Update the model instance to the database.
+        Partial update of the model instance in the database.
+
+        Emits pre_update, post_update, and around_update signals.
         """
 
         client = await SurrealDBConnectionManager.get_client()
+        sender = self.__class__
         data_set = dict(data.items())
 
         id = self.get_id()
-        if id:
+        if id is not None:
             thing = f"{self.get_table_name()}:{id}"
+            update_fields = list(data_set.keys())
+            has_signals = (
+                pre_update.has_handlers(sender) or post_update.has_handlers(sender) or around_update.has_handlers(sender)
+            )
+
+            if not has_signals:
+                await client.merge(thing, data_set)
+                await self.refresh()
+                return
+
+            await pre_update.send(sender, instance=self, update_fields=update_fields)
+
+            async with around_update.wrap(sender, instance=self, update_fields=update_fields):
+                await client.merge(thing, data_set)
+                await self.refresh()
+
+            await post_update.send(sender, instance=self, update_fields=update_fields)
 
-            await client.merge(thing, data_set)
-            await self.refresh()
             return
 
         raise SurrealDbError(f"No Id for the data to merge: {data}")
@@ -189,18 +258,36 @@ class BaseSurrealModel(BaseModel):
     async def delete(self) -> None:
         """
         Delete the model instance from the database.
+
+        Emits pre_delete, post_delete, and around_delete signals.
         """
 
         client = await SurrealDBConnectionManager.get_client()
+        sender = self.__class__
 
         id = self.get_id()
+        if id is None:
+            raise SurrealDbError("Can't delete data, no id found.")
 
         thing = f"{self.get_table_name()}:{id}"
+        has_signals = pre_delete.has_handlers(sender) or post_delete.has_handlers(sender) or around_delete.has_handlers(sender)
+
+        if not has_signals:
+            deleted = await client.delete(thing)
+            if not deleted:
+                raise SurrealDbError(f"Can't delete Record id -> '{id}' not found!")
+            logger.info(f"Record deleted -> {deleted}.")
+            return
+
+        await pre_delete.send(sender, instance=self)
+
+        async with around_delete.wrap(sender, instance=self):
+            deleted = await client.delete(thing)
 
-        deleted = await client.delete(thing)
+            if not deleted:
+                raise SurrealDbError(f"Can't delete Record id -> '{id}' not found!")
 
-        if not deleted:
-            raise SurrealDbError(f"Can't delete Record id -> '{id}' not found!")
+        await post_delete.send(sender, instance=self)
 
         logger.info(f"Record deleted -> {deleted}.")
 

surreal_orm_lite-0.4.0/src/surreal_orm_lite/signals.py

@@ -0,0 +1,286 @@
+"""
+Signal system for SurrealDB-ORM-lite.
+
+Provides Django-style pre/post signals and around signals
+for model lifecycle events (save, update, delete).
+
+Usage:
+    from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
+
+    @post_save.connect(User)
+    async def on_user_saved(sender, instance, created, **kwargs):
+        if created:
+            await send_welcome_email(instance.email)
+
+    @around_save.connect(User)
+    async def time_user_save(sender, instance, **kwargs):
+        import time
+        start = time.time()
+        yield  # save() executes here
+        duration = time.time() - start
+        print(f"Save took {duration:.3f}s")
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from collections import defaultdict
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Type alias for signal handlers
+SignalHandler = Callable[..., Coroutine[Any, Any, None]]
+AroundHandler = Callable[..., AsyncGenerator[None, None]]
+
+
+class Signal:
+    """
+    A signal that dispatches events to registered async handlers.
+
+    Handlers are registered per model class and called in registration order
+    when the signal is sent.
+
+    Example:
+        pre_save = Signal("pre_save")
+
+        @pre_save.connect(User)
+        async def on_user_pre_save(sender, instance, **kwargs):
+            print(f"About to save {instance}")
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._handlers: dict[type, list[SignalHandler]] = defaultdict(list)
+
+    def connect(self, model_class: type) -> Callable[[SignalHandler], SignalHandler]:
+        """
+        Decorator to register a handler for a specific model class.
+
+        Args:
+            model_class: The model class to listen for signals on.
+
+        Returns:
+            Decorator that registers the handler.
+        """
+
+        def decorator(handler: SignalHandler) -> SignalHandler:
+            if handler not in self._handlers[model_class]:
+                self._handlers[model_class].append(handler)
+            return handler
+
+        return decorator
+
+    def disconnect(self, handler: SignalHandler, model_class: type) -> bool:
+        """
+        Remove a handler for a specific model class.
+
+        Args:
+            handler: The handler function to remove.
+            model_class: The model class the handler was registered for.
+
+        Returns:
+            True if the handler was found and removed, False otherwise.
+        """
+        handlers = self._handlers.get(model_class, [])
+        if handler in handlers:
+            handlers.remove(handler)
+            if not handlers:
+                self._handlers.pop(model_class, None)
+            return True
+        return False
+
+    async def send(self, sender: type, **kwargs: Any) -> None:
+        """
+        Dispatch the signal to all registered handlers for the sender class.
+
+        Args:
+            sender: The model class that is sending the signal.
+            **kwargs: Additional keyword arguments passed to handlers.
+        """
+        for handler in self._handlers.get(sender, []):
+            await handler(sender=sender, **kwargs)
+
+    def has_handlers(self, model_class: type) -> bool:
+        """Check if any handlers are registered for the given model class."""
+        return bool(self._handlers.get(model_class))
+
+    def clear(self, model_class: type | None = None) -> None:
+        """
+        Clear registered handlers.
+
+        Args:
+            model_class: If provided, clear handlers only for this model.
+                        If None, clear all handlers for all models.
+        """
+        if model_class is not None:
+            self._handlers.pop(model_class, None)
+        else:
+            self._handlers.clear()
+
+
+class AroundSignal:
+    """
+    A signal that wraps an operation using async generators (context manager style).
+
+    Handlers yield once: code before yield runs before the operation,
+    code after yield runs after. This allows measuring timing, wrapping
+    in try/except, etc.
+
+    Example:
+        around_save = AroundSignal("around_save")
+
+        @around_save.connect(User)
+        async def time_user_save(sender, instance, **kwargs):
+            start = time.time()
+            yield  # save() executes here
+            duration = time.time() - start
+            print(f"Save took {duration:.3f}s")
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._handlers: dict[type, list[AroundHandler]] = defaultdict(list)
+
+    def connect(self, model_class: type) -> Callable[[AroundHandler], AroundHandler]:
+        """
+        Decorator to register an around handler for a specific model class.
+
+        Args:
+            model_class: The model class to listen for signals on.
+
+        Returns:
+            Decorator that registers the handler.
+        """
+
+        def decorator(handler: AroundHandler) -> AroundHandler:
+            if handler not in self._handlers[model_class]:
+                self._handlers[model_class].append(handler)
+            return handler
+
+        return decorator
+
+    def disconnect(self, handler: AroundHandler, model_class: type) -> bool:
+        """
+        Remove a handler for a specific model class.
+
+        Args:
+            handler: The handler function to remove.
+            model_class: The model class the handler was registered for.
+
+        Returns:
+            True if the handler was found and removed, False otherwise.
+        """
+        handlers = self._handlers.get(model_class, [])
+        if handler in handlers:
+            handlers.remove(handler)
+            if not handlers:
+                self._handlers.pop(model_class, None)
+            return True
+        return False
+
+    @contextlib.asynccontextmanager
+    async def wrap(self, sender: type, **kwargs: Any) -> AsyncGenerator[None, None]:
+        """
+        Context manager that runs all around handlers for the sender class.
+
+        The handlers' pre-yield code runs before yielding,
+        and their post-yield code runs after in reverse (LIFO) order,
+        similar to nested context managers.
+
+        Args:
+            sender: The model class that is sending the signal.
+            **kwargs: Additional keyword arguments passed to handlers.
+        """
+        handlers = self._handlers.get(sender, [])
+        active: list[tuple[AsyncGenerator[None, None], AroundHandler]] = []
+
+        # Start all generators (run pre-yield code)
+        try:
+            for handler in handlers:
+                gen = handler(sender=sender, **kwargs)
+                try:
+                    await gen.__anext__()
+                except StopAsyncIteration:
+                    logger.warning(
+                        "AroundSignal handler %r for sender %r did not yield; it must yield exactly once.",
+                        handler,
+                        sender,
+                    )
+                    with contextlib.suppress(Exception):
+                        await gen.aclose()
+                    continue
+                active.append((gen, handler))
+        except Exception:
+            # If startup fails, close any already-started generators in LIFO order
+            for gen, _ in reversed(active):
+                with contextlib.suppress(Exception):
+                    await gen.aclose()
+            raise
+
+        try:
+            yield
+        finally:
+            # Complete all generators (run post-yield code) in reverse (LIFO) order.
+            # Post-yield handler errors are logged and suppressed so they don't
+            # mask an exception raised by the wrapped operation.
+            for gen, handler in reversed(active):
+                try:
+                    await gen.__anext__()
+                except StopAsyncIteration:
+                    continue
+                except Exception:
+                    logger.exception(
+                        "AroundSignal handler %r for sender %r raised during post-yield cleanup.",
+                        handler,
+                        sender,
+                    )
+                else:
+                    logger.warning(
+                        "AroundSignal handler %r for sender %r yielded more than once; handlers must yield exactly once.",
+                        handler,
+                        sender,
+                    )
+                    with contextlib.suppress(Exception):
+                        await gen.aclose()
+
+    def has_handlers(self, model_class: type) -> bool:
+        """Check if any handlers are registered for the given model class."""
+        return bool(self._handlers.get(model_class))
+
+    def clear(self, model_class: type | None = None) -> None:
+        """
+        Clear registered handlers.
+
+        Args:
+            model_class: If provided, clear handlers only for this model.
+                        If None, clear all handlers for all models.
+        """
+        if model_class is not None:
+            self._handlers.pop(model_class, None)
+        else:
+            self._handlers.clear()
+
+
+# =============================================================================
+# Pre-defined signal instances
+# =============================================================================
+
+# Pre/Post signals for save operations
+pre_save = Signal("pre_save")
+post_save = Signal("post_save")
+
+# Pre/Post signals for update operations
+pre_update = Signal("pre_update")
+post_update = Signal("post_update")
+
+# Pre/Post signals for delete operations
+pre_delete = Signal("pre_delete")
+post_delete = Signal("post_delete")
+
+# Around signals
+around_save = AroundSignal("around_save")
+around_update = AroundSignal("around_update")
+around_delete = AroundSignal("around_delete")