pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/ast/_candidates.py

@@ -0,0 +1,309 @@
+"""Which members of a union may take an input (Effect's candidate index).
+
+A member is a candidate by the input's kind (``"string"``, ``"object"``,
+...), a ``Literal`` member only for its literal. Members that are mappings
+with required literal keys (``"_tag": "A"``) or tuples with required
+literal elements (``("a", ...)``), Effect's sentinels, are discriminated:
+an input picks them by the values it holds under those keys or indexes,
+before any member is parsed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, cast
+
+from pyfect.logger._text import format_unknown, json_quote
+from pyfect.schema.ast._arrays import Arrays
+from pyfect.schema.ast._base import AST
+from pyfect.schema.ast._class import Class
+from pyfect.schema.ast._encoding import Encoding, to_encoded
+from pyfect.schema.ast._keywords import BigInt, Boolean, Never, Null, Number, String, Unknown
+from pyfect.schema.ast._literal import Enum, Literal, LiteralValue, same_literal
+from pyfect.schema.ast._objects import ObjectKeys, Objects, reads_properties
+from pyfect.schema.ast._suspend import Suspend
+
+if TYPE_CHECKING:
+    from pyfect.schema.ast._union import Union
+
+ALL = frozenset({"null", "string", "number", "bigint", "boolean", "array", "object"})
+NOT_NULL = ALL - {"null"}
+OBJECT = frozenset({"object"})
+ARRAY = frozenset({"array"})
+
+_VALUE_KINDS: tuple[tuple[type, frozenset[str]], ...] = (
+    (type(None), frozenset({"null"})),
+    (bool, frozenset({"boolean"})),
+    (int, frozenset({"number", "bigint"})),
+    (float, frozenset({"number"})),
+    (str, frozenset({"string"})),
+    (list, frozenset({"array"})),
+    (tuple, frozenset({"array"})),
+)
+
+_NODE_KINDS: tuple[tuple[type[AST], frozenset[str]], ...] = (
+    (Null, frozenset({"null"})),
+    (String, frozenset({"string"})),
+    (Number, frozenset({"number"})),
+    (BigInt, frozenset({"bigint"})),
+    (Boolean, frozenset({"boolean"})),
+)
+
+
+def kind_of(value: object) -> frozenset[str]:
+    """The kinds a value is (a Python ``int`` is a number and a bigint)."""
+    return next((kinds for t, kinds in _VALUE_KINDS if isinstance(value, t)), OBJECT)
+
+
+def _literal_kind(literal: LiteralValue) -> frozenset[str]:
+    return (
+        frozenset({"number"})
+        if isinstance(literal, int | float) and not isinstance(literal, bool)
+        else kind_of(literal)
+    )
+
+
+def _members(ast: AST) -> tuple[AST, ...] | None:
+    """A union's members; ``None`` for any other node."""
+    from pyfect.schema.ast._union import Union
+
+    return ast.types if isinstance(ast, Union) else None
+
+
+def kinds(ast: AST) -> frozenset[str]:  # noqa: PLR0911
+    """The kinds of input ``ast`` may accept (Effect's ``getCandidateTypes``)."""
+    members = _members(ast)
+    if members is not None:
+        return frozenset[str]().union(*map(kinds, members))
+    match ast:
+        case Literal(literal=literal):
+            return _literal_kind(literal)
+        case Enum(side="decode" | "encoded"):
+            return frozenset[str]().union(*(_literal_kind(m.value) for m in ast.enum))
+        case Objects(properties=(), index_signatures=()):
+            return NOT_NULL
+        case Objects() | Class(side="decode" | "encoded"):
+            return OBJECT
+        case Arrays():
+            return ARRAY
+        case _:
+            return next((kinds for t, kinds in _NODE_KINDS if isinstance(ast, t)), ALL)
+
+
+type Sentinel = tuple[Hashable, LiteralValue]
+"""A required key (or a tuple's index) and the literal it must hold."""
+
+
+def _input_side(ast: AST) -> AST:
+    """The node of what the member takes as input (Effect's ``toCandidate``).
+    A suspended member takes anything: selecting candidates never makes it
+    (it may be the union itself)."""
+    return Unknown() if isinstance(ast, Suspend) else _settled(ast).flip().to_type()
+
+
+def _settled(ast: AST) -> AST:
+    """``ast`` with every part whose failures a middleware sees (and may
+    recover from, as ``catch_decoding`` does) taken as ``Unknown``: such a
+    part may take any input and holds no sentinel (Effect's ``toCandidate``)."""
+    encoding = ast.encoding
+    if encoding is not None:
+        return _settled_encoding(ast, encoding)
+    members = _members(ast)
+    if members is not None:
+        return cast("Union", ast).map_types(_settled)
+    match ast:
+        case Objects(properties=properties):
+            types = [_settled(p.type) for p in properties]
+            if all(t is p.type for t, p in zip(types, properties, strict=True)):
+                return ast
+            settled = (replace(p, type=t) for t, p in zip(types, properties, strict=True))
+            return replace(ast, properties=tuple(settled))
+        case Arrays():
+            return ast.map_types(_settled)
+        case _:
+            return ast
+
+
+def _settled_encoding(ast: AST, encoding: Encoding) -> AST:
+    if any(link.transformation.sees_failures for link in encoding):
+        return Unknown()
+    *links, last = encoding
+    source = _settled(last.to)
+    return ast if source is last.to else replace(ast, encoding=(*links, replace(last, to=source)))
+
+
+def sentinels(ast: AST) -> tuple[Sentinel, ...]:
+    """The required literal keys of a mapping node and the required literal
+    elements of a tuple, by index (Effect's ``collectSentinels``); a union's
+    are those all its members share."""
+    members = _members(ast)
+    if members is not None:
+        if not members:
+            return ()
+        each = [sentinels(_input_side(m)) for m in members]
+        return tuple(s for s in each[0] if all(_has(other, s) for other in each[1:]))
+    match ast:
+        case Objects(properties=properties):
+            return tuple(
+                (p.name, p.type.literal)
+                for p in properties
+                if not p.optional and isinstance(p.type, Literal)
+            )
+        case Class(side="encoded" | "decode"):
+            return sentinels(ast.shape.encoded)
+        case Arrays(elements=elements):
+            return tuple(
+                (i, e.type.literal)
+                for i, e in enumerate(elements)
+                if not e.optional and isinstance(e.type, Literal)
+            )
+        case _:
+            return ()
+
+
+def _has(found: Sequence[Sentinel], sentinel: Sentinel) -> bool:
+    key, literal = sentinel
+    return any(k == key and same_literal(literal, v) for k, v in found)
+
+
+@dataclass(frozen=True, slots=True)
+class _Member:
+    literal: tuple[LiteralValue] | None
+    """``(literal,)`` for a ``Literal`` member."""
+    sentinels: tuple[Sentinel, ...]
+    kinds: frozenset[str]
+    never: bool
+
+
+def _member(ast: AST) -> _Member:
+    side = _input_side(ast)
+    found = sentinels(side)
+    literal = (side.literal,) if isinstance(side, Literal) else None
+    return _Member(literal, found, frozenset() if found else kinds(side), isinstance(side, Never))
+
+
+_ABSENT = object()
+
+
+def _observed(
+    input: object, keys: tuple[Hashable, ...]
+) -> tuple[dict[Hashable, object], frozenset[str]] | None:
+    """The values ``input`` holds under the sentinel ``keys`` (a mapping's
+    keys, an object's attributes, a list's or tuple's indexes) and its kind;
+    ``None`` when it is none of these."""
+    if isinstance(input, Mapping) or reads_properties(input):
+        mapping = (
+            cast("Mapping[object, object]", input)
+            if isinstance(input, Mapping)
+            else ObjectKeys(input)
+        )
+        return {key: mapping[key] for key in keys if key in mapping}, OBJECT
+    if isinstance(input, list | tuple):
+        items = cast("Sequence[object]", input)
+        n = len(items)
+        return {key: items[key] for key in keys if type(key) is int and 0 <= key < n}, ARRAY
+    return None
+
+
+class CandidateIndex:
+    """The candidates of a union's members for an input."""
+
+    __slots__ = ("_members", "_only_literals", "_sentinel_keys")
+
+    def __init__(self, types: Sequence[AST]) -> None:
+        self._members = [_member(t) for t in types]
+        live = [m for m in self._members if not m.never]
+        self._only_literals = bool(live) and all(m.literal is not None for m in live)
+        keys: dict[Hashable, None] = {}
+        for m in live:
+            for key, _ in m.sentinels:
+                keys[key] = None
+        self._sentinel_keys = tuple(keys)
+
+    def __call__(self, input: object, constructing: bool = False) -> list[int]:
+        """The candidates for ``input``; under a constructor (Effect's
+        constructor mode) a missing sentinel key selects every member that
+        has it, as a constructor default may fill it in."""
+        members = self._members
+        if self._only_literals:
+            return [
+                i
+                for i, m in enumerate(members)
+                if m.literal is not None and not m.never and same_literal(m.literal[0], input)
+            ]
+        if self._sentinel_keys:
+            observed = _observed(input, self._sentinel_keys)
+            if observed is not None:
+                return self._by_sentinels(*observed, constructing)
+        return self._by_kind(input)
+
+    def _by_kind(self, input: object) -> list[int]:
+        kind = kind_of(input)
+
+        def takes(m: _Member) -> bool:
+            if m.literal is not None:
+                return same_literal(m.literal[0], input)
+            return not m.kinds.isdisjoint(kind)
+
+        return [
+            i for i, m in enumerate(self._members) if not m.never and not m.sentinels and takes(m)
+        ]
+
+    def _by_sentinels(
+        self, observed: dict[Hashable, object], kind: frozenset[str], constructing: bool
+    ) -> list[int]:
+        """Discriminated members whose sentinels the input does not
+        contradict and that one of its sentinel values selects (or, when
+        ``constructing``, that has a key the input lacks), plus the other
+        members taking the input's kind. A missing key is neutral."""
+        selected: list[int] = []
+        for i, m in enumerate(self._members):
+            if m.never:
+                continue
+            if not m.sentinels:
+                if not m.kinds.isdisjoint(kind):
+                    selected.append(i)
+                continue
+            matched = False
+            contradicted = False
+            for key, literal in m.sentinels:
+                value = observed.get(key, _ABSENT)
+                if value is _ABSENT:
+                    matched = matched or constructing
+                    continue
+                if same_literal(literal, value):
+                    matched = True
+                else:
+                    contradicted = True
+            if matched and not contradicted:
+                selected.append(i)
+        return selected
+
+
+def member_expected(ast: AST) -> str:
+    """How a union names a member: a mapping with literal keys as
+    ``{ readonly "_tag": "A", ... }``, a tuple with literal elements as
+    ``readonly [ "a", ... ]``, any other as its encoded side expects (what
+    the union decodes from)."""
+    side = to_encoded(ast)
+    if isinstance(side, Class) and side.side == "encoded":
+        side = side.shape.encoded
+    if isinstance(side, Arrays):
+        literals = [e for e in side.elements if isinstance(e.type, Literal)]
+        if literals:
+            entries = ", ".join(f"{e.type.expected()}{'?' if e.optional else ''}" for e in literals)
+            return f"{'' if side.mutable else 'readonly '}[ {entries}, ... ]"
+    if isinstance(side, Objects):
+        literals = [p for p in side.properties if isinstance(p.type, Literal)]
+        if literals:
+            entries = ", ".join(
+                f"readonly {_format_key(p.name)}{'?' if p.optional else ''}: {p.type.expected()}"
+                for p in literals
+            )
+            return f"{{ {entries}, ... }}"
+    return side.expected()
+
+
+def _format_key(key: Hashable) -> str:
+    return json_quote(key) if isinstance(key, str) else format_unknown(key)

pyfect/schema/ast/_check.py

@@ -0,0 +1,181 @@
+"""Checks (Effect's ``SchemaAST.Filter`` / ``FilterGroup``): validations a
+node runs on a value of its own kind.
+
+A ``Filter`` runs a function giving ``None`` (pass) or an issue; a
+``FilterGroup`` runs several checks as one. Each failure is wrapped in an
+``issue.Filter`` naming the check, so the formatter can print the check's
+``message`` or ``"Expected <expected>"``. With ``errors="first"`` the first
+failure stops the checks; with ``errors="all"`` every check runs unless one
+marked ``abort()`` fails.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from pyfect.schema import issue as _issue
+from pyfect.schema.issue import Composite, InvalidValue, Issue, Path, Pointer, is_issue, reported
+
+if TYPE_CHECKING:
+    from pyfect.schema._options import ParseOptions
+    from pyfect.schema.ast._base import AST, Annotations
+
+type FilterIssue = str | Issue | tuple[Path, str | Issue]
+"""One failure a filter function reports: a message, an issue, or either
+at a path below the value (Effect's ``{ path, issue }``)."""
+
+type FilterOutput = bool | FilterIssue | list[FilterIssue] | None
+"""What a filter function gives: ``True`` / ``None`` / ``[]`` to accept,
+``False`` (``"Expected <expected>"``), one failure or a list of them."""
+
+
+T_contra = TypeVar("T_contra", contravariant=True)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Filter(Generic[T_contra]):
+    """One check. ``run(value, ast, options)`` gives ``None`` or the issue;
+    ``annotations`` describe it (``expected``, ``message``, ``title``, ...);
+    an ``aborted`` filter stops the checks after it when it fails."""
+
+    run: Callable[[T_contra, AST, ParseOptions], Issue | None]
+    annotations: Annotations | None = None
+    aborted: bool = False
+
+    def annotate(self, /, **annotations: object) -> Filter[T_contra]:
+        """This filter with ``annotations`` merged over its own."""
+        return replace(self, annotations={**(self.annotations or {}), **annotations})
+
+    def abort(self) -> Filter[T_contra]:
+        """This filter, stopping the checks after it when it fails."""
+        return replace(self, aborted=True)
+
+    def and_[T](self: Filter[T], other: Check[T], /, **annotations: object) -> FilterGroup[T]:
+        """This check and ``other`` as one group (Effect's ``and``)."""
+        return FilterGroup((self, other), annotations or None)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class FilterGroup(Generic[T_contra]):
+    """Several checks run as one; ``annotations`` describe the group
+    (its ``expected`` is the default text of its members' failures)."""
+
+    checks: tuple[Check[T_contra], *tuple[Check[T_contra], ...]]
+    annotations: Annotations | None = None
+
+    def annotate(self, /, **annotations: object) -> FilterGroup[T_contra]:
+        return replace(self, annotations={**(self.annotations or {}), **annotations})
+
+    def and_[T](self: FilterGroup[T], other: Check[T], /, **annotations: object) -> FilterGroup[T]:
+        return FilterGroup((self, other), annotations or None)
+
+
+type Check[T] = Filter[T] | FilterGroup[T]
+
+
+def has_check(checks: Sequence[Check[Any]] | None, id: str) -> bool:
+    """Whether a check with the ``representation`` id ``id`` is among
+    ``checks`` or the groups inside them (Effect's ``hasCheck``)."""
+    for check in checks or ():
+        if isinstance(check, FilterGroup):
+            if has_check(check.checks, id):
+                return True
+            continue
+        representation = (check.annotations or {}).get("representation")
+        if isinstance(representation, Mapping) and representation.get("id") == id:  # pyright: ignore[reportUnknownMemberType]
+            return True
+    return False
+
+
+def make_filter[T](
+    predicate: Callable[[T], FilterOutput], /, *, abort: bool = False, **annotations: object
+) -> Filter[T]:
+    """A filter from a function returning a ``FilterOutput`` (Effect's
+    ``makeFilter``)."""
+
+    return filter_of(predicate, annotations or None, abort)
+
+
+def filter_of[T](
+    predicate: Callable[[T], FilterOutput],
+    annotations: Annotations | None = None,
+    abort: bool = False,
+) -> Filter[T]:
+    """``make_filter`` with the annotations as one mapping."""
+
+    def run(input: T, ast: AST, options: ParseOptions) -> Issue | None:
+        return normalize_filter_output(ast, predicate(input), input, options)
+
+    return Filter(run, annotations, abort)
+
+
+def make_filter_by_guard[T](
+    guard: Callable[[T], bool], annotations: Annotations | None = None
+) -> Filter[T]:
+    """A filter accepting what ``guard`` accepts; it always aborts, as the
+    checks after a guard may rely on it."""
+
+    def run(input: T, ast: AST, options: ParseOptions) -> Issue | None:
+        return None if guard(input) else InvalidValue(None, reported(input, options))
+
+    return Filter(run, annotations, True)
+
+
+def normalize_filter_output(
+    ast: AST, out: FilterOutput, input: object, options: ParseOptions
+) -> Issue | None:
+    """The issue a filter function's output stands for, or ``None``."""
+    if out is None or out is True:
+        return None
+    if out is False:
+        return InvalidValue(None, reported(input, options))
+    if not isinstance(out, list):
+        return _filter_issue(out, input, options)
+    issues = [_filter_issue(entry, input, options) for entry in out]
+    if not issues:
+        return None
+    if len(issues) == 1:
+        return issues[0]
+    return Composite(ast, (issues[0], *issues[1:]), reported(input, options))
+
+
+def _filter_issue(entry: FilterIssue, input: object, options: ParseOptions) -> Issue:
+    if isinstance(entry, str):
+        return InvalidValue({"message": entry}, reported(input, options))
+    if is_issue(entry):
+        return entry
+    path, inner = entry
+    return Pointer(path, _filter_issue(inner, input, options) if isinstance(inner, str) else inner)
+
+
+def collect_issues(
+    checks: Sequence[Check[object]], value: object, ast: AST, options: ParseOptions
+) -> tuple[Issue, *tuple[Issue, ...]] | None:
+    """The failures of ``checks`` on ``value``, or ``None``."""
+    issues: list[_issue.Filter] = []
+    _collect(checks, value, ast, options, issues)
+    return (issues[0], *issues[1:]) if issues else None
+
+
+def _collect(
+    checks: Sequence[Check[object]],
+    value: object,
+    ast: AST,
+    options: ParseOptions,
+    issues: list[_issue.Filter],
+) -> bool:
+    """Append the failures; ``True`` when the checks must stop."""
+    every = options.get("errors") == "all"
+    for check in checks:
+        if isinstance(check, FilterGroup):
+            if _collect(check.checks, value, ast, options, issues):
+                return True
+            continue
+        failure = check.run(value, ast, options)
+        if failure is not None:
+            issues.append(_issue.Filter(check, failure, reported(value, options)))
+            if not every or check.aborted:
+                return True
+    return False

pyfect/schema/ast/_class.py

@@ -0,0 +1,159 @@
+"""``Class``: instances of a schema class, encoded as a mapping of their
+fields (Effect's class declaration, linked to its struct)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from functools import partial
+from typing import Literal as _Literal
+from typing import Protocol, cast
+
+from pyfect._stack import stack_nearly_full, with_fresh_stack
+from pyfect.exit import Exit, Success
+from pyfect.exit import die as die_exit
+from pyfect.exit import fail as fail_exit
+from pyfect.schema._options import ParseOptions, is_constructing
+from pyfect.schema.ast._base import AST, Checks, invalid_type
+from pyfect.schema.ast._check import collect_issues
+from pyfect.schema.ast._objects import Objects
+from pyfect.schema.ast._result import ParseResult, flat_map
+from pyfect.schema.issue import Composite, Issue, reported
+
+type ClassSide = _Literal["decode", "encode", "type", "encoded"]
+
+
+class ClassShape(Protocol):
+    """What a ``Class`` node needs from a schema class."""
+
+    @property
+    def cls(self) -> type: ...
+
+    @property
+    def fields(self) -> Objects:
+        """The decoding struct of the fields (a tagged class's tag too)."""
+        ...
+
+    @property
+    def encoded(self) -> AST:
+        """The struct's encoded side."""
+        ...
+
+    @property
+    def checks(self) -> Checks | None:
+        """The class's own checks, run on each instance it makes."""
+        ...
+
+    def construct(self, values: dict[object, object]) -> object:
+        """An instance from parsed values, not checked again."""
+        ...
+
+    def values_of(self, instance: object) -> dict[object, object]:
+        """The struct value of ``instance`` (a tagged class's tag too)."""
+        ...
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Class(AST):
+    """Instances of ``shape.cls``. ``side`` says what the node does:
+    ``"decode"`` (a mapping to an instance), ``"encode"`` (an instance to a
+    mapping), ``"type"`` (instances) or ``"encoded"`` (mappings). Checks
+    apply to instances."""
+
+    shape: ClassShape
+    side: ClassSide = "decode"
+    _typed: list[Class] = field(default_factory=list["Class"], init=False, repr=False)
+    tag = "Class"
+
+    def get_expected(self) -> str:
+        return self.shape.cls.__name__
+
+    def expected(self) -> str:
+        # Decoding reads a mapping first: name what the struct expects, as
+        # Effect does (its identifier names the instances).
+        if self.side in ("decode", "encoded"):
+            return self.shape.encoded.expected()
+        return AST.expected(self)
+
+    def parse(self, input: object, options: ParseOptions) -> ParseResult:
+        # A class may hold itself (its fields are made on first use), so a
+        # parse recurses through it as deep as its input.
+        parse = self.parse_local if self.encoding is None else partial(AST.parse, self)
+        if not stack_nearly_full():
+            return parse(input, options)
+        return with_fresh_stack(lambda: parse(input, options))
+
+    def parse_local(self, input: object, options: ParseOptions) -> ParseResult:
+        if self.side != "encode":
+            return AST.parse_local(self, input, options)
+        # Checks describe instances: run them, then encode the fields.
+        shape = self.shape
+        return flat_map(
+            replace(self, side="type").parse_local(input, options),
+            lambda instance: shape.fields.flip().parse(shape.values_of(instance), options),
+        )
+
+    def _parse(self, input: object, options: ParseOptions) -> ParseResult:
+        match self.side:
+            case "type" | "encode":
+                if isinstance(input, self.shape.cls):
+                    return Success(input)
+                if self.side == "type" and is_constructing(options) and isinstance(input, Mapping):
+                    # A constructor makes an instance from its fields'
+                    # values (Effect's constructor descriptor).
+                    fields = cast("Mapping[object, object]", input)
+                    return self._construct(self.shape.fields.to_type(), fields, options)
+                return invalid_type(self, input, options)
+            case "encoded":
+                return self.shape.encoded.parse(input, options)
+            case "decode":
+                return self._decode(input, options)
+
+    def _decode(self, input: object, options: ParseOptions) -> ParseResult:
+        return self._construct(self.shape.fields, input, options)
+
+    def _construct(self, fields: AST, input: object, options: ParseOptions) -> ParseResult:
+        shape = self.shape
+
+        def construct(values: object) -> Exit[object, Issue]:
+            try:
+                instance = shape.construct(cast("dict[object, object]", values))
+            except Exception as defect:
+                return die_exit(defect)
+            return check_instance(shape, instance, options)
+
+        return flat_map(fields.parse(input, options), construct)
+
+    def _flip(self) -> Class:
+        flipped: dict[ClassSide, ClassSide] = {"decode": "encode", "encode": "decode"}
+        side = flipped.get(self.side)
+        return self if side is None else replace(self, side=side)
+
+    def _to_type(self) -> Class:
+        match self.side:
+            case "decode":
+                # Made once: every occurrence of the class's decoded side
+                # is one node (one definition in a document).
+                if not self._typed:
+                    self._typed.append(replace(self, side="type"))
+                return self._typed[0]
+            case "encode":
+                return replace(self, side="encoded", checks=None)
+            case _:
+                return self
+
+
+def check_instance(
+    shape: ClassShape, instance: object, options: ParseOptions
+) -> Exit[object, Issue]:
+    """``instance`` after the class's own checks."""
+    checks = shape.checks
+    if checks is None or options.get("disable_checks"):
+        return Success(instance)
+    try:
+        issues = collect_issues(checks, instance, shape.fields, options)
+    except Exception as defect:
+        return die_exit(defect)
+    if issues is None:
+        return Success(instance)
+    return fail_exit(Composite(shape.fields, issues, reported(instance, options)))