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

async_orm_kit/query/lookups/__init__.py

@@ -0,0 +1,121 @@
+"""Built-in, validated lookup operators for QuerySet filters."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from sqlalchemy import extract, func, literal
+from sqlalchemy.sql.selectable import SelectBase
+from sqlalchemy.sql.sqltypes import Date, DateTime, Time
+
+
+def _lookup_in(column: Any, value: Any):
+    if isinstance(value, (str, bytes, bytearray, Mapping)):
+        raise TypeError("The 'in' lookup requires a non-string iterable or SELECT.")
+    if not isinstance(value, SelectBase) and not isinstance(value, Iterable):
+        raise TypeError("The 'in' lookup requires an iterable or SELECT.")
+    return column.in_(value)
+
+
+def _lookup_range(column: Any, value: Any):
+    if isinstance(value, (str, bytes, bytearray, Mapping)):
+        raise TypeError("The 'range' lookup requires exactly two boundary values.")
+    if not isinstance(value, (tuple, list)) or len(value) != 2:
+        raise TypeError("The 'range' lookup requires exactly two boundary values.")
+    return column.between(value[0], value[1])
+
+
+def _lookup_iexact(column: Any, value: Any):
+    if not isinstance(value, str):
+        raise TypeError("The 'iexact' lookup requires a string value.")
+    return func.lower(column) == func.lower(literal(value))
+
+
+def _lookup_isnull(column: Any, value: Any):
+    if type(value) is not bool:
+        raise TypeError("The 'isnull' lookup requires a bool value.")
+    return column.is_(None) if value else column.is_not(None)
+
+
+def _lookup_date_part(column: Any, part: str, value: Any):
+    """Compare a real date/time column part without dynamic SQL identifiers."""
+    sql_type = getattr(column, "type", None)
+    if sql_type is None and hasattr(column, "property"):
+        columns = getattr(column.property, "columns", ())
+        if columns:
+            sql_type = columns[0].type
+    if not isinstance(sql_type, (Date, DateTime, Time)):
+        raise TypeError(f"The '{part}' lookup requires a date/time column")
+    if type(value) is not int:
+        raise TypeError(f"The '{part}' lookup requires an integer value")
+    return extract(part, column) == value
+
+
+LOOKUP_OPERATORS = {
+    "exact": lambda column, value: column == value,
+    "year": lambda column, value: _lookup_date_part(column, "year", value),
+    "month": lambda column, value: _lookup_date_part(column, "month", value),
+    "day": lambda column, value: _lookup_date_part(column, "day", value),
+    "hour": lambda column, value: _lookup_date_part(column, "hour", value),
+    "minute": lambda column, value: _lookup_date_part(column, "minute", value),
+    "second": lambda column, value: _lookup_date_part(column, "second", value),
+    "iexact": _lookup_iexact,
+    "gt": lambda column, value: column > value,
+    "gte": lambda column, value: column >= value,
+    "lt": lambda column, value: column < value,
+    "lte": lambda column, value: column <= value,
+    "in": _lookup_in,
+    "not_in": lambda column, value: ~_lookup_in(column, value),
+    "not__in": lambda column, value: ~_lookup_in(column, value),
+    "in_": _lookup_in,
+    "range": _lookup_range,
+    "between": _lookup_range,
+    "isnull": _lookup_isnull,
+}
+
+# Only comparison/pattern operators are accepted as delegated SQLAlchemy methods.
+# Methods such as asc(), desc(), op(), label(), and collate() are intentionally
+# excluded because they do not produce boolean predicates.
+STANDARD_LOOKUPS = frozenset(
+    {
+        "like",
+        "ilike",
+        "not_like",
+        "not_ilike",
+        "contains",
+        "icontains",
+        "startswith",
+        "endswith",
+        "istartswith",
+        "iendswith",
+        "match",
+        "regexp_match",
+        "is_",
+        "is_not",
+        "is_distinct_from",
+        "isnot_distinct_from",
+    }
+)
+
+FORBIDDEN_COLUMN_ATTRS = {
+    "metadata",
+    "table",
+    "expression",
+    "comparator",
+}
+
+
+__all__ = [
+    "annotations",
+    "Iterable",
+    "Mapping",
+    "Any",
+    "extract",
+    "func",
+    "literal",
+    "SelectBase",
+    "Date",
+    "DateTime",
+    "Time",
+]

async_orm_kit/query/lookups/conditions.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy.exc import ArgumentError
+
+from async_orm_kit.exceptions import (
+    FilterError,
+    InvalidLookupError,
+    InvalidRelationshipValueError,
+)
+from async_orm_kit.query.lookups import (
+    FORBIDDEN_COLUMN_ATTRS,
+    LOOKUP_OPERATORS,
+    STANDARD_LOOKUPS,
+)
+from async_orm_kit.query.lookups.resolver.context import ResolverContext
+
+if TYPE_CHECKING:
+    from async_orm_kit.query.relations.node import JoinNode
+
+
+class ConditionBuilder:
+    """Builds SQLAlchemy filter conditions from resolved columns and lookup operators.
+
+    ConditionBuilder is responsible for the final step of filter construction: taking
+    a resolved column, a lookup operator, and a value, then producing a SQLAlchemy
+    boolean expression. It handles custom lookup operators (in, range, isnull),
+    standard SQLAlchemy column operators (==, !=, <, >, etc.), and special value
+    types (F expressions, QuerySets, Case/Value).
+
+    This class follows the Single Responsibility Principle by focusing solely on
+    condition building. It does NOT handle field resolution (that's FieldResolver's
+    job) or filter parsing (that's FilterParser's job). It receives already-resolved
+    columns and produces ready-to-use SQLAlchemy clauses.
+
+    The builder validates lookup operators before use, ensuring they're not private
+    attributes, not in the forbidden list, exist on the column, are callable, and
+    are valid SQLAlchemy operators. It also handles nullable checks for LEFT JOIN
+    optimization and resolves special value types like F() and QuerySet subqueries.
+
+    Args:
+        field_resolver: Any instance for resolving F expressions and other
+        special value types that reference database fields.
+
+    Note:
+        ConditionBuilder is typically used internally by FilterParser and QueryBuilder.
+        Direct usage is rare unless you're building custom query compilation logic.
+
+        The builder maintains a reference to FieldResolver to resolve F expressions
+        and other field references that appear in filter values. This ensures consistent
+        join tracking across the entire query.
+    """
+
+    def __init__(self, field_resolver: Any):
+        """Initialize ConditionBuilder with field resolver.
+
+        Args:
+            field_resolver: Any instance for resolving F expressions and
+                           field references in filter values.
+        """
+        self.field_resolver = field_resolver
+
+    def build(
+        self,
+        column,
+        lookup: str,
+        value: Any,
+        join_node: JoinNode | None = None,
+        context: ResolverContext | None = None,
+    ):
+        """Build SQLAlchemy condition from resolved column, lookup, and value.
+        Constructs a SQLAlchemy boolean expression by applying the lookup operator
+        to the column with the given value. Handles three categories of lookups:
+
+        1. Custom lookups (in, range, isnull, etc.) via LOOKUP_OPERATORS registry
+        2. Standard SQLAlchemy operators (__eq__, __ne__, __lt__, __gt__, etc.)
+        3. Special value types (F expressions, QuerySets, Case/Value)
+
+        The method validates the lookup operator, resolves special value types,
+        marks nullable checks for JOIN optimization, and handles relationship
+        validation errors with helpful messages.
+
+        Args:
+            column: SQLAlchemy Column or InstrumentedAttribute to filter on.
+            lookup: Lookup operator string (e.g., "__eq__", "in", "gte", "isnull").
+            value: Filter value - can be scalar, list, F(), QuerySet, Case, Value, etc.
+            join_node: Optional JoinNode for tracking nullable checks that affect
+                      JOIN type selection (INNER vs LEFT).
+
+        Returns:
+            SQLAlchemy BinaryExpression or BooleanClauseList representing the filter
+            condition, ready to be added to a WHERE clause.
+
+        Raises:
+            InvalidLookupError: Lookup operator is not supported, forbidden, or nota valid SQLAlchemy operator.
+            InvalidRelationshipValueError: Value type is incompatible with relationshipfield (e.g., passing int instead of model
+                                          instance).
+            FilterError: General condition building failure, including SQLAlchemy
+                        ArgumentError or unexpected exceptions.
+
+        Note:
+            Performance is O(1) for lookup validation and value resolution. The actual
+            SQLAlchemy expression construction cost depends on the complexity of the
+            value (e.g., nested F expressions or subqueries).Nullable checks (isnull=True)
+            mark the join_node to prevent INNER JOIN
+            optimization, ensuring NULL values are included in results. This is
+            critical for correct LEFT JOIN behavior.
+        """
+        context = context or ResolverContext()
+        self._mark_nullable_checks(join_node, lookup, value)
+        value = self._resolve_value(value, context=context)
+
+        try:
+            # Application-installed lookups are per-QuerySet, never global.
+            custom_lookups = self.field_resolver.query_state.custom_lookups
+            if lookup in custom_lookups:
+                from sqlalchemy.sql.elements import ColumnElement
+                from sqlalchemy.sql.sqltypes import Boolean
+
+                result = custom_lookups[lookup](column, value)
+                if not isinstance(result, ColumnElement) or not isinstance(
+                    result.type, Boolean
+                ):
+                    raise InvalidLookupError(
+                        f"Custom lookup {lookup!r} must return a SQL boolean expression",
+                        lookup=lookup,
+                        field_name=getattr(column, "key", "<expression>"),
+                    )
+                return result
+
+            # Built-in lookup operators (in, range, isnull, etc.)
+            if lookup in LOOKUP_OPERATORS:
+                return LOOKUP_OPERATORS[lookup](column, value)
+
+            # Standard SQLAlchemy column operators (==, !=, <, >, etc.)
+            self._validate_lookup(lookup, column)
+            return getattr(column, lookup)(value)
+
+        except (FilterError, InvalidLookupError, InvalidRelationshipValueError):
+            raise
+
+        except ArgumentError as e:
+            if "mapped instance expected" in str(e).lower():
+                column_name = getattr(
+                    column, "key", getattr(column, "name", str(column))
+                )
+                raise InvalidRelationshipValueError(
+                    f"Invalid value '{value!r}' for relationship '{column_name}' "
+                    f"(lookup: '{lookup}'). Expected a mapped model instance, "
+                    f"got {type(value).__name__}.",
+                    value=value,
+                    field_name=column_name,
+                ) from e
+            raise FilterError(
+                f"Error building condition for lookup '{lookup}': {e}"
+            ) from e
+
+        except Exception as e:
+            raise FilterError(
+                f"Error building condition for lookup '{lookup}': {e}"
+            ) from e
+
+    def _resolve_value(
+        self,
+        value: Any,
+        context: ResolverContext | None = None,
+    ) -> Any:
+        """Resolve special value types to SQLAlchemy expressions.
+
+        Handles three categories of special values that require resolution before
+        being used in filter conditions:
+
+        1. F/FExpression - Field references that resolve to columns
+        2. Value/Case - Literal wrappers and conditional expressions
+        3. QuerySet - Subqueries that resolve to SELECT statements
+
+        All other value types (scalars, lists, model instances, etc.) pass through
+        unchanged. This method ensures that complex value types are properly converted
+        to SQLAlchemy expressions that can be used in WHERE clauses.
+
+        Args:
+            value: Filter value to resolve. Can be F, FExpression, Value, Case,QuerySet, or any scalar/collection type.
+
+        Returns:
+            SQLAlchemy expression if value is a special type, otherwise the original
+            value unchanged.
+
+        Example:
+            >>> # F expression resolution
+            >>> f_expr = F("cost") * 1.5
+            >>> resolved = builder._resolve_value(f_expr)
+            >>> # Returns: products.cost * 1.5 (SQLAlchemy expression)
+            >>>
+            >>> # QuerySet subquery resolution
+            >>> subquery = Product.objects.filter(category="electronics")
+            >>> resolved = builder._resolve_value(subquery)
+            >>> # Returns: SELECT ... FROM products WHERE category = 'electronics'
+            >>>
+            >>> # Scalar pass-through
+            >>> resolved = builder._resolve_value(100)
+            >>> # Returns: 100 (unchanged)
+            >>>
+            >>> # List pass-through
+            >>> resolved = builder._resolve_value([1, 2, 3])
+            >>> # Returns: [1, 2, 3] (unchanged)
+        Note:
+            Resolution is recursive for nested expressions. For example, an F expression
+            containing another F expression will resolve both levels. QuerySet resolution
+            triggers full query compilation, including joins and subquery optimization.
+        """
+        from async_orm_kit.query.expressions import Case, F, FExpression, Value
+        from async_orm_kit.queryset.queryset import QuerySet
+
+        context = context or ResolverContext()
+
+        if isinstance(value, (F, FExpression)):
+            return value.resolve(self.field_resolver, context=context)
+
+        if isinstance(value, (Value, Case)):
+            return value.resolve(self.field_resolver, context=context)
+
+        from async_orm_kit.query.mixins.combinable import CombinableMixin
+
+        if isinstance(value, CombinableMixin) and hasattr(value, "resolve"):
+            return value.resolve(self.field_resolver, context=context)
+
+        if isinstance(value, QuerySet):
+            from sqlalchemy import inspect as sa_inspect
+
+            from async_orm_kit.exceptions import QueryStateError
+
+            state = value._state.clone()
+            state.select_related.clear()
+            state.prefetch_related.clear()
+            if state.values_select is not None:
+                if len(state.values_select) != 1 or state.annotations:
+                    raise QueryStateError("Subquery must select exactly one column")
+                column = state.values_select[0][1]
+            elif state.values_list_select is not None:
+                if len(state.values_list_select) != 1 or state.annotations:
+                    raise QueryStateError("Subquery must select exactly one column")
+                column = state.values_list_select[0][1]
+            else:
+                if state.annotations or state.has_aggregates:
+                    raise QueryStateError(
+                        "Annotated subqueries require an explicit single-column projection"
+                    )
+                pk = sa_inspect(value.model).primary_key
+                if len(pk) != 1:
+                    raise QueryStateError(
+                        "Composite-key subqueries require an explicit single-column projection"
+                    )
+                column = getattr(value.model, pk[0].key)
+            compiled = value._compiler.compile(state)
+            return compiled.with_only_columns(
+                column, maintain_column_froms=True
+            ).order_by(None)
+
+        return value
+
+    @staticmethod
+    def _mark_nullable_checks(join_node, lookup: str, value: Any):
+        """Mark join node if nullable check is used to prevent INNER JOIN optimization.
+
+        When filtering with isnull=True, the query must use LEFT JOIN instead of
+        INNER JOIN to include rows where the relationship is NULL. This method marks
+        the join_node to signal the JOIN builder to use LEFT JOIN.
+
+        Args:
+            join_node: JoinNode to mark, or None if no join is involved.
+            lookup: Lookup operator string.
+            value: Filter value.
+
+        Example:
+            >>> # Without marking: INNER JOIN (excludes NULL relationships)
+            >>> Order.objects.filter(customer__name="John")
+            >>> # SELECT * FROM orders INNER JOIN customers ON ...
+            >>>
+            >>> # With marking: LEFT JOIN (includes NULL relationships)
+            >>> Order.objects.filter(customer__isnull=True)
+            >>> # SELECT * FROM orders LEFT JOIN customers ON ... WHERE customers.id IS NULL
+
+        Note:
+            This is a critical optimization for correct NULL handling. Without this
+            marking, isnull=True filters would incorrectly use INNER JOIN and return
+            empty results.
+        """
+        if join_node and lookup == "isnull" and value is True:
+            join_node.has_nullable_check = True
+
+    @staticmethod
+    def _validate_lookup(lookup: str, column):
+        """Allow only explicitly supported boolean SQLAlchemy operators."""
+        column_name = getattr(column, "key", getattr(column, "name", "<expression>"))
+
+        if (
+            not isinstance(lookup, str)
+            or lookup.startswith("_")
+            or lookup in FORBIDDEN_COLUMN_ATTRS
+            or lookup not in STANDARD_LOOKUPS
+        ):
+            raise InvalidLookupError(
+                f"Unsupported lookup '{lookup}' for field '{column_name}'",
+                lookup=lookup,
+                field_name=column_name,
+            )
+
+        attr = getattr(column, lookup, None)
+        if not callable(attr):
+            raise InvalidLookupError(
+                f"Unsupported lookup '{lookup}' for field '{column_name}'",
+                lookup=lookup,
+                field_name=column_name,
+            )

async_orm_kit/query/lookups/correlated.py

@@ -0,0 +1,86 @@
+"""Join-independent predicates for negated relationship queries.
+
+A LEFT JOIN followed by ``IS NOT TRUE`` negates individual *joined rows*, not
+an entire parent when one of its children matches. Relationship ``has``/``any``
+constructs correlated EXISTS subqueries with root-identity semantics.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import and_, inspect as sa_inspect, or_, true
+
+from async_orm_kit.exceptions import FilterError, ModelAttributeError
+from async_orm_kit.query.lookups.conditions import ConditionBuilder
+from async_orm_kit.query.lookups.parser import FilterParser
+from async_orm_kit.query.lookups.resolver.context import ResolverContext
+from async_orm_kit.query.q import Q
+
+
+def _leaf(key, value, resolver, context):
+    parsed = resolver.parse_field_key(key)
+    if not parsed.relationship_parts:
+        return FilterParser(resolver).parse({key: value}, context=context)[0]
+
+    current = resolver.model
+    chain = []
+    for part in parsed.relationship_parts:
+        relation = sa_inspect(current).relationships.get(part)
+        if relation is None:
+            raise ModelAttributeError(
+                f"Invalid relationship {part!r} on {current.__name__}"
+            )
+        chain.append(getattr(current, part))
+        current = relation.mapper.class_
+
+    if parsed.field_name:
+        if parsed.field_name == "pk":
+            pk = sa_inspect(current).primary_key
+            if len(pk) != 1:
+                raise ModelAttributeError("Composite PK requires an explicit field")
+            attribute = getattr(current, pk[0].key)
+        else:
+            mapper = sa_inspect(current)
+            if parsed.field_name not in mapper.column_attrs:
+                raise ModelAttributeError(
+                    f"{current.__name__} has no mapped column {parsed.field_name!r}"
+                )
+            attribute = getattr(current, parsed.field_name)
+        predicate = ConditionBuilder(resolver).build(
+            attribute, parsed.lookup, value, context=context
+        )
+    else:
+        # Existence-only relation checks (e.g. exclude(posts__isnull=False))
+        if value is None:
+            predicate = true()
+        else:
+            raise FilterError(
+                "Negated relationship predicates require a terminal field; "
+                "use relation__pk or an explicit isnull lookup"
+            )
+
+    for relationship in reversed(chain):
+        predicate = (
+            relationship.any(predicate)
+            if relationship.property.uselist
+            else relationship.has(predicate)
+        )
+    return predicate
+
+
+def resolve_q(q: Q, resolver, context: ResolverContext):
+    """Resolve Q with correlated EXISTS for paths involving relationships."""
+    if not q.children:
+        return None
+    expressions = []
+    for child in q.children:
+        if isinstance(child, Q):
+            expr = resolve_q(child, resolver, context)
+            if expr is not None:
+                expressions.append(expr)
+        else:
+            _, key, value = child
+            expressions.append(_leaf(key, value, resolver, context))
+    if not expressions:
+        return None
+    result = or_(*expressions) if q.connector == Q.OR else and_(*expressions)
+    return result.is_not(true()) if q.negated else result

async_orm_kit/query/lookups/json_paths.py

@@ -0,0 +1,167 @@
+"""Django-style JSON key/index traversal backed by dialect-aware SQLAlchemy JSON.
+
+Paths are SQLAlchemy bound JSON indexes; user-supplied segments never become SQL
+identifiers. This module deliberately distinguishes scalar lookup operators from
+JSON object/array containment and does not offer a generic JSON ``LIKE`` fallback.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import JSON
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.sql import sqltypes
+from sqlalchemy.sql.elements import ClauseElement
+
+from async_orm_kit.exceptions import InvalidLookupError
+from async_orm_kit.query.expressions.collections import _PostgreSQLOnly
+from async_orm_kit.query.lookups import LOOKUP_OPERATORS, STANDARD_LOOKUPS
+
+_JSONB_LOOKUPS = frozenset(
+    {"contains", "has_key", "has_keys", "has_any_keys", "contained_by"}
+)
+
+
+def json_lookup(
+    column: Any, raw_lookup: str, value: Any, *, resolver=None, context=None
+):
+    """Return a (column, lookup) pair, or a complete JSONB SQL predicate.
+
+    ``payload__user__age__gte=18`` resolves to integer JSON path extraction
+    and a regular comparison; ``payload__tags__0='python'`` resolves to JSON
+    array indexing. JSONB containment/key operators require PostgreSQL JSONB.
+    """
+    if not isinstance(getattr(column, "type", None), JSON):
+        return None
+    if raw_lookup == "exact":
+        return None
+    parts = raw_lookup.split("__")
+    if any(not part for part in parts):
+        raise InvalidLookupError(
+            "JSON path segments cannot be empty", lookup=raw_lookup, field_name="<json>"
+        )
+
+    # Non-path JSONB operators must not be interpreted as string operations.
+    operation = parts[-1]
+    if operation in _JSONB_LOOKUPS and (
+        operation != "contains" or isinstance(value, (dict, list))
+    ):
+        path_parts, operator = parts[:-1], operation
+    elif operation in LOOKUP_OPERATORS or operation in STANDARD_LOOKUPS:
+        path_parts, operator = parts[:-1], operation
+    else:
+        path_parts, operator = parts, "exact"
+
+    path = tuple(int(part) if part.isdecimal() else part for part in path_parts)
+    selected = column[path[0] if len(path) == 1 else path] if path else column
+
+    if operator in _JSONB_LOOKUPS and (
+        operator != "contains" or isinstance(value, (dict, list))
+    ):
+        if not isinstance(getattr(selected, "type", None), JSONB):
+            raise InvalidLookupError(
+                f"The JSON '{operator}' lookup requires a PostgreSQL JSONB column",
+                lookup=operator,
+                field_name="<json>",
+            )
+        if operator == "has_key" and (not isinstance(value, str) or not value):
+            raise TypeError("JSONB has_key requires a nonempty string")
+        if operator in {"has_keys", "has_any_keys"} and (
+            not isinstance(value, (tuple, list))
+            or not value
+            or any(not isinstance(key, str) or not key for key in value)
+        ):
+            raise TypeError("JSONB key lookup requires a nonempty sequence of strings")
+        method = {"has_keys": "has_all", "has_any_keys": "has_any"}.get(
+            operator, operator
+        )
+        return _PostgreSQLOnly(getattr(selected, method)(value))
+
+    if not path:
+        # The root is a JSON document, not a string; reject accidental
+        # substring matching which otherwise silently casts JSON to text.
+        if operator in {
+            "contains",
+            "like",
+            "ilike",
+            "icontains",
+            "startswith",
+            "istartswith",
+            "endswith",
+            "iendswith",
+            "match",
+            "regexp_match",
+        }:
+            raise InvalidLookupError(
+                "Use an explicit JSON path or JSONPath(..., as_type='string') for text lookups",
+                lookup=operator,
+                field_name="<json>",
+            )
+        return selected, operator
+
+    # SQLAlchemy's JSON comparators preserve the native dialect-specific
+    # extraction semantics. No SQL fragments are built from path elements.
+    if operator == "isnull":
+        return selected.as_string(), operator
+    # Expressions such as F('score') are not Python int/str instances.
+    # Infer the JSON scalar extractor from their resolved SQLAlchemy type,
+    # otherwise SQLite JSON_QUOTE could compare text against a numeric field.
+    sql_operand = None
+    if callable(getattr(value, "resolve", None)) and resolver is not None:
+        sql_operand = value.resolve(resolver, context)
+    elif isinstance(value, ClauseElement):
+        sql_operand = value
+    if sql_operand is not None:
+        operand_type = getattr(sql_operand, "type", None)
+        if isinstance(operand_type, sqltypes.Boolean):
+            return selected.as_boolean(), operator
+        if isinstance(operand_type, sqltypes.Integer):
+            return selected.as_integer(), operator
+        if isinstance(operand_type, (sqltypes.Float, sqltypes.Numeric)):
+            return selected.as_float(), operator
+        if isinstance(operand_type, sqltypes.String):
+            return selected.as_string(), operator
+        raise InvalidLookupError(
+            "JSON comparison expression needs an explicit typed JSONPath annotation",
+            lookup=operator,
+            field_name="<json>",
+        )
+    if operator in {"in", "not_in", "not__in", "in_", "range", "between"}:
+        # Membership/range values determine the JSON extractor's scalar type,
+        # never the Python collection wrapper itself.
+        candidate = (
+            next(iter(value), None) if isinstance(value, (list, tuple)) else None
+        )
+        if isinstance(candidate, bool):
+            return selected.as_boolean(), operator
+        if isinstance(candidate, int):
+            return selected.as_integer(), operator
+        if isinstance(candidate, float):
+            return selected.as_float(), operator
+        if isinstance(candidate, str):
+            return selected.as_string(), operator
+    if isinstance(value, bool):
+        return selected.as_boolean(), operator
+    if isinstance(value, int):
+        return selected.as_integer(), operator
+    if isinstance(value, float):
+        return selected.as_float(), operator
+    if isinstance(value, str) or operator in {
+        "icontains",
+        "contains",
+        "startswith",
+        "istartswith",
+        "endswith",
+        "iendswith",
+        "like",
+        "ilike",
+        "iexact",
+    }:
+        return selected.as_string(), operator
+    if value is None and operator == "exact":
+        return selected.as_string(), operator
+    return selected.as_json(), operator
+
+
+__all__ = ["json_lookup"]