pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/ast/_constructors.py

@@ -0,0 +1,65 @@
+"""Product and sum nodes built from their parts (Effect's
+``SchemaAST.struct``, ``tuple``, ``union``, ``structWithRest`` and
+``tupleWithRest``), shared by the schema constructors."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from pyfect import _json_text
+from pyfect.schema.ast._arrays import Arrays, Element
+from pyfect.schema.ast._base import AST, Annotations, Checks, join_checks
+from pyfect.schema.ast._objects import Objects, PropertySignature
+from pyfect.schema.ast._union import Union, UnionMode
+
+
+def struct(
+    fields: Mapping[str, AST], checks: Checks | None = None, annotations: Annotations | None = None
+) -> Objects:
+    """A struct of ``fields``, keys in order; a field is optional when its
+    node is ``optional_key``."""
+    return Objects(
+        tuple(PropertySignature(name, node, node.optional_key) for name, node in fields.items()),
+        annotations=annotations,
+        checks=checks,
+    )
+
+
+def tuple_(elements: Sequence[AST], checks: Checks | None = None) -> Arrays:
+    """A fixed tuple of ``elements``; an element is optional when its node
+    is ``optional_key``."""
+    return Arrays(tuple(Element(node, node.optional_key) for node in elements), checks=checks)
+
+
+def union(
+    members: Sequence[AST], mode: UnionMode = "any_of", checks: Checks | None = None
+) -> Union:
+    """A union of ``members`` in order."""
+    return Union(tuple(members), mode, checks=checks)
+
+
+def struct_with_rest(ast: Objects, records: Sequence[Objects]) -> Objects:
+    """``ast``'s keys and every record's keys and key patterns, with all
+    their checks. A node with an encoding raises ``ValueError``, as does a
+    key two of them declare."""
+    if ast.encoding is not None or any(r.encoding is not None for r in records):
+        raise ValueError("StructWithRest does not support encodings")
+    properties = list(ast.properties)
+    index_signatures = list(ast.index_signatures)
+    checks = ast.checks
+    for record in records:
+        for p in record.properties:
+            if any(q.name == p.name for q in properties):
+                raise ValueError(f"Duplicate identifier: {_json_text.stringify(p.name)}. ts(2300)")
+        properties += record.properties
+        index_signatures += record.index_signatures
+        checks = join_checks(checks, record.checks)
+    return Objects(tuple(properties), tuple(index_signatures), checks=checks)
+
+
+def tuple_with_rest(ast: Arrays, rest: Sequence[AST]) -> Arrays:
+    """``ast``'s elements, then ``rest`` (see ``Arrays``), with its checks;
+    a node with an encoding raises ``ValueError``."""
+    if ast.encoding is not None:
+        raise ValueError("TupleWithRest does not support encodings")
+    return Arrays(ast.elements, tuple(rest), ast.mutable, checks=ast.checks)

pyfect/schema/ast/_declaration.py

@@ -0,0 +1,97 @@
+"""``Declaration``: values a function parses, given the nodes of its type
+parameters (Effect's ``Declaration``): ``Option(A)``, ``frozenset[A]``,
+``timedelta``, ...
+
+``run(type_parameters)`` makes the parser on first use; the parser gets
+the input, the declaration itself (for its issues) and the parse options.
+Flipping a declaration flips its type parameters, so the same parser
+encodes with them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from dataclasses import dataclass, field, replace
+from typing import cast
+
+from pyfect.exit import Exit, Failure, Success
+from pyfect.exit import die as die_exit
+from pyfect.exit import fail as fail_exit
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import AST, issue_of, join_checks
+from pyfect.schema.ast._result import ParseResult, then
+from pyfect.schema.issue import Composite, Issue, Pointer, reported
+
+type DeclarationParser = Callable[[object, Declaration, ParseOptions], ParseResult]
+type DeclarationRun = Callable[[tuple[AST, ...]], DeclarationParser]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Declaration(AST):
+    """Values ``run(type_parameters)`` accepts. Without an ``expected``
+    annotation it expects ``<Declaration>``."""
+
+    type_parameters: tuple[AST, ...]
+    run: DeclarationRun
+    _parser: list[DeclarationParser] = field(
+        default_factory=list[DeclarationParser], init=False, repr=False
+    )
+    tag = "Declaration"
+
+    def get_expected(self) -> str:
+        expected = (self.annotations or {}).get("expected")
+        return expected if isinstance(expected, str) else "<Declaration>"
+
+    def _parse(self, input: object, options: ParseOptions) -> ParseResult:
+        # Making the parser is the declaration's own setup: an error there
+        # is raised, not turned into a defect of this input.
+        if not self._parser:
+            self._parser.append(self.run(self.type_parameters))
+        try:
+            return self._parser[0](input, self, options)
+        except Exception as defect:
+            return die_exit(defect)
+
+    def _map(self, f: Callable[[AST], AST]) -> Declaration:
+        parameters = tuple(map(f, self.type_parameters))
+        if all(a is b for a, b in zip(parameters, self.type_parameters, strict=True)):
+            return self
+        return replace(self, type_parameters=parameters)
+
+    def _flip(self) -> Declaration:
+        # Checks describe the decoded side: flipped, they check the input.
+        flipped = self._map(lambda t: t.flip())
+        if self.checks is None and self.encoding_checks is None:
+            return flipped
+        return replace(flipped, checks=self.encoding_checks, encoding_checks=self.checks)
+
+    def _to_type(self) -> Declaration:
+        typed = self._map(lambda t: t.to_type())
+        if self.encoding_checks is None:
+            return typed
+        checks = join_checks(self.checks, self.encoding_checks) if typed is self else self.checks
+        return replace(typed, checks=checks, encoding_checks=None)
+
+
+def parse_at_key(
+    ast: AST,
+    key: Hashable,
+    node: AST,
+    value: object,
+    *,
+    input: object,
+    options: ParseOptions,
+) -> ParseResult:
+    """``value`` (``input``'s part at ``key``) parsed by ``node``; an issue
+    is reported as ``ast``'s at ``key`` (Effect's ``makeCompositeAtKey``)."""
+
+    def at_key(exit: Exit[object, Issue]) -> Exit[object, Issue]:
+        if type(exit) is Success:
+            return exit
+        failure = cast("Failure[Issue]", exit)
+        issue = issue_of(failure)
+        if issue is None:
+            return failure
+        return fail_exit(Composite(ast, (Pointer((key,), issue),), reported(input, options)))
+
+    return then(node.parse(value, options), at_key)

pyfect/schema/ast/_encoding.py

@@ -0,0 +1,111 @@
+"""Encodings: how a node is reached from what it decodes (Effect's ``Link``
+and ``Encoding``).
+
+A node's ``encoding`` is a chain of links, the last one the most encoded.
+Decoding parses the input with the last link's ``to``, applies that link's
+transformation, parses with the previous link's ``to``, and so on; the
+first link's transformation gives a value the node itself then parses (with
+its checks). Flipping a node reverses the chain and flips each
+transformation, so encoding is decoding the flipped node.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Protocol
+
+from pyfect.exit import Success
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._result import MISSING, ParseResult, flat_map, map_issue
+from pyfect.schema.issue import Encoding as EncodingIssue
+from pyfect.schema.issue import reported
+
+if TYPE_CHECKING:
+    from pyfect.schema.ast._base import AST
+
+
+class LinkTransformation(Protocol):
+    """What a link applies: a ``transformation.Transformation`` (a getter
+    each way) or a ``transformation.Middleware`` (a function of the whole
+    parse each way)."""
+
+    @property
+    def sees_failures(self) -> bool:
+        """Its decoding runs on failures too (a middleware that may recover),
+        so a union cannot pick its member by the source's kind or literals."""
+        ...
+
+    def flip(self) -> LinkTransformation: ...
+
+    def decode_result(self, result: ParseResult, options: ParseOptions) -> ParseResult:
+        """The decoded side of ``result``, the parse of the source."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    """``transformation`` from values of ``to`` (Effect's ``Link``)."""
+
+    to: AST
+    transformation: LinkTransformation
+
+
+type Encoding = tuple[Link, *tuple[Link, ...]]
+
+
+def decode_chain(ast: AST, links: Encoding, input: object, options: ParseOptions) -> ParseResult:
+    """``input`` decoded through ``links``, ``ast``'s encoding, then parsed
+    by ``ast`` itself; an issue raised on the way is wrapped in
+    ``Encoding``."""
+    result = links[-1].to.parse(input, options)
+    for i in range(len(links) - 1, -1, -1):
+        result = links[i].transformation.decode_result(result, options)
+        if i:
+            node = links[i - 1].to
+            result = flat_map(result, lambda value, node=node: node.parse(value, options))
+    if type(result) is not Success:
+        shown = None if input is MISSING else reported(input, options)
+        result = map_issue(result, lambda issue: EncodingIssue(ast, issue, shown))
+    return flat_map(result, lambda value: ast.parse_local(value, options))
+
+
+def flip_encoding(ast: AST, links: Encoding) -> AST:
+    """The node that encodes what ``ast`` decodes: its most encoded node,
+    with ``links`` (``ast``'s encoding) reversed (Effect's ``flipEncoding``)."""
+    flipped = [Link(replace(ast, encoding=None).flip(), links[0].transformation.flip())]
+    for i in range(1, len(links)):
+        flipped.insert(0, Link(links[i - 1].to.flip(), links[i].transformation.flip()))
+    to = links[-1].to.flip()
+    chain = (*to.encoding, *flipped) if to.encoding else tuple(flipped)
+    out = replace(to, encoding=chain)
+    # Its decoded side is ``to``'s: a schema's encoded side stays one node.
+    object.__setattr__(out, "context_owner", to.owner())
+    return out
+
+
+def decode_to[A: AST](from_: AST, to: A, transformation: LinkTransformation) -> A:
+    """``to``, decoding from values of ``from_`` through ``transformation``
+    (Effect's ``decodeTo``): a link appended to ``to``'s encoding."""
+    link = Link(from_, transformation)
+    out = replace(to, encoding=(*to.encoding, link) if to.encoding else (link,))
+    object.__setattr__(out, "body_owner", to.body_owner or to.owner())
+    return out
+
+
+def optional_key[A: AST](ast: A) -> A:
+    """``ast`` as a struct key that may be missing on the encoded side, down
+    to its most encoded node (Effect's ``optionalKey``)."""
+    # _base imports this module.
+    from pyfect.schema.ast._base import replace_context
+
+    encoding = ast.encoding
+    if encoding is None:
+        return ast if ast.optional_key else replace_context(ast, optional_key=True)
+    last = encoding[-1]
+    chain: Encoding = (*encoding[:-1], Link(optional_key(last.to), last.transformation))
+    return replace(ast, encoding=chain, optional_key=True)
+
+
+def to_encoded(ast: AST) -> AST:
+    """The node's encoded side, as a node of its own (Effect's ``toEncoded``)."""
+    return ast.flip().to_type()

pyfect/schema/ast/_json.py

@@ -0,0 +1,129 @@
+"""JSON values and string trees (Effect's ``isJson`` / ``isStringTree`` and
+their ``Json`` / ``StringTree`` declarations)."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from typing import cast
+
+from pyfect.exit import Exit, Success
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import invalid_type
+from pyfect.schema.ast._declaration import Declaration, DeclarationParser
+from pyfect.schema.ast._encoding import Link
+from pyfect.schema.issue import Issue
+
+
+def _is_json_leaf(value: object) -> bool:
+    if value is None or isinstance(value, str | bool | int):
+        return True
+    return isinstance(value, float) and math.isfinite(value)
+
+
+def _children(value: object) -> Iterator[object] | None:
+    """The values inside a JSON container; ``None`` for anything else."""
+    if isinstance(value, list | tuple):
+        return iter(cast("Sequence[object]", value))
+    if isinstance(value, Mapping):
+        mapping = cast("Mapping[object, object]", value)
+        if all(isinstance(key, str) for key in mapping):
+            return iter(mapping.values())
+    return None
+
+
+def is_json(value: object) -> bool:
+    """``value`` is ``None``, a string, a boolean, an ``int``, a finite
+    ``float``, or a ``list`` / ``tuple`` / string-keyed ``Mapping`` of JSON
+    values. A cycle is not JSON; a value shared twice (a DAG) is. Iterative,
+    so any depth works."""
+    return _is_tree(value, _is_json_leaf)
+
+
+def _is_string_tree_leaf(value: object) -> bool:
+    return value is None or isinstance(value, str)
+
+
+def is_string_tree(value: object) -> bool:
+    """``value`` is a string, ``None`` (Effect's ``undefined``), or a
+    ``list`` / ``tuple`` / string-keyed ``Mapping`` of string trees (Effect's
+    ``isStringTree``); a cycle is not one."""
+    return _is_tree(value, _is_string_tree_leaf)
+
+
+def _is_tree(value: object, is_leaf: Callable[[object], bool]) -> bool:
+    done: set[int] = set()
+    on_path: set[int] = set()
+    stack: list[tuple[object, Iterator[object]]] = []
+    current = value
+    while True:
+        if is_leaf(current) or id(current) in done:
+            pass
+        elif id(current) in on_path:
+            return False
+        else:
+            children = _children(current)
+            if children is None:
+                return False
+            on_path.add(id(current))
+            stack.append((current, children))
+        while stack:
+            container, children = stack[-1]
+            nxt = next(children, _END)
+            if nxt is not _END:
+                current = nxt
+                break
+            stack.pop()
+            on_path.discard(id(container))
+            done.add(id(container))
+        else:
+            return True
+
+
+_END = object()
+
+
+def _run(_: tuple[object, ...]) -> DeclarationParser:
+    def parse(input: object, ast: Declaration, options: ParseOptions) -> Exit[object, Issue]:
+        return Success(input) if is_json(input) else invalid_type(ast, input, options)
+
+    return parse
+
+
+def _string_tree_run(_: tuple[object, ...]) -> DeclarationParser:
+    def parse(input: object, ast: Declaration, options: ParseOptions) -> Exit[object, Issue]:
+        return Success(input) if is_string_tree(input) else invalid_type(ast, input, options)
+
+    return parse
+
+
+def _already_canonical(_: tuple[object, ...]) -> None:
+    return None
+
+
+def _from_string_tree(_: tuple[object, ...]) -> Link:
+    from pyfect.schema._codec_links import UNKNOWN_TO_STRING_TREE
+
+    return UNKNOWN_TO_STRING_TREE
+
+
+string_tree = Declaration(
+    (),
+    _string_tree_run,
+    annotations={"expected": "StringTree", "to_codec_string_tree": _already_canonical},
+)
+"""Any string tree (``is_string_tree``), unchanged: an opaque value's
+``to_codec_string_tree`` form."""
+
+
+json = Declaration(
+    (),
+    _run,
+    annotations={
+        "expected": "JSON value",
+        "representation": {"id": "effect/schema/Json", "payload": None},
+        "to_codec_json": _already_canonical,
+        "to_codec_string_tree": _from_string_tree,
+    },
+)
+"""Any JSON value (``is_json``), unchanged."""

pyfect/schema/ast/_keywords.py

@@ -0,0 +1,125 @@
+"""The keyword nodes: one kind of value each, accepted unchanged.
+
+Python mappings: ``Number`` accepts ``int`` and ``float`` (JavaScript has one
+number type), ``BigInt`` accepts ``int``, ``Null`` is ``None``; ``bool`` is
+neither a number nor a bigint.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyfect.exit import Exit, Success
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import Refinement
+from pyfect.schema.issue import Issue
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Never(Refinement):
+    tag = "Never"
+
+    def get_expected(self) -> str:
+        return "never"
+
+    def accepts(self, input: object) -> bool:
+        return False
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Any(Refinement):
+    tag = "Any"
+
+    def get_expected(self) -> str:
+        return "any"
+
+    def accepts(self, input: object) -> bool:
+        return True
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Unknown(Refinement):
+    tag = "Unknown"
+
+    def get_expected(self) -> str:
+        return "unknown"
+
+    def accepts(self, input: object) -> bool:
+        return True
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Null(Refinement):
+    tag = "Null"
+
+    def get_expected(self) -> str:
+        return "null"
+
+    def accepts(self, input: object) -> bool:
+        return input is None
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class String(Refinement):
+    tag = "String"
+
+    def get_expected(self) -> str:
+        return "string"
+
+    def accepts(self, input: object) -> bool:
+        return isinstance(input, str)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Number(Refinement):
+    """A number; ``whole`` is the one ``S.Int`` starts from. JavaScript has one
+    number, so Effect's ``Int`` takes ``1.0``. A Python ``int`` schema gives it
+    as ``1``, which is also how JavaScript prints it; its check refuses every
+    other float."""
+
+    whole: bool = False
+    tag = "Number"
+
+    def get_expected(self) -> str:
+        return "number"
+
+    def accepts(self, input: object) -> bool:
+        return isinstance(input, int | float) and not isinstance(input, bool)
+
+    def _parse(self, input: object, options: ParseOptions) -> Exit[object, Issue]:
+        if self.whole and isinstance(input, float) and input.is_integer():
+            return Success(int(input))
+        return Refinement._parse(self, input, options)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Boolean(Refinement):
+    tag = "Boolean"
+
+    def get_expected(self) -> str:
+        return "boolean"
+
+    def accepts(self, input: object) -> bool:
+        return isinstance(input, bool)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class BigInt(Refinement):
+    tag = "BigInt"
+
+    def get_expected(self) -> str:
+        return "bigint"
+
+    def accepts(self, input: object) -> bool:
+        return isinstance(input, int) and not isinstance(input, bool)
+
+
+never = Never()
+any_ = Any()
+unknown = Unknown()
+null = Null()
+string = String()
+number = Number()
+whole_number = Number(whole=True)
+boolean = Boolean()
+big_int = BigInt()

pyfect/schema/ast/_literal.py

@@ -0,0 +1,157 @@
+"""Exact-value nodes: ``Literal`` (one value) and ``Enum`` (the members of
+a Python ``enum.Enum``).
+
+JavaScript has one number, so a number literal matches an ``int`` or a
+``float`` of that value: ``1`` and ``1.0`` are one literal, ``0.0`` and
+``-0.0`` match each other, and the input is kept (its kind and sign too). A
+``bool`` is not a number: ``1`` is not ``True``.
+"""
+
+from __future__ import annotations
+
+import enum
+import math
+from dataclasses import dataclass, replace
+from typing import Literal as _Literal
+from typing import cast
+
+from pyfect._js import js_number
+from pyfect.exit import Exit, Success
+from pyfect.logger._text import json_quote
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import AST, invalid_type
+from pyfect.schema.ast._result import ParseResult, map_value
+from pyfect.schema.issue import Issue
+
+type LiteralValue = str | int | float | bool | None
+
+
+def same_literal(literal: LiteralValue, input: object) -> bool:
+    """``input`` is ``literal``, as JavaScript's ``===`` reads them."""
+    match literal:
+        case None:
+            return input is None
+        case bool():
+            return isinstance(input, bool) and input == literal
+        case int() | float():
+            return (
+                isinstance(input, int | float) and not isinstance(input, bool) and input == literal
+            )
+        case str():
+            return isinstance(input, str) and input == literal
+
+
+def format_literal(literal: LiteralValue) -> str:
+    """A literal as Effect prints it: strings quoted, ``null``, ``true``."""
+    match literal:
+        case None:
+            return "null"
+        case bool():
+            return "true" if literal else "false"
+        case int() | float():
+            return js_number(literal)
+        case str():
+            return json_quote(literal)
+
+
+def _require_finite(value: float, what: str) -> None:
+    if not math.isfinite(value):
+        raise ValueError(f"A numeric {what} must be finite, got {js_number(value)}")
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Literal(AST):
+    """Accepts ``literal`` (Effect's ``Literal``). A non-finite number is
+    rejected when the node is made."""
+
+    literal: LiteralValue
+    tag = "Literal"
+
+    def __post_init__(self) -> None:
+        if isinstance(self.literal, float):
+            _require_finite(self.literal, "literal")
+
+    def get_expected(self) -> str:
+        return format_literal(self.literal)
+
+    def _parse(self, input: object, options: ParseOptions) -> Exit[object, Issue]:
+        if same_literal(self.literal, input):
+            return Success(input)
+        return invalid_type(self, input, options)
+
+
+type EnumSide = _Literal["decode", "encode", "type", "encoded"]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Enum(AST):
+    """The members of ``enum``, encoded as their values (Effect's ``Enum``,
+    whose values are the members). Decoding takes a value (or a member) and
+    gives the member; encoding gives the member's value. Values must be
+    strings or finite numbers.
+
+    ``side`` says what the node does: ``"decode"`` (value to member),
+    ``"encode"`` (member to value), ``"type"`` (members) or ``"encoded"``
+    (values). Checks apply to members.
+    """
+
+    enum: type[enum.Enum]
+    side: EnumSide = "decode"
+    tag = "Enum"
+
+    def __post_init__(self) -> None:
+        for member in self.enum:
+            value: object = member.value
+            if not isinstance(value, str | int | float) or isinstance(value, bool):
+                raise TypeError(
+                    f"An enum value must be a string or a number, got {value!r} ({member!r})"
+                )
+            if isinstance(value, float):
+                _require_finite(value, "enum value")
+
+    @property
+    def members(self) -> tuple[enum.Enum, ...]:
+        return tuple(self.enum)
+
+    def get_expected(self) -> str:
+        if self.side in ("type", "encode"):
+            return self.enum.__name__
+        return " | ".join(format_literal(m.value) for m in self.enum)
+
+    def parse(self, input: object, options: ParseOptions) -> ParseResult:
+        if self.encoding is not None:
+            return AST.parse(self, input, options)
+        return self.parse_local(input, options)
+
+    def parse_local(self, input: object, options: ParseOptions) -> ParseResult:
+        if self.side != "encode":
+            return AST.parse_local(self, input, options)
+        # Checks describe members: run them on the member, then encode it.
+        return map_value(
+            replace(self, side="type").parse_local(input, options),
+            lambda member: cast("enum.Enum", member).value,
+        )
+
+    def _parse(self, input: object, options: ParseOptions) -> Exit[object, Issue]:
+        if self.side in ("type", "encode"):
+            if isinstance(input, self.enum):
+                return Success(input)
+            return invalid_type(self, input, options)
+        for member in self.enum:
+            if input is member or same_literal(member.value, input):
+                return Success(member if self.side == "decode" else input)
+        return invalid_type(self, input, options)
+
+    def _flip(self) -> Enum:
+        flipped: dict[EnumSide, EnumSide] = {"decode": "encode", "encode": "decode"}
+        side = flipped.get(self.side)
+        return self if side is None else replace(self, side=side)
+
+    def _to_type(self) -> Enum:
+        match self.side:
+            case "decode":
+                return replace(self, side="type")
+            case "encode":
+                return replace(self, side="encoded", checks=None)
+            case _:
+                return self