hare-orm 0.9.0__py3-none-any.whl

hare/query/expressions/constants.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from uuid import UUID
+
+from hare.query.enums import Lookup
+from hare.sql.types.sql_types import SqlTypes
+
+#: `max_digits` of the shared DecimalField a Decimal-typed expression result (a literal, or
+#: arithmetic involving one) is decoded through - generous enough to never reject a real result.
+DECIMAL_OUTPUT_FIELD_MAX_DIGITS = 1000
+
+
+#: Lookup suffixes whose value is a list of values - any other iterable is materialized into one.
+LIST_LOOKUP_SUFFIXES = ("__in", "__not_in")
+#: The lookup suffix of a two-bound range - a bound left None opens it on its side.
+RANGE_LOOKUP_SUFFIX = "__range"
+#: The lookup suffix of a JSON filter dict - its keys name the path and the operator.
+JSON_FILTER_LOOKUP_SUFFIX = "__filter"
+#: The suffixes of filter keys whose value a plan found by the calls doesn't bind one to one,
+#: whatever its type - a list lookup, and a JSON ``__filter`` dict described by its shape.
+CALL_SIGNATURE_DESCRIBED_KEY_SUFFIXES = (*LIST_LOOKUP_SUFFIXES, JSON_FILTER_LOOKUP_SUFFIX)
+#: The types of the most frequent plain values - no container, expression or SQL term - told
+#: apart by their type alone, without an ``isinstance()`` check on a hot path.
+PLAIN_VALUE_TYPES = frozenset({int, str, float, Decimal, bytes, date, datetime, time, timedelta, UUID})
+
+#: The structure of an ``__in``/``__not_in`` list bound as one parameter, in place of its length.
+LONG_IN_LIST_STRUCTURE = "one parameter"
+
+#: The structure of a None argument - a CASE branch, a function or window argument - written as
+#: NULL, never bound.
+NULL_ARGUMENT_STRUCTURE = ("null",)
+
+#: Lookup suffixes whose boolean value picks the SQL text (``IS NULL`` or ``IS NOT NULL``) rather
+#: than a parameter.
+ISNULL_LOOKUP_SUFFIXES = ("__isnull", "__not_isnull")
+
+#: Lookups on a to-many relation's own name (``tags=``, ``tags__in=``, ...) resolved as the same
+#: lookup on the related primary key (``tags__id=``, ``tags__id__in=``, ...).
+TO_MANY_RELATION_SHORTCUT_LOOKUPS = (
+    Lookup.EXACT,
+    Lookup.NOT,
+    Lookup.IN,
+    Lookup.NOT_IN,
+    Lookup.ISNULL,
+    Lookup.NOT_ISNULL,
+)
+
+#: Lookups of ``TO_MANY_RELATION_SHORTCUT_LOOKUPS`` a many-to-many relation resolves on its own, as
+#: a correlated ``[NOT] EXISTS``.
+MANY_TO_MANY_EXISTS_LOOKUPS = (Lookup.ISNULL, Lookup.NOT_ISNULL)
+
+
+#: The lookups comparing two values - equality and order: a date is compared with a timestamp as the
+#: first moment of its day, as a date literal is, and a Decimal column with an expression of another
+#: number by its value.
+VALUE_COMPARISON_LOOKUPS = frozenset({Lookup.EXACT, "exact", Lookup.NOT, Lookup.GT, Lookup.GTE, Lookup.LT, Lookup.LTE})
+
+#: A comparison lookup to the one giving the same result with its two sides swapped.
+MIRRORED_COMPARISON_LOOKUPS: dict[str, str] = {
+    "": "",
+    "exact": "exact",
+    "not": "not",
+    "gt": "lt",
+    "gte": "lte",
+    "lt": "gt",
+    "lte": "gte",
+}
+
+# The SQL type a float/Decimal literal operand is cast to: a database would otherwise infer the
+# parameter's type from the other operand, and `F("n_int") + 0.5` would bind 0.5 as an integer.
+LITERAL_CAST_SQL_TYPE: dict[type, str] = {
+    float: SqlTypes.FLOAT,
+    Decimal: SqlTypes.NUMERIC,
+}
+
+#: The integers a database reads a bare integer literal as - its type taken from the column beside it,
+#: a 32-bit integer at least; one beyond is cast to a 64-bit integer, and one beyond that to a number.
+INTEGER_LITERAL_RANGE = (-(2**31), 2**31 - 1)
+BIG_INTEGER_LITERAL_RANGE = (-(2**63), 2**63 - 1)
+
+RAW_SQL_TOKEN_RE = re.compile(r"%%|%s")
+
+#: The levels a list, tuple or dict given as a value (``Value()``, a ``RawSQL`` parameter) may nest -
+#: the depth a JSON text is written to; a value holding itself nests without end.
+VALUE_PARAMETER_MAX_DEPTH = 255
+
+#: The origin a reference no later query can bind is recorded under (``PlanOrigins``) - a value
+#: of a query built into another one keeping no plan, a SQL term binding a value no term holds: the
+#: query keeps no plan.
+UNBINDABLE_VALUE_ORIGIN = "unbindable"
+
+
+#: The name of a ``JsonTable`` column - a Python identifier without ``__``.
+JSON_TABLE_COLUMN_NAME_PATTERN = re.compile(r"(?!.*__)[A-Za-z_][A-Za-z0-9_]*")
+
+#: The JSON path a ``JsonTable`` column reads when it names none - the item's key of its name.
+JSON_TABLE_DEFAULT_COLUMN_PATH = "$.{name}"
+
+#: The recursive CTE ``with_recursive()`` walks a relation in, its depth column, and the aliases of the
+#: model's table in its base case and in its step.
+RECURSIVE_ROWS_CTE_NAME = "hare_recursive_rows"
+
+RECURSIVE_ROWS_DEPTH_COLUMN = "hare_depth"
+
+RECURSIVE_ROWS_START_ALIAS = "hare_recursive_start"
+
+RECURSIVE_ROWS_PREVIOUS_ALIAS = "hare_recursive_previous"
+
+#: The largest ``with_recursive(max_depth=...)`` taken.
+MAX_RECURSIVE_DEPTH = 100_000
+
+#: The annotation a filter on a column of a named JOIN (``Lateral``, ``merge()``'s source row) reads the
+#: column under.
+NAMED_COLUMN_FILTER_ANNOTATION = "hare_named_column"
+
+#: No SQL type of any Python type - a literal cast only for its own range.
+NO_CAST_SQL_TYPES: dict[type, str] = {}

hare/query/expressions/declarations.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from hare.query.expressions.expression import Expression
+from hare.query.plans.description.declared_plan_parts import DeclaredPlanParts
+
+
+class ConstantExpression(Expression):
+    """An expression whose SQL text takes no value - ``PI()``, the current moment."""
+
+    plan_parts: ClassVar[DeclaredPlanParts] = ()

hare/query/expressions/enums.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ArithmeticOperator(StrEnum):
+    """Arithmetic operator connecting two expressions - each value is the corresponding
+    attribute name on the stdlib `operator` module (see TemporalArithmetic.build_term())."""
+
+    ADD = "add"
+    SUB = "sub"
+    MUL = "mul"
+    DIV = "truediv"
+    POW = "pow"
+    MOD = "mod"
+
+
+class WindowFrameUnit(StrEnum):
+    """What a window frame's offsets count - rows, or ordering values."""
+
+    ROWS = "ROWS"
+    RANGE = "RANGE"
+
+
+class TemporalType(StrEnum):
+    """Type of date/time value an arithmetic operand holds."""
+
+    DATETIME = "datetime"
+    DATE = "date"
+    TIME = "time"
+    TIMEDELTA = "timedelta"
+
+
+class NumericValueType(StrEnum):
+    """Type of number an expression's value is."""
+
+    INTEGER = "integer"
+    FLOAT = "float"
+    DECIMAL = "decimal"

hare/query/expressions/expression.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Self
+
+from hare.classes.class_path import ClassPath
+from hare.fields.field import Field
+from hare.query.plans.description.plannable import Plannable
+from hare.query.query_connection import QueryConnection
+
+if TYPE_CHECKING:
+    from hare.query.statements.awaitable_query import AwaitableQuery
+from hare.query.expressions.expression_context import ExpressionContext
+from hare.query.expressions.expression_result import ExpressionResult
+from hare.query.expressions.ordering import Ordering
+
+
+class Expression(Plannable, abstract=True):
+    """The base of the expressions of a query - what resolves to a term of its SQL against a model."""
+
+    #: The arguments the expression was constructed with - see ``deconstruct()``.
+    _constructor_arguments: tuple[tuple[Any, ...], dict[str, Any]]
+
+    unplanned_attributes = ("_constructor_arguments",)
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
+        """Creates the expression and keeps the arguments it was constructed with, for
+        ``deconstruct()``.
+
+        Args:
+            *args: The constructor's positional arguments.
+            **kwargs: The constructor's keyword arguments.
+
+        Returns:
+            The new expression.
+        """
+        expression = super().__new__(cls)
+        expression._constructor_arguments = (args, kwargs)
+        return expression
+
+    def deconstruct(self) -> tuple[str, list[Any], dict[str, Any]]:
+        """Returns how a migration file rebuilds the expression - its class path and the arguments
+        it was constructed with - so a migration keeps the expression itself, and the database a
+        migration runs on renders its own SQL for it.
+
+        Returns:
+            The path, positional arguments and keyword arguments.
+        """
+        args, kwargs = self.__dict__.get("_constructor_arguments", ((), {}))
+        return ClassPath.get(type(self)), list(args), dict(kwargs)
+
+    def __repr__(self) -> str:
+        args, kwargs = self.__dict__.get("_constructor_arguments", ((), {}))
+        arguments = [*map(repr, args), *(f"{name}={value!r}" for name, value in kwargs.items())]
+        return f"{type(self).__name__}({', '.join(arguments)})"
+
+    def get_result(self, expression_context: ExpressionContext) -> ExpressionResult:
+        """Resolves the expression against a query: its term, the joins it needs and the field its value is
+        read by.
+
+        Args:
+            expression_context: The context of the query.
+
+        Returns:
+            The result.
+        """
+        raise NotImplementedError()
+
+    def asc(self, *, nulls_first: bool = False, nulls_last: bool = False) -> Ordering:
+        """Ascending ordering by this expression's value, for ``.order_by()``/``Meta.ordering``/
+        ``Window(order_by=...)``/an ordered aggregate/an index's keys.
+
+        Args:
+            nulls_first: Place NULLs before every other value on any dialect.
+            nulls_last: Place NULLs after every other value on any dialect.
+
+        Raises:
+            QueryError: If both flags are set.
+        """
+        return Ordering.build(self, is_ascending=True, nulls_first=nulls_first, nulls_last=nulls_last)
+
+    def desc(self, *, nulls_first: bool = False, nulls_last: bool = False) -> Ordering:
+        """Descending ordering by this expression's value - see ``asc()``.
+
+        Args:
+            nulls_first: Place NULLs before every other value on any dialect.
+            nulls_last: Place NULLs after every other value on any dialect.
+
+        Raises:
+            QueryError: If both flags are set.
+        """
+        return Ordering.build(self, is_ascending=False, nulls_first=nulls_first, nulls_last=nulls_last)
+
+    #: The field of the value an expression computes when it is always of one type - a count, an
+    #: extracted date part; None when it follows the expression's arguments.
+    value_field: ClassVar[Any] = None
+
+    def get_value_field(self, result: ExpressionResult) -> Field[Any] | None:
+        """The field whose type the value this expression computes actually has - ``value_field``
+        for an expression whose result always has one type.
+
+        Args:
+            result: This expression's own resolve result.
+
+        Returns:
+            The result's output field by default; a subclass whose output field only mirrors its
+            argument's (and isn't the type of its own result) returns None instead.
+        """
+        if self.value_field is not None:
+            return self.value_field
+        return result.output_field
+
+    @staticmethod
+    def _get_wrapped_query(wrapped_query: AwaitableQuery[Any], expression_context: ExpressionContext) -> Any:
+        """Returns the query a ``Subquery(...)``/``Exists(...)`` wraps, bound to the connection the
+        outer query runs on.
+
+        Args:
+            wrapped_query: The wrapped query.
+            expression_context: The context the outer query is compiled in.
+
+        Returns:
+            A copy of the wrapped query bound to the outer query's connection.
+
+        Raises:
+            QueryError: The wrapped query is pinned to another connection than the outer query's.
+        """
+        return QueryConnection.get_bound_to(
+            wrapped_query, expression_context.connection, expression_context.model, "Subquery(...)/Exists(...)"
+        )

hare/query/expressions/expression_context.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field as dataclass_field
+from typing import TYPE_CHECKING, Any
+
+from hare.query.expressions.value_references.value_reference_types import RecordedValueReferences
+from hare.query.scopes.row_visibility import RowVisibility
+from hare.sql import Table
+
+if TYPE_CHECKING:
+    from hare.dialects.base.client.database_client import DatabaseClient
+    from hare.dialects.base.dialect import Dialect
+    from hare.models import Model
+    from hare.query.expressions.aggregate_paths.aggregated_multi_valued_paths import AggregatedMultiValuedPaths
+    from hare.query.expressions.conditions.q import Q
+
+
+@dataclass(frozen=True)
+class ExpressionContext:
+    """What an expression resolves against: the query's model, table and annotations, the dialect and the
+    state the expressions of one build share."""
+
+    model: type[Model]
+    table: Table
+    annotations: dict[str, Any]
+    # Set by a query recording its plan: every filter kwarg, literal and cursor value resolved
+    # appends `(key, value reference | None)` - a reference when the built term took a form a plan
+    # can bind a new value into, None otherwise (the query is then built in full every time). None
+    # here means nothing is recorded.
+    value_wrapper_references: RecordedValueReferences | None = None
+    # Select(relation, extra_condition=Q(...)) conditions by dotted relation path - a nested filter
+    # crossing such a relation builds its JOIN with the condition, since the JOIN built first is the
+    # one kept.
+    select_related_extra_conditions: Mapping[str, Q] | None = None
+    # The dotted relation path walked to reach this resolve - a multi-hop nested filter matches an
+    # extra_condition registered under the full path.
+    select_related_path_prefix: str = ""
+    # Whether a filter on a Window(...) annotation resolves to its window function term instead
+    # of raising - set for a query that applies such filters to itself wrapped as a derived table
+    # (.values()/.values_list()), and for a When(...) condition, which is valid in SELECT.
+    window_function_filter_allowed: bool = False
+    # Shared by the filters of one build: a to-many relation's dotted path to the .filter() call
+    # generation that took its plain join alias. A later, different generation over the same path
+    # gets a JOIN of its own.
+    multi_valued_join_generations: dict[str, int] | None = None
+    # Shared by the same build: the to-many relations the aggregate annotations crossed. Annotations
+    # resolve before filters, so a filter about to split such a relation into a second JOIN - which
+    # the aggregate wouldn't see - is detected.
+    aggregated_multi_valued_paths: AggregatedMultiValuedPaths | None = None
+    # The visibility of the query being resolved - every JOIN to a related model is scoped by it. A
+    # context built further down passes it on unchanged.
+    visibility: RowVisibility = RowVisibility.DEFAULT
+    # The annotations being resolved up the chain, shared by it - an annotation referencing itself
+    # through another raises QueryError instead of recursing forever.
+    annotation_names_in_progress: set[str] = dataclass_field(default_factory=set)
+    # Whether the expression is a value written into a column - its integer arithmetic is then left to
+    # the database, which wraps the result into the column's type; a read result is widened and checked.
+    writes_column_value: bool = False
+    #: The dialect the expressions compile for.
+    dialect: Dialect = dataclass_field(kw_only=True)
+    #: The connection the query runs on; None when compiling DDL or SQL for no particular database.
+    connection: DatabaseClient | None = dataclass_field(kw_only=True)

hare/query/expressions/expression_result.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field as dataclass_field
+from itertools import chain
+from typing import Any
+
+from hare.fields.field import Field
+from hare.sql import Table
+from hare.sql.enums import Order
+from hare.sql.terms.criteria.criterion import Criterion
+from hare.sql.terms.term import Term
+
+#: One JOIN: the table joined and the ON criterion.
+TableCriterionTuple = tuple[Table, Criterion]
+
+
+@dataclass
+class ExpressionResult:
+    """What an expression resolves to: its term, the joins it needs and the field its value is read by."""
+
+    term: Term
+    joins: list[TableCriterionTuple] = dataclass_field(default_factory=list)
+    output_field: Field[Any] | None = None
+    #: The ``FILTER (WHERE ...)`` condition of an aggregate's resolved argument (``_filter=``).
+    aggregate_filter: Criterion | None = None
+    #: The order an aggregate reads its rows in (``order_by=``), each term with its direction.
+    aggregate_orderings: list[tuple[Term, Order | None]] = dataclass_field(default_factory=list)
+
+    @staticmethod
+    def dedup_joins(*joins: Iterable[TableCriterionTuple]) -> list[TableCriterionTuple]:
+        """Merges any number of join-tuple collections into one deduplicated list, keeping the
+        order they are given in - a JOIN can read the table of an earlier one.
+
+        Args:
+            joins: The collections of ``(table, criterion)`` joins.
+
+        Returns:
+            The joins, each once.
+        """
+        return list(dict.fromkeys(chain.from_iterable(joins)))

hare/query/expressions/f.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from hare.exceptions import FieldError, QueryError
+from hare.fields.data.json.json_field import JSONField
+from hare.fields.encrypted.encrypted_json_field import EncryptedJSONField
+from hare.fields.relations.fields.relational_field import RelationalField
+from hare.query.expressions.aggregate_paths.aggregated_multi_valued_paths import AggregatedMultiValuedPaths
+from hare.query.expressions.arithmetic.combinable_expression import CombinableExpression
+from hare.query.expressions.expression import Expression
+from hare.query.expressions.expression_context import ExpressionContext
+from hare.query.expressions.expression_result import ExpressionResult, TableCriterionTuple
+from hare.query.expressions.joins.named_join import NamedJoin
+from hare.query.expressions.ordering import Ordering
+from hare.query.filters.lookups.json.json_filter_parser import JsonFilterParser
+from hare.query.lookup_info.lookup_paths import LookupPaths
+from hare.query.lookup_info.value_paths import ValuePaths
+from hare.query.plans.description.declared_plan_parts import DeclaredPlanParts
+from hare.query.plans.enums import PlanPartType
+from hare.sql.terms.term import Term
+
+if TYPE_CHECKING:
+    from hare.fields.field import Field
+
+
+class F(CombinableExpression):
+    """A reference to a model field (``F("id")``), a field of a related model
+    (``F("related__field")``), an annotation, or a path into a JSON field's value
+    (``F("data__owner__name")``, ``F("data__0")``).
+
+    Args:
+        name: The name of the field to reference.
+    """
+
+    # A bare reference to a model column has that column's own type - its value is decoded
+    # through the field's from_db_value(), exactly like the same column in .values().
+    populate_field_object = True
+    plan_parts: ClassVar[DeclaredPlanParts] = (("name", PlanPartType.KEY),)
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __eq__(self, other: object) -> bool:
+        return type(other) is type(self) and cast("F", other).name == self.name
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.name))
+
+    def __repr__(self) -> str:
+        return f"F({self.name!r})"
+
+    def get_value_field(self, result: ExpressionResult) -> Field[Any] | None:
+        """The field whose type the referenced value has - a relation's own name reads the
+        related model's primary key.
+
+        Args:
+            result: This reference's own resolve result.
+
+        Returns:
+            The referenced column's field, or None when the reference has no model field.
+        """
+        output_field = result.output_field
+        if isinstance(output_field, RelationalField):
+            return output_field.related_model._meta.pk
+        return output_field
+
+    def is_json_path_of(self, annotation: Any) -> bool:
+        """Whether this path into a JSON annotation isn't an annotation of its own name - none, or
+        the path itself registered by ``values()``/``order_by()``."""
+        return annotation is None or (isinstance(annotation, F) and annotation.name == self.name)
+
+    def asc(self, *, nulls_first: bool = False, nulls_last: bool = False) -> Ordering:
+        """
+        Ascending ordering by this reference, for ``.order_by()``/``.latest()``/``.earliest()``/``Meta.ordering``.
+
+        Args:
+            nulls_first: Place NULLs before every other value on any dialect.
+            nulls_last: Place NULLs after every other value on any dialect. With neither flag the
+                dialect's own default applies (``Features.sorts_nulls_first``).
+
+        Raises:
+            QueryError: If both flags are set.
+        """
+        return Ordering.build(self.name, is_ascending=True, nulls_first=nulls_first, nulls_last=nulls_last)
+
+    def desc(self, *, nulls_first: bool = False, nulls_last: bool = False) -> Ordering:
+        """
+        Descending ordering by this reference, for ``.order_by()``/``.latest()``/``.earliest()``/``Meta.ordering``.
+
+        Args:
+            nulls_first: Place NULLs before every other value on any dialect.
+            nulls_last: Place NULLs after every other value on any dialect. With neither flag the
+                dialect's own default applies (``Features.sorts_nulls_first``).
+
+        Raises:
+            QueryError: If both flags are set.
+        """
+        return Ordering.build(self.name, is_ascending=False, nulls_first=nulls_first, nulls_last=nulls_last)
+
+    def get_generic_type_expression(self, expression_context: ExpressionContext) -> Expression | None:
+        """The expression of the type of a generic foreign key the path reads (``target__type``).
+
+        Args:
+            expression_context: The context the reference is resolved in.
+
+        Returns:
+            The ``CASE`` naming the branch set, None for a path reading no such type.
+        """
+        # Local import: the generic foreign key types build Case/Q of this package.
+        from hare.query.generic_foreign_keys.generic_foreign_key_types import GenericForeignKeyTypes
+
+        return GenericForeignKeyTypes.get_type_aliases(expression_context.model, (self.name,)).get(self.name)
+
+    def get_result(self, expression_context: ExpressionContext) -> ExpressionResult:
+        term: Term
+        joins: list[TableCriterionTuple] = []
+        output_field = None
+
+        main_name_part, __, rest_name_parts = self.name.partition("__")
+        relation_alias = expression_context.annotations.get(main_name_part)
+        if isinstance(relation_alias, NamedJoin):
+            # A path through a named JOIN - a FilteredRelation's related field, a Lateral's column.
+            return relation_alias.get_path_result(rest_name_parts, expression_context)
+        if main_name_part in expression_context.model._meta.fetch_fields:
+            # field in the format of "related_field__field" or "related_field__another_rel_field__field"
+            if (tracker := AggregatedMultiValuedPaths.get_from(expression_context)) is not None:
+                tracker.record_lookup(
+                    expression_context.model, self.name, expression_context.select_related_path_prefix
+                )
+            term, joins, output_field = LookupPaths.get_nested_field(
+                expression_context.model,
+                expression_context.table,
+                self.name,
+                visibility=expression_context.visibility,
+                select_related_extra_conditions=expression_context.select_related_extra_conditions,
+                dialect=expression_context.dialect,
+                connection=expression_context.connection,
+            )
+        elif rest_name_parts and (path_split := ValuePaths.get_value_path_split(expression_context.model, self.name)):
+            # A path inside a JSON, array or range field's value, e.g. F("data__a__b"), F("tags__0")
+            # or F("during__startswith") - a JSON path reads the JSON value itself, not its text,
+            # so it's decoded, compared and ordered as JSON.
+            __, path_field, path_segments = path_split
+            column = expression_context.table[expression_context.model._meta.fields_db_projection[main_name_part]]
+            term, output_field = ValuePaths.get_value_path_term(
+                column, path_field, path_segments, self.name, expression_context.dialect
+            )
+        elif (
+            rest_name_parts
+            and main_name_part in expression_context.annotations
+            and self.is_json_path_of(expression_context.annotations.get(self.name))
+        ):
+            # A path into a JSON annotation, e.g. F("summary__total") over annotate(summary=JSONObject(...))
+            annotation_result = F(main_name_part).get_result(expression_context)
+            annotation_field = annotation_result.output_field
+            if not isinstance(annotation_field, JSONField) or isinstance(annotation_field, EncryptedJSONField):
+                raise FieldError(
+                    f"F({self.name!r}): the annotation {main_name_part!r} isn't a JSON value, so it has no "
+                    f"{rest_name_parts!r} path"
+                )
+            term = JsonFilterParser.get_field_path(
+                annotation_result.term, JsonFilterParser.get_key_parts(rest_name_parts), as_text=False
+            )
+            joins = annotation_result.joins
+            output_field = annotation_field.get_path_value_field()
+        elif self.name in expression_context.annotations:
+            # reference to another annotation, e.g. M.annotate(f1=...).annotate(f2=F("f1")).values('field')
+            if self.name in expression_context.annotation_names_in_progress:
+                raise QueryError(
+                    f"Circular annotation reference detected: {self.name!r} depends on itself "
+                    "(directly or through another annotation)"
+                )
+            expression_context.annotation_names_in_progress.add(self.name)
+            try:
+                annotation = expression_context.annotations[self.name]
+                if isinstance(annotation, Term) and not isinstance(annotation, Expression):
+                    term = annotation
+                else:
+                    referenced_result = annotation.get_result(expression_context)
+                    term = referenced_result.term
+                    # The referenced annotation's own value type - e.g. Length("name") is an
+                    # integer, not its argument's CharField.
+                    output_field = annotation.get_value_field(referenced_result)
+            finally:
+                expression_context.annotation_names_in_progress.discard(self.name)
+        elif rest_name_parts and (type_expression := self.get_generic_type_expression(expression_context)):
+            # The type of a generic foreign key, e.g. F("target__type") - the branch set, as a CASE.
+            return type_expression.get_result(expression_context)
+        else:
+            # a regular model field, e.g. F("id")
+            try:
+                meta = expression_context.model._meta
+                field_name = (
+                    meta.primary_key_attribute
+                    if self.name == "pk" and isinstance(meta.primary_key_attribute, str)
+                    else self.name
+                )
+                # Table-qualified, not a bare HareSqlField(column) - unqualified is ambiguous SQL
+                # the moment any OTHER join in the same query happens to have a same-named
+                # column, even though this F() always meant this specific model's own field.
+                term = expression_context.table[meta.fields_db_projection[field_name]]
+
+                if (output_field := meta.fields_map.get(field_name, None)) and (
+                    function_cast := output_field.get_function_cast(expression_context.dialect)
+                ):
+                    term = function_cast(output_field, term)
+            except KeyError:
+                raise FieldError(
+                    f"There is no non-virtual field {self.name} on Model {expression_context.model.__name__}"
+                ) from None
+        return ExpressionResult(term=term, output_field=output_field, joins=joins)

hare/query/expressions/frames/__init__.py

@@ -0,0 +1,12 @@
+"""The frames of a window function: ``RowRange`` and ``ValueRange``."""
+
+from __future__ import annotations
+
+from hare.query.expressions.frames.declarations import RowRange, ValueRange
+from hare.query.expressions.frames.window_frame import WindowFrame
+
+__all__ = [
+    "RowRange",
+    "ValueRange",
+    "WindowFrame",
+]

hare/query/expressions/frames/constants.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.fields.data.numeric.decimal_field import DecimalField
+from hare.fields.data.numeric.float_field import FloatField
+from hare.fields.data.numeric.int_field import IntField
+from hare.fields.field import Field
+
+#: The largest offset of a window frame edge - a 64-bit integer, the widest a database takes.
+MAX_WINDOW_FRAME_OFFSET = 2**63 - 1
+
+#: The fields a frame of value offsets orders by - the offset is added to and taken from a number.
+VALUE_OFFSET_ORDERING_FIELD_CLASSES: tuple[type[Field[Any]], ...] = (IntField, FloatField, DecimalField)

hare/query/expressions/frames/declarations.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from hare.query.expressions.enums import WindowFrameUnit
+from hare.query.expressions.frames.window_frame import WindowFrame
+
+
+class RowRange(WindowFrame):
+    """A frame of rows - ``ROWS BETWEEN ...``: ``RowRange(start=-2, end=0)`` is the two rows before
+    the current one and the current one."""
+
+    frame_type: ClassVar[WindowFrameUnit] = WindowFrameUnit.ROWS
+
+
+class ValueRange(WindowFrame):
+    """A frame of ordering values - ``RANGE BETWEEN ...``: ``ValueRange(start=-10, end=0)`` is every
+    row whose ordering value is at most 10 below the current row's, the current row's peers
+    included; an offset needs the window ordered by exactly one numeric field."""
+
+    frame_type: ClassVar[WindowFrameUnit] = WindowFrameUnit.RANGE
+    offsets_need_one_ordering: ClassVar[bool] = True