lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/expr/derivations.py

@@ -0,0 +1,306 @@
+"""Derivations (design 5.8): compile ``expression`` Derivations and aggregate filters, evaluate
+them over one Record, and tell which derived Attributes and Relations they read.
+
+Recomputing derived values when Records change is the materializer's job; this module only
+computes one value from one Record (whose values may include other derived values).
+``derivation_inputs`` lists the derived Attributes a Derivation may read, for cycle detection
+and evaluation order; ``links_read`` lists the ``links.<relation>`` fields an expression reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, fields
+
+from pydantic import JsonValue
+
+from lorebase_core.expr.ast import Ident, Node, Select, parse
+from lorebase_core.expr.compiler import CompiledExpression, compile, run
+from lorebase_core.expr.context import EvaluationContext, activation
+from lorebase_core.expr.environment import LINKS, LinkField, link_fields, record_environment
+from lorebase_core.expr.errors import ExprError, ExprErrorCode, PathPart
+from lorebase_core.expr.limits import ExprLimits
+from lorebase_core.expr.ops import require_bool
+from lorebase_core.expr.types import BOOL, from_type_spec
+from lorebase_core.expr.values import encode_result
+from lorebase_core.model.derivation import AggregateDerivation, Derivation, ExpressionDerivation
+from lorebase_core.model.record import Record
+from lorebase_core.model.schema import Schema
+from lorebase_core.types import TypeSpec
+
+
+@dataclass(frozen=True, eq=False)
+class CompiledDerivation:
+    """An ``expression`` Derivation (``expression`` and ``target`` set) or an aggregate with a
+    ``filter`` over the Records it aggregates."""
+
+    derivation: Derivation
+    expression: CompiledExpression | None = None
+    target: TypeSpec | None = None
+    filter: CompiledExpression | None = None
+
+
+def _compile(
+    schema: Schema, derivation: Derivation, limits: ExprLimits, errors: list[ExprError] | None
+) -> CompiledDerivation:
+    definition = derivation.definition
+
+    def fail(error: ExprError, path: tuple[PathPart, ...]) -> None:
+        error.located(path=path)
+        if errors is None:
+            raise error
+        errors.append(error)
+
+    if isinstance(definition, ExpressionDerivation):
+        kind = schema.kinds.get(definition.kind)
+        attribute = kind.attributes.get(definition.attribute) if kind is not None else None
+        if kind is None or attribute is None:
+            if errors is None:
+                raise ExprError(ExprErrorCode.TYPE, "the Derivation's target does not exist")
+            return CompiledDerivation(derivation)
+        if LINKS in {a.api_name for a in kind.attributes.values()}:
+            fail(
+                ExprError(
+                    ExprErrorCode.TYPE, f"attribute name {LINKS!r} is reserved in expressions"
+                ),
+                ("definition", "kind"),
+            )
+        try:
+            program = compile(
+                definition.expression,
+                record_environment(schema, kind.id),
+                expected=from_type_spec(attribute.type),
+                nullable=True,
+                limits=limits,
+            )
+        except ExprError as error:
+            fail(error, ("definition", "expression"))
+            return CompiledDerivation(derivation)
+        return CompiledDerivation(derivation, expression=program, target=attribute.type)
+    if isinstance(definition, AggregateDerivation) and definition.filter is not None:
+        relation = schema.link_relation(definition.relation)
+        if relation is None:
+            if errors is None:
+                raise ExprError(ExprErrorCode.TYPE, "the aggregated Relation does not exist")
+            return CompiledDerivation(derivation)
+        far = relation.far_endpoint(definition.direction)
+        try:
+            program = compile(
+                definition.filter,
+                record_environment(schema, far),
+                expected=BOOL,
+                limits=limits,
+            )
+        except ExprError as error:
+            fail(error, ("definition", "filter"))
+            return CompiledDerivation(derivation)
+        return CompiledDerivation(derivation, filter=program)
+    return CompiledDerivation(derivation)
+
+
+def compile_derivation(
+    schema: Schema, derivation: Derivation, limits: ExprLimits | None = None
+) -> CompiledDerivation:
+    """Compile the expressions of ``derivation``; raises the first ``ExprError``."""
+    return _compile(schema, derivation, limits or ExprLimits(), None)
+
+
+def derivation_expression_errors(
+    schema: Schema, derivation: Derivation, limits: ExprLimits | None = None
+) -> list[ExprError]:
+    """Every expression problem of ``derivation`` (paths inside the element)."""
+    errors: list[ExprError] = []
+    _compile(schema, derivation, limits or ExprLimits(), errors)
+    return errors
+
+
+def evaluate_derivation(
+    compiled: CompiledDerivation, record: Record, context: EvaluationContext
+) -> JsonValue:
+    """The canonical value an ``expression`` Derivation computes for ``record``.
+
+    ``None`` means no value. Raises ``ExprError`` when evaluation fails or the result does
+    not fit the target Attribute (``expression.value_invalid``).
+    """
+    if compiled.expression is None or compiled.target is None:
+        raise ExprError(ExprErrorCode.EVALUATION, "not an expression Derivation")
+    program = compiled.expression
+    variables = activation(program.environment, record=record)
+    value = run(
+        program,
+        variables,
+        now=context.now,
+        resolver=context.resolver,
+        limits=context.limits,
+    )
+    return encode_result(compiled.target, value)
+
+
+def matches_filter(
+    compiled: CompiledDerivation, record: Record, context: EvaluationContext
+) -> bool:
+    """Whether a Record at the far end of an aggregate passes its ``filter`` (true if none)."""
+    if compiled.filter is None:
+        return True
+    variables = activation(compiled.filter.environment, record=record)
+    value = run(
+        compiled.filter,
+        variables,
+        now=context.now,
+        resolver=context.resolver,
+        limits=context.limits,
+    )
+    return require_bool(value, "filter")
+
+
+# Dependencies ------------------------------------------------------------------------------------
+
+
+def _nodes(node: Node) -> Iterator[Node]:
+    """``node`` and every node below it."""
+    yield node
+    for item in fields(node):
+        value = getattr(node, item.name)
+        children = value if isinstance(value, tuple) else (value,)
+        for child in children:
+            for part in child if isinstance(child, tuple) else (child,):
+                if isinstance(part, Node):
+                    yield from _nodes(part)
+
+
+@dataclass(frozen=True)
+class _Names:
+    """Identifiers, selected fields and ``links.<name>`` fields of an expression."""
+
+    idents: frozenset[str]
+    fields: frozenset[str]
+    links: frozenset[str]
+
+
+def _names(root: Node) -> _Names:
+    idents: set[str] = set()
+    selected: set[str] = set()
+    links: set[str] = set()
+    for node in _nodes(root):
+        if isinstance(node, Ident):
+            idents.add(node.name)
+        elif isinstance(node, Select):
+            selected.add(node.field)
+            if isinstance(node.operand, Ident) and node.operand.name == LINKS:
+                links.add(node.field)
+    return _Names(frozenset(idents), frozenset(selected), frozenset(links))
+
+
+def links_read(program: CompiledExpression) -> list[LinkField]:
+    """The ``links.<relation>`` fields a Record expression reads, in name order."""
+    names = _names(program.root).links
+    available = program.environment.link_fields
+    return [available[name] for name in sorted(names) if name in available]
+
+
+def _record_inputs(schema: Schema, kind_id: str, source: str, limits: ExprLimits) -> set[str]:
+    """Derived Attributes an expression over a Record of ``kind_id`` may read: its own derived
+    Attributes named in it, and derived Attributes of Records one hop away (through a
+    ``links.<relation>`` field) whose name appears in it. Conservative by design."""
+    try:
+        names = _names(parse(source, limits))
+    except ExprError:
+        return set()  # reported by expression validation
+    words = names.idents | names.fields
+    inputs: set[str] = set()
+    kind = schema.kinds.get(kind_id)
+    if kind is not None:
+        inputs.update(
+            a.id for a in kind.attributes.values() if a.is_derived and a.api_name in names.idents
+        )
+    available = link_fields(schema, kind_id)
+    for name in names.links:
+        field = available.get(name)
+        far = (
+            None
+            if field is None
+            else schema.kinds.get(field.relation.far_endpoint(field.direction))
+        )
+        if far is not None:
+            inputs.update(
+                a.id for a in far.attributes.values() if a.is_derived and a.api_name in words
+            )
+    return inputs
+
+
+def derivation_inputs(
+    schema: Schema, derivation: Derivation, limits: ExprLimits | None = None
+) -> frozenset[str]:
+    """Ids of the derived Attributes ``derivation`` may read (a superset, never fewer).
+
+    An ``expression`` Derivation reads its Record and the Records one hop away; an aggregate
+    reads the ``source_attribute`` and the ``filter`` of the Records it aggregates. Path
+    Derivations read nothing derived.
+    """
+    limits = limits or ExprLimits()
+    definition = derivation.definition
+    if isinstance(definition, ExpressionDerivation):
+        return frozenset(_record_inputs(schema, definition.kind, definition.expression, limits))
+    if not isinstance(definition, AggregateDerivation):
+        return frozenset()
+    relation = schema.link_relation(definition.relation)
+    if relation is None:
+        return frozenset()
+    far_id = relation.far_endpoint(definition.direction)
+    far = schema.kinds.get(far_id)
+    inputs: set[str] = set()
+    if far is not None and definition.source_attribute is not None:
+        source = far.attributes.get(definition.source_attribute)
+        if source is not None and source.is_derived:
+            inputs.add(source.id)
+    if definition.filter is not None:
+        inputs.update(_record_inputs(schema, far_id, definition.filter, limits))
+    return frozenset(inputs)
+
+
+def _expression_reads(
+    schema: Schema, kind_id: str, source: str, limits: ExprLimits
+) -> set[tuple[str, str]]:
+    """`(Kind id, Attribute id)` of every Attribute an expression over a Record of `kind_id`
+    may read: its own Attributes named in it and those of Records one hop away (through a
+    ``links.<relation>`` field) whose name appears in it. A superset, never fewer."""
+    try:
+        names = _names(parse(source, limits))
+    except ExprError:
+        return set()  # reported by expression validation
+    words = names.idents | names.fields
+    reads: set[tuple[str, str]] = set()
+    kind = schema.kinds.get(kind_id)
+    if kind is not None:
+        reads.update((kind_id, a.id) for a in kind.attributes.values() if a.api_name in words)
+    available = link_fields(schema, kind_id)
+    for name in names.links:
+        field = available.get(name)
+        far_id = None if field is None else field.relation.far_endpoint(field.direction)
+        far = None if far_id is None else schema.kinds.get(far_id)
+        if far is not None:
+            reads.update((far.id, a.id) for a in far.attributes.values() if a.api_name in words)
+    return reads
+
+
+def derivation_reads(
+    schema: Schema, derivation: Derivation, limits: ExprLimits | None = None
+) -> frozenset[tuple[str, str]]:
+    """`(Kind id, Attribute id)` of every Attribute, stored or derived, a Derivation may read
+    (a superset): what its value can tell, for sensitivity (`schema.sensitivity_inherited`)."""
+    limits = limits or ExprLimits()
+    definition = derivation.definition
+    if isinstance(definition, ExpressionDerivation):
+        return frozenset(_expression_reads(schema, definition.kind, definition.expression, limits))
+    if not isinstance(definition, AggregateDerivation):
+        return frozenset()
+    relation = schema.link_relation(definition.relation)
+    if relation is None:
+        return frozenset()
+    far_id = relation.far_endpoint(definition.direction)
+    reads: set[tuple[str, str]] = set()
+    if definition.source_attribute is not None:
+        reads.add((far_id, definition.source_attribute))
+    if definition.filter is not None:
+        reads.update(_expression_reads(schema, far_id, definition.filter, limits))
+    return frozenset(reads)

lorebase_core/expr/environment.py

@@ -0,0 +1,176 @@
+"""Typed environments: the names an expression may use, derived from the Schema.
+
+- Operation expressions (preconditions, review policy, step values): ``params.<name>`` and
+  each parameter by its bare name, ``principal.id`` and ``principal.subjects``, the
+  functions ``record(ref)`` and ``links(ref, "relation")``; in steps also ``$step[n]``, the
+  Record of an earlier step.
+- Record expressions (Derivations, aggregate filters): the Record's Attributes by api name,
+  ``key``, and ``links.<relation>``: the Records one hop away, by forward or inverse
+  Relation name (or path Derivation name).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from lorebase_core.expr.types import (
+    DOUBLE,
+    DYN,
+    GEO_POINT,
+    STRING,
+    ExprType,
+    TypeKind,
+    from_type_spec,
+    list_of,
+    object_of,
+    record_of,
+    ref_of,
+)
+from lorebase_core.model.operation import (
+    CreateRecordStep,
+    DeleteRecordStep,
+    Operation,
+    UpdateRecordStep,
+)
+from lorebase_core.model.relation import LinkDirection, Relation
+from lorebase_core.model.schema import Schema
+from lorebase_core.types import TypeSpec
+
+#: Names an Operation environment defines itself; parameters cannot use them.
+PARAMS = "params"
+PRINCIPAL = "principal"
+#: Names a Record environment defines itself; Attributes cannot use them (``key`` is
+#: reserved for Attributes by schema validation already).
+KEY = "key"
+LINKS = "links"
+#: Fields of a ``record(Kind)`` value besides its Attributes.
+RECORD_KEY = "key"
+RECORD_REF = "ref"
+
+PRINCIPAL_FIELDS: Mapping[str, ExprType] = {"id": STRING, "subjects": list_of(STRING)}
+GEO_POINT_FIELDS: Mapping[str, ExprType] = {"lat": DOUBLE, "lon": DOUBLE}
+
+
+@dataclass(frozen=True, slots=True)
+class LinkField:
+    """A ``links.<name>`` field: the Relation and the direction it is traversed in."""
+
+    relation: Relation
+    direction: LinkDirection
+
+
+@dataclass(frozen=True, eq=False)
+class Environment:
+    """Declared names and types. ``subject`` is the Kind id whose Attributes are variables;
+    ``parameters`` are the Operation parameter types (to decode parameter values)."""
+
+    schema: Schema
+    variables: Mapping[str, ExprType]
+    objects: Mapping[str, Mapping[str, ExprType]] = field(default_factory=dict)
+    subject: str | None = None
+    records: bool = False
+    step_types: tuple[ExprType | None, ...] | None = None
+    link_fields: Mapping[str, LinkField] = field(default_factory=dict)
+    parameters: Mapping[str, TypeSpec] = field(default_factory=dict)
+    _record_fields: dict[str, dict[str, ExprType]] = field(
+        default_factory=dict, repr=False, compare=False
+    )
+
+    def kind_name(self, kind_id: str) -> str:
+        kind = self.schema.kinds.get(kind_id)
+        return kind.api_name if kind is not None else kind_id
+
+    def describe(self, expr_type: ExprType) -> str:
+        return expr_type.describe(self.kind_name)
+
+    def record_fields(self, kind_id: str) -> dict[str, ExprType]:
+        """Fields of ``record(kind)`` values: Attributes by api name, ``key`` and ``ref``."""
+        cached = self._record_fields.get(kind_id)
+        if cached is not None:
+            return cached
+        fields: dict[str, ExprType] = {}
+        kind = self.schema.kinds.get(kind_id)
+        if kind is not None:
+            fields = {a.api_name: from_type_spec(a.type) for a in kind.attributes.values()}
+        fields[RECORD_KEY] = STRING
+        fields[RECORD_REF] = ref_of(kind_id)
+        self._record_fields[kind_id] = fields
+        return fields
+
+    def fields_of(self, expr_type: ExprType) -> Mapping[str, ExprType] | None:
+        """Fields of a record or object type; ``None`` for other types."""
+        if expr_type.kind is TypeKind.RECORD and expr_type.name is not None:
+            return self.record_fields(expr_type.name)
+        if expr_type.kind is TypeKind.OBJECT and expr_type.name is not None:
+            if expr_type.name == GEO_POINT:
+                return GEO_POINT_FIELDS
+            return self.objects.get(expr_type.name)
+        return None
+
+
+def operation_environment(
+    schema: Schema, operation: Operation, *, step_index: int | None = None
+) -> Environment:
+    """Environment of an Operation's expressions; with ``step_index``, of that step's."""
+    parameters = {p.name: from_type_spec(p.type) for p in operation.parameters}
+    variables: dict[str, ExprType] = dict(parameters)
+    variables[PARAMS] = object_of(PARAMS)
+    variables[PRINCIPAL] = object_of(PRINCIPAL)
+    step_types: tuple[ExprType | None, ...] | None = None
+    if step_index is not None:
+        step_types = tuple(_step_type(schema, step) for step in operation.steps[:step_index])
+    return Environment(
+        schema=schema,
+        variables=variables,
+        objects={PARAMS: parameters, PRINCIPAL: PRINCIPAL_FIELDS},
+        records=True,
+        step_types=step_types,
+        parameters={p.name: p.type for p in operation.parameters},
+    )
+
+
+def _step_type(schema: Schema, step: object) -> ExprType | None:
+    """Type of ``$step[n]``: the Record reference, ``dyn`` for an unknown Kind (reported by
+    schema validation), ``None`` for Link steps."""
+    if isinstance(step, CreateRecordStep | UpdateRecordStep | DeleteRecordStep):
+        return ref_of(step.kind) if step.kind in schema.kinds else DYN
+    return None
+
+
+def record_environment(schema: Schema, kind_id: str) -> Environment:
+    """Environment of expressions over one Record of ``kind_id`` (Derivations, filters)."""
+    kind = schema.kinds.get(kind_id)
+    variables: dict[str, ExprType] = {}
+    if kind is not None:
+        variables = {a.api_name: from_type_spec(a.type) for a in kind.attributes.values()}
+    links = link_fields(schema, kind_id)
+    variables[KEY] = STRING
+    variables[LINKS] = object_of(LINKS)
+    link_types = {
+        name: list_of(record_of(f.relation.far_endpoint(f.direction))) for name, f in links.items()
+    }
+    return Environment(
+        schema=schema,
+        variables=variables,
+        objects={LINKS: link_types},
+        subject=kind_id,
+        link_fields=links,
+    )
+
+
+def link_fields(schema: Schema, kind_id: str) -> dict[str, LinkField]:
+    """Relation names usable from a Record of ``kind_id``: forward names of Relations that
+    start at the Kind, inverse names of Relations that end there; path Derivations count as
+    Relations (their virtual Relation, design 5.8)."""
+    fields: dict[str, LinkField] = {}
+    relations = [
+        *schema.relations.values(),
+        *(path.relation for path in schema.path_relations().values()),
+    ]
+    for relation in relations:
+        if relation.to_kind == kind_id and relation.inverse_api_name:
+            fields[relation.inverse_api_name] = LinkField(relation, LinkDirection.INVERSE)
+        if relation.from_kind == kind_id:
+            fields[relation.api_name] = LinkField(relation, LinkDirection.FORWARD)
+    return fields

lorebase_core/expr/errors.py

@@ -0,0 +1,98 @@
+"""Errors of the expression engine: one exception type with a stable code and a position."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+PathPart = str | int
+
+
+class ExprErrorCode(StrEnum):
+    """Stable codes; ``syntax`` and ``type`` are static, the others come from evaluation."""
+
+    SYNTAX = "expression.syntax"
+    TYPE = "expression.type"
+    EVALUATION = "expression.evaluation"
+    LIMIT_EXCEEDED = "expression.limit_exceeded"
+    VALUE_INVALID = "expression.value_invalid"
+    RECORD_NOT_FOUND = "record.not_found"
+    RECORD_EXISTS = "record.exists"
+
+
+@dataclass(frozen=True, slots=True)
+class Position:
+    """1-based line and column of a node in the expression source."""
+
+    line: int
+    column: int
+
+    def __str__(self) -> str:
+        return f"{self.line}:{self.column}"
+
+
+class ExprError(Exception):
+    """A problem with an expression: compiling it, or evaluating it.
+
+    ``path`` locates the expression inside its schema element (for example
+    ``("preconditions", 0, "expression")``); it is empty until a caller sets it.
+    """
+
+    def __init__(
+        self,
+        code: ExprErrorCode,
+        message: str,
+        *,
+        position: Position | None = None,
+        source: str | None = None,
+        path: tuple[PathPart, ...] = (),
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.position = position
+        self.source = source
+        self.path = path
+
+    def located(
+        self, *, source: str | None = None, path: tuple[PathPart, ...] | None = None
+    ) -> ExprError:
+        """This error with the expression source and path filled in where they are missing."""
+        if source is not None and self.source is None:
+            self.source = source
+        if path is not None and not self.path:
+            self.path = path
+        return self
+
+    def describe(self) -> str:
+        """``line:column: message`` when the position is known, the message otherwise."""
+        if self.position is None:
+            return self.message
+        return f"{self.position}: {self.message}"
+
+    def snippet(self) -> str:
+        """The source line of the error with a caret under the column (empty if unknown)."""
+        if self.position is None or self.source is None:
+            return ""
+        lines = self.source.splitlines() or [""]
+        line = lines[min(self.position.line, len(lines)) - 1]
+        return f"{line}\n{' ' * (self.position.column - 1)}^"
+
+    def __str__(self) -> str:
+        return self.describe()
+
+
+def syntax_error(message: str, position: Position | None = None) -> ExprError:
+    return ExprError(ExprErrorCode.SYNTAX, message, position=position)
+
+
+def type_error(message: str, position: Position | None = None) -> ExprError:
+    return ExprError(ExprErrorCode.TYPE, message, position=position)
+
+
+def evaluation_error(message: str, position: Position | None = None) -> ExprError:
+    return ExprError(ExprErrorCode.EVALUATION, message, position=position)
+
+
+def limit_error(message: str, position: Position | None = None) -> ExprError:
+    return ExprError(ExprErrorCode.LIMIT_EXCEEDED, message, position=position)