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

async_orm_kit/query/debugger.py

@@ -0,0 +1,269 @@
+"""Backward-compatible query diagnostics, backed by real SQLAlchemy events.
+
+For concurrent async applications prefer ``QueryProfiler.capture()`` so each
+request/task receives isolated statistics. The original global debugger and
+manually started detector remain supported for development/CLI workflows.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from async_orm_kit._logging import get_logger
+from async_orm_kit.query.observability import (
+    QueryProfiler,
+    QueryRecord,
+    sanitized_sql,
+    sql_fingerprint,
+)
+
+logger = get_logger(__name__)
+
+
+class QueryDebugger:
+    """Opt-in bounded SQL diagnostics with optional automatic event capture.
+
+    ``enable()`` controls recording; ``attach(engine)`` connects SQLAlchemy
+    cursor events. Without attachment, manual ``log_query()`` still works.
+    Explicitly ``detach()`` after monitoring to remove engine listeners.
+
+    This class is intentionally process-wide if reused globally. In async web
+    handlers, use a fresh ``QueryProfiler`` and its ``capture()`` method.
+    """
+
+    def __init__(
+        self, *, max_entries: int = 1000, slow_threshold_ms: float = 1000.0
+    ) -> None:
+        if (
+            isinstance(max_entries, bool)
+            or not isinstance(max_entries, int)
+            or max_entries < 1
+        ):
+            raise ValueError("max_entries must be an integer >= 1")
+        if slow_threshold_ms < 0:
+            raise ValueError("slow_threshold_ms must be nonnegative")
+        self.query_log: list[dict[str, Any]] = []
+        self.enabled = False
+        self._max_entries = max_entries
+        self._slow_threshold_ms = slow_threshold_ms
+        self._profiler: QueryProfiler | None = None
+        self._engine: Engine | AsyncEngine | None = None
+        self._lock = threading.RLock()
+
+    def enable(self) -> None:
+        self.enabled = True
+        logger.info("Query debugging enabled")
+
+    def disable(self) -> None:
+        self.enabled = False
+        logger.info("Query debugging disabled")
+
+    def attach(self, engine: Engine | AsyncEngine) -> None:
+        """Attach to an Engine/AsyncEngine (idempotent for the same engine)."""
+        with self._lock:
+            if self._engine is engine:
+                return
+            self.detach()
+            self._profiler = QueryProfiler(engine, on_query=self._record_event)
+            self._profiler.attach()
+            self._engine = engine
+
+    def detach(self) -> None:
+        """Stop automatic event collection without changing enabled state."""
+        with self._lock:
+            if self._profiler is not None:
+                self._profiler.detach()
+            self._profiler = None
+            self._engine = None
+
+    def _record_event(self, record: QueryRecord) -> None:
+        self.log_query(
+            record.sql,
+            record.duration_ms / 1000,
+            record.row_count,
+            success=record.success,
+            error_type=record.error_type,
+        )
+
+    def log_query(
+        self,
+        sql: str,
+        duration: float,
+        row_count: int | None,
+        *,
+        success: bool = True,
+        error_type: str | None = None,
+    ) -> None:
+        """Record one cursor execution; duration is expressed in seconds."""
+        if not self.enabled:
+            return
+        duration_ms = round(duration * 1000, 3)
+        safe_sql = sanitized_sql(sql)
+        entry = {
+            "sql": safe_sql,
+            "duration_ms": duration_ms,
+            "row_count": row_count
+            if row_count is not None and row_count >= 0
+            else None,
+            "timestamp": time.time(),
+            "success": success,
+            "error_type": error_type,
+        }
+        with self._lock:
+            if len(self.query_log) >= self._max_entries:
+                self.query_log.pop(0)
+            self.query_log.append(entry)
+        if duration_ms >= self._slow_threshold_ms:
+            logger.warning(
+                "Slow query detected", duration_ms=duration_ms, sql=safe_sql[:200]
+            )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Return summary statistics for the retained history."""
+        with self._lock:
+            entries = list(self.query_log)
+        if not entries:
+            return {
+                "total_queries": 0,
+                "total_duration_ms": 0,
+                "avg_duration_ms": 0,
+                "slowest_query": None,
+            }
+        total = sum(entry["duration_ms"] for entry in entries)
+        slowest = max(entries, key=lambda entry: entry["duration_ms"])
+        return {
+            "total_queries": len(entries),
+            "total_duration_ms": round(total, 2),
+            "avg_duration_ms": round(total / len(entries), 2),
+            "slowest_query": {
+                "sql": slowest["sql"][:200],
+                "duration_ms": slowest["duration_ms"],
+            },
+        }
+
+    def clear(self) -> None:
+        with self._lock:
+            self.query_log.clear()
+
+    @contextmanager
+    def measure_query(self, description: str = "") -> Iterator[None]:
+        """Time a Python block for logging (not a DB cursor execution)."""
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            if self.enabled:
+                logger.debug(
+                    "Query block measured",
+                    description=description,
+                    duration_ms=round((time.perf_counter() - start) * 1000, 2),
+                )
+
+
+query_debugger = QueryDebugger()
+
+
+class NPlusOneDetector:
+    """Heuristically identify repeated SELECT/WHERE SQL fingerprints.
+
+    This cannot prove a relationship-level N+1 issue; it finds likely candidates
+    for inspection. Attach an engine to receive real executions or manually
+    feed ``record_query()`` for backward compatibility. Use QueryProfile's
+    n_plus_one_report() for request-scoped async observations instead.
+    """
+
+    def __init__(self, *, threshold: int = 10) -> None:
+        if (
+            isinstance(threshold, bool)
+            or not isinstance(threshold, int)
+            or threshold < 2
+        ):
+            raise ValueError("threshold must be an integer >= 2")
+        self.query_count = 0
+        self.query_patterns: dict[str, int] = {}
+        self.monitoring = False
+        self.threshold = threshold
+        self._profiler: QueryProfiler | None = None
+        self._engine: Engine | AsyncEngine | None = None
+        self._lock = threading.RLock()
+
+    def start_monitoring(self) -> None:
+        with self._lock:
+            self.monitoring = True
+            self.query_count = 0
+            self.query_patterns.clear()
+        logger.info("N+1 monitoring started")
+
+    def stop_monitoring(self) -> None:
+        self.monitoring = False
+
+    def attach(self, engine: Engine | AsyncEngine) -> None:
+        """Install event monitoring for executed SQL statements."""
+        with self._lock:
+            if self._engine is engine:
+                return
+            self.detach()
+            self._profiler = QueryProfiler(engine, on_query=self._record_event)
+            self._profiler.attach()
+            self._engine = engine
+
+    def detach(self) -> None:
+        with self._lock:
+            if self._profiler is not None:
+                self._profiler.detach()
+            self._profiler = None
+            self._engine = None
+
+    def _record_event(self, record: QueryRecord) -> None:
+        if record.success:
+            self.record_query(record.sql)
+
+    def record_query(self, sql: str) -> None:
+        if not self.monitoring:
+            return
+        pattern = self._normalize_sql(sql)
+        with self._lock:
+            self.query_count += 1
+            self.query_patterns[pattern] = self.query_patterns.get(pattern, 0) + 1
+
+    def _normalize_sql(self, sql: str) -> str:
+        return sql_fingerprint(sql)
+
+    def report(self) -> dict[str, Any]:
+        with self._lock:
+            patterns = dict(self.query_patterns)
+            count = self.query_count
+        suspects: list[dict[str, Any]] = [
+            {
+                "pattern": pattern[:200],
+                "count": occurrences,
+                "severity": "high" if occurrences > 100 else "medium",
+            }
+            for pattern, occurrences in patterns.items()
+            if occurrences >= self.threshold
+            and pattern.lstrip().upper().startswith("SELECT ")
+            and " WHERE " in f" {pattern.upper()} "
+        ]
+        suspects.sort(key=lambda x: (-x["count"], x["pattern"]))
+        result = {
+            "total_queries": count,
+            "unique_patterns": len(patterns),
+            "potential_n_plus_one": suspects,
+        }
+        if suspects:
+            logger.warning(
+                "Potential repeated-query patterns detected",
+                patterns=len(suspects),
+                total_queries=count,
+            )
+        return result
+
+
+__all__ = ["QueryDebugger", "NPlusOneDetector", "query_debugger"]

async_orm_kit/query/expressions/__init__.py

@@ -0,0 +1,62 @@
+from .case import Case, When
+from .collections import (
+    ArrayContains,
+    ArrayIndex,
+    ArrayLength,
+    ArrayOverlap,
+    JSONContains,
+    JSONHasKey,
+    JSONPath,
+)
+from .f import F, FExpression
+from .functions import (
+    Abs,
+    Cast,
+    Coalesce,
+    Concat,
+    Extract,
+    Length,
+    Lower,
+    NullIf,
+    Round,
+    Trim,
+    Upper,
+)
+from .subquery import Exists, OuterRef, Subquery
+from .value import Value
+from .window import DenseRank, Lag, Lead, Rank, RowNumber, Window
+
+__all__ = [
+    "Case",
+    "When",
+    "ArrayContains",
+    "ArrayIndex",
+    "ArrayLength",
+    "ArrayOverlap",
+    "JSONContains",
+    "JSONHasKey",
+    "JSONPath",
+    "F",
+    "FExpression",
+    "Abs",
+    "Cast",
+    "Coalesce",
+    "Concat",
+    "Extract",
+    "Length",
+    "Lower",
+    "NullIf",
+    "Round",
+    "Trim",
+    "Upper",
+    "Exists",
+    "OuterRef",
+    "Subquery",
+    "Value",
+    "DenseRank",
+    "Lag",
+    "Lead",
+    "Rank",
+    "RowNumber",
+    "Window",
+]

async_orm_kit/query/expressions/analysis.py

@@ -0,0 +1,56 @@
+"""SQL expression analysis independent of query-side mutation.
+
+Inspect *resolved* SQLAlchemy expressions rather than guessing from a wrapper's
+outer type. In particular, ``Sum(...) + 1`` and CASE nested sums are aggregates,
+whereas ``SUM(...) OVER (...)`` is a window expression, not a GROUP BY aggregate.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.sql.elements import ClauseElement, Over
+from sqlalchemy.sql.functions import FunctionElement
+from sqlalchemy.sql.selectable import Exists as SAExists, ScalarSelect, SelectBase
+
+_AGGREGATES = frozenset(
+    {
+        "count",
+        "sum",
+        "avg",
+        "min",
+        "max",
+        "array_agg",
+        "string_agg",
+        "bool_and",
+        "bool_or",
+        "every",
+        "json_agg",
+        "jsonb_agg",
+    }
+)
+
+
+def contains_aggregate(expression: ClauseElement) -> bool:
+    """Return whether SQL contains a non-window aggregate call."""
+
+    def visit(node: ClauseElement) -> bool:
+        if isinstance(node, (Over, ScalarSelect, SAExists, SelectBase)):
+            # A nested SELECT owns its own grouping/window context. Walking into
+            # it would erroneously mark the containing queryset as aggregate.
+            return False
+        if getattr(node, "_annotations", {}).get("async_orm_kit_aggregate") is True:
+            return True
+        if isinstance(node, FunctionElement) and str(node.name).lower() in _AGGREGATES:
+            return True
+        return any(visit(child) for child in node.get_children())
+
+    return visit(expression)
+
+
+def contains_window(expression: ClauseElement) -> bool:
+    """Determine whether expression includes SQL OVER window clauses."""
+    if isinstance(expression, Over):
+        return True
+    if isinstance(expression, (ScalarSelect, SAExists, SelectBase)):
+        # Window functions inside a subquery are legal in the outer WHERE.
+        return False
+    return any(contains_window(child) for child in expression.get_children())

async_orm_kit/query/expressions/case.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import and_, case, literal
+
+from async_orm_kit._logging import get_logger
+from async_orm_kit.exceptions import FilterError
+from async_orm_kit.query.lookups.resolver import FieldResolver, ResolverContext
+from async_orm_kit.query.mixins.combinable import CombinableMixin
+from async_orm_kit.query.mixins.orderable import OrderableMixin
+from async_orm_kit.types import SAFE_SCALAR_TYPES
+
+logger = get_logger(__name__)
+
+
+class When:
+    """
+    Represents a single WHEN ... THEN ... branch in a CASE expression.
+
+    Supports both kwargs-style conditions and Q objects:
+
+        When(status="active", then=Value("Active"))
+        When(Q(score__gte=90) | Q(is_vip=True), then=Value("Priority"))
+        When(Q(price__gt=100), category="electronics", then=Value("Premium"))
+
+    Args:
+        *args:       Q() objects for complex boolean conditions.
+        then:        The output value when the condition matches.
+        **condition: Filter-style keyword arguments (same as .filter()).
+
+    Raises:
+        ValueError: If no conditions provided (neither Q objects nor kwargs).
+        TypeError:  If positional args are not Q() instances.
+    """
+
+    __slots__ = ("q_objects", "condition", "then")
+
+    def __init__(self, *args, then: Any, **condition):
+        from async_orm_kit.query.q import Q
+
+        # Validate positional args are Q objects
+        invalid_args = [a for a in args if not isinstance(a, Q)]
+        if invalid_args:
+            raise TypeError(
+                f"When() positional arguments must be Q() instances. "
+                f"Got: {[type(a).__name__ for a in invalid_args]}"
+            )
+
+        if not args and not condition:
+            raise ValueError(
+                "When() requires at least one condition — "
+                "either Q() objects or keyword arguments. "
+                "Example: When(status='active', then=Value('Active'))"
+            )
+        if then is None:
+            raise ValueError(
+                "When() 'then' argument cannot be None. "
+                "To represent a SQL NULL, use Value(None)."
+            )
+
+        from async_orm_kit.query.q import _snapshot_value
+
+        self.q_objects = args
+        self.condition = {
+            key: _snapshot_value(value) for key, value in condition.items()
+        }
+        self.then = then
+
+    def resolve(
+        self,
+        field_resolver: FieldResolver,
+        context: ResolverContext = ResolverContext(),
+    ):
+        """
+        Resolve condition(s) and then-clause against the shared FieldResolver.
+
+        Combines Q objects and kwargs into a single AND condition,
+        matching Django's behavior where::
+
+            When(Q(...), Q(...), field=val, then=...)
+
+        is equivalent to::
+
+            When(Q(...) & Q(...) & Q(field=val), then=...)
+        """
+        from async_orm_kit.query.lookups.parser import FilterParser
+
+        all_conditions = []
+
+        # 1. Resolve Q() objects
+        for q in self.q_objects:
+            resolved = q.resolve(field_resolver=field_resolver, context=context)
+            if resolved is not None:
+                all_conditions.append(resolved)
+
+        # 2. Resolve kwargs via FilterParser
+        if self.condition:
+            parser = FilterParser(field_resolver)
+            parsed = parser.parse(self.condition, context=context)
+            all_conditions.extend(parsed)
+
+        if not all_conditions:
+            raise ValueError("When() resolved to zero conditions")
+
+        if len(all_conditions) == 1:
+            resolved_condition = all_conditions[0]
+        else:
+            resolved_condition = and_(*all_conditions)
+
+        # 3. Resolve the THEN clause
+        resolved_then = _resolve_expression(self.then, field_resolver, context)
+
+        return resolved_condition, resolved_then
+
+    def __eq__(self, other):
+        if not isinstance(other, When):
+            return False
+        return _when_key(self) == _when_key(other)
+
+    def __hash__(self):
+        return hash(("When", _when_key(self)))
+
+
+def _when_key(branch):
+    """Structural key without invoking SQL-expression overloaded equality.
+
+    SQLAlchemy ClauseElements are deliberately identified by object identity;
+    the ORM's own F/Value/FExpression nodes receive stable structural keys.
+    """
+    from async_orm_kit.query.expressions.f import F, FExpression
+    from async_orm_kit.query.expressions.value import Value
+    from async_orm_kit.query.q import _freeze_value
+
+    def freeze(value):
+        if isinstance(value, F):
+            return ("F", value.name)
+        if isinstance(value, FExpression):
+            op = value.operator
+            return (
+                "FExpression",
+                op if isinstance(op, str) else getattr(op, "__name__", str(op)),
+                freeze(value.left),
+                freeze(value.right),
+            )
+        if isinstance(value, Value):
+            return ("Value", _freeze_value(value.value))
+        if isinstance(value, (tuple, list)):
+            return (type(value).__name__, tuple(freeze(v) for v in value))
+        if isinstance(value, dict):
+            return (
+                "dict",
+                tuple(
+                    sorted(((freeze(k), freeze(v)) for k, v in value.items()), key=repr)
+                ),
+            )
+        return _freeze_value(value)
+
+    return freeze((branch.q_objects, branch.condition, branch.then))
+
+
+class Case(CombinableMixin, OrderableMixin):
+    """
+    Represents a SQL CASE WHEN ... THEN ... [ELSE ...] END expression.
+
+    Can be used anywhere an expression is accepted:
+    - annotate()                    -> adds a computed column
+    - aggregate functions (Sum, Count, etc.)  -> conditional aggregation
+    - order_by()                    -> conditional ordering
+    - update()                      -> conditional bulk update
+
+    Args:
+        *whens:  One or more When() instances defining the branches.
+                 Evaluated left to right; first matching branch wins.
+        default: The ELSE value/expression. Defaults to SQL NULL if omitted.
+                 Can be Value(), F(), or another Case().
+
+    Raises:
+        ValueError: If no When() branches are provided.
+        TypeError:  If positional args contain non-When() instances.
+
+    .. code-block:: python
+
+        # Basic label mapping
+        Case(
+            When(status="active",  then=Value("Active")),
+            When(status="banned",  then=Value("Banned")),
+            default=Value("Unknown"),
+        )
+
+        # Conditional aggregation
+        Sum(Case(
+            When(amount__gte=1000, then=Value(1)),
+            default=Value(0),
+        ))
+
+        # Nested Case
+        Case(
+            When(score__gte=90, then=Value("A")),
+            When(score__gte=70, then=Case(
+                When(attendance__gte=80, then=Value("B+")),
+                default=Value("B"),
+            )),
+            default=Value("C"),
+        )
+    """
+
+    __slots__ = ("whens", "default")
+
+    def __init__(self, *whens: When, default: Any | None = None):
+        if not whens:
+            raise ValueError(
+                "Case() requires at least one When() clause. "
+                "Example: Case(When(status='active', then=Value(1)), default=Value(0))"
+            )
+        invalid = [w for w in whens if not isinstance(w, When)]
+        if invalid:
+            raise TypeError(
+                f"Case() only accepts When() instances as positional arguments. "
+                f"Got: {[type(w).__name__ for w in invalid]}"
+            )
+
+        self.whens = whens
+        self.default = default
+
+    def resolve(
+        self,
+        field_resolver: FieldResolver,
+        context: ResolverContext = ResolverContext(),
+    ):
+        """
+        Resolve all When branches and the ELSE clause.
+
+        Delegates condition parsing to the shared FieldResolver so that
+        auto-joins, lookup validation, and F() resolution all work correctly.
+
+        Returns:
+            SQLAlchemy case() construct ready for use in SELECT/WHERE/ORDER BY.
+        """
+        resolved_whens = []
+        for when in self.whens:
+            try:
+                condition, then = when.resolve(
+                    field_resolver=field_resolver, context=context
+                )
+                resolved_whens.append((condition, then))
+            except FilterError:
+                raise
+            except Exception as e:
+                raise FilterError(
+                    f"Failed to resolve When({when.condition!r}): {e}"
+                ) from e
+
+        resolved_default = None
+        if self.default is not None:
+            try:
+                resolved_default = _resolve_expression(
+                    expr=self.default, field_resolver=field_resolver, context=context
+                )
+            except FilterError:
+                raise
+            except Exception as e:
+                raise FilterError(
+                    f"Failed to resolve Case default={self.default!r}: {e}"
+                ) from e
+
+        logger.debug(
+            "Resolved Case expression",
+            branches=len(resolved_whens),
+            has_default=resolved_default is not None,
+        )
+
+        return case(*resolved_whens, else_=resolved_default)
+
+    def __repr__(self):
+        whens_repr = ", ".join(repr(w) for w in self.whens)
+        return f"Case({whens_repr}, default={self.default!r})"
+
+
+def _resolve_expression(
+    expr: Any, field_resolver: FieldResolver, context: ResolverContext
+):
+    """
+    Resolve any supported expression type to a SQLAlchemy construct.
+
+    Resolution order:
+        1. Value(x)      -> literal(x)
+        2. F("field")    -> resolved column (with auto-join)
+        3. Case(...)     -> nested CASE expression
+        4. Q(...)        -> boolean expression (for nested conditions)
+        5. Safe scalars  -> literal(x) via auto-wrap
+        6. Anything else -> TypeError
+
+    Kept as a module-level function to avoid circular imports while
+    remaining accessible to When and Case.
+    """
+    from sqlalchemy.sql.elements import ClauseElement
+
+    from async_orm_kit.query.aggregations.base import Aggregate
+    from async_orm_kit.query.q import Q
+
+    if isinstance(expr, Aggregate):
+        return expr.resolve(field_resolver=field_resolver, context=context)
+
+    if isinstance(expr, CombinableMixin) and hasattr(expr, "resolve"):
+        return expr.resolve(field_resolver=field_resolver, context=context)
+
+    if isinstance(expr, ClauseElement):
+        return expr
+
+    if isinstance(expr, Q):
+        return expr.resolve(field_resolver=field_resolver, context=context)
+
+    # Auto-wrap only safe scalar types
+    if isinstance(expr, SAFE_SCALAR_TYPES):
+        return literal(expr)
+
+    raise TypeError(
+        f"Unsupported expression type in Case/When: {type(expr).__name__!r}. "
+        f"Wrap it in Value(), F(), or use a Q() object."
+    )