pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/_tree.py

@@ -0,0 +1,27 @@
+"""``Tree(node)`` (Effect's ``Tree``): a node value, a tuple of trees or a
+string-keyed dict of trees::
+
+    S.Tree(S.Number).decode_unknown_sync({"a": [1, {"b": 2}]})
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from pyfect.schema._arrays import Array
+from pyfect.schema._literals import Union
+from pyfect.schema._primitives import String
+from pyfect.schema._record import Record
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema._struct import suspend
+
+type TreeValue[N] = N | Sequence[TreeValue[N]] | Mapping[str, TreeValue[N]]
+"""A node, a sequence of trees or a string-keyed mapping of trees (decoded
+as a tuple and a dict)."""
+
+
+def Tree[T, E, RD, RE](node: Codec[T, E, RD, RE], /) -> Bottom[TreeValue[T], TreeValue[E], RD, RE]:
+    """The recursive schema of trees of ``node``'s values."""
+    tree: Bottom[TreeValue[T], TreeValue[E], RD, RE] = suspend(lambda: schema)
+    schema = Union(node, Array(tree), Record(String, tree))
+    return schema

pyfect/schema/_type_walk.py

@@ -0,0 +1,53 @@
+"""What ``to_equivalence`` and ``to_formatter`` share: how a node names its
+own derivation, which union member a value belongs to, and which keys of a
+mapping an index signature covers (Effect's ``getCandidateIndex``,
+``SchemaParser._is`` and ``getIndexSignatureKeys``)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Mapping
+from typing import cast
+
+from pyfect.exit import Success
+from pyfect.schema import ast
+
+
+def annotation_of(node: ast.AST, key: str) -> object | None:
+    """The ``key`` annotation describing ``node`` (its last check's, else
+    its own); a declaration's built-in one stays found under checks."""
+    found = (node.resolve() or {}).get(key)
+    if found is None and isinstance(node, ast.Declaration):
+        found = (node.annotations or {}).get(key)
+    return found
+
+
+def member_selector(
+    node: ast.Union,
+) -> Callable[[object], list[tuple[int, Callable[[object], bool]]]]:
+    """For a value: the members it may belong to, in order, each with a
+    guard on the member's decoded side."""
+    typed = cast("ast.Union", node.to_type())
+    guards = [_guard(member) for member in typed.types]
+
+    def select(value: object) -> list[tuple[int, Callable[[object], bool]]]:
+        return [(i, guards[i]) for i in typed.candidates(value)]
+
+    return select
+
+
+def _guard(node: ast.AST) -> Callable[[object], bool]:
+    def guard(value: object) -> bool:
+        return type(ast.run_now(node.parse(value, {}))) is Success
+
+    return guard
+
+
+def index_keys(value: Mapping[object, object], index: ast.IndexSignature) -> list[Hashable]:
+    """The keys of ``value`` that ``index`` covers, in ``value``'s order."""
+    return [key for key in value if index.selects(key)]
+
+
+def class_name(node: ast.Class) -> str:
+    """The name a class's values are written with: its ``identifier``, else
+    the class name."""
+    return ast.AST.expected(node)

pyfect/schema/_undefined.py

@@ -0,0 +1,58 @@
+"""Effect's ``Schema.Undefined`` for schemas whose wire form must match Effect's
+(``Schema.optional``, ``RpcMessage.EncodedSchema``'s optional fields). Python has
+one absent value, so its values are ``None``; ``S.Null`` stays a different
+layout, and JSON writes both as ``null``, as Effect's does."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TypeIs, cast
+
+from pyfect.schema import ast
+from pyfect.schema._codec_links import link
+from pyfect.schema._declare import declare
+from pyfect.schema._schema import Bottom
+
+UNDEFINED_ID = "pyfect/schema/Undefined"
+VOID_ID = "pyfect/schema/Void"
+OBJECT_KEYWORD_ID = "pyfect/schema/ObjectKeyword"
+
+
+def _is_none(value: object) -> TypeIs[None]:
+    return value is None
+
+
+def _none_strategy(_: tuple[object, ...]) -> object:
+    from pyfect.schema._strategy import st
+
+    return st.none()
+
+
+def _nothing(_: object) -> None:
+    return None
+
+
+def to_null_json(_: tuple[ast.AST, ...]) -> ast.Link:
+    """JSON writes ``undefined`` and ``void`` as ``null``, and reads only that."""
+    return link(ast.null, decode=_nothing, encode=_nothing)
+
+
+def stays_absent_in_a_string_tree(_: tuple[ast.AST, ...]) -> None:
+    """A string tree holds ``undefined`` itself, as ``None``; ``S.Null`` is the text ``null``."""
+
+
+Undefined: Bottom[None] = declare(
+    _is_none,
+    expected="undefined",
+    to_codec_json=to_null_json,
+    to_codec_string_tree=stays_absent_in_a_string_tree,
+    representation={"id": UNDEFINED_ID, "payload": None},
+    to_arbitrary=_none_strategy,
+)
+
+
+def is_undefined(node: ast.AST) -> bool:
+    representation = (node.annotations or {}).get("representation")
+    if not isinstance(representation, Mapping):
+        return False
+    return cast("Mapping[str, object]", representation).get("id") == UNDEFINED_ID

pyfect/schema/_value_codecs.py

@@ -0,0 +1,84 @@
+"""How the single-value declarations are written in JSON (their
+``to_codec_json`` links, as Effect writes them).
+
+A date-time or a zone is its text; a zone offset its milliseconds; a byte
+size its count, as a bigint; a duration ``{"_tag": "Millis", "value": n}``
+when it is a whole number of milliseconds, else
+``{"_tag": "Nanos", "value": n}`` (a ``timedelta`` is never infinite, so
+Effect's ``Infinity`` forms are not used).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import timedelta
+from fractions import Fraction
+from typing import Any
+
+from pyfect.schema import ast
+from pyfect.schema import transformation as T
+from pyfect.schema._checks_number import int_value, is_greater_than_or_equal_to_big_int
+from pyfect.schema._codec_links import CodecLink, partial_link, tagged
+
+_INT = ast.append_checks(ast.whole_number, (int_value(),))
+_US_PER_MS = 1000
+_NS_PER_US = 1000
+
+
+def string_codec(transformation: T.Transformation[Any, str]) -> CodecLink:
+    """A declaration written as text through ``transformation``."""
+
+    def make(_: tuple[ast.AST, ...]) -> ast.Link:
+        return ast.Link(ast.string, transformation)
+
+    return make
+
+
+def time_zone_offset_codec(_: tuple[ast.AST, ...]) -> ast.Link:
+    return ast.Link(_INT, T.time_zone_offset_from_number)
+
+
+_NON_NEGATIVE_BIG_INT = ast.append_checks(ast.big_int, (is_greater_than_or_equal_to_big_int(0),))
+
+
+def byte_size_codec(_: tuple[ast.AST, ...]) -> ast.Link:
+    return ast.Link(_NON_NEGATIVE_BIG_INT, T.byte_size_from_big_int)
+
+
+def _duration_of(encoded: Mapping[str, Any]) -> timedelta | None:
+    # A ``timedelta`` holds less than a billion days (Effect's are not bounded).
+    try:
+        if encoded["_tag"] == "Millis":
+            return timedelta(milliseconds=encoded["value"])
+        return timedelta(microseconds=round(Fraction(encoded["value"], _NS_PER_US)))
+    except OverflowError:
+        return None
+
+
+def _duration_to(duration: timedelta) -> Mapping[str, object]:
+    micros = duration // timedelta(microseconds=1)
+    if micros % _US_PER_MS == 0:
+        return {"_tag": "Millis", "value": micros // _US_PER_MS}
+    return {"_tag": "Nanos", "value": micros * _NS_PER_US}
+
+
+_DURATION = ast.Union((tagged("Nanos", value=ast.big_int), tagged("Millis", value=_INT)))
+
+
+def duration_codec(_: tuple[ast.AST, ...]) -> ast.Link:
+    return partial_link(
+        _DURATION,
+        decode=_duration_of,
+        encode=_duration_to,
+        expected="a duration a timedelta can hold",
+    )
+
+
+_BYTE_SIZE_STRING = ast.annotate(
+    ast.string, {"expected": "a string that will be decoded as a ByteSize"}
+)
+
+
+def byte_size_string_tree_codec(_: tuple[ast.AST, ...]) -> ast.Link:
+    """A byte size in a string tree: its text (``"10 MB"``), as Effect's."""
+    return ast.Link(_BYTE_SIZE_STRING, T.byte_size_from_string)

pyfect/schema/_values.py

@@ -0,0 +1,123 @@
+"""Schemas of single values: durations, date-times and zones, byte sizes
+and JSON (Effect's declarations of them), over the Python types pyfect
+uses for them.
+
+``Duration`` is a ``timedelta``. ``DateTimeUtc`` is an aware ``datetime``
+whose zone is ``timezone.utc``; ``DateTimeZoned`` any aware ``datetime``
+(pyfect's UTC and zero-offset date-times are the same value). A
+``TimeZoneNamed`` is a ``ZoneInfo``, a ``TimeZoneOffset`` a
+``datetime.timezone``. Each is taken unchanged, on both sides.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta, timezone, tzinfo
+from typing import Never, TypeIs
+from zoneinfo import ZoneInfo
+
+from pyfect._json_value import JsonValue
+from pyfect.byte_size import ByteSize as _ByteSize
+from pyfect.byte_size import is_byte_size
+from pyfect.schema import _arbitrary_links as _arb
+from pyfect.schema import ast
+from pyfect.schema import transformation as T
+from pyfect.schema._declare import declare, instance_of
+from pyfect.schema._instances import (
+    DATE_TIME_UTC_FORMATTER,
+    DATE_TIME_ZONED_FORMATTER,
+    ZONE_FORMATTER,
+)
+from pyfect.schema._primitives import String
+from pyfect.schema._record import Record, RecordSchema
+from pyfect.schema._schema import Bottom
+from pyfect.schema._value_codecs import (
+    byte_size_codec,
+    byte_size_string_tree_codec,
+    duration_codec,
+    string_codec,
+    time_zone_offset_codec,
+)
+
+Duration: Bottom[timedelta] = instance_of(
+    timedelta,
+    expected="Duration",
+    representation={"id": "effect/schema/Duration", "payload": None},
+    to_codec_json=duration_codec,
+)
+"""A ``timedelta`` (Effect's ``Duration``)."""
+
+
+def _is_utc(value: object) -> TypeIs[datetime]:
+    return isinstance(value, datetime) and value.tzinfo is UTC
+
+
+def _is_zoned(value: object) -> TypeIs[datetime]:
+    return isinstance(value, datetime) and value.utcoffset() is not None
+
+
+DateTimeUtc: Bottom[datetime] = declare(
+    _is_utc,
+    expected="DateTime.Utc",
+    representation={"id": "effect/schema/DateTimeUtc", "payload": None},
+    to_codec_arbitrary=_arb.date_time_utc,
+    to_codec_json=string_codec(T.date_time_utc_from_string),
+    to_formatter=DATE_TIME_UTC_FORMATTER,
+)
+"""An aware ``datetime`` in ``timezone.utc`` (Effect's ``DateTimeUtc``)."""
+DateTimeZoned: Bottom[datetime] = declare(
+    _is_zoned,
+    expected="DateTime.Zoned",
+    representation={"id": "effect/schema/DateTimeZoned", "payload": None},
+    to_codec_arbitrary=_arb.date_time_zoned,
+    to_codec_json=string_codec(T.date_time_zoned_from_string),
+    to_formatter=DATE_TIME_ZONED_FORMATTER,
+)
+"""An aware ``datetime`` (Effect's ``DateTimeZoned``); a naive one is
+rejected."""
+TimeZoneNamed: Bottom[ZoneInfo] = instance_of(
+    ZoneInfo,
+    expected="DateTime.TimeZone.Named",
+    representation={"id": "effect/schema/TimeZoneNamed", "payload": None},
+    to_codec_arbitrary=_arb.time_zone_named,
+    to_codec_json=string_codec(T.time_zone_named_from_string),
+    to_formatter=ZONE_FORMATTER,
+)
+"""A ``ZoneInfo`` (Effect's ``TimeZoneNamed``)."""
+TimeZoneOffset: Bottom[timezone] = instance_of(
+    timezone,
+    expected="DateTime.TimeZone.Offset",
+    representation={"id": "effect/schema/TimeZoneOffset", "payload": None},
+    to_codec_arbitrary=_arb.time_zone_offset,
+    to_codec_json=time_zone_offset_codec,
+    to_formatter=ZONE_FORMATTER,
+)
+"""A fixed-offset ``datetime.timezone`` (Effect's ``TimeZoneOffset``)."""
+
+
+def _is_zone(value: object) -> TypeIs[tzinfo]:
+    return isinstance(value, ZoneInfo | timezone)
+
+
+TimeZone: Bottom[tzinfo] = declare(
+    _is_zone,
+    expected="DateTime.TimeZone",
+    representation={"id": "effect/schema/TimeZone", "payload": None},
+    to_codec_arbitrary=_arb.time_zone,
+    to_codec_json=string_codec(T.time_zone_from_string),
+    to_formatter=ZONE_FORMATTER,
+)
+"""A ``ZoneInfo`` or a ``datetime.timezone`` (Effect's ``TimeZone``)."""
+ByteSize: Bottom[_ByteSize] = declare(
+    is_byte_size,
+    expected="ByteSize",
+    representation={"id": "effect/schema/ByteSize", "payload": None},
+    to_codec_json=byte_size_codec,
+    to_codec_string_tree=byte_size_string_tree_codec,
+)
+"""A ``byte_size.ByteSize``: a non-negative ``int`` (Effect's ``ByteSize``)."""
+
+Json: Bottom[JsonValue] = Bottom(ast.json)
+"""Any JSON value (``ast.is_json``), unchanged: ``Expected JSON value``
+otherwise (Effect's ``Json``)."""
+JsonObject: RecordSchema[str, JsonValue, str, JsonValue, Never, Never] = Record(String, Json)
+"""A string-keyed mapping of JSON values (Effect's ``JsonObject``)."""

pyfect/schema/_void.py

@@ -0,0 +1,86 @@
+"""Effect's ``Undefined``, ``Void`` and ``ObjectKeyword``."""
+
+from __future__ import annotations
+
+from types import NoneType
+from typing import TypeIs
+
+from pyfect.exit import Exit, Success
+from pyfect.schema import ast
+from pyfect.schema import transformation as T
+from pyfect.schema._codec_links import UNKNOWN_TO_STRING_TREE
+from pyfect.schema._declare import Parse, declare
+from pyfect.schema._options import ParseOptions
+from pyfect.schema._schema import Bottom
+from pyfect.schema._undefined import (
+    OBJECT_KEYWORD_ID,
+    VOID_ID,
+    Undefined,
+    stays_absent_in_a_string_tree,
+    to_null_json,
+)
+from pyfect.schema.issue import Issue
+
+
+def _void_run(_: tuple[ast.AST, ...]) -> Parse[None]:
+    def parse(_input: object, _node: ast.Declaration, _options: ParseOptions) -> Exit[None, Issue]:
+        return Success(None)
+
+    return parse
+
+
+Void: Bottom[None, object] = Bottom(
+    ast.Declaration(
+        (),
+        _void_run,
+        annotations={
+            "expected": "void",
+            "to_codec_json": to_null_json,
+            "to_codec_string_tree": stays_absent_in_a_string_tree,
+            "representation": {"id": VOID_ID, "payload": None},
+        },
+    )
+)
+"""Takes anything and gives ``None``, in both directions, as ``void`` ignores a
+value; JSON writes it as ``null``."""
+
+
+def _is_object(value: object) -> TypeIs[object]:
+    return not isinstance(value, str | int | float | NoneType)
+
+
+def _object_strategy(_: tuple[object, ...]) -> object:
+    from pyfect.schema._strategy import st
+
+    return st.dictionaries(st.text(), st.integers())
+
+
+_ARRAY_OR_OBJECT = ast.Union(
+    (
+        ast.Arrays(rest=(ast.json,), mutable=True),
+        ast.Objects(index_signatures=(ast.IndexSignature(ast.string, ast.json),)),
+    )
+)
+
+
+def _object_to_json(_: tuple[ast.AST, ...]) -> ast.Link:
+    unchanged: T.Transformation[object, object] = T.passthrough()
+    return ast.Link(_ARRAY_OR_OBJECT, unchanged)
+
+
+def _object_to_string_tree(_: tuple[ast.AST, ...]) -> ast.Link:
+    return UNKNOWN_TO_STRING_TREE
+
+
+ObjectKeyword: Bottom[object] = declare(
+    _is_object,
+    expected="object | array | function",
+    to_arbitrary=_object_strategy,
+    to_codec_json=_object_to_json,
+    to_codec_string_tree=_object_to_string_tree,
+    representation={"id": OBJECT_KEYWORD_ID, "payload": None},
+)
+"""Anything but a primitive; JSON holds an array or an object of JSON, a string tree those of
+string trees, as Effect's."""
+
+__all__ = ["ObjectKeyword", "Undefined", "Void"]

pyfect/schema/ast/__init__.py

@@ -0,0 +1,227 @@
+"""The schema AST (Effect's ``SchemaAST``): one node per kind of value.
+
+A schema object (``Bottom``) wraps one of these. Each node knows the text
+of what it expects (``get_expected``, ``"string"``) and parses a value of
+its own kind (``parse``), then runs its ``checks`` (``Filter`` /
+``FilterGroup``) on the value. ``annotations`` hold documentation and
+message overrides (``identifier``, ``message``, ``expected``, ...), keyed
+in snake_case.
+
+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. ``Enum`` is a Python ``enum.Enum``, decoded
+from its values. ``Symbol`` and ``UniqueSymbol`` have no Python counterpart; ``S.Undefined``,
+``S.Void`` and ``S.ObjectKeyword`` are declarations here, not nodes.
+"""
+
+from pyfect.schema.ast._annotations import (
+    is_optional,
+    resolve_at,
+    resolve_description,
+    resolve_identifier,
+    resolve_title,
+)
+from pyfect.schema.ast._arrays import Arrays, Element
+from pyfect.schema.ast._base import (
+    AST,
+    Annotations,
+    Checks,
+    Refinement,
+    annotate,
+    append_checks,
+    invalid_type,
+    issue_of,
+    join_checks,
+    replace_context,
+    with_constructor_default,
+)
+from pyfect.schema.ast._check import (
+    Check,
+    Filter,
+    FilterGroup,
+    FilterIssue,
+    FilterOutput,
+    collect_issues,
+    filter_of,
+    has_check,
+    make_filter,
+    make_filter_by_guard,
+    normalize_filter_output,
+)
+from pyfect.schema.ast._class import Class, ClassShape, ClassSide, check_instance
+from pyfect.schema.ast._constructors import (
+    struct,
+    struct_with_rest,
+    tuple_,
+    tuple_with_rest,
+    union,
+)
+from pyfect.schema.ast._declaration import (
+    Declaration,
+    DeclarationParser,
+    DeclarationRun,
+    parse_at_key,
+)
+from pyfect.schema.ast._encoding import (
+    Encoding,
+    Link,
+    LinkTransformation,
+    decode_to,
+    optional_key,
+    to_encoded,
+)
+from pyfect.schema.ast._json import is_json, is_string_tree, json, string_tree
+from pyfect.schema.ast._keywords import (
+    Any,
+    BigInt,
+    Boolean,
+    Never,
+    Null,
+    Number,
+    String,
+    Unknown,
+    any_,
+    big_int,
+    boolean,
+    never,
+    null,
+    number,
+    string,
+    unknown,
+    whole_number,
+)
+from pyfect.schema.ast._literal import (
+    Enum,
+    EnumSide,
+    Literal,
+    LiteralValue,
+    format_literal,
+    same_literal,
+)
+from pyfect.schema.ast._objects import IndexSignature, Objects, PropertySignature
+from pyfect.schema.ast._record import record
+from pyfect.schema.ast._result import (
+    MISSING,
+    MISSING_EXIT,
+    Missing,
+    ParseResult,
+    call,
+    flat_map,
+    is_exit,
+    map_issue,
+    map_value,
+    run_now,
+    then,
+    to_effect,
+)
+from pyfect.schema.ast._suspend import Suspend
+from pyfect.schema.ast._template_literal import (
+    BIG_INT_PATTERN,
+    FINITE_PATTERN,
+    STRING_PATTERN,
+    TemplateLiteral,
+    match_part,
+)
+from pyfect.schema.ast._union import Union, UnionMode
+
+__all__ = [
+    "AST",
+    "BIG_INT_PATTERN",
+    "FINITE_PATTERN",
+    "MISSING",
+    "MISSING_EXIT",
+    "STRING_PATTERN",
+    "Annotations",
+    "Any",
+    "Arrays",
+    "BigInt",
+    "Boolean",
+    "Check",
+    "Checks",
+    "Class",
+    "ClassShape",
+    "ClassSide",
+    "Declaration",
+    "DeclarationParser",
+    "DeclarationRun",
+    "Element",
+    "Encoding",
+    "Enum",
+    "EnumSide",
+    "Filter",
+    "FilterGroup",
+    "FilterIssue",
+    "FilterOutput",
+    "IndexSignature",
+    "Link",
+    "LinkTransformation",
+    "Literal",
+    "LiteralValue",
+    "Missing",
+    "Never",
+    "Null",
+    "Number",
+    "Objects",
+    "ParseResult",
+    "PropertySignature",
+    "Refinement",
+    "String",
+    "Suspend",
+    "TemplateLiteral",
+    "Union",
+    "UnionMode",
+    "Unknown",
+    "annotate",
+    "any_",
+    "append_checks",
+    "big_int",
+    "boolean",
+    "call",
+    "check_instance",
+    "collect_issues",
+    "decode_to",
+    "filter_of",
+    "flat_map",
+    "format_literal",
+    "has_check",
+    "invalid_type",
+    "is_exit",
+    "is_json",
+    "is_optional",
+    "is_string_tree",
+    "issue_of",
+    "join_checks",
+    "json",
+    "make_filter",
+    "make_filter_by_guard",
+    "map_issue",
+    "map_value",
+    "match_part",
+    "never",
+    "normalize_filter_output",
+    "null",
+    "number",
+    "optional_key",
+    "parse_at_key",
+    "record",
+    "replace_context",
+    "resolve_at",
+    "resolve_description",
+    "resolve_identifier",
+    "resolve_title",
+    "run_now",
+    "same_literal",
+    "string",
+    "string_tree",
+    "struct",
+    "struct_with_rest",
+    "then",
+    "to_effect",
+    "to_encoded",
+    "tuple_",
+    "tuple_with_rest",
+    "union",
+    "unknown",
+    "whole_number",
+    "with_constructor_default",
+]