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

async_orm_kit/queryset/state.py

@@ -0,0 +1,164 @@
+import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class QueryState:
+    """Immutable snapshot of QuerySet configuration state.
+
+    Encapsulates all query parameters and transformations applied to a QuerySet.
+    Designed for efficient cloning to support QuerySet's immutable chain pattern.
+    Each QuerySet operation clones the state, modifies the clone, and returns a
+    new QuerySet with the updated state.
+
+    This separation of state from behavior enables:
+    - QuerySet immutability (operations return new instances)
+    - Efficient query building without side effects
+    - Easy state inspection and debugging
+    - Clean separation between query construction and execution
+
+    Attributes:
+        model: The SQLAlchemy model class this query operates on.
+        filters: List of filter conditions (WHERE clauses).
+        order_by: List of ordering expressions (ORDER BY clauses).
+        limit_val: Maximum number of rows to return (LIMIT).
+        offset_val: Number of rows to skip (OFFSET).
+        is_distinct: Whether to apply DISTINCT to remove duplicates.
+        distinct_on: Fields for DISTINCT ON (PostgreSQL only).
+        group_by_fields: Fields for GROUP BY aggregation.
+        having_conditions: Conditions for HAVING clause (post-aggregation filters).
+        annotations: Computed fields added via annotate() (e.g., aggregates, expressions).
+        annotation_paths: Relationship paths for each annotation field.
+        has_aggregates: Whether query contains aggregate functions (Count, Sum, etc.).
+        select_related: Relationships to JOIN and load eagerly (1-to-1, many-to-1).
+        prefetch_related: Relationships to load in separate queries (1-to-many, many-to-many).
+        values_select: Fields to project as dicts (values() mode).
+        values_list_select: Fields to project as tuples (values_list() mode).
+        values_list_flat: Whether to flatten single-field values_list() results.
+        only_fields: Fields to load immediately (deferred loading mode).
+        join_graph: Internal join planning structure for relationship traversal.
+
+    Example:
+        >>> # QueryState is internal - users interact via QuerySet
+        >>> from your_app.models import DBUser
+        >>> qs = DBUser.objects.filter(active=True).order_by("-created_at")
+        >>>
+        >>> # Inspect internal state (debugging)
+        >>> state = qs._state
+        >>> print(state.model)  # <class 'User'>
+        >>> print(state.filters)  # [BinaryExpression(...)]
+        >>> print(state.order_by)  # [UnaryExpression(...)]
+        >>>
+        >>> # State is cloned on each operation
+        >>> qs2 = qs.limit(10)
+        >>> assert qs._state is not qs2._state  # Different objects
+        >>> assert qs._state.limit_val is None  # Original unchanged
+        >>> assert qs2._state.limit_val == 10  # Clone modified
+    Note:
+        Performance: Uses __slots__ for memory efficiency. Cloning is O(n) where
+        n is the number of filters/annotations, but typically very fast since
+        most lists are small. Deep copying is avoided - lists are shallow copied
+        and their contents (SQLAlchemy expressions) are reused.
+    """
+
+    model: type
+    filters: list[Any] = field(default_factory=list)
+    order_by: list[Any] = field(default_factory=list)
+    limit_val: int | None = None
+    offset_val: int | None = None
+    is_distinct: bool = False
+    distinct_on: list[Any] = field(default_factory=list)
+    group_by_fields: list[Any] = field(default_factory=list)
+    having_conditions: list[Any] = field(default_factory=list)
+    annotations: dict[str, Any] = field(default_factory=dict)
+    annotation_paths: dict[str, list[str]] = field(default_factory=dict)
+    has_aggregates: bool = False
+    for_update: dict[str, Any] | None = None
+    select_related: list[str] = field(default_factory=list)
+    prefetch_related: list[str] = field(default_factory=list)
+    values_select: list[tuple[str, Any]] | None = None
+    values_list_select: list[tuple[str, Any]] | None = None
+    values_list_flat: bool = False
+    only_fields: list[Any] | None = None
+    deferred_fields: list[str] = field(default_factory=list)
+    custom_lookups: dict[str, Any] = field(default_factory=dict)
+    ordering_fields: list[str] = field(default_factory=list)
+    seek_active: bool = False
+    join_graph: Any = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Create the empty join graph required by every compiler execution path."""
+        from async_orm_kit.query.relations.graph import JoinGraph
+
+        self.join_graph = JoinGraph(self.model)
+
+    def clone(self) -> "QueryState":
+        """Create a shallow copy of this state for immutable query chaining.
+
+        Clones the QueryState to enable QuerySet's immutable pattern where each
+        operation returns a new QuerySet without modifying the original. Uses
+        shallow copying for efficiency - list contents (SQLAlchemy expressions)
+        are reused, not deep copied.
+
+        Returns:
+            New QueryState instance with copied lists and same scalar values.
+
+        Example:
+            >>> state = QueryState(model=User)
+            >>> state.filters.append(some_condition)
+            >>>
+            >>> cloned = state.clone()
+            >>> cloned.filters.append(another_condition)
+            >>>
+            >>> len(state.filters)  # 1 - original unchanged
+            >>> len(cloned.filters)  # 2 - clone modified
+            >>>
+            >>> # Scalar values are copied
+            >>> cloned.limit_val = 10
+            >>> assert state.limit_val is None
+
+        Note:
+            Performance: O(n) where n is total items across all lists. Typically
+            very fast since most queries have few filters/annotations. Uses
+            shallow copy - SQLAlchemy expression objects are reused, not cloned.
+            JoinGraph is deep cloned if present to maintain isolation.
+        """
+        new_state = copy.copy(self)
+        new_state.filters = self.filters.copy()
+        new_state.order_by = self.order_by.copy()
+        new_state.is_distinct = self.is_distinct
+        new_state.distinct_on = self.distinct_on.copy()
+        new_state.annotations = self.annotations.copy()
+        new_state.annotation_paths = {
+            name: paths.copy() for name, paths in self.annotation_paths.items()
+        }
+        new_state.has_aggregates = self.has_aggregates
+        new_state.for_update = (
+            self.for_update.copy() if self.for_update is not None else None
+        )
+        new_state.select_related = self.select_related.copy()
+        new_state.prefetch_related = self.prefetch_related.copy()
+        new_state.group_by_fields = self.group_by_fields.copy()
+        new_state.having_conditions = self.having_conditions.copy()
+        new_state.only_fields = (
+            self.only_fields.copy() if self.only_fields is not None else None
+        )
+        new_state.values_select = (
+            self.values_select.copy() if self.values_select is not None else None
+        )
+        new_state.values_list_select = (
+            self.values_list_select.copy()
+            if self.values_list_select is not None
+            else None
+        )
+        new_state.values_list_flat = self.values_list_flat
+        new_state.deferred_fields = self.deferred_fields.copy()
+        new_state.custom_lookups = self.custom_lookups.copy()
+        new_state.ordering_fields = self.ordering_fields.copy()
+        new_state.seek_active = self.seek_active
+
+        # Clone join graph and planner
+        new_state.join_graph = self.join_graph.clone()
+
+        return new_state

async_orm_kit/queryset/validators.py

@@ -0,0 +1,361 @@
+from async_orm_kit.exceptions import QueryStateError
+from async_orm_kit.queryset.state import QueryState
+
+
+class QuerySetValidator:
+    """Validates QuerySet method calls and state transitions for correctness.
+
+    Enforces Django-style ORM constraints by validating that QuerySet methods are
+    called in compatible combinations. Prevents invalid state transitions like calling
+    select_related() after values() (which returns dicts, not model instances), or
+    using HAVING without aggregates. Follows Single Responsibility Principle by
+    separating validation logic from QuerySet's query building responsibilities.
+
+    Attributes:
+        _state: QueryState instance containing current query configuration to validate.
+    Example:
+        >>> # QuerySetValidator is internal - users see validation errors via QuerySet
+        >>> from your_app.models import DBUser
+        >>>
+        >>> # Invalid: select_related after values
+        >>> try:
+        ...     DBUser.objects.values("username").select_related("profile")
+        ... except QueryStateError as e:
+        ...     print(e)  # "Cannot call select_related() after values()..."
+        >>>
+        >>> # Invalid: order_by field not in values selection
+        >>> try:
+        ...     User.objects.values("username").order_by("email")
+        ... except QueryStateError as e:
+        ...     print(e)  # "Cannot order by 'email' - not in values() selection..."
+        >>>
+        >>> # Invalid: having without aggregates
+        >>> try:
+        ...     User.objects.having(count__gte=5)
+        ... except QueryStateError as e:
+        ...     print(e)  # "having() requires at least one aggregate annotation..."
+    Note:
+        Performance: All validations are O(1) or O(n) where n is number of fields,
+        executed in-memory before database queries. Validation overhead is negligible
+        compared to query execution time.
+    """
+
+    __slots__ = ("_state",)
+
+    def __init__(self, state: QueryState):
+        """Initialize validator with QueryState to validate.
+
+        Args:
+            state: QueryState instance containing query configuration to validate.
+        """
+        self._state = state
+
+    def validate_requires_model_instances(self, method_name: str) -> None:
+        """Validate that QuerySet returns model instances, not dicts or tuples.
+
+        Methods like select_related(), prefetch_related(), and only() operate on
+        model instances by loading related objects or deferring fields. These methods
+        are incompatible with values() and values_list() which return dictionaries
+        and tuples respectively. This validation prevents nonsensical combinations
+        like trying to eager-load relationships on dictionary results.
+
+        Args:
+            method_name: Name of method being called (for error message).
+
+        Raises:
+            QueryStateError: If values() or values_list() was called before this method,
+                           making the operation invalid.
+
+        Example:
+            >>> # Valid: select_related on model instances
+            >>> User.objects.select_related("profile").all()
+            >>>
+            >>> # Invalid: select_related after values
+            >>> User.objects.values("username").select_related("profile")
+            >>> # Raises: QueryStateError("Cannot call select_related() after values()...")
+            >>>
+            >>> # Invalid: only after values_list
+            >>> User.objects.values_list("id").only("username")
+            >>> # Raises: QueryStateError("Cannot call only() after values_list()...")
+        Note:
+            Performance: O(1) - simple attribute checks. Called before query building,
+            preventing invalid queries from reaching the database.
+        """
+        if self._state.values_select is not None:
+            raise QueryStateError(
+                f"Cannot call {method_name}() after values(). "
+                f"values() returns dictionaries, not model instances."
+            )
+        if self._state.values_list_select is not None:
+            raise QueryStateError(
+                f"Cannot call {method_name}() after values_list(). "
+                f"values_list() returns tuples, not model instances."
+            )
+
+    def validate_not_deferred_loading(self, method_name: str) -> None:
+        """Validate that deferred loading (only) is not active.
+
+        The only() method implements deferred loading by selecting specific fields
+        and deferring others. Methods like values() and values_list() have their own
+        field selection semantics that conflict with only()'s approach. This validation
+        prevents combining these incompatible field selection strategies.
+
+        Args:
+            method_name: Name of method being called (for error message).
+
+        Raises:
+            QueryStateError: If only() was called before this method, creating
+                           conflicting field selection semantics.
+
+        Example:
+            >>> # Valid: values without only
+            >>> User.objects.values("username", "email")
+            >>>
+            >>> # Invalid: values after only
+            >>> User.objects.only("username").values("email")
+            >>> # Raises: QueryStateError("Cannot call values() after only()...")
+            >>>
+            >>> # Invalid: values_list after only
+            >>> User.objects.only("id", "username").values_list("email")
+            >>> # Raises: QueryStateError("Cannot call values_list() after only()...")
+
+        Note:
+            Performance: O(1) - simple boolean check on only_fields set. Prevents
+            ambiguous field selection before query compilation.
+        """
+        if self._state.only_fields or self._state.deferred_fields:
+            method = "only" if self._state.only_fields else "defer"
+            raise QueryStateError(
+                f"Cannot call {method_name}() after {method}(). "
+                "These methods have conflicting field selection semantics."
+            )
+
+    def validate_order_by_fields(self, fields: tuple) -> None:
+        """Validate that order_by fields exist in current selection mode.
+
+        When using values() or values_list() to project specific fields, ORDER BY
+        can only reference fields that are in the SELECT clause or are annotations.
+        This is a SQL requirement - you cannot order by fields that aren't selected.
+        When returning model instances (no values/values_list), all model fields are
+        available for ordering.
+
+        Args:
+            fields: Tuple of field names to order by. May include "-" prefix for
+                   descending order (e.g., "-created_at").
+
+        Raises:
+            QueryStateError: If any order_by field is not in the values/values_list
+                           selection or annotations, making the SQL query invalid.
+
+        Example:
+            >>> # Valid: order by selected field
+            >>> User.objects.values("username", "email").order_by("username")
+            >>>
+            >>> # Valid: order by annotation
+            >>> User.objects.values("username").annotate(
+            ...     post_count=Count("posts")
+            ... ).order_by("post_count")
+            >>>
+            >>> # Invalid: order by non-selected field
+            >>> User.objects.values("username").order_by("email")
+            >>> # Raises: QueryStateError("Cannot order by 'email' - not in values() selection...")
+            >>>
+            >>> # Valid: descending order with prefix
+            >>> User.objects.values("username", "created_at").order_by("-created_at")
+
+        Note:
+            Performance: O(n*m) where n is number of order_by fields and m is number
+            of selected fields. Typically small numbers, negligible overhead. Strips
+            "-" prefix for descending order before validation.
+        """
+        if self._state.values_select is None and self._state.values_list_select is None:
+            return  # No restriction when returning model instances
+
+        selected_fields = self._get_selected_fields()
+        annotation_names = set(self._state.annotations.keys())
+        allowed_fields = selected_fields | annotation_names
+
+        for field in fields:
+            if not isinstance(field, str):
+                raise QueryStateError(
+                    "Expression-based ordering is only supported when returning "
+                    "model instances; annotate the expression and select its alias "
+                    "when using values() or values_list()."
+                )
+            if not field or field == "-" or field.startswith("--"):
+                raise QueryStateError(f"Invalid order_by field {field!r}.")
+            field_name = field[1:] if field.startswith("-") else field
+            if field_name not in allowed_fields:
+                mode = (
+                    "values()"
+                    if self._state.values_select is not None
+                    else "values_list()"
+                )
+                raise QueryStateError(
+                    f"Cannot order by '{field_name}' - not in {mode} selection. "
+                    f"Available fields: {sorted(allowed_fields)}"
+                )
+
+    def validate_distinct_fields(self, fields: tuple) -> None:
+        """Validate that DISTINCT ON fields exist in current selection mode.
+
+        PostgreSQL's DISTINCT ON requires that distinct fields appear in the SELECT
+        clause. When using values() or values_list() to project specific fields,
+        DISTINCT ON can only reference those selected fields. Plain DISTINCT (without
+        fields) is always valid. When returning model instances, all fields are available.
+
+        Args:
+            fields: Tuple of field names for DISTINCT ON. Empty tuple means plain
+                   DISTINCT (no field-specific deduplication).
+
+        Raises:
+            QueryStateError: If any DISTINCT ON field is not in the values/values_list
+                           selection, making the PostgreSQL query invalid.
+
+        Example:
+            >>> # Valid: plain DISTINCT
+            >>> User.objects.values("username").distinct()
+            >>>
+            >>> # Valid: DISTINCT ON selected field
+            >>> User.objects.values("username", "email").distinct("username")
+            >>>
+            >>> # Invalid: DISTINCT ON non-selected field
+            >>> User.objects.values("username").distinct("email")
+            >>> # Raises: QueryStateError("distinct() field 'email' must be in values() selection...")
+            >>>
+            >>> # Valid: DISTINCT ON with model instances
+            >>> User.objects.distinct("username")  # All fields available
+
+        Note:
+            Performance: O(n*m) where n is number of distinct fields and m is number
+            of selected fields. Empty fields tuple (plain DISTINCT) returns immediately.
+            PostgreSQL-specific feature - other databases may not support DISTINCT ON.
+        """
+        if not fields:
+            return  # DISTINCT without fields is always valid
+
+        if self._state.values_select is None and self._state.values_list_select is None:
+            return  # No restriction when returning model instances
+
+        selected_fields = self._get_selected_fields()
+
+        for field in fields:
+            if field not in selected_fields:
+                mode = "values()" if self._state.values_select else "values_list()"
+                raise QueryStateError(
+                    f"distinct() field '{field}' must be in {mode} selection. "
+                    f"Available: {sorted(selected_fields)}"
+                )
+
+    def validate_values_list_flat(self, fields: tuple, flat: bool) -> None:
+        """Validate that flat parameter is used correctly with values_list.
+
+        The flat=True parameter flattens values_list results from list of tuples to
+        list of scalar values. This only makes sense when selecting exactly one field,
+        as multiple fields cannot be flattened to scalars. This validation prevents
+        ambiguous flattening like trying to flatten (id, username) tuples.
+
+        Args:
+            fields: Tuple of field names being selected.
+            flat: Whether to flatten results to scalar values.
+
+        Raises:
+            QueryStateError: If flat=True with multiple fields, creating ambiguous
+                           flattening behavior.
+
+        Example:
+            >>> # Valid: flat with single field
+            >>> ids = User.objects.values_list("id", flat=True)
+            >>> # Returns: [1, 2, 3] instead of [(1,), (2,), (3,)]
+            >>>
+            >>> # Valid: flat=False with multiple fields
+            >>> pairs = User.objects.values_list("id", "username", flat=False)
+            >>> # Returns: [(1, "alice"), (2, "bob")]
+            >>>
+            >>> # Invalid: flat with multiple fields
+            >>> User.objects.values_list("id", "username", flat=True)
+            >>> # Raises: QueryStateError("values_list() with flat=True requires exactly one field...")
+
+        Note:
+            Performance: O(1) - simple length check. Called before query execution
+            to prevent invalid result transformation.
+        """
+        if type(flat) is not bool:
+            raise TypeError("flat must be a bool.")
+        if flat and len(fields) != 1:
+            raise QueryStateError(
+                "values_list() with flat=True requires exactly one field, "
+                f"got {len(fields)} fields"
+            )
+
+    def validate_having_requires_aggregates(self) -> None:
+        """Validate that HAVING clause is used with aggregate functions.
+
+        SQL's HAVING clause filters grouped results after aggregation, requiring a
+        GROUP BY clause (created by aggregates). Using HAVING without aggregates is
+        semantically incorrect - use WHERE/filter() instead for row-level filtering.
+        This validation enforces Django-style ORM behavior where HAVING only makes
+        sense with annotate() containing aggregate functions like Count, Sum, Avg.
+
+        Raises:
+            QueryStateError: If having() is called without any aggregate annotations,
+                           making the HAVING clause semantically invalid.
+
+        Example:
+            >>> # Valid: having with aggregates
+            >>> User.objects.annotate(
+            ...     post_count=Count("posts")
+            ... ).having(post_count__gte=5)
+            >>>
+            >>> # Valid: multiple aggregates
+            >>> User.objects.annotate(
+            ...     total_views=Sum("posts__views"),
+            ...     avg_rating=Avg("posts__rating")
+            ... ).having(total_views__gte=1000, avg_rating__gte=4.0)
+            >>>
+            >>> # Invalid: having without aggregates
+            >>> User.objects.having(username__startswith="a")
+            >>> # Raises: QueryStateError("having() requires at least one aggregate annotation...")
+            >>>
+            >>> # Invalid: having with non-aggregate annotation
+            >>> User.objects.annotate(
+            ...     full_name=Concat("first_name", Value(" "), "last_name")
+            ... ).having(full_name__icontains="smith")
+            >>> # Raises: QueryStateError (no aggregates, so no GROUP BY)
+
+        Note:
+            Performance: O(1) - simple boolean check on has_aggregates flag. Prevents
+            invalid SQL generation before query compilation. Use filter() instead of
+            having() for row-level filtering without aggregates.
+        """
+        if not self._state.has_aggregates:
+            raise QueryStateError(
+                "having() requires at least one aggregate annotation. "
+                "Call .annotate(total=Sum('amount')) before .having(total__gte=100). "
+                f"Current annotations: {list(self._state.annotations.keys()) or 'none'}"
+            )
+
+    def _get_selected_fields(self) -> set[str]:
+        """Extract field names from current values/values_list selection.
+
+        Helper method that unpacks field names from the (field_name, column) tuples
+        stored in values_select or values_list_select. Returns empty set if neither
+        projection mode is active (returning model instances).
+
+        Returns:
+            Set of field names currently selected, or empty set if no projection.
+
+        Example:
+            >>> # Internal usage in validation methods
+            >>> validator = QuerySetValidator(state)
+            >>> fields = validator._get_selected_fields()
+            >>> # Returns: {"username", "email"} if values("username", "email")
+            >>> # Returns: set() if no values/values_list
+        """
+        if self._state.values_select is not None:
+            # Unpack field names from (field_name, column) tuples
+            return {field_name for field_name, col in self._state.values_select}
+        if self._state.values_list_select is not None:
+            # Unpack field names from (field_name, column) tuples
+            return {field_name for field_name, col in self._state.values_list_select}
+        return set()