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

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

@@ -5,6 +5,64 @@ 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
+
+- **Aggregation Functions**: New aggregation classes for database calculations
+  - `Count()` - Count records
+  - `Sum(field)` - Sum numeric field values
+  - `Avg(field)` - Calculate average of numeric field
+  - `Min(field)` - Find minimum value
+  - `Max(field)` - Find maximum value
+
+- **QuerySet Aggregation Methods**: Shortcut methods for common aggregations
+  - `count()` - Returns count as integer directly
+  - `sum(field)` - Returns sum as float/int
+  - `avg(field)` - Returns average as float
+  - `min(field)` - Returns minimum value
+  - `max(field)` - Returns maximum value
+
+- **GROUP BY Support**: Django-style grouping with annotations
+  - `values(*fields)` - Specify fields for GROUP BY
+  - `annotate(**aggregations)` - Add aggregation annotations
+
+- **exists() Method**: Efficiently check if records exist
+
+- **raw_query() Class Method**: Execute arbitrary SurrealQL queries with variables
+
+- New test file `tests/test_aggregations.py` with comprehensive unit and e2e tests
+
+### Changed
+
+- QuerySet now tracks `_group_by_fields` and `_annotations` for GROUP BY queries
+- `exec()` method now handles GROUP BY queries differently, returning dicts instead of model instances
+
 ## [0.2.2] - 2026-02-05
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.2.2
+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.2.2 → 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.2.2 → surreal_orm_lite-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.2.2"
+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.4.0/src/surreal_orm_lite/__init__.py

@@ -0,0 +1,64 @@
+__version__ = "0.4.0"
+
+from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
+from .connection_manager import SurrealDBConnectionManager
+from .enum import OrderBy
+from .exceptions import (
+    SurrealDbConnectionError,
+    SurrealDbError,
+    SurrealDbNotFoundError,
+    SurrealDbValidationError,
+    SurrealORMError,
+)
+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__",
+    # Connection
+    "SurrealDBConnectionManager",
+    # Model
+    "BaseSurrealModel",
+    "SurrealConfigDict",
+    # QuerySet
+    "QuerySet",
+    "OrderBy",
+    # Aggregations
+    "Aggregation",
+    "Count",
+    "Sum",
+    "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",
+    "SurrealDbConnectionError",
+    "SurrealDbValidationError",
+    "SurrealDbNotFoundError",
+]

surreal_orm_lite-0.4.0/src/surreal_orm_lite/aggregations.py

@@ -0,0 +1,279 @@
+"""
+Aggregation classes for SurrealDB-ORM-lite.
+
+This module provides Django-style aggregation functions that can be used
+with QuerySet to perform aggregate calculations on database fields.
+
+Example:
+    ```python
+    from surreal_orm_lite import Count, Sum, Avg, Min, Max
+
+    # Simple aggregations
+    count = await User.objects().count()
+    total = await Order.objects().sum("amount")
+
+    # With GROUP BY
+    results = await User.objects().values("status").annotate(count=Count()).exec()
+    ```
+"""
+
+from abc import ABC, abstractmethod
+
+from .utils import validate_field_name
+
+
+class Aggregation(ABC):
+    """
+    Base class for all aggregation functions.
+
+    Aggregations are used to compute summary values from a set of records.
+    Each aggregation must implement the `to_sql()` method that returns
+    the SurrealDB SQL expression for the aggregation.
+    """
+
+    def __init__(self, field: str | None = None, alias: str | None = None) -> None:
+        """
+        Initialize an aggregation.
+
+        Args:
+            field: The field name to aggregate. Some aggregations (like Count)
+                   don't require a field.
+            alias: Optional alias for the result. If not provided, a default
+                   alias will be generated.
+        """
+        self.field = field
+        self.alias = alias
+
+    @abstractmethod
+    def to_sql(self) -> str:
+        """
+        Convert the aggregation to a SurrealDB SQL expression.
+
+        Returns:
+            str: The SQL expression for this aggregation.
+        """
+        pass  # pragma: no cover
+
+    def get_alias(self) -> str:
+        """
+        Get the alias for this aggregation result.
+
+        Returns:
+            str: The alias name for the aggregation result.
+        """
+        if self.alias:
+            return self.alias
+        if self.field:
+            return f"{self.__class__.__name__.lower()}_{self.field}"
+        return self.__class__.__name__.lower()
+
+
+class Count(Aggregation):
+    """
+    Count aggregation function.
+
+    Counts the number of records in a query result.
+
+    Example:
+        ```python
+        # Count all users
+        count = await User.objects().count()
+
+        # Count with filter
+        active_count = await User.objects().filter(status="active").count()
+
+        # Count with GROUP BY
+        results = await User.objects().values("status").annotate(count=Count()).exec()
+        ```
+    """
+
+    def __init__(self, field: str | None = None, alias: str | None = None) -> None:
+        """
+        Initialize a Count aggregation.
+
+        Args:
+            field: Optional field name. If not provided, counts all records.
+            alias: Optional alias for the result.
+        """
+        if field is not None:
+            validate_field_name(field, "Count field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "count()" or "count(field)" expression.
+        """
+        if self.field:
+            return f"count({self.field})"
+        return "count()"
+
+
+class Sum(Aggregation):
+    """
+    Sum aggregation function.
+
+    Calculates the sum of a numeric field.
+
+    Example:
+        ```python
+        # Sum of all order amounts
+        total = await Order.objects().sum("amount")
+
+        # Sum with filter
+        total_completed = await Order.objects().filter(status="completed").sum("amount")
+
+        # Sum with GROUP BY
+        results = await Order.objects().values("customer_id").annotate(total=Sum("amount")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Sum aggregation.
+
+        Args:
+            field: The numeric field to sum.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Sum requires a field name")
+        validate_field_name(field, "Sum field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::sum(field)" expression.
+        """
+        return f"math::sum({self.field})"
+
+
+class Avg(Aggregation):
+    """
+    Average aggregation function.
+
+    Calculates the average of a numeric field.
+
+    Example:
+        ```python
+        # Average age of all users
+        avg_age = await User.objects().avg("age")
+
+        # Average with filter
+        avg_active = await User.objects().filter(status="active").avg("age")
+
+        # Average with GROUP BY
+        results = await User.objects().values("department").annotate(avg_salary=Avg("salary")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize an Avg aggregation.
+
+        Args:
+            field: The numeric field to average.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Avg requires a field name")
+        validate_field_name(field, "Avg field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::mean(field)" expression.
+        """
+        return f"math::mean({self.field})"
+
+
+class Min(Aggregation):
+    """
+    Minimum aggregation function.
+
+    Finds the minimum value of a field.
+
+    Example:
+        ```python
+        # Minimum price
+        min_price = await Product.objects().min("price")
+
+        # Minimum with filter
+        min_active = await Product.objects().filter(active=True).min("price")
+
+        # Minimum with GROUP BY
+        results = await Product.objects().values("category").annotate(min_price=Min("price")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Min aggregation.
+
+        Args:
+            field: The field to find the minimum value of.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Min requires a field name")
+        validate_field_name(field, "Min field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::min(field)" expression.
+        """
+        return f"math::min({self.field})"
+
+
+class Max(Aggregation):
+    """
+    Maximum aggregation function.
+
+    Finds the maximum value of a field.
+
+    Example:
+        ```python
+        # Maximum price
+        max_price = await Product.objects().max("price")
+
+        # Maximum with filter
+        max_active = await Product.objects().filter(active=True).max("price")
+
+        # Maximum with GROUP BY
+        results = await Product.objects().values("category").annotate(max_price=Max("price")).exec()
+        ```
+    """
+
+    def __init__(self, field: str, alias: str | None = None) -> None:
+        """
+        Initialize a Max aggregation.
+
+        Args:
+            field: The field to find the maximum value of.
+            alias: Optional alias for the result.
+        """
+        if not field or not field.strip():
+            raise ValueError("Max requires a field name")
+        validate_field_name(field, "Max field")
+        super().__init__(field, alias)
+
+    def to_sql(self) -> str:
+        """
+        Convert to SurrealDB SQL.
+
+        Returns:
+            str: "math::max(field)" expression.
+        """
+        return f"math::max({self.field})"