lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/expr/ops.py

@@ -0,0 +1,243 @@
+"""Operator semantics on runtime values: equality, ordering, arithmetic.
+
+CEL rules with the Lorebase additions: ``decimal`` arithmetic is exact (with ``int``
+operands promoted), numbers of different kinds compare by value, ``date`` takes whole-day
+durations, and integer results must stay in the int64 range. ``int`` and ``double`` do not
+mix in arithmetic (convert with ``double()`` or ``decimal()``). Division by zero, overflow
+and arithmetic on an absent value (null) are evaluation errors.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import date, datetime, timedelta
+from decimal import Context, Decimal, DecimalException
+from typing import TypeGuard
+
+from lorebase_core.expr.errors import ExprError, evaluation_error
+from lorebase_core.expr.values import ObjectValue, RecordValue, Ref, type_name
+from lorebase_core.types import INT64_MAX, INT64_MIN, GeoPoint
+
+_DAY = timedelta(days=1)
+
+
+Number = int | float | Decimal
+
+
+def is_number(value: object) -> TypeGuard[Number]:
+    return isinstance(value, int | float | Decimal) and not isinstance(value, bool)
+
+
+def check_int(value: int) -> int:
+    if not INT64_MIN <= value <= INT64_MAX:
+        raise evaluation_error("integer overflow: the result is outside the int64 range")
+    return value
+
+
+def require_bool(value: object, what: str) -> bool:
+    if not isinstance(value, bool):
+        raise evaluation_error(f"{what} must be a bool, got {type_name(value)}")
+    return value
+
+
+def _absent(operation: str) -> ExprError:
+    return evaluation_error(
+        f"{operation} on an absent value (null); test presence with has() first"
+    )
+
+
+def equals(left: object, right: object) -> bool:
+    """CEL equality: values of different types are not equal, numbers compare by value."""
+    if left is None or right is None:
+        return left is None and right is None
+    if isinstance(left, bool) or isinstance(right, bool):
+        return isinstance(left, bool) and isinstance(right, bool) and left == right
+    if is_number(left) and is_number(right):
+        return bool(left == right)
+    if isinstance(left, datetime) or isinstance(right, datetime):
+        return isinstance(left, datetime) and isinstance(right, datetime) and left == right
+    if isinstance(left, RecordValue) and isinstance(right, RecordValue):
+        return left.kind.id == right.kind.id and left.key == right.key
+    if isinstance(left, list) and isinstance(right, list):
+        return len(left) == len(right) and all(
+            equals(a, b) for a, b in zip(left, right, strict=True)
+        )
+    if isinstance(left, dict) and isinstance(right, dict):
+        if len(left) != len(right):
+            return False
+        for key, value in left.items():
+            match = [k for k in right if equals(k, key)]
+            if not match or not equals(value, right[match[0]]):
+                return False
+        return True
+    if isinstance(left, ObjectValue) and isinstance(right, ObjectValue):
+        return left.name == right.name and equals(dict(left.fields), dict(right.fields))
+    if type(left) is not type(right) and not (
+        isinstance(left, GeoPoint) and isinstance(right, GeoPoint)
+    ):
+        return False
+    return bool(left == right)
+
+
+def contains(container: object, item: object) -> bool:
+    """``item in container`` for lists (elements) and maps (keys)."""
+    if isinstance(container, list):
+        return any(equals(item, element) for element in container)
+    if isinstance(container, dict):
+        return any(equals(item, key) for key in container)
+    if container is None:
+        raise _absent("'in'")
+    raise evaluation_error(f"'in' needs a list or a map, got {type_name(container)}")
+
+
+def compare(left: object, right: object) -> int:
+    """-1, 0 or 1; numbers of any kind compare by value, other values within their type."""
+    if left is None or right is None:
+        raise _absent("comparison")
+    if is_number(left) and is_number(right):
+        return int(left > right) - int(left < right)
+    same = type(left) is type(right) or (
+        isinstance(left, date)
+        and isinstance(right, date)
+        and isinstance(left, datetime) == isinstance(right, datetime)
+    )
+    if same and isinstance(left, str | bytes | bool | date | timedelta):
+        return (left > right) - (left < right)  # type: ignore[operator]
+    raise evaluation_error(f"cannot order {type_name(left)} and {type_name(right)}")
+
+
+def negate(value: object, decimals: Context) -> object:
+    if value is None:
+        raise _absent("negation")
+    if isinstance(value, bool):
+        raise evaluation_error("cannot negate a bool; use !")
+    if isinstance(value, int):
+        return check_int(-value)
+    if isinstance(value, float):
+        return -value
+    if isinstance(value, Decimal):
+        return decimals.minus(value)
+    if isinstance(value, timedelta):
+        return -value
+    raise evaluation_error(f"cannot negate {type_name(value)}")
+
+
+def arithmetic(op: str, left: object, right: object, decimals: Context) -> object:
+    """``+ - * / %`` on runtime values (see the module docstring)."""
+    if left is None or right is None:
+        raise _absent(f"operator {op}")
+    try:
+        result = _arithmetic(op, left, right, decimals)
+    except (OverflowError, DecimalException) as error:
+        raise evaluation_error(f"operator {op} failed: {_reason(error)}") from None
+    if result is NotImplemented:
+        raise evaluation_error(
+            f"operator {op} is not defined for {type_name(left)} and {type_name(right)}"
+        )
+    return result
+
+
+def _reason(error: Exception) -> str:
+    if isinstance(error, DecimalException):
+        return error.__class__.__name__.lower()
+    return str(error) or error.__class__.__name__
+
+
+def _arithmetic(op: str, left: object, right: object, decimals: Context) -> object:
+    if isinstance(left, bool) or isinstance(right, bool):
+        return NotImplemented
+    if is_number(left) and is_number(right):
+        return _numeric(op, left, right, decimals)
+    if op == "+":
+        if isinstance(left, str) and isinstance(right, str):
+            return left + right
+        if isinstance(left, bytes) and isinstance(right, bytes):
+            return left + right
+        if isinstance(left, list) and isinstance(right, list):
+            return left + right
+    return _temporal(op, left, right)
+
+
+def _numeric(op: str, left: object, right: object, decimals: Context) -> object:
+    if isinstance(left, Decimal) or isinstance(right, Decimal):
+        if isinstance(left, float) or isinstance(right, float):
+            raise evaluation_error("decimal and double do not mix; convert with decimal()")
+        assert is_number(left)
+        assert is_number(right)
+        a = left if isinstance(left, Decimal) else Decimal(left)
+        b = right if isinstance(right, Decimal) else Decimal(right)
+        if op in ("/", "%") and b.is_zero():
+            raise evaluation_error("division by zero")
+        operations = {
+            "+": decimals.add,
+            "-": decimals.subtract,
+            "*": decimals.multiply,
+            "/": decimals.divide,
+            "%": decimals.remainder,
+        }
+        return operations[op](a, b)
+    if isinstance(left, float) or isinstance(right, float):
+        if not (isinstance(left, float) and isinstance(right, float)):
+            raise evaluation_error("int and double do not mix; convert with double() or int()")
+        if op == "%":
+            return NotImplemented
+        if op == "/" and right == 0.0:
+            raise evaluation_error("division by zero")
+        value = {"+": left + right, "-": left - right, "*": left * right}.get(op)
+        result = left / right if value is None else value
+        if not math.isfinite(result):
+            raise evaluation_error(f"operator {op} overflowed the double range")
+        return result
+    assert isinstance(left, int)
+    assert isinstance(right, int)
+    if op in ("/", "%"):
+        if right == 0:
+            raise evaluation_error("division by zero")
+        quotient = abs(left) // abs(right)
+        if (left < 0) != (right < 0):
+            quotient = -quotient
+        return check_int(quotient if op == "/" else left - right * quotient)
+    return check_int({"+": left + right, "-": left - right, "*": left * right}[op])
+
+
+def _temporal(op: str, left: object, right: object) -> object:
+    if op == "+":
+        if isinstance(left, timedelta) and isinstance(right, date | timedelta):
+            left, right = right, left
+        if isinstance(left, datetime) and isinstance(right, timedelta):
+            return left + right
+        if isinstance(left, date) and isinstance(right, timedelta):
+            return left + _whole_days(right)
+        if isinstance(left, timedelta) and isinstance(right, timedelta):
+            return left + right
+        return NotImplemented
+    if op == "-":
+        if isinstance(left, datetime) and isinstance(right, datetime):
+            return left - right
+        if isinstance(left, datetime) and isinstance(right, timedelta):
+            return left - right
+        if isinstance(left, datetime) or isinstance(right, datetime):
+            return NotImplemented
+        if isinstance(left, date) and isinstance(right, date):
+            return left - right
+        if isinstance(left, date) and isinstance(right, timedelta):
+            return left - _whole_days(right)
+        if isinstance(left, timedelta) and isinstance(right, timedelta):
+            return left - right
+    return NotImplemented
+
+
+def _whole_days(duration: timedelta) -> timedelta:
+    if duration % _DAY:
+        raise evaluation_error("only whole days can be added to or subtracted from a date")
+    return duration
+
+
+def ref_key(value: object, what: str) -> Ref:
+    if isinstance(value, Ref):
+        return value
+    if isinstance(value, RecordValue):
+        return value.ref
+    if value is None:
+        raise evaluation_error(f"{what} is null")
+    raise evaluation_error(f"{what} must be a Record reference, got {type_name(value)}")

lorebase_core/expr/resolver.py

@@ -0,0 +1,96 @@
+"""How evaluation reads Records it does not hold: the ``RecordResolver`` protocol.
+
+The engine never touches a store. Callers pass a resolver answering from Records they have
+loaded. A resolver that has not loaded what is asked raises ``RecordNotLoaded``; the engine
+lets it through untouched, so the caller can load the Record (or the Links) and evaluate
+again. Evaluation is deterministic, so a retry computes the same result.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from pydantic import JsonValue
+
+from lorebase_core.model.relation import LinkDirection
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRequest:
+    """One Record by Kind id and key."""
+
+    kind: str
+    key: str
+
+
+@dataclass(frozen=True, slots=True)
+class LinksRequest:
+    """The Records linked to ``key`` through ``relation``, traversed in ``direction``."""
+
+    relation: str
+    direction: LinkDirection
+    key: str
+
+
+@dataclass(frozen=True, slots=True)
+class LinkedRecord:
+    """A Record at the far end of a Link: its key, its values and the Link's values."""
+
+    key: str
+    values: Mapping[str, JsonValue]
+    link_values: Mapping[str, JsonValue] = field(default_factory=dict)
+
+
+class RecordNotLoaded(Exception):  # noqa: N818 - a signal to the caller, not an error
+    """The resolver does not hold what evaluation needs; load ``request`` and retry."""
+
+    def __init__(self, request: RecordRequest | LinksRequest) -> None:
+        super().__init__(f"not loaded: {request}")
+        self.request = request
+
+
+class RecordResolver(Protocol):
+    """Read access to Records for ``record()``, ``links()`` and ``links.<relation>``.
+
+    Values are canonical and keyed by Attribute id (derived values may be included).
+    """
+
+    def record(self, kind_id: str, key: str) -> Mapping[str, JsonValue] | None:
+        """The values of the Record, ``None`` if it does not exist."""
+        ...
+
+    def linked(
+        self, relation_id: str, direction: LinkDirection, key: str
+    ) -> Sequence[LinkedRecord]:
+        """Records linked to ``key``; ``direction`` says which end ``key`` is."""
+        ...
+
+
+@dataclass
+class MemoryResolver:
+    """A resolver over loaded data. Unknown entries raise ``RecordNotLoaded``.
+
+    ``records`` maps ``(kind_id, key)`` to values, or to ``None`` for a Record known not to
+    exist. ``links`` maps ``(relation_id, direction, key)`` to the linked Records.
+    """
+
+    records: dict[tuple[str, str], Mapping[str, JsonValue] | None] = field(default_factory=dict)
+    links: dict[tuple[str, LinkDirection, str], Sequence[LinkedRecord]] = field(
+        default_factory=dict
+    )
+
+    def record(self, kind_id: str, key: str) -> Mapping[str, JsonValue] | None:
+        try:
+            return self.records[(kind_id, key)]
+        except KeyError:
+            raise RecordNotLoaded(RecordRequest(kind_id, key)) from None
+
+    def linked(
+        self, relation_id: str, direction: LinkDirection, key: str
+    ) -> Sequence[LinkedRecord]:
+        try:
+            return self.links[(relation_id, direction, key)]
+        except KeyError:
+            raise RecordNotLoaded(LinksRequest(relation_id, direction, key)) from None

lorebase_core/expr/rows.py

@@ -0,0 +1,148 @@
+"""Expressions over one row of a Source (design 5.9): the ``expression`` of an Attribute
+mapping.
+
+A row is what the Source reads before any mapping: column name to raw value (text for CSV and
+TSV, native values for JSON and databases). Every column whose name is an identifier is a
+variable, typed ``dyn`` because the Source does not declare column types; ``row`` is the map of
+all columns, for names that are not identifiers (``row["Legal name"]``). Nothing else is in
+scope: no Records, no Links, no principal.
+
+The result is a runtime value that the mapping's transforms take as the column value, and that
+is coerced to the Attribute type like one. ``row_value`` gives its JSON form.
+
+``RowExpressions`` compiles each expression once over the columns of a Source (the header, or
+every key its rows have) and evaluates it on any row: a column the row lacks is null. Scribe
+maps rows and Keeper previews them with it, so both give the same value for the same rows.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import JsonValue
+
+from lorebase_core.expr.compiler import CompiledExpression, compile, run
+from lorebase_core.expr.environment import Environment
+from lorebase_core.expr.errors import ExprError
+from lorebase_core.expr.limits import ExprLimits
+from lorebase_core.expr.types import DYN, STRING, map_of
+from lorebase_core.expr.values import to_raw
+from lorebase_core.model.schema import Schema
+
+#: The variable holding every column of the row.
+ROW = "row"
+
+#: Decimal results whose adjusted exponent is beyond this get the exponent form in
+#: ``row_value`` (``1E+100000``), not a plain form of that many digits.
+PLAIN_DECIMAL_MAX_EXPONENT = 100
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_RESERVED = frozenset(
+    {"true", "false", "null", "in", "as", "break", "const", "continue", "else", "for", "function"}
+    | {"if", "import", "let", "loop", "package", "namespace", "return", "var", "void", "while"}
+    | {ROW}
+)
+
+
+def row_variables(columns: Iterable[str]) -> list[str]:
+    """The columns that are variables of a row expression, sorted."""
+    return sorted({c for c in columns if _IDENTIFIER.match(c) and c not in _RESERVED})
+
+
+def row_environment(schema: Schema, columns: Iterable[str]) -> Environment:
+    """Environment of the expressions over rows with these columns."""
+    variables = dict.fromkeys(row_variables(columns), DYN)
+    variables[ROW] = map_of(STRING, DYN)
+    return Environment(schema=schema, variables=variables)
+
+
+def compile_row_expression(
+    schema: Schema, expression: str, columns: Iterable[str], limits: ExprLimits | None = None
+) -> CompiledExpression:
+    """Parse and type check ``expression`` over rows with ``columns``; raises ``ExprError``."""
+    return compile(expression, row_environment(schema, columns), limits=limits)
+
+
+def evaluate_row_expression(
+    compiled: CompiledExpression, row: Mapping[str, object], *, now: datetime
+) -> object:
+    """The runtime value of ``compiled`` for ``row``; raises ``ExprError``. Every column
+    ``compiled`` was compiled over is a variable: one the row lacks is null."""
+    variables: dict[str, object] = {
+        name: row.get(name) for name in compiled.environment.variables if name != ROW
+    }
+    variables[ROW] = dict(row)
+    return run(compiled, variables, now=now)
+
+
+class RowExpressions:
+    """The expressions of one Source over its columns, each compiled once.
+
+    ``columns`` are the columns the Source has (its header, or every key its rows have); a row
+    with a column not declared yet adds it, and the expressions are compiled again over the
+    larger set. A declared column a row lacks is null, as a variable and in ``row``.
+    """
+
+    def __init__(
+        self, schema: Schema, columns: Iterable[str] = (), limits: ExprLimits | None = None
+    ) -> None:
+        self._schema = schema
+        self._limits = limits
+        self._columns: dict[str, None] = dict.fromkeys(columns)
+        self._programs: dict[str, CompiledExpression | ExprError] = {}
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        """The declared columns, in the order they were first seen."""
+        return tuple(self._columns)
+
+    def declare(self, columns: Iterable[str]) -> None:
+        """Add columns; the expressions compile again only when one is new."""
+        added = [c for c in columns if c not in self._columns]
+        if added:
+            self._columns.update(dict.fromkeys(added))
+            self._programs.clear()
+
+    def compiled(self, expression: str) -> CompiledExpression:
+        """``expression`` compiled over the declared columns; raises ``ExprError`` (the error
+        is kept like a program, so a bad expression is checked once)."""
+        program = self._programs.get(expression)
+        if program is None:
+            try:
+                program = compile_row_expression(
+                    self._schema, expression, self._columns, self._limits
+                )
+            except ExprError as error:
+                program = error
+            self._programs[expression] = program
+        if isinstance(program, ExprError):
+            raise program.with_traceback(None)
+        return program
+
+    def evaluate(self, expression: str, row: Mapping[str, object], *, now: datetime) -> object:
+        """The runtime value of ``expression`` for ``row``; raises ``ExprError``."""
+        self.declare(row)
+        compiled = self.compiled(expression)
+        return evaluate_row_expression(compiled, {**dict.fromkeys(self._columns), **row}, now=now)
+
+
+def row_value(value: object) -> JsonValue:
+    """JSON form of a runtime value: decimals and dates as text, containers recursively.
+    A decimal is in plain form unless its exponent is beyond ``PLAIN_DECIMAL_MAX_EXPONENT``."""
+    raw = to_raw(value)
+    if raw is None or isinstance(raw, bool | int | float | str):
+        return raw
+    if isinstance(raw, Decimal):
+        if raw.is_finite() and abs(raw.adjusted()) > PLAIN_DECIMAL_MAX_EXPONENT:
+            return str(raw)
+        return format(raw, "f")
+    if isinstance(raw, datetime | date):
+        return raw.isoformat()
+    if isinstance(raw, list):
+        return [row_value(item) for item in raw]
+    if isinstance(raw, dict):
+        return {str(k): row_value(v) for k, v in raw.items()}
+    return str(raw)