surrealdb-orm 0.1.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

surreal_orm/__init__.py

@@ -1,12 +1,81 @@
-from .model_base import BaseSurrealModel, SurrealConfigDict
+"""
+SurrealDB ORM - A Django-style ORM for SurrealDB.
+
+This package provides:
+- Model definitions with Pydantic validation
+- Query building with fluent interface
+- Migration system with version control
+- JWT authentication support
+- CLI tools for schema management
+"""
+
 from .connection_manager import SurrealDBConnectionManager
-from .query_set import QuerySet
 from .enum import OrderBy
+from .model_base import (
+    BaseSurrealModel,
+    SurrealConfigDict,
+    SurrealDbError,
+    get_registered_models,
+)
+from .query_set import QuerySet
+from .types import (
+    EncryptionAlgorithm,
+    FieldType,
+    SchemaMode,
+    TableType,
+)
+from .fields import Encrypted
+from .fields import (
+    ForeignKey,
+    ManyToMany,
+    Relation,
+    RelationInfo,
+    get_relation_info,
+    is_foreign_key,
+    is_graph_relation,
+    is_many_to_many,
+    is_relation_field,
+)
+from .auth import AuthenticatedUserMixin
+from .aggregations import Aggregation, Count, Sum, Avg, Min, Max
 
 __all__ = [
+    # Connection
     "SurrealDBConnectionManager",
+    # Models
     "BaseSurrealModel",
+    "SurrealConfigDict",
+    "SurrealDbError",
+    "get_registered_models",
+    # Query
     "QuerySet",
     "OrderBy",
-    "SurrealConfigDict",
+    # Aggregations
+    "Aggregation",
+    "Count",
+    "Sum",
+    "Avg",
+    "Min",
+    "Max",
+    # Types
+    "TableType",
+    "SchemaMode",
+    "FieldType",
+    "EncryptionAlgorithm",
+    # Fields
+    "Encrypted",
+    # Relations
+    "ForeignKey",
+    "ManyToMany",
+    "Relation",
+    "RelationInfo",
+    "get_relation_info",
+    "is_foreign_key",
+    "is_graph_relation",
+    "is_many_to_many",
+    "is_relation_field",
+    # Auth
+    "AuthenticatedUserMixin",
 ]
+
+__version__ = "0.4.0"

surreal_orm/aggregations.py

@@ -0,0 +1,164 @@
+"""
+Aggregation classes for QuerySet GROUP BY operations.
+
+These classes are used with QuerySet.annotate() to compute aggregated values.
+
+Example:
+    from surreal_orm import QuerySet
+    from surreal_orm.aggregations import Count, Sum, Avg
+
+    stats = await Order.objects().values("status").annotate(
+        count=Count(),
+        total=Sum("amount"),
+        avg_amount=Avg("amount"),
+    )
+"""
+
+from abc import ABC, abstractmethod
+
+
+class Aggregation(ABC):
+    """Base class for aggregation functions."""
+
+    @abstractmethod
+    def to_surql(self, alias: str) -> str:
+        """
+        Convert the aggregation to SurrealQL syntax.
+
+        Args:
+            alias: The alias for the result field.
+
+        Returns:
+            str: SurrealQL expression for the aggregation.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def function_name(self) -> str:
+        """Return the SurrealQL function name."""
+        ...
+
+
+class Count(Aggregation):
+    """
+    Count aggregation.
+
+    Counts the number of records in each group.
+
+    Example:
+        Count()  # Counts all records
+    """
+
+    def to_surql(self, alias: str) -> str:
+        return f"count() AS {alias}"
+
+    @property
+    def function_name(self) -> str:
+        return "count"
+
+
+class Sum(Aggregation):
+    """
+    Sum aggregation.
+
+    Calculates the sum of a numeric field.
+
+    Args:
+        field: The field name to sum.
+
+    Example:
+        Sum("amount")  # Sums the "amount" field
+    """
+
+    def __init__(self, field: str):
+        self.field = field
+
+    def to_surql(self, alias: str) -> str:
+        return f"math::sum({self.field}) AS {alias}"
+
+    @property
+    def function_name(self) -> str:
+        return "math::sum"
+
+
+class Avg(Aggregation):
+    """
+    Average aggregation.
+
+    Calculates the average of a numeric field.
+
+    Args:
+        field: The field name to average.
+
+    Example:
+        Avg("age")  # Averages the "age" field
+    """
+
+    def __init__(self, field: str):
+        self.field = field
+
+    def to_surql(self, alias: str) -> str:
+        return f"math::mean({self.field}) AS {alias}"
+
+    @property
+    def function_name(self) -> str:
+        return "math::mean"
+
+
+class Min(Aggregation):
+    """
+    Minimum aggregation.
+
+    Finds the minimum value of a field.
+
+    Args:
+        field: The field name to find minimum of.
+
+    Example:
+        Min("price")  # Finds minimum "price"
+    """
+
+    def __init__(self, field: str):
+        self.field = field
+
+    def to_surql(self, alias: str) -> str:
+        return f"math::min({self.field}) AS {alias}"
+
+    @property
+    def function_name(self) -> str:
+        return "math::min"
+
+
+class Max(Aggregation):
+    """
+    Maximum aggregation.
+
+    Finds the maximum value of a field.
+
+    Args:
+        field: The field name to find maximum of.
+
+    Example:
+        Max("price")  # Finds maximum "price"
+    """
+
+    def __init__(self, field: str):
+        self.field = field
+
+    def to_surql(self, alias: str) -> str:
+        return f"math::max({self.field}) AS {alias}"
+
+    @property
+    def function_name(self) -> str:
+        return "math::max"
+
+
+__all__ = [
+    "Aggregation",
+    "Count",
+    "Sum",
+    "Avg",
+    "Min",
+    "Max",
+]

surreal_orm/auth/__init__.py

@@ -0,0 +1,15 @@
+"""
+Authentication module for SurrealDB ORM.
+
+Provides JWT authentication support using SurrealDB's native
+DEFINE ACCESS ... TYPE RECORD feature.
+"""
+
+from .access import AccessDefinition, AccessGenerator
+from .mixins import AuthenticatedUserMixin
+
+__all__ = [
+    "AccessDefinition",
+    "AccessGenerator",
+    "AuthenticatedUserMixin",
+]

surreal_orm/auth/access.py

@@ -0,0 +1,167 @@
+"""
+Access definition generator for SurrealDB authentication.
+
+Generates DEFINE ACCESS ... TYPE RECORD statements for user authentication
+using SurrealDB's built-in JWT support.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ..types import EncryptionAlgorithm, TableType
+
+if TYPE_CHECKING:
+    from ..model_base import BaseSurrealModel
+
+
+@dataclass
+class AccessDefinition:
+    """
+    Configuration for generating DEFINE ACCESS statements.
+
+    This class represents the authentication configuration for a USER table,
+    including signup/signin logic and token durations.
+
+    Attributes:
+        name: Access definition name (e.g., "user_auth")
+        table: Associated table name
+        identifier_field: Field used for signin (e.g., "email")
+        password_field: Field containing password
+        signup_fields: Dict of field -> expression for signup
+        signin_where: WHERE clause for signin validation
+        duration_token: JWT token lifetime (e.g., "15m")
+        duration_session: Session lifetime (e.g., "12h")
+        algorithm: Password hashing algorithm
+    """
+
+    name: str
+    table: str
+    identifier_field: str = "email"
+    password_field: str = "password"
+    signup_fields: dict[str, str] = field(default_factory=dict)
+    signin_where: str | None = None
+    duration_token: str = "15m"
+    duration_session: str = "12h"
+    algorithm: EncryptionAlgorithm = EncryptionAlgorithm.ARGON2
+
+    def __post_init__(self) -> None:
+        """Build default signin_where if not provided."""
+        if not self.signin_where:
+            self.signin_where = (
+                f"{self.identifier_field} = ${self.identifier_field} AND "
+                f"crypto::{self.algorithm}::compare({self.password_field}, ${self.password_field})"
+            )
+
+    def to_surreal_ql(self) -> str:
+        """
+        Generate the DEFINE ACCESS SurrealQL statement.
+
+        Returns:
+            Complete DEFINE ACCESS statement
+        """
+        # Build signup SET clause
+        signup_sets = ", ".join(f"{field_name} = {expr}" for field_name, expr in self.signup_fields.items())
+
+        return f"""DEFINE ACCESS {self.name} ON DATABASE TYPE RECORD
+    SIGNUP (CREATE {self.table} SET {signup_sets})
+    SIGNIN (SELECT * FROM {self.table} WHERE {self.signin_where})
+    DURATION FOR TOKEN {self.duration_token}, FOR SESSION {self.duration_session};"""
+
+    def to_remove_ql(self) -> str:
+        """
+        Generate the REMOVE ACCESS SurrealQL statement.
+
+        Returns:
+            REMOVE ACCESS statement
+        """
+        return f"REMOVE ACCESS {self.name} ON DATABASE;"
+
+
+class AccessGenerator:
+    """
+    Generates AccessDefinition objects from User models.
+
+    This class inspects USER type models and generates the appropriate
+    DEFINE ACCESS configuration for authentication.
+    """
+
+    @staticmethod
+    def from_model(model: type["BaseSurrealModel"]) -> AccessDefinition | None:
+        """
+        Generate AccessDefinition from a model.
+
+        Only generates for USER type tables.
+
+        Args:
+            model: The model class to generate access for
+
+        Returns:
+            AccessDefinition if model is USER type, None otherwise
+        """
+        # Check if this is a USER table
+        table_type = model.get_table_type()
+        if table_type != TableType.USER:
+            return None
+
+        table_name = model.get_table_name()
+        identifier_field = model.get_identifier_field()
+        password_field = model.get_password_field()
+
+        # Get algorithm from config or default
+        config = getattr(model, "model_config", {})
+        algorithm_str = config.get("encryption_algorithm", "argon2")
+        try:
+            algorithm = EncryptionAlgorithm(algorithm_str)
+        except ValueError:
+            algorithm = EncryptionAlgorithm.ARGON2
+
+        # Build signup fields from model fields
+        signup_fields: dict[str, str] = {}
+
+        for field_name in model.model_fields:
+            if field_name == "id":
+                continue
+
+            if field_name == password_field:
+                # Password gets encrypted
+                signup_fields[field_name] = f"crypto::{algorithm}::generate(${field_name})"
+            else:
+                # Regular fields are passed through
+                signup_fields[field_name] = f"${field_name}"
+
+        # Add created_at if not in model
+        if "created_at" not in signup_fields:
+            signup_fields["created_at"] = "time::now()"
+
+        # Get durations from config
+        token_duration = config.get("token_duration", "15m")
+        session_duration = config.get("session_duration", "12h")
+
+        return AccessDefinition(
+            name=f"{table_name.lower()}_auth",
+            table=table_name,
+            identifier_field=identifier_field,
+            password_field=password_field,
+            signup_fields=signup_fields,
+            duration_token=token_duration,
+            duration_session=session_duration,
+            algorithm=algorithm,
+        )
+
+    @staticmethod
+    def generate_all(models: list[type["BaseSurrealModel"]]) -> list[AccessDefinition]:
+        """
+        Generate AccessDefinitions for all USER type models.
+
+        Args:
+            models: List of model classes
+
+        Returns:
+            List of AccessDefinition objects for USER tables
+        """
+        definitions = []
+        for model in models:
+            definition = AccessGenerator.from_model(model)
+            if definition:
+                definitions.append(definition)
+        return definitions