pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/ast/_steps.py

@@ -0,0 +1,209 @@
+"""Parsing a composite one child at a time, synchronously until a child's
+parse is an ``Effect``, then inside an effect.
+
+A composite's parse is a ``Steps``: ``run_from(i)`` parses the children
+from the ``i``-th on, recording each outcome, until a child's parse is an
+effect: it then hands back that step's index and a ``Pending`` (the effect
+and what to do with its exit). ``run_steps`` returns the outcome, or an
+effect that copies the state and goes on from there, so the sync prefix
+runs once and every run of the effect starts from the same state (an
+effect may be run again, by ``retry`` say).
+
+With the ``concurrency`` parse option, a product's effectful children run
+at once, up to the limit (Effect's ``iterateConcurrent``): each worker takes
+the next step, records its outcome when it ends (in completion order), and
+the first step that ends the parse interrupts the others.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Generator
+from dataclasses import dataclass
+from typing import Any
+
+from pyfect._concurrency import Concurrency, for_each
+from pyfect._core import Effect
+from pyfect.cause import Cause, Fail
+from pyfect.effect import fail, gen
+from pyfect.effect import suspend as _suspend
+from pyfect.exit import Exit, Failure, Success
+from pyfect.schema.ast._result import ParseResult, to_effect
+from pyfect.schema.issue import Issue
+
+
+class Stop(Exception):
+    """Parsing stops: ``finish`` gives the outcome (the first mismatch
+    under ``errors="first"``, a union's match, ...)."""
+
+
+class Abort(Exception):
+    """Parsing ends with ``failure`` as it is (a child's defect)."""
+
+    def __init__(self, failure: Failure[Issue]) -> None:
+        self.failure = failure
+
+
+@dataclass(frozen=True, slots=True)
+class Pending[S]:
+    """A child's parse still running: ``then(steps, exit)`` records its
+    outcome and may hand back the next child's."""
+
+    effect: Effect[object, Issue, Any]
+    then: Callable[[S, Exit[object, Issue]], Pending[S] | None]
+
+
+type Suspended[S] = tuple[int, Pending[S]]
+"""Where a parse waits: the step's index and its child's ``Pending``."""
+
+
+class Steps[S](ABC):
+    """One parse of a composite (see the module); ``S`` is the subclass."""
+
+    __slots__ = ()
+
+    @abstractmethod
+    def run_from(self, start: int) -> Suspended[S] | None:
+        """Run the steps from ``start`` on, stopping at the first child
+        whose parse is an effect; ``Stop`` / ``Abort`` end the parse."""
+
+    @abstractmethod
+    def finish(self) -> Exit[object, Issue]:
+        """The outcome once the steps ran or one stopped."""
+
+    @abstractmethod
+    def copy(self) -> S:
+        """An independent copy of the state, to go on from."""
+
+    @abstractmethod
+    def size(self) -> int:
+        """How many steps there are."""
+
+
+def run_steps(steps: Steps[Any], concurrency: Concurrency = None) -> ParseResult:
+    """The outcome of ``steps``: an ``Exit`` when every child's parse was
+    one, else the effect finishing the parse, its effectful children run
+    ``concurrency`` at a time (one by one by default)."""
+    try:
+        suspended = steps.run_from(0)
+    except Stop:
+        return steps.finish()
+    except Abort as abort:
+        return abort.failure
+    if suspended is None:
+        return steps.finish()
+    workers = _workers(concurrency, steps.size() - suspended[0])
+    if workers > 1:
+        return _resume_concurrently(steps, *suspended, workers)
+    return resume(steps, *suspended)
+
+
+def _workers(concurrency: Concurrency, remaining: int) -> int:
+    if concurrency is None:
+        return 1
+    if concurrency == "unbounded":
+        return remaining
+    return min(concurrency, remaining)
+
+
+def resume[S: Steps[Any]](
+    snapshot: Steps[S], index: int, first: Pending[S]
+) -> Effect[object, Issue, Any]:
+    """The effect finishing a parse that waits at step ``index``."""
+
+    def run() -> Generator[Effect[Any, Issue, Any], Any, object]:
+        steps = snapshot.copy()
+        pending: Pending[S] | None = first
+        i = index
+        try:
+            while True:
+                while pending is not None:
+                    exit: Exit[object, Issue] = yield from pending.effect.exit()
+                    pending = pending.then(steps, exit)
+                suspended = steps.run_from(i + 1)
+                if suspended is None:
+                    break
+                i, pending = suspended
+        except Stop:
+            pass
+        except Abort as abort:
+            return (yield from to_effect(abort.failure))
+        return (yield from to_effect(steps.finish()))
+
+    return gen(run)
+
+
+class _End(Exception):
+    """A worker's failure: a step ended the parse (``failure`` is an
+    ``Abort``'s, ``None`` a ``Stop``)."""
+
+    def __init__(self, failure: Failure[Issue] | None) -> None:
+        self.failure = failure
+
+
+def _resume_concurrently[S: Steps[Any]](
+    snapshot: Steps[S], index: int, first: Pending[S], workers: int
+) -> Effect[object, Issue, Any]:
+    """The effect finishing a parse that waits at step ``index``, with up
+    to ``workers`` children running at once."""
+
+    def run() -> Effect[object, Issue, Any]:
+        steps = snapshot.copy()
+        next: list[Pending[S] | None] = [first]
+        at = index
+        done = False
+
+        def take() -> Pending[S] | None:
+            # The next child to run, recording the synchronous ones on the way.
+            nonlocal at, done
+            if next[0] is not None:
+                pending, next[0] = next[0], None
+                return pending
+            if done:
+                return None
+            suspended = steps.run_from(at + 1)
+            if suspended is None:
+                done = True
+                return None
+            at, pending = suspended
+            return pending
+
+        def worker() -> Generator[Effect[Any, Any, Any], Any]:
+            try:
+                while (pending := take()) is not None:
+                    while pending is not None:
+                        exit: Exit[object, Issue] = yield from pending.effect.exit()
+                        pending = pending.then(steps, exit)
+            except Stop:
+                yield from fail(_End(None))
+            except Abort as abort:
+                yield from fail(_End(abort.failure))
+
+        def outcome(exit: Exit[object, Any]) -> Effect[object, Issue, Any]:
+            if isinstance(exit, Failure):
+                return to_effect(_ended(steps, exit.cause))
+            return to_effect(steps.finish())
+
+        return (
+            for_each(range(workers), lambda _: gen(worker), concurrency="unbounded")
+            .exit()
+            .flat_map(outcome)
+        )
+
+    return _suspend(run)
+
+
+def _ended(steps: Steps[Any], cause: Cause[Any]) -> Exit[object, Issue]:
+    """The outcome once a worker failed: the step that ended the parse
+    decides it; anything else the workers raised is a defect beside it."""
+    end = next(
+        (r.error for r in cause.reasons if isinstance(r, Fail) and isinstance(r.error, _End)),
+        None,
+    )
+    if end is None:
+        return Failure(cause)
+    outcome = steps.finish() if end.failure is None else end.failure
+    rest = Cause(tuple(r for r in cause.reasons if not (isinstance(r, Fail) and r.error is end)))
+    if not rest.reasons:
+        return outcome
+    return Failure(rest if isinstance(outcome, Success) else outcome.cause + rest)

pyfect/schema/ast/_suspend.py

@@ -0,0 +1,65 @@
+"""``Suspend``: a node made on first use, for recursive schemas."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+
+from pyfect._stack import stack_nearly_full, with_fresh_stack
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import AST
+from pyfect.schema.ast._result import MISSING, ParseResult
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Suspend(AST):
+    """The node ``thunk`` returns, made once on first use (Effect's
+    ``Suspend``): a schema may then refer to itself."""
+
+    thunk: Callable[[], AST]
+    _memo: list[AST] = field(default_factory=list[AST], init=False, repr=False)
+    _typed: list[Suspend] = field(default_factory=list["Suspend"], init=False, repr=False)
+    tag = "Suspend"
+
+    @property
+    def target(self) -> AST:
+        if not self._memo:
+            self._memo.append(self.thunk())
+        return self._memo[0]
+
+    def get_expected(self) -> str:
+        return self.target.expected()
+
+    def parse(self, input: object, options: ParseOptions) -> ParseResult:
+        # A missing key goes through the target as well, as in Effect: it is
+        # how a target that only reaches itself shows up on an absent key.
+        if input is MISSING and self.encoding is None:
+            return self.target.parse(MISSING, options)
+        return AST.parse(self, input, options)
+
+    def _parse(self, input: object, options: ParseOptions) -> ParseResult:
+        # The one node through which a parse recurses as deep as its input.
+        target = self.target
+        if not stack_nearly_full():
+            return target.parse(input, options)
+        return with_fresh_stack(lambda: target.parse(input, options))
+
+    def _flip(self) -> Suspend:
+        # Lazy: the target is not made until the flipped node is used.
+        def flipped() -> AST:
+            return self.target.flip()
+
+        return replace(self, thunk=flipped)
+
+    def _to_type(self) -> Suspend:
+        # Made once, so the decoded side of a recursive schema refers back
+        # to itself: a finite graph, as the schema is.
+        if not self._typed:
+
+            def typed() -> AST:
+                return self.target.to_type()
+
+            decoded = replace(self, thunk=typed)
+            decoded._typed.append(decoded)
+            self._typed.append(decoded)
+        return self._typed[0]

pyfect/schema/ast/_template_literal.py

@@ -0,0 +1,256 @@
+"""``TemplateLiteral``: strings made of ordered parts (Effect's
+``TemplateLiteral``), as TypeScript's `` `user_${string}` `` types.
+
+A part is a ``String``, ``Number`` or ``BigInt`` node (its checks kept), a
+``Literal`` (its text) or, unchecked, a nested ``TemplateLiteral`` or a
+``Union`` of parts; no part may have an encoding. A string matches when it
+splits into one segment per part, each matching its part: the split is
+greedy (a segment takes as much as it can) and backtracks, as Effect's.
+A number part matches finite decimal text (``"+1"``, ``"1e5"``), a bigint
+part ``-?digits``.
+
+``template_literal_parser`` is the tuple of the parts' values decoded from
+such a string (Effect's ``templateLiteralParser``).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING, Never
+
+from pyfect.exit import Exit, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast._base import AST, invalid_type, issue_of
+from pyfect.schema.ast._check import collect_issues
+from pyfect.schema.ast._encoding import to_encoded
+from pyfect.schema.ast._keywords import BigInt, Number, String
+from pyfect.schema.ast._literal import Literal
+from pyfect.schema.ast._result import ParseResult, run_now
+from pyfect.schema.ast._union import Union
+from pyfect.schema.getter._coerce import to_string
+from pyfect.schema.issue import Composite, InvalidValue, Issue, reported
+
+if TYPE_CHECKING:
+    from pyfect.schema.ast._arrays import Arrays
+
+FINITE_PATTERN = r"[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[Ee][+-]?\d+)?"
+"""Finite decimal text, with an optional exponent (Effect's ``FINITE_PATTERN``)."""
+STRING_PATTERN = r"[\s\S]*?"
+"""Any text, newlines included (Effect's ``STRING_PATTERN``)."""
+BIG_INT_PATTERN = r"-?\d+"
+_FINITE = re.compile(f"{FINITE_PATTERN}\\Z", re.ASCII)
+_BIG_INT = re.compile(f"{BIG_INT_PATTERN}\\Z", re.ASCII)
+_SAFE_INTEGER = 2**53 - 1
+_MISMATCH = "a string matching template literal parts"
+
+
+def _part_path(path: str | int) -> str:
+    return f"parts[{path}]" if isinstance(path, int) else path
+
+
+def _validate(node: AST, path: str | int, validated: set[int]) -> bool:
+    """``node`` may be a part; one with an encoding raises ``ValueError``."""
+    if id(node) in validated:
+        return True
+    if node.encoding is not None:
+        raise ValueError(f"TemplateLiteral parts cannot have an encoding at {_part_path(path)}")
+    match node:
+        case String() | Number() | BigInt():
+            valid = True
+        case Literal():
+            valid = node.checks is None
+        case TemplateLiteral():
+            # Its own parts were validated when it was made.
+            valid = node.checks is None
+        case Union():
+            here = _part_path(path)
+            valid = node.checks is None and all(
+                _validate(member, f"{here}.types[{i}]", validated)
+                for i, member in enumerate(node.types)
+            )
+        case _:
+            return False
+    if valid:
+        validated.add(id(node))
+    return valid
+
+
+def _passes(node: AST, value: object, options: ParseOptions) -> bool:
+    checks = node.checks
+    return (
+        checks is None
+        or bool(options.get("disable_checks"))
+        or (collect_issues(checks, value, node, options) is None)
+    )
+
+
+def _number(text: str) -> float:
+    value = float(text)
+    return int(value) if value.is_integer() and abs(value) <= _SAFE_INTEGER else value
+
+
+def match_part(node: AST, text: str, options: ParseOptions) -> bool:  # noqa: PLR0911
+    """``text`` is a segment of the part ``node`` (Effect's ``matchPart``)."""
+    match node:
+        case String():
+            return _passes(node, text, options)
+        case Number():
+            return _FINITE.match(text) is not None and _passes(node, _number(text), options)
+        case BigInt():
+            return _BIG_INT.match(text) is not None and _passes(node, int(text), options)
+        case Literal():
+            return text == to_string(node.literal)
+        case TemplateLiteral():
+            return segment(node, text, options) is not None
+        case Union():
+            return any(match_part(member, text, options) for member in node.types)
+        case _:
+            return False
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class TemplateLiteral(AST):
+    """A string made of ``parts`` (see the module). A part that cannot be
+    one raises ``ValueError`` when the node is made."""
+
+    parts: tuple[AST, ...]
+    literals: tuple[str | None, ...] = field(init=False, repr=False)
+    """Each part's text when it is a ``Literal``."""
+    suffix_lengths: tuple[int, ...] = field(init=False, repr=False)
+    """The length of the literal text after each position."""
+    _segments: list[Arrays] = field(default_factory=list["Arrays"], init=False, repr=False)
+    tag = "TemplateLiteral"
+
+    def __post_init__(self) -> None:
+        validated: set[int] = set()
+        for index, part in enumerate(self.parts):
+            if not _validate(part, index, validated):
+                raise ValueError(f"Invalid TemplateLiteral part {part.tag}")
+        literals = tuple(
+            to_string(part.literal) if isinstance(part, Literal) else None for part in self.parts
+        )
+        suffix = [0] * (len(literals) + 1)
+        for i in range(len(literals) - 1, -1, -1):
+            suffix[i] = suffix[i + 1] + len(literals[i] or "")
+        object.__setattr__(self, "literals", literals)
+        object.__setattr__(self, "suffix_lengths", tuple(suffix))
+
+    def get_expected(self) -> str:
+        return "string"
+
+    @property
+    def segments(self) -> Arrays:
+        """The tuple of the parts read from their segments' text."""
+        if not self._segments:
+            from pyfect.schema._template_literal import part_from_string, segments_tuple
+
+            self._segments.append(segments_tuple(tuple(map(part_from_string, self.parts))))
+        return self._segments[0]
+
+    def _parse(self, input: object, options: ParseOptions) -> ParseResult:
+        if not isinstance(input, str):
+            return invalid_type(self, input, options)
+        parts = segment(self, input, options)
+        if parts is None:
+            shown = reported(input, options)
+            return fail_exit(
+                Composite(self, (InvalidValue({"expected": _MISMATCH}, shown),), shown)
+            )
+        # The parts have no encodings, so this is an ``Exit``.
+        result = run_now(self.segments.parse(tuple(parts), options))
+        if isinstance(result, Success):
+            return Success(input)
+        issue = issue_of(result)
+        if issue is None:
+            return result
+        return fail_exit(Composite(self, (issue,), reported(input, options)))
+
+    def _flip(self) -> AST:
+        return self
+
+
+def segment(node: TemplateLiteral, input: str, options: ParseOptions) -> list[str] | None:
+    """``input`` split into one segment per part, or ``None`` when it does
+    not match (Effect's ``segmentTemplateLiteralParts``)."""
+    parts = node.parts
+    literals = node.literals
+    size = len(input)
+    if any(literal and literal not in input for literal in literals):
+        return None
+    if node.suffix_lengths[0] > size:
+        return None
+    out = [""] * len(parts)
+    failures: set[int] = set()
+
+    def last_index(anchor: str, start: int) -> int:
+        # JavaScript's ``lastIndexOf(anchor, start)``.
+        return input.rfind(anchor, 0, max(start, 0) + len(anchor))
+
+    def go(i: int, pos: int) -> bool:
+        if i == len(parts):
+            return pos == size
+        key = i * (size + 1) + pos
+        if key in failures:
+            return False
+        part = parts[i]
+        if i == len(parts) - 1:
+            text = input[pos:]
+            if match_part(part, text, options):
+                out[i] = text
+                return True
+        elif isinstance(part, Literal):
+            text = literals[i] or ""
+            if input.startswith(text, pos) and go(i + 1, pos + len(text)):
+                out[i] = text
+                return True
+        else:
+            maximum = size - node.suffix_lengths[i + 1]
+            # A split before a literal need only try where that literal occurs.
+            anchor = literals[i + 1]
+            end = maximum if anchor is None else last_index(anchor, maximum)
+            while end >= pos:
+                text = input[pos:end]
+                if match_part(part, text, options) and go(i + 1, end):
+                    out[i] = text
+                    return True
+                if end == 0:
+                    break
+                end = end - 1 if anchor is None else last_index(anchor, end - 1)
+        failures.add(key)
+        return False
+
+    return out if go(0, 0) else None
+
+
+def normalize_encoded(nodes: Sequence[AST]) -> tuple[AST, ...]:
+    """The encoded sides of ``nodes`` as template parts: a union's members
+    may overlap there even when decoding picks one, so every union is
+    ``any_of``. A node shared in ``nodes`` (a union's members too) gives one
+    shared part."""
+    memo: dict[int, AST] = {}
+
+    def union(node: Union) -> AST:
+        types = tuple(map(encoded, node.types))
+        same = all(a is b for a, b in zip(types, node.types, strict=True))
+        return node if same and node.mode == "any_of" else replace(node, types=types, mode="any_of")
+
+    def encoded(node: AST) -> AST:
+        done = memo.get(id(node))
+        if done is None:
+            plain = node.encoding is None and node.checks is None and node.encoding_checks is None
+            if isinstance(node, Union) and plain:
+                done = union(node)
+            else:
+                side = to_encoded(node)
+                done = union(side) if isinstance(side, Union) and side.checks is None else side
+            memo[id(node)] = done
+        return done
+
+    return tuple(map(encoded, nodes))
+
+
+def template_mismatch(input: str, options: ParseOptions) -> Exit[Never, Issue]:
+    return fail_exit(InvalidValue({"expected": _MISMATCH}, reported(input, options)))