async-orm-kit 1.0.0__py3-none-any.whl

async_orm_kit/models/fields/typed/string.py

@@ -0,0 +1,38 @@
+from sqlalchemy import String
+
+from async_orm_kit.models.fields.typed.base import BaseValidatedType, ValidatorType
+from async_orm_kit.models.fields.validators import (
+    MaxLengthValidator,
+    MinLengthValidator,
+)
+
+
+class StringField(BaseValidatedType):
+    cache_ok = True
+    impl = String
+
+    def __init__(
+        self,
+        max_length: int | None = None,
+        min_length: int | None = None,
+        validators: list[ValidatorType] | None = None,
+        **kwargs,
+    ):
+        self.min_length = min_length
+        self.max_length = max_length
+
+        v: list[ValidatorType] = list(validators or [])
+
+        if max_length is not None:
+            v.append(MaxLengthValidator(max_length))
+
+        if min_length is not None:
+            v.append(MinLengthValidator(min_length))
+
+        super().__init__(validators=v, **kwargs)
+
+    def load_dialect_impl(self, dialect):
+        """Build the dialect string type with the configured maximum length."""
+        if self.max_length:
+            return dialect.type_descriptor(String(self.max_length))
+        return dialect.type_descriptor(String())

async_orm_kit/models/fields/validators.py

@@ -0,0 +1,110 @@
+import re
+from typing import Any
+
+from async_orm_kit.models.fields.exceptions import FieldValidationError
+
+
+class FieldValidator:
+    def __call__(self, value: Any) -> None:
+        """
+        Base validator interface.
+
+        Contract:
+          - Do nothing if `value` is valid.
+          - Raise FieldValidationError (or subclass) if invalid.
+          - Does NOT return or transform the value.
+        """
+        return None
+
+
+class MaxLengthValidator(FieldValidator):
+    def __init__(self, limit: int):
+        self.limit = limit
+
+    def __call__(self, value) -> None:
+        if value is None:
+            return
+        try:
+            length = len(value)
+        except TypeError:
+            raise FieldValidationError(
+                f"Ensure this value has at most {self.limit} characters "
+                f"(it has a non-measurable length).",
+                code="max_length",
+            ) from None
+        if length > self.limit:
+            raise FieldValidationError(
+                f"Ensure this value has at most {self.limit} characters "
+                f"(it has {length}).",
+                code="max_length",
+            )
+
+
+class MinLengthValidator(FieldValidator):
+    def __init__(self, limit: int):
+        self.limit = limit
+
+    def __call__(self, value) -> None:
+        if value is None:
+            return
+        try:
+            length = len(value)
+        except TypeError:
+            raise FieldValidationError(
+                f"Ensure this value has at least {self.limit} characters "
+                f"(it has a non-measurable length).",
+                code="min_length",
+            ) from None
+        if length < self.limit:
+            raise FieldValidationError(
+                f"Ensure this value has at least {self.limit} characters "
+                f"(it has {length}).",
+                code="min_length",
+            )
+
+
+class RangeValidator(FieldValidator):
+    def __init__(self, *, min: int | None = None, max: int | None = None):
+        self.min = min
+        self.max = max
+
+    def __call__(self, value) -> None:
+        if value is None:
+            return
+
+        # Non-numeric or non-orderable values
+        try:
+            _ = value < value  # just to trigger TypeError for non-comparables
+        except TypeError:
+            raise FieldValidationError(
+                "Ensure this value is a comparable numeric-type.",
+                code="invalid_type",
+            ) from None
+
+        if self.min is not None and value < self.min:
+            raise FieldValidationError(
+                f"Ensure this value is greater than or equal to {self.min} "
+                f"(it is {value}).",
+                code="min_value",
+            )
+        if self.max is not None and value > self.max:
+            raise FieldValidationError(
+                f"Ensure this value is less than or equal to {self.max} "
+                f"(it is {value}).",
+                code="max_value",
+            )
+
+
+class Regex(FieldValidator):
+    def __init__(self, pattern: str | re.Pattern, message: str = "Invalid format"):
+        self.pattern = re.compile(pattern) if isinstance(pattern, str) else pattern
+        self.message = message
+
+    def __call__(self, value) -> None:
+        if value is None:
+            return
+        if not self.pattern.match(value):
+            raise FieldValidationError(
+                self.message,
+                code="regex",
+            )

async_orm_kit/models/meta.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import DeclarativeBase
+
+from async_orm_kit._logging import get_logger
+from async_orm_kit.exceptions import MultipleObjectsReturned, ObjectDoesNotExist
+from async_orm_kit.manager import Manager
+from async_orm_kit.models.fields.typed.base import BaseValidatedType
+
+logger = get_logger(__name__)
+
+
+class Base(DeclarativeBase):
+    """SQLAlchemy declarative base for all ORM models.
+    Provides the foundation for all model classes in the framework.
+    Models should inherit from ``Model`` rather than using this directly.
+    """
+
+    pass
+
+
+class ModelMeta(type(Base)):  # type: ignore[misc]  # SQLAlchemy supplies the declarative metaclass dynamically.
+    """Metaclass for automatic manager registration and model initialization.
+
+    Handles the setup of managers with observers and model-specific exceptions
+    during class creation. Automatically discovers managers from the class
+    hierarchy, creates model-specific exception classes, and registers observers.
+
+    Responsibilities:
+        - Create model-specific ``DoesNotExist`` and ``MultipleObjectsReturned``
+          exception classes for each model
+        - Discover and register Manager instances with their observers from class and parent classes
+        - Add default ``objects`` manager if no managers are defined
+        - Collect and register model and queryset observers from class hierarchy
+        - Call ``contribute_to_class()`` on each manager to bind it to the model
+
+    Class Attributes Created:
+        DoesNotExist: Model-specific exception for missing objects.
+        MultipleObjectsReturned: Model-specific exception for ambiguous queries.
+        _managers: List of manager attribute names on this model.
+        _default_manager: The default manager instance (typically ``objects``).
+        _model_observers: List of registered model lifecycle observers.
+
+    Example:
+        >>> class User(Model):  # Uses ModelMeta automatically
+        ...     id: Mapped[int] = mapped_column(primary_key=True)
+        ...     username: Mapped[str]
+        ...
+        ...     # Custom manager
+        ...     active = ActiveUserManager()
+        >>>
+        >>> # Model-specific exceptions created automatically
+        >>> try:
+        ...     await User.objects.get(id=999)
+        ... except User.DoesNotExist:
+        ...     print("User not found")
+        >>>
+        >>> # Managers registered and accessible
+        >>> User._managers
+        ['objects', 'active']
+        >>> User._default_manager
+        <Manager for User>
+
+    Note:
+        This metaclass is applied automatically when inheriting from ``Model``.
+        Abstract models (``__abstract__ = True``) skip manager registration.
+    """
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ) -> type:
+        """Create and initialize a new model class.
+
+        Args:
+            name: Name of the class being created.
+            bases: Tuple of base classes.
+            namespace: Class namespace dictionary containing attributes and methods.
+            **kwargs: Additional keyword arguments passed to parent metaclass.
+
+        Returns:
+            Newly created and initialized model class with managers and
+            exceptions registered.
+        """
+        # Create the class
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+
+        # Skip for abstract base classes
+        if namespace.get("__abstract__", False):
+            return cls
+
+        # Create model-specific exceptions
+        cls.DoesNotExist = type(
+            f"{name}.DoesNotExist",
+            (ObjectDoesNotExist,),
+            {"__module__": cls.__module__},
+        )
+
+        cls.MultipleObjectsReturned = type(
+            f"{name}.MultipleObjectsReturned",
+            (MultipleObjectsReturned,),
+            {"__module__": cls.__module__},
+        )
+
+        cls._model_field_types = {}  # {field_name: field_instance}
+        cls._file_fields = {}
+        if hasattr(cls, "__table__"):
+            for column in cls.__table__.columns:
+                if isinstance(column.type, BaseValidatedType):
+                    attr_name = column.key
+                    attr = getattr(cls, attr_name)
+                    column.type.contribute_to_class(cls, attr_name, attr)
+
+        # Collect inherited managers and observers in MRO order. Managers must
+        # be cloned for each concrete model because they hold a model binding and
+        # mutable hooks/observer registries.
+        inherited_managers: dict[str, Manager] = {}
+        observers: list[Any] = []
+        queryset_observers: list[Any] = []
+
+        def append_unique(target: list[Any], values: Any) -> None:
+            for value in values or ():
+                if all(existing is not value for existing in target):
+                    target.append(value)
+
+        # Resolve manager attributes using normal Python MRO precedence. A
+        # nearer non-manager attribute intentionally shadows a base manager.
+        seen_attributes: set[str] = set()
+        for base in cls.__mro__[1:]:
+            for attr_name, attr_value in base.__dict__.items():
+                if attr_name in seen_attributes:
+                    continue
+                seen_attributes.add(attr_name)
+                if isinstance(attr_value, Manager):
+                    inherited_managers[attr_name] = attr_value
+
+        # Observer registration order is base-to-derived and stable. Identity
+        # de-duplication avoids requiring observer instances to be hashable.
+        for base in reversed(cls.__mro__[1:]):
+            append_unique(observers, base.__dict__.get("model_observers", ()))
+            append_unique(
+                queryset_observers,
+                base.__dict__.get("queryset_observers", ()),
+            )
+
+        managers: dict[str, Manager] = {
+            name: manager.clone_for_model()
+            for name, manager in inherited_managers.items()
+        }
+
+        # Explicit managers on this class override inherited managers.
+        for attr_name, attr_value in namespace.items():
+            if isinstance(attr_value, Manager):
+                managers[attr_name] = attr_value
+
+        append_unique(observers, namespace.get("model_observers", ()))
+        append_unique(queryset_observers, namespace.get("queryset_observers", ()))
+
+        # Add a fresh default manager when no manager is inherited or declared.
+        if not managers:
+            managers["objects"] = Manager()
+
+        # Bind every manager to this model and give it an independent observer list.
+        for manager_name, manager in managers.items():
+            manager._observers = list(manager._observers)
+            append_unique(manager._observers, queryset_observers)
+            manager.contribute_to_class(cls, manager_name)
+
+        cls._managers = list(managers)
+        cls._default_manager = managers.get("objects") or next(
+            iter(managers.values()), None
+        )
+        cls._model_observers = observers
+        cls._queryset_observers = queryset_observers
+
+        return cls

async_orm_kit/models/mixins.py

@@ -0,0 +1,19 @@
+from typing import ClassVar
+
+from async_orm_kit.observers import BaseModelObserver, BaseQuerySetObserver
+from async_orm_kit.observers.mixin import ObserverMixin
+
+
+class ModelObserverMixin(ObserverMixin):
+    """Mixin to add observer support to Model"""
+
+    model_observers: ClassVar[list[BaseModelObserver]] = []
+    _model_observers: ClassVar[list[BaseModelObserver]] = []
+    queryset_observers: ClassVar[list[BaseQuerySetObserver]] = []
+    _queryset_observers: ClassVar[list[BaseQuerySetObserver]] = []
+
+    async def _trigger_model_observers(self, event: str, **kwargs) -> None:
+        """Trigger model-level observers"""
+        await self._trigger_observers(
+            self._model_observers, event, instance=self, **kwargs
+        )

async_orm_kit/observers/__init__.py

@@ -0,0 +1,4 @@
+from .model_observer import BaseModelObserver
+from .queryset_observer import BaseQuerySetObserver
+
+__all__ = ["BaseModelObserver", "BaseQuerySetObserver"]

async_orm_kit/observers/mixin.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterable
+from typing import Any
+
+
+class ObserverMixin:
+    """Shared, deterministic dispatcher for model and QuerySet observers."""
+
+    async def _trigger_observers(
+        self, observers: Iterable[Any], event: str, **kwargs: Any
+    ) -> None:
+        """Invoke observers in registration order.
+
+        Both synchronous and asynchronous handlers are supported. Exceptions are
+        intentionally propagated to the caller; observer failures must never be
+        hidden in untracked background tasks.
+        """
+        for observer in observers:
+            handler = getattr(observer, event, None)
+            if handler is None:
+                continue
+            result = handler(**kwargs)
+            if inspect.isawaitable(result):
+                await result

async_orm_kit/observers/model_observer.py

@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from async_orm_kit.models import Model
+
+
+class BaseModelObserver:
+    """Base observer for single model instance lifecycle"""
+
+    async def pre_save(self, instance: "Model", **kwargs) -> None:
+        pass
+
+    async def post_save(self, instance: "Model", created: bool, **kwargs) -> None:
+        pass
+
+    async def pre_delete(self, instance: "Model", **kwargs) -> None:
+        pass
+
+    async def post_delete(self, instance: "Model", **kwargs) -> None:
+        pass

async_orm_kit/observers/queryset_observer.py

@@ -0,0 +1,38 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from async_orm_kit.queryset.queryset import QuerySet
+
+
+class BaseQuerySetObserver:
+    """Base observer for queryset operations"""
+
+    async def pre_stream(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def post_stream(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def pre_execute(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def post_execute(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def pre_bulk_create(self, **kwargs) -> None:
+        pass
+
+    async def post_bulk_create(self, **kwargs) -> None:
+        pass
+
+    async def pre_bulk_update(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def post_bulk_update(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def pre_bulk_delete(self, queryset: "QuerySet", **kwargs) -> None:
+        pass
+
+    async def post_bulk_delete(self, queryset: "QuerySet", **kwargs) -> None:
+        pass

async_orm_kit/query/aggregations/__init__.py

@@ -0,0 +1,8 @@
+from .avg import Avg
+from .base import Aggregate, AggregateFunction
+from .count import Count
+from .max import Max
+from .min import Min
+from .sum import Sum
+
+__all__ = ["Avg", "Aggregate", "AggregateFunction", "Count", "Max", "Min", "Sum"]

async_orm_kit/query/aggregations/avg.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ColumnElement, func
+
+from async_orm_kit.query.aggregations.base import Aggregate
+from async_orm_kit.query.lookups.resolver import ResolverContext
+
+if TYPE_CHECKING:
+    from async_orm_kit.query.lookups.resolver import FieldResolver
+
+
+class Avg(Aggregate):
+    """Calculate average (mean) of numeric field values across grouped rows.
+
+    Generates SQL AVG() aggregate function for computing arithmetic mean of field
+    values. Supports DISTINCT modifier to average only unique values. Commonly used
+    with QuerySet.annotate() for per-group averages or QuerySet.aggregate() for
+    overall dataset average.
+
+    Handles NULL values per SQL standard: NULLs are excluded from calculation, and
+    AVG of all-NULL column returns NULL. Works with numeric types (integers, decimals,
+    floats) and may return decimal results even for integer inputs depending on
+    database dialect.
+
+    Args:
+        field: Field to average. Accepts str column name, F() expression for computed
+              averages, Value() for literals, or Case() for conditional averaging.
+        distinct: Whether to average only distinct values. Useful for deduplicating
+                 before averaging. Defaults to False.
+        **extra: Additional arguments like output_field for type coercion.
+
+    Returns:Decimal or float representing average value, or None if no non-NULL values.
+
+    Note:
+        Performance: AVG requires scanning all rows in group. On large datasets,
+        ensure grouped columns are indexed. DISTINCT adds deduplication overhead.
+
+        Database differences: PostgreSQL returns numeric type, MySQL returns double.
+        Use output_field parameter for consistent type handling across databases.
+
+        NULL handling: AVG(NULL, NULL, NULL) returns NULL, not 0. Use COALESCE or
+        Case() with default=Value(0) if you need zero for empty groups.
+    """
+
+    def resolve(
+        self,
+        field_resolver: FieldResolver,
+        context: ResolverContext = ResolverContext(),
+    ) -> ColumnElement:
+        """Resolve to SQLAlchemy AVG() function expression.
+
+        Args:
+            field_resolver: FieldResolver for column resolution and join tracking.
+            context: ResolverContext for OR context and filter marking propagation.
+
+        Returns:
+            SQLAlchemy func.avg() expression with optional DISTINCT modifier.
+
+        Example:
+            >>> # Generates: AVG(orders.amount)
+            >>> Avg("amount").resolve(field_resolver, context)
+            >>>
+            >>> # Generates: AVG(DISTINCT orders.amount)
+            >>> Avg("amount", distinct=True).resolve(field_resolver, context)
+        """
+        col = self._resolve_column(field_resolver=field_resolver, context=context)
+        return self._finish(
+            func.avg(self._prepare_column(col, field_resolver, context))
+        )