plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/expressions.py

@@ -0,0 +1,1912 @@
+from __future__ import annotations
+
+import copy
+import datetime
+import functools
+import inspect
+from collections import defaultdict
+from decimal import Decimal
+from functools import cached_property
+from types import NoneType
+from typing import TYPE_CHECKING, Any, Protocol, Self, runtime_checkable
+from uuid import UUID
+
+from plain.postgres import fields
+from plain.postgres.constants import LOOKUP_SEP
+from plain.postgres.db import NotSupportedError
+from plain.postgres.dialect import (
+    CURRENT_ROW,
+    FOLLOWING,
+    PRECEDING,
+    UNBOUNDED_FOLLOWING,
+    UNBOUNDED_PRECEDING,
+    combine_expression,
+    quote_name,
+    subtract_temporals,
+    window_frame_range_start_end,
+    window_frame_rows_start_end,
+)
+from plain.postgres.exceptions import EmptyResultSet, FieldError, FullResultSet
+from plain.postgres.query_utils import Q
+from plain.utils.deconstruct import deconstructible
+from plain.utils.hashable import make_hashable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+
+    from plain.postgres.connection import DatabaseConnection
+    from plain.postgres.fields import Field
+    from plain.postgres.lookups import Lookup, Transform
+    from plain.postgres.query import QuerySet
+    from plain.postgres.sql.compiler import SQLCompilable, SQLCompiler
+    from plain.postgres.sql.query import Query
+
+__all__ = [
+    # Core expression classes
+    "F",
+    "Value",
+    "Case",
+    "When",
+    "Subquery",
+    "Exists",
+    "OuterRef",
+    "Window",
+    "ExpressionWrapper",
+    "RawSQL",
+    "OrderBy",
+    # Base classes (for extension)
+    "Func",
+    "Expression",
+    "Combinable",
+    # Window frame specs
+    "RowRange",
+    "ValueRange",
+]
+
+
+@runtime_checkable
+class ResolvableExpression(Protocol):
+    """Protocol for expressions that can be resolved in query context."""
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Any: ...
+
+
+@runtime_checkable
+class ReplaceableExpression(Protocol):
+    """Protocol for expressions that support expression replacement."""
+
+    def replace_expressions(self, replacements: dict[Any, Any]) -> Self: ...
+
+
+class Combinable:
+    """
+    Provide the ability to combine one or two objects with
+    some connector. For example F('foo') + F('bar').
+    """
+
+    # Arithmetic connectors
+    ADD = "+"
+    SUB = "-"
+    MUL = "*"
+    DIV = "/"
+    POW = "^"
+    # The following is a quoted % operator - it is quoted because it can be
+    # used in strings that also have parameter substitution.
+    MOD = "%%"
+
+    # Bitwise operators - note that these are generated by .bitand()
+    # and .bitor(), the '&' and '|' are reserved for boolean operator
+    # usage.
+    BITAND = "&"
+    BITOR = "|"
+    BITLEFTSHIFT = "<<"
+    BITRIGHTSHIFT = ">>"
+    BITXOR = "#"
+
+    def _combine(
+        self, other: Any, connector: str, reversed: bool
+    ) -> CombinedExpression:
+        if not isinstance(other, ResolvableExpression):
+            # everything must be resolvable to an expression
+            other = Value(other)
+
+        if reversed:
+            return CombinedExpression(other, connector, self)
+        return CombinedExpression(self, connector, other)
+
+    #############
+    # OPERATORS #
+    #############
+
+    def __neg__(self) -> CombinedExpression:
+        return self._combine(-1, self.MUL, False)
+
+    def __add__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.ADD, False)
+
+    def __sub__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.SUB, False)
+
+    def __mul__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.MUL, False)
+
+    def __truediv__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.DIV, False)
+
+    def __mod__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.MOD, False)
+
+    def __pow__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.POW, False)
+
+    def __and__(self, other: Any) -> Q:
+        if getattr(self, "conditional", False) and getattr(other, "conditional", False):
+            return Q(self) & Q(other)
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def bitand(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.BITAND, False)
+
+    def bitleftshift(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.BITLEFTSHIFT, False)
+
+    def bitrightshift(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.BITRIGHTSHIFT, False)
+
+    def __xor__(self, other: Any) -> Q:
+        if getattr(self, "conditional", False) and getattr(other, "conditional", False):
+            return Q(self) ^ Q(other)
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def bitxor(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.BITXOR, False)
+
+    def __or__(self, other: Any) -> Q:
+        if getattr(self, "conditional", False) and getattr(other, "conditional", False):
+            return Q(self) | Q(other)
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def bitor(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.BITOR, False)
+
+    def __radd__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.ADD, True)
+
+    def __rsub__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.SUB, True)
+
+    def __rmul__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.MUL, True)
+
+    def __rtruediv__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.DIV, True)
+
+    def __rmod__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.MOD, True)
+
+    def __rpow__(self, other: Any) -> CombinedExpression:
+        return self._combine(other, self.POW, True)
+
+    def __rand__(self, other: Any) -> None:
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def __ror__(self, other: Any) -> None:
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def __rxor__(self, other: Any) -> None:
+        raise NotImplementedError(
+            "Use .bitand(), .bitor(), and .bitxor() for bitwise logical operations."
+        )
+
+    def __invert__(self) -> NegatedExpression:
+        return NegatedExpression(self)
+
+
+class BaseExpression:
+    """Base class for all query expressions."""
+
+    empty_result_set_value = NotImplemented
+    # aggregate specific fields
+    is_summary = False
+    _output_field_resolved_to_none = False
+    # Can the expression be used in a WHERE clause?
+    filterable = True
+    # Can the expression can be used as a source expression in Window?
+    window_compatible = False
+
+    def __init__(self, output_field: Field | None = None):
+        if output_field is not None:
+            self.output_field = output_field
+
+    def __getstate__(self) -> dict[str, Any]:
+        state = self.__dict__.copy()
+        state.pop("convert_value", None)
+        return state
+
+    def get_db_converters(
+        self, connection: DatabaseConnection
+    ) -> list[Callable[..., Any]]:
+        converters = []
+        if self.convert_value is not self._convert_value_noop:
+            converters.append(self.convert_value)
+        converters.extend(self.output_field.get_db_converters(connection))
+        return converters
+
+    def get_source_expressions(self) -> list[Any]:
+        return []
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        assert not exprs
+
+    def _parse_expressions(self, *expressions: Any) -> list[Any]:
+        return [
+            arg
+            if isinstance(arg, ResolvableExpression)
+            else (F(arg) if isinstance(arg, str) else Value(arg))
+            for arg in expressions
+        ]
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, Sequence[Any]]:
+        """
+        Return a (sql, params) tuple to be included in the current query.
+
+        Arguments:
+         * compiler: the query compiler responsible for generating the query.
+           Must have a compile method, returning a (sql, [params]) tuple.
+           Calling compiler(value) will return a quoted `value`.
+
+         * connection: the database connection used for the current query.
+
+        Return: (sql, params)
+          Where `sql` is a string containing ordered sql parameters to be
+          replaced with the elements of the list `params`.
+        """
+        raise NotImplementedError("Subclasses must implement as_sql()")
+
+    @cached_property
+    def contains_aggregate(self) -> bool:
+        return any(
+            expr and expr.contains_aggregate for expr in self.get_source_expressions()
+        )
+
+    @cached_property
+    def contains_over_clause(self) -> bool:
+        return any(
+            expr and expr.contains_over_clause for expr in self.get_source_expressions()
+        )
+
+    @cached_property
+    def contains_column_references(self) -> bool:
+        return any(
+            expr and expr.contains_column_references
+            for expr in self.get_source_expressions()
+        )
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Self:
+        """
+        Provide the chance to do any preprocessing or validation before being
+        added to the query.
+
+        Arguments:
+         * query: the backend query implementation
+         * allow_joins: boolean allowing or denying use of joins
+           in this query
+         * reuse: a set of reusable joins for multijoins
+         * summarize: a terminal aggregate clause
+         * for_save: whether this expression about to be used in a save or update
+
+        Return: an Expression to be added to the query.
+        """
+        c = self.copy()
+        c.is_summary = summarize
+        c.set_source_expressions(
+            [
+                expr.resolve_expression(query, allow_joins, reuse, summarize)
+                if expr
+                else None
+                for expr in c.get_source_expressions()
+            ]
+        )
+        return c
+
+    @property
+    def conditional(self) -> bool:
+        output_field = getattr(self, "output_field", None)
+        return isinstance(output_field, fields.BooleanField)
+
+    @property
+    def field(self) -> Field:
+        return self.output_field
+
+    @cached_property
+    def output_field(self) -> Field:
+        """Return the output type of this expressions."""
+        output_field = self._resolve_output_field()
+        if output_field is None:
+            self._output_field_resolved_to_none = True
+            raise FieldError("Cannot resolve expression type, unknown output_field")
+        return output_field
+
+    @cached_property
+    def _output_field_or_none(self) -> Field | None:
+        """
+        Return the output field of this expression, or None if
+        _resolve_output_field() didn't return an output type.
+        """
+        try:
+            return self.output_field
+        except FieldError:
+            if not self._output_field_resolved_to_none:
+                raise
+            return None
+
+    def _resolve_output_field(self) -> Field | None:
+        """
+        Attempt to infer the output type of the expression.
+
+        As a guess, if the output fields of all source fields match then simply
+        infer the same type here.
+
+        If a source's output field resolves to None, exclude it from this check.
+        If all sources are None, then an error is raised higher up the stack in
+        the output_field property.
+        """
+        # This guess is mostly a bad idea, but there is quite a lot of code
+        # (especially 3rd party Func subclasses) that depend on it, we'd need a
+        # deprecation path to fix it.
+        sources_iter = (
+            source for source in self.get_source_fields() if source is not None
+        )
+        for output_field in sources_iter:
+            for source in sources_iter:
+                if not isinstance(output_field, source.__class__):
+                    raise FieldError(
+                        f"Expression contains mixed types: {output_field.__class__.__name__}, {source.__class__.__name__}. You must "
+                        "set output_field."
+                    )
+            return output_field
+        return None
+
+    @staticmethod
+    def _convert_value_noop(
+        value: Any, expression: Any, connection: DatabaseConnection
+    ) -> Any:
+        return value
+
+    @cached_property
+    def convert_value(self) -> Callable[[Any, Any, Any], Any]:
+        """
+        Expressions provide their own converters because users have the option
+        of manually specifying the output_field which may be a different type
+        from the one the database returns.
+        """
+        field = self.output_field
+        internal_type = field.get_internal_type()
+        if internal_type == "FloatField":
+            return (
+                lambda value, expression, connection: None
+                if value is None
+                else float(value)
+            )
+        elif internal_type.endswith("IntegerField"):
+            return (
+                lambda value, expression, connection: None
+                if value is None
+                else int(value)
+            )
+        elif internal_type == "DecimalField":
+            return (
+                lambda value, expression, connection: None
+                if value is None
+                else Decimal(value)
+            )
+        return self._convert_value_noop
+
+    def get_lookup(self, lookup: str) -> type[Lookup] | None:
+        return self.output_field.get_lookup(lookup)
+
+    def get_transform(self, name: str) -> type[Transform] | None:
+        return self.output_field.get_transform(name)  # type: ignore[return-type]
+
+    def relabeled_clone(self, change_map: dict[str, str]) -> Self:
+        clone = self.copy()
+        clone.set_source_expressions(
+            [
+                e.relabeled_clone(change_map) if e is not None else None
+                for e in self.get_source_expressions()
+            ]
+        )
+        return clone
+
+    def replace_expressions(self, replacements: dict[BaseExpression, Any]) -> Self:
+        if replacement := replacements.get(self):
+            return replacement
+        clone = self.copy()
+        source_expressions = clone.get_source_expressions()
+        clone.set_source_expressions(
+            [
+                expr.replace_expressions(replacements) if expr else None
+                for expr in source_expressions
+            ]
+        )
+        return clone
+
+    def get_refs(self) -> set[str]:
+        refs = set()
+        for expr in self.get_source_expressions():
+            refs |= expr.get_refs()
+        return refs
+
+    def copy(self) -> Self:
+        return copy.copy(self)
+
+    def prefix_references(self, prefix: str) -> Self:
+        clone = self.copy()
+        clone.set_source_expressions(
+            [
+                F(f"{prefix}{expr.name}")
+                if isinstance(expr, F)
+                else expr.prefix_references(prefix)
+                for expr in self.get_source_expressions()
+            ]
+        )
+        return clone
+
+    def get_group_by_cols(self) -> list[BaseExpression]:
+        if not self.contains_aggregate:
+            return [self]
+        cols: list[BaseExpression] = []
+        for source in self.get_source_expressions():
+            cols.extend(source.get_group_by_cols())
+        return cols
+
+    def get_source_fields(self) -> list[Field | None]:
+        """Return the underlying field types used by this aggregate."""
+        return [e._output_field_or_none for e in self.get_source_expressions()]
+
+    def asc(self, **kwargs: Any) -> OrderBy:
+        return OrderBy(self, **kwargs)
+
+    def desc(self, **kwargs: Any) -> OrderBy:
+        return OrderBy(self, descending=True, **kwargs)
+
+    def reverse_ordering(self) -> Self:
+        return self
+
+    def flatten(self) -> Iterable[Any]:
+        """
+        Recursively yield this expression and all subexpressions, in
+        depth-first order.
+        """
+        yield self
+        for expr in self.get_source_expressions():
+            if expr:
+                if hasattr(expr, "flatten"):
+                    yield from expr.flatten()
+                else:
+                    yield expr
+
+    def select_format(
+        self, compiler: SQLCompiler, sql: str, params: Sequence[Any]
+    ) -> tuple[str, Sequence[Any]]:
+        """Custom format for select clauses."""
+        if output_field := getattr(self, "output_field", None):
+            if select_format := getattr(output_field, "select_format", None):
+                return select_format(compiler, sql, params)
+        return sql, params
+
+
+@deconstructible
+class Expression(BaseExpression, Combinable):
+    """An expression that can be combined with other expressions."""
+
+    # Set by @deconstructible decorator in __new__
+    _constructor_args: tuple[tuple[Any, ...], dict[str, Any]]
+
+    @cached_property
+    def identity(self) -> tuple[Any, ...]:
+        constructor_signature = inspect.signature(self.__init__)
+        args, kwargs = self._constructor_args
+        signature = constructor_signature.bind_partial(*args, **kwargs)
+        signature.apply_defaults()
+        arguments = signature.arguments.items()
+        identity: list[Any] = [self.__class__]
+        for arg, value in arguments:
+            if isinstance(value, fields.Field):
+                if value.name and value.model:
+                    value = (value.model.model_options.label, value.name)
+                else:
+                    value = type(value)
+            else:
+                value = make_hashable(value)
+            identity.append((arg, value))
+        return tuple(identity)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Expression):
+            return NotImplemented
+        return other.identity == self.identity
+
+    def __hash__(self) -> int:
+        return hash(self.identity)
+
+
+# Type inference for CombinedExpression.output_field.
+# Missing items will result in FieldError, by design.
+#
+# The current approach for NULL is based on lowest common denominator behavior
+# i.e. if one of the supported databases is raising an error (rather than
+# return NULL) for `val <op> NULL`, then Plain raises FieldError.
+
+_connector_combinations = [
+    # Numeric operations - operands of same type.
+    {
+        connector: [
+            (fields.IntegerField, fields.IntegerField, fields.IntegerField),
+            (fields.FloatField, fields.FloatField, fields.FloatField),
+            (fields.DecimalField, fields.DecimalField, fields.DecimalField),
+        ]
+        for connector in (
+            Combinable.ADD,
+            Combinable.SUB,
+            Combinable.MUL,
+            Combinable.DIV,
+            Combinable.MOD,
+            Combinable.POW,
+        )
+    },
+    # Numeric operations - operands of different type.
+    {
+        connector: [
+            (fields.IntegerField, fields.DecimalField, fields.DecimalField),
+            (fields.DecimalField, fields.IntegerField, fields.DecimalField),
+            (fields.IntegerField, fields.FloatField, fields.FloatField),
+            (fields.FloatField, fields.IntegerField, fields.FloatField),
+        ]
+        for connector in (
+            Combinable.ADD,
+            Combinable.SUB,
+            Combinable.MUL,
+            Combinable.DIV,
+            Combinable.MOD,
+        )
+    },
+    # Bitwise operators.
+    {
+        connector: [
+            (fields.IntegerField, fields.IntegerField, fields.IntegerField),
+        ]
+        for connector in (
+            Combinable.BITAND,
+            Combinable.BITOR,
+            Combinable.BITLEFTSHIFT,
+            Combinable.BITRIGHTSHIFT,
+            Combinable.BITXOR,
+        )
+    },
+    # Numeric with NULL.
+    {
+        connector: [
+            (field_type, NoneType, field_type),
+            (NoneType, field_type, field_type),
+        ]
+        for connector in (
+            Combinable.ADD,
+            Combinable.SUB,
+            Combinable.MUL,
+            Combinable.DIV,
+            Combinable.MOD,
+            Combinable.POW,
+        )
+        for field_type in (fields.IntegerField, fields.DecimalField, fields.FloatField)
+    },
+    # Date/DateTimeField/DurationField/TimeField.
+    {
+        Combinable.ADD: [
+            # Date/DateTimeField.
+            (fields.DateField, fields.DurationField, fields.DateTimeField),
+            (fields.DateTimeField, fields.DurationField, fields.DateTimeField),
+            (fields.DurationField, fields.DateField, fields.DateTimeField),
+            (fields.DurationField, fields.DateTimeField, fields.DateTimeField),
+            # DurationField.
+            (fields.DurationField, fields.DurationField, fields.DurationField),
+            # TimeField.
+            (fields.TimeField, fields.DurationField, fields.TimeField),
+            (fields.DurationField, fields.TimeField, fields.TimeField),
+        ],
+    },
+    {
+        Combinable.SUB: [
+            # Date/DateTimeField.
+            (fields.DateField, fields.DurationField, fields.DateTimeField),
+            (fields.DateTimeField, fields.DurationField, fields.DateTimeField),
+            (fields.DateField, fields.DateField, fields.DurationField),
+            (fields.DateField, fields.DateTimeField, fields.DurationField),
+            (fields.DateTimeField, fields.DateField, fields.DurationField),
+            (fields.DateTimeField, fields.DateTimeField, fields.DurationField),
+            # DurationField.
+            (fields.DurationField, fields.DurationField, fields.DurationField),
+            # TimeField.
+            (fields.TimeField, fields.DurationField, fields.TimeField),
+            (fields.TimeField, fields.TimeField, fields.DurationField),
+        ],
+    },
+]
+
+_connector_combinators = defaultdict(list)
+
+
+def register_combinable_fields(
+    lhs: type[Field] | type[None],
+    connector: str,
+    rhs: type[Field] | type[None],
+    result: type[Field],
+) -> None:
+    """
+    Register combinable types:
+        lhs <connector> rhs -> result
+    e.g.
+        register_combinable_fields(
+            IntegerField, Combinable.ADD, FloatField, FloatField
+        )
+    """
+    _connector_combinators[connector].append((lhs, rhs, result))
+
+
+for d in _connector_combinations:
+    for connector, field_types in d.items():
+        for lhs, rhs, result in field_types:
+            register_combinable_fields(lhs, connector, rhs, result)
+
+
+@functools.lru_cache(maxsize=128)
+def _resolve_combined_type(
+    connector: str, lhs_type: type[Field], rhs_type: type[Field]
+) -> type[Field] | None:
+    combinators = _connector_combinators.get(connector, ())
+    for combinator_lhs_type, combinator_rhs_type, combined_type in combinators:
+        if issubclass(lhs_type, combinator_lhs_type) and issubclass(
+            rhs_type, combinator_rhs_type
+        ):
+            return combined_type
+    return None
+
+
+class CombinedExpression(Expression):
+    def __init__(
+        self, lhs: Any, connector: str, rhs: Any, output_field: Field | None = None
+    ):
+        super().__init__(output_field=output_field)
+        self.connector = connector
+        self.lhs = lhs
+        self.rhs = rhs
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def __str__(self) -> str:
+        return f"{self.lhs} {self.connector} {self.rhs}"
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.lhs, self.rhs]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.lhs, self.rhs = exprs
+
+    def _resolve_output_field(self) -> Field | None:
+        # We avoid using super() here for reasons given in
+        # Expression._resolve_output_field()
+        combined_type = _resolve_combined_type(
+            self.connector,
+            type(self.lhs._output_field_or_none),
+            type(self.rhs._output_field_or_none),
+        )
+        if combined_type is None:
+            raise FieldError(
+                f"Cannot infer type of {self.connector!r} expression involving these "
+                f"types: {self.lhs.output_field.__class__.__name__}, "
+                f"{self.rhs.output_field.__class__.__name__}. You must set "
+                f"output_field."
+            )
+        return combined_type()
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        expressions = []
+        expression_params = []
+        sql, params = compiler.compile(self.lhs)
+        expressions.append(sql)
+        expression_params.extend(params)
+        sql, params = compiler.compile(self.rhs)
+        expressions.append(sql)
+        expression_params.extend(params)
+        # order of precedence
+        expression_wrapper = "(%s)"
+        sql = combine_expression(self.connector, expressions)
+        return expression_wrapper % sql, expression_params
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> CombinedExpression | TemporalSubtraction:
+        lhs = self.lhs.resolve_expression(
+            query, allow_joins, reuse, summarize, for_save
+        )
+        rhs = self.rhs.resolve_expression(
+            query, allow_joins, reuse, summarize, for_save
+        )
+        if not isinstance(self, TemporalSubtraction):
+            try:
+                lhs_type = lhs.output_field.get_internal_type()
+            except (AttributeError, FieldError):
+                lhs_type = None
+            try:
+                rhs_type = rhs.output_field.get_internal_type()
+            except (AttributeError, FieldError):
+                rhs_type = None
+            datetime_fields = {"DateField", "DateTimeField", "TimeField"}
+            if (
+                self.connector == self.SUB
+                and lhs_type in datetime_fields
+                and lhs_type == rhs_type
+            ):
+                return TemporalSubtraction(self.lhs, self.rhs).resolve_expression(
+                    query,
+                    allow_joins,
+                    reuse,
+                    summarize,
+                    for_save,
+                )
+        c = self.copy()
+        c.is_summary = summarize
+        c.lhs = lhs
+        c.rhs = rhs
+        return c
+
+
+class TemporalSubtraction(CombinedExpression):
+    output_field = fields.DurationField()
+
+    def __init__(self, lhs: Any, rhs: Any):
+        super().__init__(lhs, self.SUB, rhs)
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        lhs = compiler.compile(self.lhs)
+        rhs = compiler.compile(self.rhs)
+        sql, params = subtract_temporals(
+            self.lhs.output_field.get_internal_type(), lhs, rhs
+        )
+        return sql, list(params)
+
+
+@deconstructible(path="plain.postgres.F")
+class F(Combinable):
+    """An object capable of resolving references to existing query objects."""
+
+    def __init__(self, name: str):
+        """
+        Arguments:
+         * name: the name of the field this expression references
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Any:
+        return query.resolve_ref(self.name, allow_joins, reuse, summarize)
+
+    def replace_expressions(self, replacements: dict[Any, Any]) -> F:
+        return replacements.get(self, self)
+
+    def asc(self, **kwargs: Any) -> OrderBy:
+        return OrderBy(self, **kwargs)
+
+    def desc(self, **kwargs: Any) -> OrderBy:
+        return OrderBy(self, descending=True, **kwargs)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, F):
+            return NotImplemented
+        return self.__class__ == other.__class__ and self.name == other.name
+
+    def __hash__(self) -> int:
+        return hash(self.name)
+
+    def copy(self) -> Self:
+        return copy.copy(self)
+
+
+class ResolvedOuterRef(F):
+    """
+    An object that contains a reference to an outer query.
+
+    In this case, the reference to the outer query has been resolved because
+    the inner query has been used as a subquery.
+    """
+
+    contains_aggregate = False
+    contains_over_clause = False
+
+    def as_sql(self, *args: Any, **kwargs: Any) -> None:
+        raise ValueError(
+            "This queryset contains a reference to an outer query and may "
+            "only be used in a subquery."
+        )
+
+    def resolve_expression(self, *args: Any, **kwargs: Any) -> Any:
+        col = super().resolve_expression(*args, **kwargs)
+        if col.contains_over_clause:
+            raise NotSupportedError(
+                f"Referencing outer query window expression is not supported: "
+                f"{self.name}."
+            )
+        # FIXME: Rename possibly_multivalued to multivalued and fix detection
+        # for non-multivalued JOINs (e.g. foreign key fields). This should take
+        # into account only many-to-many and one-to-many relationships.
+        col.possibly_multivalued = LOOKUP_SEP in self.name
+        return col
+
+    def relabeled_clone(self, relabels: dict[str, str]) -> ResolvedOuterRef:
+        return self
+
+    def get_group_by_cols(self) -> list[Any]:
+        return []
+
+
+class OuterRef(F):
+    contains_aggregate = False
+
+    def resolve_expression(self, *args: Any, **kwargs: Any) -> ResolvedOuterRef | F:
+        if isinstance(self.name, self.__class__):
+            return self.name
+        return ResolvedOuterRef(self.name)
+
+    def relabeled_clone(self, relabels: dict[str, str]) -> OuterRef:
+        return self
+
+
+@deconstructible(path="plain.postgres.Func")
+class Func(Expression):
+    """An SQL function call."""
+
+    function = None
+    template = "%(function)s(%(expressions)s)"
+    arg_joiner = ", "
+    arity = None  # The number of arguments the function accepts.
+
+    def __init__(
+        self, *expressions: Any, output_field: Field | None = None, **extra: Any
+    ):
+        if self.arity is not None and len(expressions) != self.arity:
+            raise TypeError(
+                "'{}' takes exactly {} {} ({} given)".format(
+                    self.__class__.__name__,
+                    self.arity,
+                    "argument" if self.arity == 1 else "arguments",
+                    len(expressions),
+                )
+            )
+        super().__init__(output_field=output_field)
+        self.source_expressions: list[Any] = self._parse_expressions(*expressions)
+        self.extra = extra
+
+    def __repr__(self) -> str:
+        args = self.arg_joiner.join(str(arg) for arg in self.source_expressions)
+        extra = {**self.extra, **self._get_repr_options()}
+        if extra:
+            extra = ", ".join(
+                str(key) + "=" + str(val) for key, val in sorted(extra.items())
+            )
+            return f"{self.__class__.__name__}({args}, {extra})"
+        return f"{self.__class__.__name__}({args})"
+
+    def _get_repr_options(self) -> dict[str, Any]:
+        """Return a dict of extra __init__() options to include in the repr."""
+        return {}
+
+    def get_source_expressions(self) -> list[Any]:
+        return self.source_expressions
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.source_expressions = list(exprs)
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Self:
+        c = self.copy()
+        c.is_summary = summarize
+        for pos, arg in enumerate(c.source_expressions):
+            c.source_expressions[pos] = arg.resolve_expression(
+                query, allow_joins, reuse, summarize, for_save
+            )
+        return c
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        function: str | None = None,
+        template: str | None = None,
+        arg_joiner: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, list[Any]]:
+        sql_parts = []
+        params = []
+        for arg in self.source_expressions:
+            try:
+                arg_sql, arg_params = compiler.compile(arg)
+            except EmptyResultSet:
+                empty_result_set_value = getattr(
+                    arg, "empty_result_set_value", NotImplemented
+                )
+                if empty_result_set_value is NotImplemented:
+                    raise
+                arg_sql, arg_params = compiler.compile(Value(empty_result_set_value))
+            except FullResultSet:
+                arg_sql, arg_params = compiler.compile(Value(True))
+            sql_parts.append(arg_sql)
+            params.extend(arg_params)
+        data = {**self.extra, **extra_context}
+        # Use the first supplied value in this order: the parameter to this
+        # method, a value supplied in __init__()'s **extra (the value in
+        # `data`), or the value defined on the class.
+        if function is not None:
+            data["function"] = function
+        else:
+            data.setdefault("function", self.function)
+        template = template or data.get("template", self.template)
+        arg_joiner = arg_joiner or data.get("arg_joiner", self.arg_joiner)
+        data["expressions"] = data["field"] = arg_joiner.join(sql_parts)
+        return template % data, params
+
+    def copy(self) -> Self:
+        clone = super().copy()
+        clone.source_expressions = self.source_expressions[:]
+        clone.extra = self.extra.copy()
+        return clone
+
+
+@deconstructible(path="plain.postgres.Value")
+class Value(Expression):
+    """Represent a wrapped value as a node within an expression."""
+
+    # Provide a default value for `for_save` in order to allow unresolved
+    # instances to be compiled until a decision is taken in #25425.
+    for_save = False
+
+    def __init__(self, value: Any, output_field: Field | None = None):
+        """
+        Arguments:
+         * value: the value this expression represents. The value will be
+           added into the sql parameter list and properly quoted.
+
+         * output_field: an instance of the model field type that this
+           expression will return, such as IntegerField() or CharField().
+        """
+        super().__init__(output_field=output_field)
+        self.value = value
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.value!r})"
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        val = self.value
+        output_field = self._output_field_or_none
+        if output_field is not None:
+            if self.for_save:
+                val = output_field.get_db_prep_save(val, connection=connection)
+            else:
+                val = output_field.get_db_prep_value(val, connection=connection)
+            if hasattr(output_field, "get_placeholder"):
+                return output_field.get_placeholder(val, compiler, connection), [val]  # type: ignore[call-non-callable]
+        if val is None:
+            return "NULL", []
+        return "%s", [val]
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Value:
+        c = super().resolve_expression(query, allow_joins, reuse, summarize, for_save)
+        c.for_save = for_save
+        return c
+
+    def get_group_by_cols(self) -> list[Any]:
+        return []
+
+    def _resolve_output_field(self) -> Field | None:
+        if isinstance(self.value, str):
+            return fields.CharField()
+        if isinstance(self.value, bool):
+            return fields.BooleanField()
+        if isinstance(self.value, int):
+            return fields.IntegerField()
+        if isinstance(self.value, float):
+            return fields.FloatField()
+        if isinstance(self.value, datetime.datetime):
+            return fields.DateTimeField()
+        if isinstance(self.value, datetime.date):
+            return fields.DateField()
+        if isinstance(self.value, datetime.time):
+            return fields.TimeField()
+        if isinstance(self.value, datetime.timedelta):
+            return fields.DurationField()
+        if isinstance(self.value, Decimal):
+            return fields.DecimalField()
+        if isinstance(self.value, bytes):
+            return fields.BinaryField()
+        if isinstance(self.value, UUID):
+            return fields.UUIDField()
+
+    @property
+    def empty_result_set_value(self) -> Any:
+        return self.value
+
+
+class RawSQL(Expression):
+    def __init__(
+        self, sql: str, params: Sequence[Any], output_field: Field | None = None
+    ):
+        if output_field is None:
+            output_field = fields.Field()
+        self.sql, self.params = sql, params
+        super().__init__(output_field=output_field)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.sql}, {self.params})"
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, Sequence[Any]]:
+        return f"({self.sql})", self.params
+
+    def get_group_by_cols(self) -> list[BaseExpression]:
+        return [self]
+
+
+class Star(Expression):
+    def __repr__(self) -> str:
+        return "'*'"
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        return "*", []
+
+
+class Col(Expression):
+    contains_column_references = True
+    possibly_multivalued = False
+
+    def __init__(
+        self, alias: str | None, target: Any, output_field: Field | None = None
+    ):
+        if output_field is None:
+            output_field = target
+        super().__init__(output_field=output_field)
+        self.alias, self.target = alias, target
+
+    def __repr__(self) -> str:
+        alias, target = self.alias, self.target
+        identifiers = (alias, str(target)) if alias else (str(target),)
+        return "{}({})".format(self.__class__.__name__, ", ".join(identifiers))
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        alias, column = self.alias, self.target.column
+        identifiers = (alias, column) if alias else (column,)
+        sql = ".".join(map(compiler.quote_name_unless_alias, identifiers))
+        return sql, []
+
+    def relabeled_clone(self, change_map: dict[str, str]) -> Self:
+        if self.alias is None:
+            return self
+        return self.__class__(
+            change_map.get(self.alias, self.alias), self.target, self.output_field
+        )
+
+    def get_group_by_cols(self) -> list[BaseExpression]:
+        return [self]
+
+    def get_db_converters(
+        self, connection: DatabaseConnection
+    ) -> list[Callable[..., Any]]:
+        if self.target == self.output_field:
+            return self.output_field.get_db_converters(connection)
+        return self.output_field.get_db_converters(
+            connection
+        ) + self.target.get_db_converters(connection)
+
+
+class Ref(Expression):
+    """
+    Reference to column alias of the query. For example, Ref('sum_cost') in
+    qs.annotate(sum_cost=Sum('cost')) query.
+    """
+
+    def __init__(self, refs: str, source: Any):
+        super().__init__()
+        self.refs, self.source = refs, source
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.refs}, {self.source})"
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.source]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        (self.source,) = exprs
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Ref:
+        # The sub-expression `source` has already been resolved, as this is
+        # just a reference to the name of `source`.
+        return self
+
+    def get_refs(self) -> set[str]:
+        return {self.refs}
+
+    def relabeled_clone(self, change_map: dict[str, str]) -> Self:
+        return self
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        return quote_name(self.refs), []
+
+    def get_group_by_cols(self) -> list[BaseExpression]:
+        return [self]
+
+
+class ExpressionList(Func):
+    """
+    An expression containing multiple expressions. Can be used to provide a
+    list of expressions as an argument to another expression, like a partition
+    clause.
+    """
+
+    template = "%(expressions)s"
+
+    def __init__(self, *expressions: Any, **extra: Any):
+        if not expressions:
+            raise ValueError(
+                f"{self.__class__.__name__} requires at least one expression."
+            )
+        super().__init__(*expressions, **extra)
+
+    def __str__(self) -> str:
+        return self.arg_joiner.join(str(arg) for arg in self.source_expressions)
+
+
+class OrderByList(Func):
+    template = "ORDER BY %(expressions)s"
+
+    def __init__(self, *expressions: Any, **extra: Any):
+        expressions_tuple = tuple(
+            (
+                OrderBy(F(expr[1:]), descending=True)
+                if isinstance(expr, str) and expr[0] == "-"
+                else expr
+            )
+            for expr in expressions
+        )
+        super().__init__(*expressions_tuple, **extra)
+
+    def as_sql(self, *args: Any, **kwargs: Any) -> tuple[str, list[Any]]:
+        if not self.source_expressions:
+            return "", []
+        sql, params = super().as_sql(*args, **kwargs)
+        return sql, list(params)
+
+    def get_group_by_cols(self) -> list[Any]:
+        group_by_cols = []
+        for order_by in self.get_source_expressions():
+            group_by_cols.extend(order_by.get_group_by_cols())
+        return group_by_cols
+
+
+@deconstructible(path="plain.postgres.ExpressionWrapper")
+class ExpressionWrapper(Expression):
+    """
+    An expression that can wrap another expression so that it can provide
+    extra context to the inner expression, such as the output_field.
+    """
+
+    def __init__(self, expression: Any, output_field: Field):
+        super().__init__(output_field=output_field)
+        self.expression = expression
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.expression = exprs[0]
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.expression]
+
+    def get_group_by_cols(self) -> list[Any]:
+        if isinstance(self.expression, Expression):
+            expression = self.expression.copy()
+            expression.output_field = self.output_field
+            return expression.get_group_by_cols()
+        # For non-expressions e.g. an SQL WHERE clause, the entire
+        # `expression` must be included in the GROUP BY clause.
+        return super().get_group_by_cols()
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, Sequence[Any]]:
+        return compiler.compile(self.expression)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.expression})"
+
+
+class NegatedExpression(ExpressionWrapper):
+    """The logical negation of a conditional expression."""
+
+    def __init__(self, expression: Any):
+        super().__init__(expression, output_field=fields.BooleanField())
+
+    def __invert__(self) -> Any:
+        return self.expression.copy()
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, Sequence[Any]]:
+        try:
+            sql, params = super().as_sql(compiler, connection)
+        except EmptyResultSet:
+            return compiler.compile(Value(True))
+        return f"NOT {sql}", params
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> NegatedExpression:
+        resolved = super().resolve_expression(
+            query, allow_joins, reuse, summarize, for_save
+        )
+        if not getattr(resolved.expression, "conditional", False):
+            raise TypeError("Cannot negate non-conditional expressions.")
+        return resolved
+
+    def select_format(
+        self, compiler: SQLCompiler, sql: str, params: Sequence[Any]
+    ) -> tuple[str, Sequence[Any]]:
+        # Boolean expressions work directly in SELECT
+        return sql, params
+
+
+@deconstructible(path="plain.postgres.When")
+class When(Expression):
+    template = "WHEN %(condition)s THEN %(result)s"
+    # This isn't a complete conditional expression, must be used in Case().
+    conditional = False
+    condition: SQLCompilable
+
+    def __init__(
+        self, condition: Q | Expression | None = None, then: Any = None, **lookups: Any
+    ):
+        lookups_dict: dict[str, Any] | None = lookups or None
+        if lookups_dict:
+            if condition is None:
+                condition, lookups_dict = Q(**lookups_dict), None
+            elif getattr(condition, "conditional", False):
+                condition, lookups_dict = Q(condition, **lookups_dict), None
+        if (
+            condition is None
+            or not getattr(condition, "conditional", False)
+            or lookups_dict
+        ):
+            raise TypeError(
+                "When() supports a Q object, a boolean expression, or lookups "
+                "as a condition."
+            )
+        if isinstance(condition, Q) and not condition:
+            raise ValueError("An empty Q() can't be used as a When() condition.")
+        super().__init__(output_field=None)
+        self.condition = condition  # type: ignore[assignment]
+        self.result = self._parse_expressions(then)[0]
+
+    def __str__(self) -> str:
+        return f"WHEN {self.condition!r} THEN {self.result!r}"
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.condition, self.result]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.condition, self.result = exprs
+
+    def get_source_fields(self) -> list[Field | None]:
+        # We're only interested in the fields of the result expressions.
+        return [self.result._output_field_or_none]
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> When:
+        c = self.copy()
+        c.is_summary = summarize
+        if isinstance(c.condition, ResolvableExpression):
+            c.condition = c.condition.resolve_expression(
+                query, allow_joins, reuse, summarize, False
+            )
+        c.result = c.result.resolve_expression(
+            query, allow_joins, reuse, summarize, for_save
+        )
+        return c
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        template: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
+        template_params = extra_context
+        sql_params = []
+        # After resolve_expression, condition is WhereNode | resolved Expression (both SQLCompilable)
+        condition_sql, condition_params = compiler.compile(self.condition)
+        template_params["condition"] = condition_sql
+        result_sql, result_params = compiler.compile(self.result)
+        template_params["result"] = result_sql
+        template = template or self.template
+        return template % template_params, (
+            *sql_params,
+            *condition_params,
+            *result_params,
+        )
+
+    def get_group_by_cols(self) -> list[Any]:
+        # This is not a complete expression and cannot be used in GROUP BY.
+        cols = []
+        for source in self.get_source_expressions():
+            cols.extend(source.get_group_by_cols())
+        return cols
+
+
+@deconstructible(path="plain.postgres.Case")
+class Case(Expression):
+    """
+    An SQL searched CASE expression:
+
+        CASE
+            WHEN n > 0
+                THEN 'positive'
+            WHEN n < 0
+                THEN 'negative'
+            ELSE 'zero'
+        END
+    """
+
+    template = "CASE %(cases)s ELSE %(default)s END"
+    case_joiner = " "
+
+    def __init__(
+        self,
+        *cases: When,
+        default: Any = None,
+        output_field: Field | None = None,
+        **extra: Any,
+    ):
+        if not all(isinstance(case, When) for case in cases):
+            raise TypeError("Positional arguments must all be When objects.")
+        super().__init__(output_field)
+        self.cases = list(cases)
+        self.default = self._parse_expressions(default)[0]
+        self.extra = extra
+
+    def __str__(self) -> str:
+        return "CASE {}, ELSE {!r}".format(
+            ", ".join(str(c) for c in self.cases),
+            self.default,
+        )
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def get_source_expressions(self) -> list[Any]:
+        return self.cases + [self.default]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        *self.cases, self.default = exprs
+
+    def resolve_expression(
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Case:
+        c = self.copy()
+        c.is_summary = summarize
+        for pos, case in enumerate(c.cases):
+            c.cases[pos] = case.resolve_expression(
+                query, allow_joins, reuse, summarize, for_save
+            )
+        c.default = c.default.resolve_expression(
+            query, allow_joins, reuse, summarize, for_save
+        )
+        return c
+
+    def copy(self) -> Self:
+        c = super().copy()
+        c.cases = c.cases[:]
+        return c
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        template: str | None = None,
+        case_joiner: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, list[Any]]:
+        if not self.cases:
+            sql, params = compiler.compile(self.default)
+            return sql, list(params)
+        template_params = {**self.extra, **extra_context}
+        case_parts = []
+        sql_params = []
+        default_sql, default_params = compiler.compile(self.default)
+        for case in self.cases:
+            try:
+                case_sql, case_params = compiler.compile(case)
+            except EmptyResultSet:
+                continue
+            except FullResultSet:
+                default_sql, default_params = compiler.compile(case.result)
+                break
+            case_parts.append(case_sql)
+            sql_params.extend(case_params)
+        if not case_parts:
+            return default_sql, list(default_params)
+        case_joiner = case_joiner or self.case_joiner
+        template_params["cases"] = case_joiner.join(case_parts)
+        template_params["default"] = default_sql
+        sql_params.extend(default_params)
+        template = template or template_params.get("template", self.template)
+        sql = template % template_params
+        if self._output_field_or_none is not None:
+            sql = connection.unification_cast_sql(self.output_field) % sql
+        return sql, sql_params
+
+    def get_group_by_cols(self) -> list[Any]:
+        if not self.cases:
+            return self.default.get_group_by_cols()
+        return super().get_group_by_cols()
+
+
+class Subquery(BaseExpression, Combinable):
+    """
+    An explicit subquery. It may contain OuterRef() references to the outer
+    query which will be resolved when it is applied to that query.
+    """
+
+    template = "(%(subquery)s)"
+    contains_aggregate = False
+    empty_result_set_value = None
+
+    def __init__(
+        self,
+        query: QuerySet[Any] | Query,
+        output_field: Field | None = None,
+        **extra: Any,
+    ):
+        # Import here to avoid circular import
+        from plain.postgres.sql.query import Query
+
+        # Allow the usage of both QuerySet and sql.Query objects.
+        if isinstance(query, Query):
+            # It's already a Query object, use it directly
+            sql_query = query
+        else:
+            # It's a QuerySet, extract the sql.Query
+            sql_query = query.sql_query
+        self.query = sql_query.clone()
+        self.query.subquery = True
+        self.extra = extra
+        super().__init__(output_field)
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.query]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.query = exprs[0]
+
+    def _resolve_output_field(self) -> Field | None:
+        return self.query.output_field
+
+    def copy(self) -> Self:
+        clone = super().copy()
+        clone.query = clone.query.clone()
+        return clone
+
+    @property
+    def external_aliases(self) -> dict[str, bool]:
+        return self.query.external_aliases
+
+    def get_external_cols(self) -> list[Any]:
+        return self.query.get_external_cols()
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        template: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
+        template_params = {**self.extra, **extra_context}
+        subquery_sql, sql_params = self.query.as_sql(compiler, connection)
+        template_params["subquery"] = subquery_sql[1:-1]
+
+        template = template or template_params.get("template", self.template)
+        sql = template % template_params
+        return sql, sql_params
+
+    def get_group_by_cols(self) -> list[Any]:
+        return self.query.get_group_by_cols(wrapper=self)
+
+
+class Exists(Subquery):
+    template = "EXISTS(%(subquery)s)"
+    output_field = fields.BooleanField()
+    empty_result_set_value = False
+
+    def __init__(self, query: QuerySet[Any] | Query, **kwargs: Any):
+        super().__init__(query, **kwargs)
+        self.query = self.query.exists()
+
+    def select_format(
+        self, compiler: SQLCompiler, sql: str, params: Sequence[Any]
+    ) -> tuple[str, Sequence[Any]]:
+        # Boolean expressions work directly in SELECT
+        return sql, params
+
+
+@deconstructible(path="plain.postgres.OrderBy")
+class OrderBy(Expression):
+    template = "%(expression)s %(ordering)s"
+    conditional = False
+
+    def __init__(
+        self,
+        expression: Any,
+        descending: bool = False,
+        nulls_first: bool | None = None,
+        nulls_last: bool | None = None,
+    ):
+        if nulls_first and nulls_last:
+            raise ValueError("nulls_first and nulls_last are mutually exclusive")
+        if nulls_first is False or nulls_last is False:
+            raise ValueError("nulls_first and nulls_last values must be True or None.")
+        self.nulls_first = nulls_first
+        self.nulls_last = nulls_last
+        self.descending = descending
+        if not isinstance(expression, ResolvableExpression):
+            raise ValueError("expression must be an expression type")
+        self.expression = expression
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.expression}, descending={self.descending})"
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.expression = exprs[0]
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.expression]
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        template: str | None = None,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
+        template = template or self.template
+        # Handle NULLS FIRST/LAST modifiers
+        if self.nulls_last:
+            template = f"{template} NULLS LAST"
+        elif self.nulls_first:
+            template = f"{template} NULLS FIRST"
+        expression_sql, params = compiler.compile(self.expression)
+        placeholders = {
+            "expression": expression_sql,
+            "ordering": "DESC" if self.descending else "ASC",
+            **extra_context,
+        }
+        params *= template.count("%(expression)s")
+        return (template % placeholders).rstrip(), params
+
+    def get_group_by_cols(self) -> list[Any]:
+        cols = []
+        for source in self.get_source_expressions():
+            cols.extend(source.get_group_by_cols())
+        return cols
+
+    def reverse_ordering(self) -> OrderBy:
+        self.descending = not self.descending
+        if self.nulls_first:
+            self.nulls_last = True
+            self.nulls_first = None
+        elif self.nulls_last:
+            self.nulls_first = True
+            self.nulls_last = None
+        return self
+
+    def asc(self) -> None:  # type: ignore[override]
+        self.descending = False
+
+    def desc(self) -> None:  # type: ignore[override]
+        self.descending = True
+
+
+class Window(Expression):
+    template = "%(expression)s OVER (%(window)s)"
+    # Although the main expression may either be an aggregate or an
+    # expression with an aggregate function, the GROUP BY that will
+    # be introduced in the query as a result is not desired.
+    contains_aggregate = False
+    contains_over_clause = True
+    partition_by: ExpressionList | None
+    order_by: OrderByList | None
+
+    def __init__(
+        self,
+        expression: Any,
+        partition_by: Any = None,
+        order_by: Any = None,
+        frame: Any = None,
+        output_field: Field | None = None,
+    ):
+        self.partition_by = partition_by
+        self.order_by = order_by
+        self.frame = frame
+
+        if not getattr(expression, "window_compatible", False):
+            raise ValueError(
+                f"Expression '{expression.__class__.__name__}' isn't compatible with OVER clauses."
+            )
+
+        if self.partition_by is not None:
+            partition_by_values = (
+                self.partition_by
+                if isinstance(self.partition_by, tuple | list)
+                else (self.partition_by,)
+            )
+            self.partition_by = ExpressionList(*partition_by_values)
+
+        if self.order_by is not None:
+            if isinstance(self.order_by, list | tuple):
+                self.order_by = OrderByList(*self.order_by)
+            elif isinstance(self.order_by, BaseExpression | str):
+                self.order_by = OrderByList(self.order_by)
+            else:
+                raise ValueError(
+                    "Window.order_by must be either a string reference to a "
+                    "field, an expression, or a list or tuple of them."
+                )
+        super().__init__(output_field=output_field)
+        self.source_expression = self._parse_expressions(expression)[0]
+
+    def _resolve_output_field(self) -> Field | None:
+        return self.source_expression.output_field
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.source_expression, self.partition_by, self.order_by, self.frame]
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.source_expression, self.partition_by, self.order_by, self.frame = exprs
+
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: DatabaseConnection,
+        template: str | None = None,
+    ) -> tuple[str, tuple[Any, ...]]:
+        expr_sql, params = compiler.compile(self.source_expression)
+        window_sql, window_params = [], ()
+
+        if self.partition_by is not None:
+            sql_expr, sql_params = self.partition_by.as_sql(
+                compiler=compiler,
+                connection=connection,
+                template="PARTITION BY %(expressions)s",
+            )
+            window_sql.append(sql_expr)
+            window_params += tuple(sql_params)
+
+        if self.order_by is not None:
+            order_sql, order_params = compiler.compile(self.order_by)
+            window_sql.append(order_sql)
+            window_params += tuple(order_params)
+
+        if self.frame:
+            frame_sql, frame_params = compiler.compile(self.frame)
+            window_sql.append(frame_sql)
+            window_params += tuple(frame_params)
+
+        template = template or self.template
+
+        return (
+            template % {"expression": expr_sql, "window": " ".join(window_sql).strip()},
+            (*params, *window_params),
+        )
+
+    def __str__(self) -> str:
+        return "{} OVER ({}{}{})".format(
+            str(self.source_expression),
+            "PARTITION BY " + str(self.partition_by) if self.partition_by else "",
+            str(self.order_by or ""),
+            str(self.frame or ""),
+        )
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def get_group_by_cols(self) -> list[Any]:
+        group_by_cols = []
+        if self.partition_by:
+            group_by_cols.extend(self.partition_by.get_group_by_cols())
+        if self.order_by is not None:
+            group_by_cols.extend(self.order_by.get_group_by_cols())
+        return group_by_cols
+
+
+class WindowFrame(Expression):
+    """
+    Model the frame clause in window expressions. There are two types of frame
+    clauses which are subclasses, however, all processing and validation (by no
+    means intended to be complete) is done here. Thus, providing an end for a
+    frame is optional (the default is UNBOUNDED FOLLOWING, which is the last
+    row in the frame).
+    """
+
+    template = "%(frame_type)s BETWEEN %(start)s AND %(end)s"
+    frame_type: str
+
+    def __init__(self, start: int | None = None, end: int | None = None):
+        self.start = Value(start)
+        self.end = Value(end)
+
+    def set_source_expressions(self, exprs: Sequence[Any]) -> None:
+        self.start, self.end = exprs
+
+    def get_source_expressions(self) -> list[Any]:
+        return [self.start, self.end]
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        start, end = self.window_frame_start_end(
+            connection, self.start.value, self.end.value
+        )
+        return (
+            self.template
+            % {
+                "frame_type": self.frame_type,
+                "start": start,
+                "end": end,
+            },
+            [],
+        )
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def get_group_by_cols(self) -> list[Any]:
+        return []
+
+    def __str__(self) -> str:
+        if self.start.value is not None and self.start.value < 0:
+            start = f"{abs(self.start.value)} {PRECEDING}"
+        elif self.start.value is not None and self.start.value == 0:
+            start = CURRENT_ROW
+        else:
+            start = UNBOUNDED_PRECEDING
+
+        if self.end.value is not None and self.end.value > 0:
+            end = f"{self.end.value} {FOLLOWING}"
+        elif self.end.value is not None and self.end.value == 0:
+            end = CURRENT_ROW
+        else:
+            end = UNBOUNDED_FOLLOWING
+        return self.template % {
+            "frame_type": self.frame_type,
+            "start": start,
+            "end": end,
+        }
+
+    def window_frame_start_end(
+        self, connection: DatabaseConnection, start: int | None, end: int | None
+    ) -> tuple[str, str]:
+        """Return the window frame start and end for the given connection."""
+        raise NotImplementedError("Subclasses must implement window_frame_start_end()")
+
+
+class RowRange(WindowFrame):
+    frame_type = "ROWS"
+
+    def window_frame_start_end(
+        self, connection: DatabaseConnection, start: int | None, end: int | None
+    ) -> tuple[str, str]:
+        return window_frame_rows_start_end(start, end)
+
+
+class ValueRange(WindowFrame):
+    frame_type = "RANGE"
+
+    def window_frame_start_end(
+        self, connection: DatabaseConnection, start: int | None, end: int | None
+    ) -> tuple[str, str]:
+        return window_frame_range_start_end(start, end)