hare-orm 0.9.0__py3-none-any.whl

hare/sql/functions/datetime/extract.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hare.sql.builder_methods import BuilderMethods
+from hare.sql.terms.functions.function import Function
+from hare.sql.terms.term import Term
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Self
+
+    from hare.sql.builder.tables.table import Table
+    from hare.sql.terms.node import TNode
+
+
+class Extract(Function):
+    """A part of a date or time - written by the dialect's renderer."""
+
+    requires_dialect_renderer = True
+
+    def __init__(
+        self,
+        date_part: Any,
+        term: Term,
+        alias: str | None = None,
+        *,
+        zone_name: str | None = None,
+        use_local_zone_when_naive: bool = False,
+        as_integer: bool = False,
+        zone_as_literal: bool = False,
+        is_time_of_day: bool = False,
+    ) -> None:
+        """
+        Args:
+            date_part: Which component to extract (``DatePart.YEAR``, etc).
+            term: The term to extract from.
+            zone_name: When set, the extraction happens in this named time zone instead of
+                whatever zone the underlying value is already stored/returned in. Only passed
+                for an aware ``DatetimeField`` under ``use_timezone=True``; a ``DateField`` has no
+                time component for a zone to shift, and passing ``None`` here (the default)
+                renders exactly the previous, unqualified extraction.
+            use_local_zone_when_naive: When ``zone_name`` is ``None`` and this is ``True``, the
+                extraction reads the value in the machine's local zone - on a dialect whose
+                timestamp column holds an instant (a naive value held as an instant in that zone,
+                while a bare ``EXTRACT`` would read it in the session's zone). A dialect storing the
+                wall-clock digits themselves extracts them as they are and ignores it. Only set for a
+                naive ``DatetimeField`` (``use_timezone=False``).
+            alias: Optional alias for the term.
+            as_integer: Cast the result to an integer - ``EXTRACT`` may return a numeric.
+            zone_as_literal: Render ``zone_name`` as a literal rather than a parameter - an
+                extraction selected, grouped, ordered and made ``DISTINCT ON`` renders the same
+                expression in each clause, which a database compares by text (two parameters
+                are two expressions). The zone is a validated IANA name.
+            is_time_of_day: The term is a time of day - on a database storing one as text, the text
+                is read as a time first.
+        """
+        super().__init__("EXTRACT", date_part, alias=alias)
+        self.field = term
+        self.date_part = date_part
+        self.zone_name = zone_name
+        self.use_local_zone_when_naive = use_local_zone_when_naive
+        self.as_integer = as_integer
+        self.zone_as_literal = zone_as_literal
+        self.is_time_of_day = is_time_of_day
+
+    def nodes_(self) -> Iterator[TNode]:
+        yield from super().nodes_()
+        yield from self.field.nodes_()
+
+    @property
+    def is_aggregate(self) -> bool | None:  # type:ignore[override]
+        """Whether the extraction reads an aggregate - by the term it reads, kept apart from its
+        arguments: of a column it is grouped by, not taken for a constant."""
+        return Term.get_combined_is_aggregate([*(arg.is_aggregate for arg in self.args), self.field.is_aggregate])
+
+    @BuilderMethods.builder
+    def replace_table(self, current_table: Table | None, new_table: Table | None) -> Self:
+        """Replaces all occurrences of the specified table with the new table.
+
+        Useful when reusing fields across queries.
+
+        Args:
+            current_table: The table to be replaced.
+            new_table: The table to replace with.
+
+        Returns:
+            A copy of the term with the tables replaced.
+        """
+        self.args = [parameter.replace_table(current_table, new_table) for parameter in self.args]
+        self.field = self.field.replace_table(current_table, new_table)
+        return self

hare/sql/functions/datetime/now.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.function import Function
+
+
+class Now(Function):
+    """The current moment - ISO SQL's ``CURRENT_TIMESTAMP``."""
+
+    def __init__(self, alias: str | None = None) -> None:
+        super().__init__("CURRENT_TIMESTAMP", alias=alias)
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        return "CURRENT_TIMESTAMP"

hare/sql/functions/datetime/temporal_difference.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class TemporalDifference(Function):
+    """Difference `left - right` of two datetime or two date terms, as a BIGINT of microseconds.
+
+    Each dialect computes it exactly - from the epoch difference for datetimes and the integer day
+    difference for dates, or by hare's function where it has none.
+    """
+
+    requires_dialect_renderer = True
+
+    def __init__(self, left: Any, right: Any, *, is_date: bool = False, alias: str | None = None) -> None:
+        """
+        Args:
+            left: The minuend datetime/date term.
+            right: The subtrahend datetime/date term.
+            is_date: Whether both terms are dates rather than datetimes.
+            alias: Optional alias for the term.
+        """
+        super().__init__("TEMPORAL_DIFFERENCE", left, right, alias=alias)
+        self.is_date = is_date

hare/sql/functions/datetime/temporal_shift.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class TemporalShift(Function):
+    """Adds a signed microsecond count to a datetime or date - an absolute duration, never a calendar
+    day; a date result is floored back to a date. A dialect writes it as interval arithmetic of whole
+    hours plus a microsecond remainder, or calls hare's function doing the same on the stored text.
+    """
+
+    requires_dialect_renderer = True
+
+    def __init__(
+        self,
+        base: Any,
+        microseconds: Any,
+        *,
+        is_date: bool = False,
+        is_subtraction: bool = False,
+        is_naive: bool = False,
+        alias: str | None = None,
+    ) -> None:
+        """
+        Args:
+            base: The datetime/date term to shift.
+            microseconds: A BIGINT term holding the (unsigned-by-operator) microsecond count.
+            is_date: Whether `base` is a date rather than a datetime.
+            is_subtraction: Whether the count is subtracted instead of added.
+            is_naive: Whether `base` is a wall clock in no zone (``NaiveDatetimeField``).
+            alias: Optional alias for the term.
+        """
+        super().__init__("TEMPORAL_SHIFT", base, microseconds, alias=alias)
+        self.is_date = is_date
+        self.is_subtraction = is_subtraction
+        self.is_naive = is_naive

hare/sql/functions/datetime/timestamp_comparand.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.function import Function
+
+
+class TimestampComparand(Function):
+    """A timestamp a date column is compared with - the column is compared as ``DateAsTimestamp``.
+    Rendered as the timestamp itself."""
+
+    def __init__(self, term: Any, zone_name: str | None, alias: str | None = None) -> None:
+        super().__init__("CAST", term, alias=alias)
+        self.zone_name = zone_name
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        return self.get_arg_sql(self.args[0], sql_context)

hare/sql/functions/declarations.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from hare.sql.functions.json.json_value import JsonValue
+from hare.sql.terms.functions.function import Function
+
+
+class MathFunction(Function):
+    """A math function - the database's own, or hare's where the dialect registers one."""
+
+
+class TextFunction(Function):
+    """A text function - the database's own (its first argument read as text), or hare's where the
+    dialect registers one."""
+
+
+class JsonComparand(JsonValue):
+    """The JSON value of a typed expression, in the form the value at a JSON path compares with -
+    the dialect's JSON form of it (a number as it is and any other value as JSON text, say). NULL stays
+    NULL."""

hare/sql/functions/distinct_option_function.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hare.sql.builder_methods import BuilderMethods
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.aggregate_function import AggregateFunction
+
+if TYPE_CHECKING:
+    from typing import Self
+
+
+class DistinctOptionFunction(AggregateFunction):
+    """An aggregate taking ``DISTINCT`` before its arguments (``distinct()``)."""
+
+    def __init__(self, name: str, *args: Any, **kwargs: Any) -> None:
+        alias = kwargs.get("alias")
+        super().__init__(name, *args, alias=alias)
+        self._distinct = False
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        function_sql = super().get_function_sql(sql_context)
+
+        # After the name the SQL was written with - the dialect's own name when it renames it.
+        name_length = len(self.get_dialect_special_name(sql_context) or self.name) + 1
+        if self._distinct:
+            return function_sql[:name_length] + "DISTINCT " + function_sql[name_length:]
+        return function_sql
+
+    @BuilderMethods.builder
+    def distinct(self) -> Self:
+        self._distinct = True
+        return self

hare/sql/functions/greatest_least.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.function import Function
+
+
+class GreatestLeast(Function):
+    """``GREATEST``/``LEAST`` - the database's own, or hare's comparing Decimals kept as text as numbers
+    where the dialect registers one."""
+
+    def __init__(self, name: str, *args: Any, compares_numbers: bool = False, alias: str | None = None) -> None:
+        """
+        Args:
+            name: ``GREATEST`` or ``LEAST``.
+            args: The values.
+            compares_numbers: The values are numbers - compared numerically, also as stored text.
+            alias: Optional alias for the term.
+        """
+        super().__init__(name, *args, alias=alias)
+        self.compares_numbers = compares_numbers
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        return f"{self.name}({', '.join(self.get_arg_sql(arg, sql_context) for arg in self.args)})"

hare/sql/functions/grouping_function.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.aggregate_function import AggregateFunction
+
+
+class GroupingFunction(AggregateFunction):
+    """``GROUPING(a, b)`` - per group of several groupings, a bit per term set where the group leaves
+    the term out (SQL:1999). Computed per group, like an aggregate."""
+
+    def __init__(self, *terms: Any, alias: str | None = None) -> None:
+        super().__init__("GROUPING", *terms, alias=alias)

hare/sql/functions/json/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

hare/sql/functions/json/json_array.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class JsonArray(Function):
+    """A JSON array of the arguments - each dialect writes its own function."""
+
+    requires_dialect_renderer = True
+
+    def __init__(self, *arguments: Any, alias: str | None = None) -> None:
+        super().__init__("JSON_ARRAY", *arguments, alias=alias)

hare/sql/functions/json/json_object.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class JsonObject(Function):
+    """A JSON object of ``key, value, ...`` arguments - each dialect writes its own function."""
+
+    requires_dialect_renderer = True
+
+    def __init__(self, *arguments: Any, alias: str | None = None) -> None:
+        super().__init__("JSON_OBJECT", *arguments, alias=alias)

hare/sql/functions/json/json_sort_key.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class JsonSortKey(Function):
+    """A JSON value in the form its database orders and compares it - the value itself, the value a
+    database's own function reads of a path, or the typed value it reads of JSON text."""
+
+    requires_dialect_renderer = True
+
+    def __init__(self, term: Any, alias: str | None = None) -> None:
+        super().__init__("JSON", term, alias=alias)

hare/sql/functions/json/json_value.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.enums import JsonValueType
+from hare.sql.functions.text.collate import Collate
+from hare.sql.terms.functions.function import Function
+
+
+class JsonValue(Function):
+    """A value of a JSON value a database builds, with the type its database writes it by. A naive
+    timestamp (``is_aware=False``) is written as its wall clock."""
+
+    requires_dialect_renderer = True
+
+    def __init__(self, term: Any, value_type: JsonValueType, is_aware: bool = True, alias: str | None = None) -> None:
+        super().__init__("JSON", Collate.strip(term), alias=alias)
+        self.value_type = value_type
+        self.is_aware = is_aware

hare/sql/functions/numeric_cast.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.functions.cast import Cast
+from hare.sql.types.sql_types import SqlTypes
+
+
+class NumericCast(Cast):
+    """``CAST(term AS NUMERIC)`` for a Decimal compared or aggregated outside a column, on a dialect
+    storing Decimals as text - a value without column affinity compares TEXT above every number.
+    Such a NUMERIC may not be exact: a fractional value keeps ~15 significant digits.
+    """
+
+    def __init__(self, term: Any, alias: str | None = None) -> None:
+        super().__init__(term, SqlTypes.NUMERIC, alias=alias)

hare/sql/functions/random_number.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from hare.sql.terms.functions.function import Function
+
+
+class RandomNumber(Function):
+    """A random float from 0 (included) to 1 (excluded), new for every row - each dialect writes
+    its own function."""
+
+    requires_dialect_renderer = True
+
+    def __init__(self, alias: str | None = None) -> None:
+        super().__init__("RANDOM", alias=alias)

hare/sql/functions/round.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.exceptions import QueryException
+from hare.sql.terms.functions.function import Function
+from hare.sql.terms.values.literal_value import LiteralValue
+
+
+class Round(Function):
+    """``ROUND(x, precision)``."""
+
+    def __init__(self, term: Any, precision: int, alias: str | None = None) -> None:
+        if isinstance(precision, bool) or not isinstance(precision, int):
+            raise QueryException(f"ROUND takes an int precision, got {precision!r}")
+        # The precision is a SQL literal, not a bind parameter - it's part of the SQL text.
+        super().__init__("ROUND", term, LiteralValue(str(int(precision))), alias=alias)
+        self.precision = int(precision)
+        #: Whether the value rounded is a Decimal - a dialect rounding a double rounds it otherwise.
+        self.rounds_decimal = False

hare/sql/functions/statistic.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from hare.sql.functions.distinct_option_function import DistinctOptionFunction
+from hare.sql.sql_context import SqlContext
+
+
+class Statistic(DistinctOptionFunction):
+    """A statistic aggregate (``STDDEV_POP``, ``VAR_SAMP``, ...) - the database's own, or hare's where it
+    has none."""
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        return self.get_statistic_sql(self.name, sql_context)
+
+    def get_statistic_sql(self, name: str, sql_context: SqlContext) -> str:
+        """The aggregate called by ``name``."""
+        args_sql = ",".join(self.get_arg_sql(arg, sql_context) for arg in self.args)
+        sql = f"{name}({'DISTINCT ' if self._distinct else ''}{args_sql})"
+        if self._include_filter:
+            sql += f" FILTER({self.get_filter_sql(sql_context)})"
+        return sql

hare/sql/functions/std_dev.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.functions.statistic import Statistic
+
+
+# Arithmetic Functions
+class StdDev(Statistic):
+    """The sample standard deviation - ``STDDEV``."""
+
+    def __init__(self, term: Any, alias: str | None = None) -> None:
+        super().__init__("STDDEV_SAMP", term, alias=alias)

hare/sql/functions/text/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

hare/sql/functions/text/collate.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.function import Function
+
+
+class Collate(Function):
+    """`term COLLATE collation` - compares and sorts a text value by the named collation.
+
+    A database may carry an explicit collation on into every expression built on top of the term (a
+    function call, CASE, COALESCE), not just into the comparison it's written in.
+    """
+
+    def __init__(self, term: Any, collation: str, alias: str | None = None, *, names_collation: bool = False) -> None:
+        """
+        Args:
+            term: The text term.
+            collation: The collation - its SQL as it is, or a name the dialect writes.
+            alias: The term's alias.
+            names_collation: Whether ``collation`` is a name the dialect writes
+                (``SqlLiterals.get_collation_sql()``) - one a user gave.
+        """
+        super().__init__("COLLATE", term, alias=alias)
+        self.collation = collation
+        self.names_collation = names_collation
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        term_sql = self.get_arg_sql(self.args[0], sql_context)
+        collation_sql = (
+            sql_context.dialect.literals.get_collation_sql(self.collation) if self.names_collation else self.collation
+        )
+        return f"({term_sql} COLLATE {collation_sql})"
+
+    @classmethod
+    def strip(cls, term: Any) -> Any:
+        """The term without its collation.
+
+        Args:
+            term: A term, possibly a `Collate`.
+
+        Returns:
+            The collated term itself for a `Collate`, `term` unchanged otherwise.
+        """
+        return term.args[0] if isinstance(term, cls) else term
+
+    @staticmethod
+    def is_decimal_text(term: Any) -> bool:
+        """Whether a term is a DecimalField column's text under an exact-decimal collation.
+
+        Args:
+            term: A term.
+
+        Returns:
+            True for a `DecimalTextCollate`.
+        """
+        # Imported here: the modules import each other.
+        from hare.sql.functions.text.decimal_text_collate import DecimalTextCollate
+
+        return isinstance(term, DecimalTextCollate)

hare/sql/functions/text/concat.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.sql_context import SqlContext
+from hare.sql.terms.functions.function import Function
+
+
+class Concat(Function):
+    """The texts of its terms joined, a NULL term read as empty text - ISO SQL's ``||`` over
+    ``COALESCE(term, '')``; a dialect with a ``CONCAT()`` of the same meaning renders that."""
+
+    def __init__(self, *terms: Any, **kwargs: Any) -> None:
+        super().__init__("CONCAT", *terms, **kwargs)
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        terms_sql = [f"COALESCE({self.get_arg_sql(term, sql_context)}, '')" for term in self.args]
+        return f"({' || '.join(terms_sql)})"

hare/sql/functions/text/concat_function.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, time
+from decimal import Decimal
+from typing import Any
+
+from hare.sql import SqlContext, functions
+from hare.sql.terms.values.value_wrapper import ValueWrapper
+from hare.time import Timezone
+
+
+class ConcatFunction(functions.Concat):
+    """``CONCAT`` of arguments - a Python literal as its text: a bool as 'true'/'false', a float as
+    ``repr()`` writes it, a Decimal with every digit it has and no exponent, a date/datetime/time as ISO text;
+    the dialect types what is left."""
+
+    @staticmethod
+    def format_temporal_literal(value: date) -> str:
+        """Text a date/datetime literal is concatenated as - the same on every dialect.
+
+        Args:
+            value: The literal; an aware datetime is converted to UTC first - without time zone
+                support (``use_timezone=False``) to the local wall clock a naive value is written as.
+
+        Returns:
+            The ISO-formatted text.
+        """
+        if isinstance(value, datetime):
+            if value.tzinfo is not None:
+                value = (
+                    value.astimezone(UTC) if Timezone.get_use_timezone() else Timezone.get_system_local_naive(value)
+                )
+            return value.isoformat(" ")
+        return value.isoformat()
+
+    @classmethod
+    def get_arg_sql(cls, arg: Any, sql_context: SqlContext) -> str:
+        if isinstance(arg, ValueWrapper) and isinstance(arg.value, (bool, date, time, float, Decimal)):
+            # Rendered as its text - the parameter holds no value of the literal itself.
+            if sql_context.parameterizer is not None:
+                sql_context.parameterizer.record_literal(arg)
+            if isinstance(arg.value, bool):
+                arg = ValueWrapper("true" if arg.value else "false")
+            elif isinstance(arg.value, date):
+                arg = ValueWrapper(cls.format_temporal_literal(arg.value))
+            elif isinstance(arg.value, time):
+                arg = ValueWrapper(arg.value.isoformat())
+            elif isinstance(arg.value, Decimal):
+                arg = ValueWrapper(format(arg.value, "f"))
+            else:
+                arg = ValueWrapper(repr(arg.value))
+        sql = arg.get_sql(sql_context.copy(with_alias=False)) if hasattr(arg, "get_sql") else str(arg)
+        return sql_context.dialect.renderers.get_concatenated_argument_sql(sql, arg)

hare/sql/functions/text/decimal_text_collate.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from hare.sql.functions.text.collate import Collate
+from hare.sql.sql_context import SqlContext
+
+
+class DecimalTextCollate(Collate):
+    """A DecimalField column's text compared by an exact-decimal collation, on a dialect storing a
+    Decimal as text. SQL kept in DDL or a migration can't name the collation - a Decimal compares as
+    a number there.
+    """
+
+    def get_function_sql(self, sql_context: SqlContext) -> str:
+        if sql_context.native_functions_only:
+            return f"CAST({self.get_arg_sql(self.args[0], sql_context)} AS NUMERIC)"
+        return super().get_function_sql(sql_context)

hare/sql/functions/text/lower.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class Lower(Function):
+    """``LOWER(text)``."""
+
+    def __init__(self, term: Any, alias: str | None = None) -> None:
+        super().__init__("LOWER", term, alias=alias)

hare/sql/functions/text/replace.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class Replace(Function):
+    """``REPLACE(text, from, to)`` - every ``from`` in ``text`` replaced by ``to``."""
+
+    def __init__(self, term: Any, old: Any, new: Any, alias: str | None = None) -> None:
+        super().__init__("REPLACE", term, old, new, alias=alias)

hare/sql/functions/text/upper.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.sql.terms.functions.function import Function
+
+
+class Upper(Function):
+    """``UPPER(text)``."""
+
+    def __init__(self, term: Any, alias: str | None = None) -> None:
+        super().__init__("UPPER", term, alias=alias)