pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/_graph.py

@@ -0,0 +1,271 @@
+"""``Graph``: Effect's ``Schema.Graph``, immutable ``pyfect.graph`` graphs
+of one kind whose node and edge payloads are schemas' values.
+
+A graph is parsed as its snapshot, ``{"type", "nodes": [{"index",
+"data"}], "edges": [{"index", "source", "target", "data"}]}``, so a
+payload's issue is at ``["nodes"][i]["data"]``. JSON writes that snapshot;
+decoding checks that indexes strictly increase and that every endpoint is
+an encoded node, at the offending path, before the graph is built.
+Removed-index history is not kept: new indexes start after the highest.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, cast
+
+from pyfect import graph as _graph
+from pyfect.exit import Exit, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.graph import IndexedEdge, IndexedNode, Kind, Snapshot
+from pyfect.schema import ast
+from pyfect.schema import getter as G
+from pyfect.schema import transformation as T
+from pyfect.schema._arbitrary_constraint import ArbitraryConstraint
+from pyfect.schema._checks_number import is_less_than_or_equal_to
+from pyfect.schema._checks_size import is_min_length
+from pyfect.schema._options import ParseOptions
+from pyfect.schema._primitives import Natural
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema._to_equivalence import Equivalence
+from pyfect.schema.issue import InvalidValue, Issue, Pointer, reported
+
+# Explicit covariant parameters: a frozen dataclass's fields would make
+# inferred ones invariant (``tests/test_schema_variance.py``).
+N_co = TypeVar("N_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+NI_co = TypeVar("NI_co", covariant=True)
+EI_co = TypeVar("EI_co", covariant=True)
+K_co = TypeVar("K_co", bound=Kind, covariant=True)
+RD_co = TypeVar("RD_co", covariant=True)
+RE_co = TypeVar("RE_co", covariant=True)
+
+type _Encoded = Mapping[str, Any]
+type _AnyGraph = _graph.Graph[Any, Any, Kind]
+
+_INDEX = ast.append_checks(Natural.ast, (is_less_than_or_equal_to(2**53 - 1),))
+"""A node or edge index: a non-negative safe integer (Effect's ``Natural``)."""
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class GraphSchema(
+    Bottom[_graph.Graph[N_co, E_co, K_co], _graph.Graph[NI_co, EI_co, K_co], RD_co, RE_co],
+    Generic[N_co, E_co, NI_co, EI_co, K_co, RD_co, RE_co],
+):
+    """Immutable ``kind`` graphs of ``node`` and ``edge`` payloads."""
+
+    kind: K_co
+    node: Codec[N_co, NI_co, RD_co, RE_co]
+    edge: Codec[E_co, EI_co, RD_co, RE_co]
+
+
+def _encoded_schema(kind: Kind, node: ast.AST, edge: ast.AST) -> ast.Objects:
+    def record(**fields: ast.AST) -> ast.AST:
+        return ast.Objects(tuple(ast.PropertySignature(k, v) for k, v in fields.items()))
+
+    return ast.Objects(
+        (
+            ast.PropertySignature("type", ast.Literal(kind)),
+            ast.PropertySignature("nodes", ast.Arrays(rest=(record(index=_INDEX, data=node),))),
+            ast.PropertySignature(
+                "edges",
+                ast.Arrays(rest=(record(index=_INDEX, source=_INDEX, target=_INDEX, data=edge),)),
+            ),
+        )
+    )
+
+
+def _invalid(
+    path: tuple[object, ...], expected: str, value: object, options: ParseOptions
+) -> Exit[Any, Issue]:
+    return fail_exit(Pointer(path, InvalidValue({"expected": expected}, reported(value, options))))
+
+
+def _decode(encoded: _Encoded, options: ParseOptions) -> Exit[_AnyGraph, Issue]:
+    """The graph of a parsed snapshot, or the issue at the first index
+    that does not increase or endpoint that names no node."""
+    nodes = cast("Sequence[_Encoded]", encoded["nodes"])
+    edges = cast("Sequence[_Encoded]", encoded["edges"])
+    previous = -1
+    indexes: set[int] = set()
+    for i, node in enumerate(nodes):
+        index = node["index"]
+        if index <= previous:
+            return _invalid(
+                ("nodes", i, "index"), "a strictly increasing node index", index, options
+            )
+        previous = index
+        indexes.add(index)
+    previous = -1
+    for i, edge in enumerate(edges):
+        if edge["index"] <= previous:
+            expected = "a strictly increasing edge index"
+            return _invalid(("edges", i, "index"), expected, edge["index"], options)
+        previous = edge["index"]
+        for end in ("source", "target"):
+            if edge[end] not in indexes:
+                return _invalid(("edges", i, end), "an encoded node index", edge[end], options)
+    snapshot = Snapshot(
+        encoded["type"],
+        tuple(IndexedNode(n["index"], n["data"]) for n in nodes),
+        tuple(IndexedEdge(e["index"], e["source"], e["target"], e["data"]) for e in edges),
+    )
+    return Success(_graph.from_snapshot(snapshot))
+
+
+def _encoded(g: _AnyGraph) -> _Encoded:
+    snapshot = g.to_snapshot()
+    return {
+        "type": snapshot.type,
+        "nodes": tuple({"index": n.index, "data": n.data} for n in snapshot.nodes),
+        "edges": tuple(
+            {"index": e.index, "source": e.source, "target": e.target, "data": e.data}
+            for e in snapshot.edges
+        ),
+    }
+
+
+def _is_graph_of(kind: Kind, value: object) -> bool:
+    return isinstance(value, _graph.Graph) and cast("_AnyGraph", value).type == kind
+
+
+def _run(kind: Kind) -> ast.DeclarationRun:
+    def run(nodes: tuple[ast.AST, ...]) -> ast.DeclarationParser:
+        encoded = _encoded_schema(kind, *nodes)
+
+        def parse(input: object, node: ast.Declaration, options: ParseOptions) -> ast.ParseResult:
+            if not _is_graph_of(kind, input):
+                return ast.invalid_type(node, input, options)
+            snapshot = _encoded(cast("_AnyGraph", input))
+            return ast.flat_map(
+                encoded.parse(snapshot, options),
+                lambda parsed: _decode(cast("_Encoded", parsed), options),
+            )
+
+        return parse
+
+    return run
+
+
+def _codec(kind: Kind) -> Callable[[tuple[ast.AST, ...]], ast.Link]:
+    expected = f"an immutable {kind} Graph"
+
+    def encode(g: _AnyGraph, options: ParseOptions) -> Exit[_Encoded, Issue]:
+        if not _is_graph_of(kind, g):
+            return fail_exit(InvalidValue({"expected": expected}, reported(g, options)))
+        return Success(_encoded(g))
+
+    def to_codec(nodes: tuple[ast.AST, ...]) -> ast.Link:
+        return ast.Link(
+            _encoded_schema(kind, *nodes), T.transform_effect(decode=_decode, encode=encode)
+        )
+
+    return to_codec
+
+
+def _arbitrary(kind: Kind) -> Callable[[tuple[ast.AST, ...], ArbitraryConstraint], ast.Link]:
+    """Effect's ``graphToArbitrary``: ``None`` for the empty graph, or
+    node payloads and ``(source, target, data)`` edges whose endpoints
+    wrap around the node count."""
+
+    def build(drawn: _Encoded | None) -> _AnyGraph:
+        if drawn is None:
+            return _graph.from_snapshot(Snapshot(kind))
+        data = cast("Sequence[object]", drawn["nodes"])
+        edges = cast("Sequence[tuple[int, int, object]]", drawn["edges"])
+        count = len(data)
+        return _graph.from_snapshot(
+            Snapshot(
+                kind,
+                tuple(IndexedNode(i, d) for i, d in enumerate(data)),
+                tuple(
+                    IndexedEdge(i, source % count, target % count, d)
+                    for i, (source, target, d) in enumerate(edges)
+                ),
+            )
+        )
+
+    def unbuild(g: _AnyGraph) -> _Encoded | None:
+        snapshot = g.to_snapshot()
+        if not snapshot.nodes:
+            return None
+        return {
+            "nodes": tuple(n.data for n in snapshot.nodes),
+            "edges": tuple((e.source, e.target, e.data) for e in snapshot.edges),
+        }
+
+    def to_codec_arbitrary(nodes: tuple[ast.AST, ...], _: ArbitraryConstraint) -> ast.Link:
+        node, edge = nodes
+        drawn = ast.Objects(
+            (
+                ast.PropertySignature(
+                    "nodes", ast.append_checks(ast.Arrays(rest=(node,)), (is_min_length(1),))
+                ),
+                ast.PropertySignature(
+                    "edges",
+                    ast.Arrays(
+                        rest=(
+                            ast.Arrays(
+                                (
+                                    ast.Element(Natural.ast),
+                                    ast.Element(Natural.ast),
+                                    ast.Element(edge),
+                                )
+                            ),
+                        )
+                    ),
+                ),
+            )
+        )
+        return ast.Link(
+            ast.Union((ast.null, drawn)), T.Transformation(G.transform(build), G.transform(unbuild))
+        )
+
+    return to_codec_arbitrary
+
+
+def _equivalence(
+    parameters: tuple[Equivalence[Any], ...],
+) -> Equivalence[_AnyGraph]:
+    """Effect's ``graphToEquivalence``: the same kind, node indexes and
+    edge indexes in order, equivalent payloads and the same endpoints (in
+    either order for an undirected edge)."""
+    node, edge = parameters
+
+    def equivalent(self: _AnyGraph, that: _AnyGraph) -> bool:
+        a, b = self.to_snapshot(), that.to_snapshot()
+        if a.type != b.type or len(a.nodes) != len(b.nodes) or len(a.edges) != len(b.edges):
+            return False
+        for an, bn in zip(a.nodes, b.nodes, strict=True):
+            if an.index != bn.index or not node(an.data, bn.data):
+                return False
+        for ae, be in zip(a.edges, b.edges, strict=True):
+            ends = (ae.source, ae.target)
+            same_ends = ends == (be.source, be.target) or (
+                a.type == "undirected" and ends == (be.target, be.source)
+            )
+            if ae.index != be.index or not same_ends or not edge(ae.data, be.data):
+                return False
+        return True
+
+    return equivalent
+
+
+def Graph[N, E, NI, EI, K: Kind, RD, RE](
+    kind: K, node: Codec[N, NI, RD, RE], edge: Codec[E, EI, RD, RE], /
+) -> GraphSchema[N, E, NI, EI, K, RD, RE]:
+    """Immutable ``kind`` graphs (``"directed"`` / ``"undirected"``) of
+    ``node`` and ``edge`` payloads (Effect's ``Schema.Graph``). A mutable
+    graph or one of the other kind is ``Expected an immutable <kind>
+    Graph``. JSON writes the graph's snapshot, indexes kept."""
+    nodes = (node.__codec__().ast, edge.__codec__().ast)
+    annotations = {
+        "representation": {"id": "effect/schema/Graph", "payload": kind},
+        "expected": f"an immutable {kind} Graph",
+        "to_codec": _codec(kind),
+        "to_codec_arbitrary": _arbitrary(kind),
+        "to_equivalence": _equivalence,
+    }
+    declaration = ast.Declaration(nodes, _run(kind), annotations=annotations)
+    return GraphSchema(declaration, kind, node, edge)

pyfect/schema/_instances.py

@@ -0,0 +1,240 @@
+"""The ``to_equivalence`` and ``to_formatter`` annotations of the built-in
+declarations: Effect's ``toEquivalence`` / ``toFormatter`` cases for
+``Option``, ``Result``, ``CauseReason``, ``Cause``, ``Exit``, sets, maps,
+``Redacted``, ``URL``, date-times and zones."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from datetime import tzinfo
+from typing import Any, cast
+from urllib.parse import SplitResult, urlunsplit
+
+from pyfect import redacted
+from pyfect._js import js_sort_key
+from pyfect.cause import Cause, Die, Fail, Interrupt, Reason
+from pyfect.date_time import format_iso_zoned, zone_to_string
+from pyfect.date_time._iso import utc_to_string
+from pyfect.exit import Exit, Success
+from pyfect.option import Option, Some
+from pyfect.result import Ok, Result
+from pyfect.schema._to_equivalence import Equivalence, same_items
+from pyfect.schema._to_formatter import Formatter
+
+type _Equivalences = tuple[Equivalence[Any], ...]
+type _Formatters = tuple[Formatter[Any], ...]
+
+
+def _fixed[A](instance: A) -> Callable[[tuple[object, ...]], A]:
+    return lambda _: instance
+
+
+# ------------------------------------------------------------------ Option
+
+
+def option_equivalence(parameters: _Equivalences) -> Equivalence[Option[object]]:
+    (value,) = parameters
+
+    def equivalent(a: Option[object], b: Option[object]) -> bool:
+        if isinstance(a, Some) and isinstance(b, Some):
+            return value(a.value, b.value)
+        return a is None and b is None
+
+    return equivalent
+
+
+def option_formatter(parameters: _Formatters) -> Formatter[Option[object]]:
+    (value,) = parameters
+    return lambda o: f"some({value(o.value)})" if isinstance(o, Some) else "none()"
+
+
+# ------------------------------------------------------------------ Result
+
+
+def result_equivalence(parameters: _Equivalences) -> Equivalence[Result[object, object]]:
+    success, failure = parameters
+
+    def equivalent(a: Result[object, object], b: Result[object, object]) -> bool:
+        match a, b:
+            case Ok(), Ok():
+                return success(a.value, b.value)
+            case Ok(), _:
+                return False
+            case _, Ok():
+                return False
+            case _:
+                return failure(a.error, b.error)
+
+    return equivalent
+
+
+def result_formatter(parameters: _Formatters) -> Formatter[Result[object, object]]:
+    success, failure = parameters
+    return lambda r: (
+        f"success({success(r.value)})" if isinstance(r, Ok) else f"failure({failure(r.error)})"
+    )
+
+
+# ------------------------------------------------------------------- Cause
+
+
+def _reason_equivalence(
+    error: Equivalence[object], defect: Equivalence[object]
+) -> Equivalence[Reason[object]]:
+    def equivalent(a: Reason[object], b: Reason[object]) -> bool:
+        if type(a) is not type(b):
+            return False
+        match a:
+            case Fail():
+                return error(a.error, cast("Fail[object]", b).error)
+            case Die():
+                return defect(a.defect, cast("Die", b).defect)
+            case _:
+                return a.fiber_id == cast("Interrupt", b).fiber_id
+
+    return equivalent
+
+
+def _reason_formatter(
+    error: Formatter[object], defect: Formatter[object]
+) -> Formatter[Reason[object]]:
+    def format(reason: Reason[object]) -> str:
+        match reason:
+            case Fail():
+                return f"Fail({error(reason.error)})"
+            case Die():
+                return f"Die({defect(reason.defect)})"
+            case _:
+                return "Interrupt"
+
+    return format
+
+
+def _cause_equivalence(
+    error: Equivalence[object], defect: Equivalence[object]
+) -> Equivalence[Cause[object]]:
+    reason = _reason_equivalence(error, defect)
+
+    def equivalent(a: Cause[object], b: Cause[object]) -> bool:
+        return len(a.reasons) == len(b.reasons) and all(map(reason, a.reasons, b.reasons))
+
+    return equivalent
+
+
+def _cause_formatter(
+    error: Formatter[object], defect: Formatter[object]
+) -> Formatter[Cause[object]]:
+    reason = _reason_formatter(error, defect)
+    return lambda cause: f"Cause([{', '.join(map(reason, cause.reasons))}])"
+
+
+def reason_equivalence(parameters: _Equivalences) -> Equivalence[Reason[object]]:
+    return _reason_equivalence(*parameters)
+
+
+def reason_formatter(parameters: _Formatters) -> Formatter[Reason[object]]:
+    return _reason_formatter(*parameters)
+
+
+def cause_equivalence(parameters: _Equivalences) -> Equivalence[Cause[object]]:
+    return _cause_equivalence(*parameters)
+
+
+def cause_formatter(parameters: _Formatters) -> Formatter[Cause[object]]:
+    return _cause_formatter(*parameters)
+
+
+def exit_equivalence(parameters: _Equivalences) -> Equivalence[Exit[object, object]]:
+    value, error, defect = parameters
+    cause = _cause_equivalence(error, defect)
+
+    def equivalent(a: Exit[object, object], b: Exit[object, object]) -> bool:
+        match a, b:
+            case Success(), Success():
+                return value(a.value, b.value)
+            case Success(), _:
+                return False
+            case _, Success():
+                return False
+            case _:
+                return cause(a.cause, b.cause)
+
+    return equivalent
+
+
+def exit_formatter(parameters: _Formatters) -> Formatter[Exit[object, object]]:
+    value, error, defect = parameters
+    cause = _cause_formatter(error, defect)
+    return lambda e: (
+        f"Exit.Success({value(e.value)})"
+        if isinstance(e, Success)
+        else f"Exit.Failure({cause(e.cause)})"
+    )
+
+
+# ------------------------------------------------------- Sets and maps
+
+
+def set_equivalence(parameters: _Equivalences) -> Equivalence[Iterable[object]]:
+    return same_items(parameters[0])
+
+
+def set_formatter(parameters: _Formatters) -> Formatter[frozenset[object]]:
+    (value,) = parameters
+
+    def format(items: frozenset[object]) -> str:
+        if not items:
+            return "FrozenSet(0) {}"
+        texts = sorted(map(value, items), key=js_sort_key)
+        return f"FrozenSet({len(items)}) {{ {', '.join(texts)} }}"
+
+    return format
+
+
+def map_equivalence(parameters: _Equivalences) -> Equivalence[Mapping[object, object]]:
+    key, value = parameters
+
+    def same_entry(a: tuple[object, object], b: tuple[object, object]) -> bool:
+        return key(a[0], b[0]) and value(a[1], b[1])
+
+    entries = same_items(same_entry)
+    return lambda a, b: entries(a.items(), b.items())
+
+
+def map_formatter(parameters: _Formatters) -> Formatter[Mapping[object, object]]:
+    key, value = parameters
+
+    def format(entries: Mapping[object, object]) -> str:
+        if not entries:
+            return "Map(0) {}"
+        texts = sorted((f"{key(k)} => {value(v)}" for k, v in entries.items()), key=js_sort_key)
+        return f"Map({len(entries)}) {{ {', '.join(texts)} }}"
+
+    return format
+
+
+# ---------------------------------------------------------------- Values
+
+
+def redacted_equivalence(parameters: _Equivalences) -> Equivalence[redacted.Redacted[object]]:
+    (value,) = parameters
+    return lambda a, b: value(redacted.value(a), redacted.value(b))
+
+
+def _url_text(url: SplitResult) -> str:
+    return urlunsplit(url)
+
+
+def _same_url(a: SplitResult, b: SplitResult) -> bool:
+    return _url_text(a) == _url_text(b)
+
+
+URL_INSTANCES: dict[str, object] = {
+    "to_equivalence": _fixed(_same_url),
+    "to_formatter": _fixed(_url_text),
+}
+
+
+DATE_TIME_UTC_FORMATTER = _fixed(utc_to_string)
+DATE_TIME_ZONED_FORMATTER = _fixed(format_iso_zoned)
+ZONE_FORMATTER: Callable[[tuple[object, ...]], Formatter[tzinfo]] = _fixed(zone_to_string)

pyfect/schema/_jsonschema/__init__.py

@@ -0,0 +1,90 @@
+"""``to_json_schema_document``: the JSON Schema (Draft 2020-12) of a
+schema's canonical JSON form (Effect's ``Schema.toJsonSchemaDocument``).
+
+The document describes the encoded side of ``to_codec_json(schema)``:
+decode JSON with that codec. It is meant for preliminary validation: the
+schema's decoder stays the authority (a check without a JSON Schema
+fragment is left out, and an approximation never rejects a valid value).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Literal
+
+from pyfect.json_schema import Document, MultiDocument
+from pyfect.schema._jsonschema._annotations import (
+    OnExcessProperty,
+    Options,
+    ReferenceCandidate,
+    ReferencePolicy,
+)
+from pyfect.schema._jsonschema._checks import CheckContext, CheckOutput, ToJsonSchema
+from pyfect.schema._jsonschema._compile import Compiler
+from pyfect.schema._jsonschema._references import References
+from pyfect.schema._schema import Top
+from pyfect.schema._to_codec_json import to_codec_json_asts
+
+__all__ = [
+    "CheckContext",
+    "CheckOutput",
+    "OnExcessProperty",
+    "ReferenceCandidate",
+    "ReferencePolicy",
+    "ToJsonSchema",
+    "to_json_schema_document",
+    "to_json_schema_multi_document",
+]
+
+type Draft2020 = Literal["draft-2020-12"]
+
+
+def to_json_schema_multi_document(
+    schemas: tuple[Top, *tuple[Top, ...]],
+    /,
+    *,
+    on_excess_property: OnExcessProperty = "ignore",
+    generate_descriptions: bool = False,
+    include_annotation_key: Callable[[str], bool] | None = None,
+    reference_policy: ReferencePolicy | None = None,
+) -> MultiDocument[Draft2020]:
+    """The JSON Schemas of several schemas, sharing their definitions.
+
+    ``on_excess_property="error"`` closes objects to keys the schema does
+    not model (as the decoder option of that name does);
+    ``generate_descriptions`` describes a check without a ``description``
+    by its ``expected`` text; ``include_annotation_key(key)`` admits other
+    annotations with JSON values (``"x-..."``); ``reference_policy`` decides
+    which nodes become definitions (default: those with an
+    ``identifier``)."""
+    nodes = to_codec_json_asts([schema.__codec__().ast for schema in schemas])
+    references = References(nodes, reference_policy)
+    compiler = Compiler(
+        references,
+        Options(on_excess_property, generate_descriptions, include_annotation_key),
+    )
+    roots = [compiler.recur(node, []) for node in nodes]
+    out, definitions = compiler.finish(roots)
+    return MultiDocument("draft-2020-12", tuple(out), definitions)
+
+
+def to_json_schema_document(
+    schema: Top,
+    /,
+    *,
+    on_excess_property: OnExcessProperty = "ignore",
+    generate_descriptions: bool = False,
+    include_annotation_key: Callable[[str], bool] | None = None,
+    reference_policy: ReferencePolicy | None = None,
+) -> Document[Draft2020]:
+    """The JSON Schema of ``schema``'s canonical JSON form, with its
+    definitions apart (see ``to_json_schema_multi_document`` for the
+    options)."""
+    multi = to_json_schema_multi_document(
+        (schema,),
+        on_excess_property=on_excess_property,
+        generate_descriptions=generate_descriptions,
+        include_annotation_key=include_annotation_key,
+        reference_policy=reference_policy,
+    )
+    return Document("draft-2020-12", multi.schemas[0], multi.definitions)