oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/models/lookups.py

@@ -0,0 +1,667 @@
+"""Django-style field lookups for query filtering.
+
+This module implements the lookup system that powers filter() expressions.
+Lookups are suffixes like __gte, __contains, __in that modify comparisons.
+
+Lookup Categories by Field Type:
+    String fields:
+        exact, iexact, contains, icontains, startswith, istartswith,
+        endswith, iendswith, in, isnull
+
+    Numeric fields (int, float, Decimal):
+        exact, gt, gte, lt, lte, between, range, in, isnull
+
+    DateTime/Date fields:
+        exact, gt, gte, lt, lte, between, range, year, month, day,
+        in, isnull
+
+    Time fields:
+        exact, gt, gte, lt, lte, between, range, in, isnull
+
+    UUID fields:
+        exact, gt, gte, lt, lte, between, range, in, isnull
+
+    Boolean fields:
+        exact, in, isnull
+
+    Array fields (list[T]) and JSON fields:
+        exact, contains, contained_by, overlap, in, isnull
+
+    All fields:
+        exact (default), in, isnull
+
+Key Functions:
+    _split_lookup_key(key: str) -> tuple[str, str]:
+        Split "name__contains" into ("name", "contains").
+        Returns ("name", "exact") if no __ present.
+
+    _build_lookup_conditions(model, field, lookup, value, meta) -> list[Condition]:
+        Convert a lookup into Condition objects for the IR.
+
+    _resolve_column_meta(model, field) -> ColumnMeta:
+        Get metadata for a field, with fallback for non-table models.
+
+SQL Mapping:
+    exact     → = (or IS NULL for None)
+    gt/gte    → > / >=
+    lt/lte    → < / <=
+    in        → IN (...)
+    between   → BETWEEN ... AND ...
+    isnull    → IS NULL / IS NOT NULL
+    contains  → LIKE '%...%'
+    icontains → ILIKE '%...%' (case-insensitive)
+    startswith → LIKE '...%'
+    endswith  → LIKE '%...'
+    iexact    → ILIKE '...'
+    year/month/day → range conditions on date/datetime
+
+    On array and JSON fields, with a list or tuple value:
+    contains     → every given element is in the stored array
+    contained_by → every stored element is among the given ones
+    overlap      → at least one element in common
+    (A string ``contains`` on a str field stored as JSON keeps LIKE.)
+
+Example:
+    User.objects.filter(
+        name__icontains="alice",  # ILIKE '%alice%'
+        age__gte=18,              # >= 18
+        status__in=["active", "pending"],
+        created_at__year=2024,    # >= '2024-01-01' AND < '2025-01-01'
+    )
+"""
+
+from __future__ import annotations
+
+import collections.abc
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from oxyde.core.types import TYPE_REGISTRY
+from oxyde.exceptions import FieldError, FieldLookupError, FieldLookupValueError
+from oxyde.models.metadata import ColumnMeta, column_type_for_meta
+from oxyde.models.utils import _unpack_annotated, _unwrap_optional
+from oxyde.queries.base import _resolve_registered_model
+from oxyde.queries.conditions import Condition
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+# Lookup constants
+STRING_LOOKUPS = [
+    "contains",
+    "icontains",
+    "startswith",
+    "istartswith",
+    "endswith",
+    "iendswith",
+    "iexact",
+]
+NUMERIC_LOOKUPS = ["gt", "gte", "lt", "lte", "between", "range"]
+DATETIME_LOOKUPS = ["gt", "gte", "lt", "lte", "between", "range"]
+UUID_LOOKUPS = ["gt", "gte", "lt", "lte", "between", "range"]
+BOOL_LOOKUPS: list[str] = []
+GENERIC_LOOKUPS: list[str] = []
+COMMON_LOOKUPS = ["in", "isnull"]
+DATE_PART_LOOKUPS = ["year", "month", "day"]
+ARRAY_LOOKUPS = ["contains", "contained_by", "overlap"]
+
+# Lookup → IR operator for array/JSON-array filters (evaluated in Rust/SQL)
+ARRAY_OPERATORS = {
+    "contains": "ARRAY_CONTAINS",
+    "contained_by": "ARRAY_CONTAINED_BY",
+    "overlap": "ARRAY_OVERLAP",
+}
+
+# Array lookup names that were plain field names before array lookups:
+# "window__overlap" still filters a related model's ``overlap`` field.
+_FIELD_NAMED_LOOKUPS = frozenset(["contained_by", "overlap"])
+
+# All known lookups for path parsing
+ALL_LOOKUPS = frozenset(
+    ["exact"]
+    + STRING_LOOKUPS
+    + NUMERIC_LOOKUPS
+    + COMMON_LOOKUPS
+    + DATE_PART_LOOKUPS
+    + ARRAY_LOOKUPS
+)
+
+
+def _lookup_category(meta: ColumnMeta) -> str:
+    """Determine lookup category based on field metadata.
+
+    Uses exact type() lookup via TYPE_REGISTRY — no issubclass ordering
+    issues (bool is correctly categorized as "bool", not "numeric").
+    """
+    if meta.foreign_key is not None:
+        return "numeric"
+    desc = TYPE_REGISTRY.get(meta.python_type)
+    return desc.category if desc is not None else "generic"
+
+
+def _field_spec(model_class: type[Model], meta: ColumnMeta) -> dict[str, Any] | None:
+    """ColumnTypeSpec of a field, from its model's cached column_types."""
+    cached = model_class._db_meta.column_types
+    if cached is not None and meta.db_column in cached:
+        return cached[meta.db_column]
+    return column_type_for_meta(meta)
+
+
+def _supports_array_lookups(meta: ColumnMeta, spec: dict[str, Any] | None) -> bool:
+    """Whether the field supports array lookups.
+
+    ``spec`` is the field's ColumnTypeSpec (``_field_spec``). Typed arrays
+    (``list[T]``) and JSON columns qualify. Nested typed arrays
+    (``list[list[T]]``) do not: they have no array lookup semantics on
+    PostgreSQL; store them in a JSON column instead.
+    """
+    if _lookup_category(meta) not in ("generic", "string") or spec is None:
+        return False
+    kind = spec.get("kind")
+    if kind == "array":
+        item = spec.get("item") or {}
+        return item.get("kind") != "array"
+    return kind in ("json", "json_binary")
+
+
+def _allowed_lookups_for_meta(
+    meta: ColumnMeta, spec: dict[str, Any] | None
+) -> list[str]:
+    """Get list of allowed lookups for a given field metadata.
+
+    ``spec`` is the field's ColumnTypeSpec (``_field_spec``).
+    """
+    category = _lookup_category(meta)
+    lookups: list[str] = ["exact"]
+    if category == "string":
+        lookups.extend(STRING_LOOKUPS)
+    elif category == "numeric":
+        lookups.extend(NUMERIC_LOOKUPS)
+    elif category == "datetime":
+        lookups.extend(DATETIME_LOOKUPS)
+        lookups.extend(DATE_PART_LOOKUPS)
+    elif category == "time":
+        # Comparisons are valid for times of day, but there is no calendar
+        # part to extract — the year/month/day builders reject time fields.
+        lookups.extend(DATETIME_LOOKUPS)
+    elif category == "uuid":
+        lookups.extend(UUID_LOOKUPS)
+    elif category == "bool":
+        lookups.extend(BOOL_LOOKUPS)
+    else:
+        lookups.extend(GENERIC_LOOKUPS)
+    if _supports_array_lookups(meta, spec):
+        lookups.extend(ARRAY_LOOKUPS)
+    lookups.extend(COMMON_LOOKUPS)
+    # Deduplicate while preserving order
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in lookups:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def _split_lookup_key(key: str) -> tuple[str, str]:
+    """Split field__lookup key into field name and lookup type.
+
+    For simple cases like "name__contains", returns ("name", "contains").
+    For nested paths like "user__age__gte", use _parse_lookup_path instead.
+    """
+    if "__" not in key:
+        return key, "exact"
+    field_name, lookup = key.split("__", 1)
+    if not field_name:
+        raise FieldLookupError("Lookup key must include a field name before '__'")
+    return field_name, lookup
+
+
+def _parse_lookup_path(key: str) -> tuple[list[str], str]:
+    """Parse a lookup key into field path and lookup type.
+
+    Handles nested paths like "user__age__gte" -> (["user", "age"], "gte").
+
+    Args:
+        key: Lookup key like "name", "name__contains", or "user__age__gte"
+
+    Returns:
+        Tuple of (field_path, lookup_type) where field_path is a list of field names
+
+    Examples:
+        "name" -> (["name"], "exact")
+        "name__contains" -> (["name"], "contains")
+        "user__age" -> (["user", "age"], "exact")
+        "user__age__gte" -> (["user", "age"], "gte")
+        "user__profile__city__icontains" -> (["user", "profile", "city"], "icontains")
+    """
+    if "__" not in key:
+        return [key], "exact"
+
+    parts = key.split("__")
+    if not parts[0]:
+        raise FieldLookupError("Lookup key must include a field name before '__'")
+
+    # Check if last part is a known lookup
+    if parts[-1] in ALL_LOOKUPS:
+        return parts[:-1], parts[-1]
+
+    # No lookup suffix, treat entire path as field path with "exact" lookup
+    return parts, "exact"
+
+
+@dataclass
+class ResolvedPath:
+    """Result of resolving a field path through FK relationships."""
+
+    # List of (relation_name, target_model) for each FK traversal
+    joins: list[tuple[str, type[Model]]]
+    # Final field name (e.g., "age" in "user__age")
+    final_field: str
+    # Final model class where final_field is defined
+    final_model: type[Model]
+    # Column metadata for the final field
+    column_meta: ColumnMeta
+
+
+def _resolve_field_path(
+    model_class: type[Model],
+    field_path: list[str],
+) -> ResolvedPath:
+    """Resolve a field path through FK relationships.
+
+    For "user__age" on Post model:
+    1. Post.user is FK to User
+    2. User.age is the final field
+
+    Args:
+        model_class: Starting model (e.g., Post)
+        field_path: List of field names (e.g., ["user", "age"])
+
+    Returns:
+        ResolvedPath with joins info and final field metadata
+
+    Raises:
+        FieldError: If field doesn't exist
+        FieldLookupError: If path traverses non-FK field
+    """
+    joins: list[tuple[str, type[Model]]] = []
+    current_model = model_class
+
+    # Traverse all but the last field (those must be FK fields)
+    for i, field_name in enumerate(field_path[:-1]):
+        meta = current_model._db_meta.field_metadata.get(field_name)
+
+        if meta is None:
+            raise FieldError(f"{current_model.__name__} has no field '{field_name}'")
+
+        if meta.foreign_key is None:
+            raise FieldLookupError(
+                f"Cannot traverse '{field_name}' in path "
+                f"'{'.'.join(field_path)}': not a foreign key"
+            )
+
+        # Resolve target model
+        target_model = _resolve_registered_model(meta.foreign_key.target)
+        joins.append((field_name, target_model))
+        current_model = target_model
+
+    # Resolve the final field
+    final_field = field_path[-1]
+    column_meta = _resolve_column_meta(current_model, final_field)
+
+    return ResolvedPath(
+        joins=joins,
+        final_field=final_field,
+        final_model=current_model,
+        column_meta=column_meta,
+    )
+
+
+def _resolve_column_meta(model_class: type[Model], field_name: str) -> ColumnMeta:
+    """Resolve column metadata for a field, creating basic metadata if needed."""
+    meta = model_class._db_meta.field_metadata.get(field_name)
+    if meta is not None:
+        return meta
+
+    model_field = model_class.model_fields.get(field_name)
+    if model_field is None:
+        raise FieldError(f"{model_class.__name__} has no field '{field_name}'")
+
+    base_hint, _ = _unpack_annotated(model_field.annotation)
+    python_type, optional_flag = _unwrap_optional(base_hint)
+    nullable = optional_flag or not model_field.is_required()
+
+    return ColumnMeta(
+        name=field_name,
+        db_column=field_name,
+        python_type=python_type,
+        nullable=nullable,
+    )
+
+
+def _resolve_lookup(model_class: type[Model], key: str) -> tuple[ResolvedPath, str]:
+    """Resolve a filter key to its field and its lookup.
+
+    The key is a field ("name"), or a path through FK relations
+    ("user__age"), optionally followed by a lookup ("user__age__gte"), as
+    ``_parse_lookup_path`` reads it. Raises ``FieldLookupError`` when the
+    lookup is not allowed on the field.
+
+    ``contained_by`` and ``overlap`` were plain names before they were
+    lookups. When the field before one of them does not allow it and the
+    whole key names a field through relations, the key is that field with
+    "exact": "window__overlap" filters a related model's ``overlap`` field,
+    since FK columns have no array lookups.
+    """
+    field_path, lookup = _parse_lookup_path(key)
+    resolved = _resolve_field_path(model_class, field_path)
+    spec = _field_spec(resolved.final_model, resolved.column_meta)
+    if lookup in _allowed_lookups_for_meta(resolved.column_meta, spec):
+        return resolved, lookup
+
+    error = FieldLookupError(
+        f"Lookup '{lookup}' is not supported for field '{resolved.final_field}'"
+    )
+    if lookup not in _FIELD_NAMED_LOOKUPS:
+        raise error
+    try:
+        return _resolve_field_path(model_class, [*field_path, lookup]), "exact"
+    except (FieldError, FieldLookupError):
+        raise error from None
+
+
+def _build_lookup_conditions(
+    model_class: type[Model],
+    field_name: str,
+    lookup: str,
+    value: Any,
+    column_meta: ColumnMeta,
+) -> list[Condition]:
+    """Build query conditions for a given field lookup."""
+    lookup = lookup or "exact"
+    array_lookups = _supports_array_lookups(
+        column_meta, _field_spec(model_class, column_meta)
+    )
+    db_column = column_meta.db_column
+
+    if lookup in ARRAY_LOOKUPS:
+        # ``array_lookups`` is the field's ``_supports_array_lookups``.
+        # ``contains`` keeps its LIKE meaning on other fields, and for a string
+        # value on a str field, including str fields stored as JSON.
+        string_contains = lookup == "contains" and (
+            not array_lookups
+            or (isinstance(value, str) and _lookup_category(column_meta) == "string")
+        )
+        if not string_contains:
+            if not array_lookups:
+                raise FieldLookupError(
+                    f"Lookup '{lookup}' requires an array or JSON field, "
+                    f"got '{field_name}' of type {column_meta.python_type}"
+                )
+            return [_build_array_condition(field_name, lookup, value, column_meta)]
+
+    if lookup == "exact":
+        if value is None:
+            return [Condition(field_name, "IS NULL", None, column=db_column)]
+        return [Condition(field_name, "=", value, column=db_column)]
+
+    if lookup in {"gt", "gte", "lt", "lte"}:
+        if value is None:
+            raise FieldLookupValueError(f"Lookup '{lookup}' requires a non-null value")
+        op_map = {"gt": ">", "gte": ">=", "lt": "<", "lte": "<="}
+        return [Condition(field_name, op_map[lookup], value, column=db_column)]
+
+    if lookup == "in":
+        if value is None:
+            raise FieldLookupValueError("Lookup 'in' requires an iterable of values")
+        if isinstance(value, (str, bytes)):
+            raise FieldLookupValueError(
+                "Lookup 'in' does not accept string values; use a sequence"
+            )
+        if not isinstance(value, collections.abc.Iterable):
+            raise FieldLookupValueError("Lookup 'in' requires an iterable value")
+        return [Condition(field_name, "IN", list(value), column=db_column)]
+
+    if lookup in ("between", "range"):
+        if not isinstance(value, (tuple, list)) or len(value) != 2:
+            raise FieldLookupValueError(
+                f"Lookup '{lookup}' requires a tuple/list of two values"
+            )
+        return [
+            Condition(
+                field_name,
+                "BETWEEN",
+                [value[0], value[1]],
+                column=column_meta.db_column,
+            )
+        ]
+
+    if lookup == "isnull":
+        flag = bool(value)
+        return [
+            Condition(
+                field_name,
+                "IS NULL" if flag else "IS NOT NULL",
+                None,
+                column=column_meta.db_column,
+            )
+        ]
+
+    if lookup in {
+        "contains",
+        "icontains",
+        "startswith",
+        "istartswith",
+        "endswith",
+        "iendswith",
+    }:
+        if not isinstance(value, str):
+            raise FieldLookupValueError(f"Lookup '{lookup}' requires a string value")
+
+        operator = "LIKE"
+        if lookup in {"icontains", "istartswith", "iendswith"}:
+            operator = "ILIKE"
+
+        escape = None
+        escaped_value = value
+        if any(ch in value for ch in ("\\", "%", "_")):
+            # Escape SQL wildcards to treat them as literal characters
+            # Order matters: escape backslash first, then wildcards
+            escaped_value = (
+                value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            )
+            escape = "\\"
+
+        if lookup.endswith("contains"):
+            pattern = f"%{escaped_value}%"
+        elif lookup.endswith("startswith"):
+            pattern = f"{escaped_value}%"
+        else:  # endswith / iendswith
+            pattern = f"%{escaped_value}"
+
+        return [
+            Condition(
+                field_name,
+                operator,
+                pattern,
+                column=column_meta.db_column,
+                escape=escape,
+            )
+        ]
+
+    if lookup == "iexact":
+        if not isinstance(value, str):
+            raise FieldLookupValueError("Lookup 'iexact' requires a string value")
+        escape = None
+        escaped_value = value
+        if any(ch in value for ch in ("\\", "%", "_")):
+            escaped_value = (
+                value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            )
+            escape = "\\"
+        return [
+            Condition(
+                field_name,
+                "ILIKE",
+                escaped_value,
+                column=column_meta.db_column,
+                escape=escape,
+            )
+        ]
+
+    if lookup == "year":
+        return _build_year_conditions(field_name, value, column_meta)
+
+    if lookup == "month":
+        return _build_month_conditions(field_name, value, column_meta)
+
+    if lookup == "day":
+        return _build_day_conditions(field_name, value, column_meta)
+
+    raise FieldLookupError(f"Unsupported lookup '{lookup}' for field '{field_name}'")
+
+
+def _build_array_condition(
+    field_name: str, lookup: str, value: Any, meta: ColumnMeta
+) -> Condition:
+    """Build an array containment/overlap condition on an array or JSON field.
+
+    Matching is done by the database: Rust validates the operand against the
+    column's spec (from the query's column_types), casts it to the column's
+    db_type on PostgreSQL (column_db_types) and picks the dialect's SQL.
+    """
+    if not isinstance(value, (list, tuple)):
+        raise FieldLookupValueError(
+            f"Lookup '{lookup}' requires a list or tuple of values"
+        )
+    return Condition(field_name, ARRAY_OPERATORS[lookup], value, column=meta.db_column)
+
+
+def _ensure_date_inputs(value: Any, expected: int, label: str) -> tuple[int, ...]:
+    """Validate and normalize date/time lookup inputs."""
+    if isinstance(value, int) and expected == 1:
+        return (value,)
+    if isinstance(value, (tuple, list)) and len(value) == expected:
+        if all(isinstance(v, int) for v in value):
+            return tuple(value)
+    raise FieldLookupValueError(f"Lookup '{label}' expects {expected} integer value(s)")
+
+
+def _build_year_conditions(
+    field_name: str, value: Any, meta: ColumnMeta
+) -> list[Condition]:
+    """Build conditions for year lookup."""
+    (year,) = _ensure_date_inputs(value, 1, "year")
+    start: datetime | date
+    end: datetime | date
+    if isinstance(meta.python_type, type) and issubclass(meta.python_type, datetime):
+        start = datetime(year, 1, 1)
+        end = datetime(year + 1, 1, 1)
+    elif isinstance(meta.python_type, type) and issubclass(meta.python_type, date):
+        start = date(year, 1, 1)
+        end = date(year + 1, 1, 1)
+    else:
+        raise FieldLookupError(
+            f"Lookup 'year' is not supported for field type {meta.python_type}"
+        )
+    return [
+        Condition(field_name, ">=", start.isoformat(), column=meta.db_column),
+        Condition(field_name, "<", end.isoformat(), column=meta.db_column),
+    ]
+
+
+def _build_month_conditions(
+    field_name: str, value: Any, meta: ColumnMeta
+) -> list[Condition]:
+    """Build conditions for month lookup."""
+    year, month = _ensure_date_inputs(value, 2, "month")
+    if not 1 <= month <= 12:
+        raise FieldLookupValueError("Lookup 'month' requires month in range 1..12")
+    start: datetime | date
+    end: datetime | date
+    if isinstance(meta.python_type, type) and issubclass(meta.python_type, datetime):
+        start = datetime(year, month, 1)
+        end_month = month + 1
+        end_year = year
+        if end_month == 13:
+            end_month = 1
+            end_year += 1
+        end = datetime(end_year, end_month, 1)
+    elif isinstance(meta.python_type, type) and issubclass(meta.python_type, date):
+        start = date(year, month, 1)
+        end_month = month + 1
+        end_year = year
+        if end_month == 13:
+            end_month = 1
+            end_year += 1
+        end = date(end_year, end_month, 1)
+    else:
+        raise FieldLookupError(
+            f"Lookup 'month' is not supported for field type {meta.python_type}"
+        )
+    return [
+        Condition(field_name, ">=", start.isoformat(), column=meta.db_column),
+        Condition(field_name, "<", end.isoformat(), column=meta.db_column),
+    ]
+
+
+def _build_day_conditions(
+    field_name: str, value: Any, meta: ColumnMeta
+) -> list[Condition]:
+    """Build conditions for day lookup."""
+    year, month, day = _ensure_date_inputs(value, 3, "day")
+    start: datetime | date
+    end: datetime | date
+    try:
+        if isinstance(meta.python_type, type) and issubclass(
+            meta.python_type, datetime
+        ):
+            start = datetime(year, month, day)
+            end = start + timedelta(days=1)
+        elif isinstance(meta.python_type, type) and issubclass(meta.python_type, date):
+            start = date(year, month, day)
+            end = start + timedelta(days=1)
+        else:
+            raise FieldLookupError(
+                f"Lookup 'day' is not supported for field type {meta.python_type}"
+            )
+    except ValueError as exc:  # invalid date
+        raise FieldLookupValueError(str(exc)) from exc
+    return [
+        Condition(field_name, ">=", start.isoformat(), column=meta.db_column),
+        Condition(field_name, "<", end.isoformat(), column=meta.db_column),
+    ]
+
+
+__all__ = [
+    "STRING_LOOKUPS",
+    "NUMERIC_LOOKUPS",
+    "DATETIME_LOOKUPS",
+    "UUID_LOOKUPS",
+    "BOOL_LOOKUPS",
+    "GENERIC_LOOKUPS",
+    "COMMON_LOOKUPS",
+    "DATE_PART_LOOKUPS",
+    "ARRAY_LOOKUPS",
+    "ARRAY_OPERATORS",
+    "ALL_LOOKUPS",
+    "ResolvedPath",
+    "_lookup_category",
+    "_field_spec",
+    "_supports_array_lookups",
+    "_allowed_lookups_for_meta",
+    "_split_lookup_key",
+    "_parse_lookup_path",
+    "_resolve_field_path",
+    "_resolve_column_meta",
+    "_resolve_lookup",
+    "_build_lookup_conditions",
+    "_build_array_condition",
+    "_ensure_date_inputs",
+    "_build_year_conditions",
+    "_build_month_conditions",
+    "_build_day_conditions",
+]