pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/getter/_tree_record.py

@@ -0,0 +1,170 @@
+"""Bracket paths (Effect's ``makeTreeRecord`` / ``collectBracketPathEntries``):
+flat ``(path, value)`` entries, as form fields and query strings carry
+them, to a nested tree and back::
+
+    make_tree_record([("user[name]", "Al"), ("user[tags][]", "a")])
+    # {"user": {"name": "Al", "tags": ["a"]}}
+
+``"a[b]"`` and ``"a.b"`` are a key, ``"a[0]"`` an index (a canonical array
+index below 2**32 - 1, else a key), ``"a[]"`` the next index; a repeated
+path collects its values in a list; a later path needing a different
+container replaces what was there. An indexed container becomes a list
+(``None`` in its holes) only with at most 20 holes, else a dict keyed by
+the index text, so ``a[4294967294]`` cannot make a huge list.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeIs, cast
+
+from pyfect._digits import parse_digits
+
+if TYPE_CHECKING:
+    from pyfect.schema._tree import TreeValue
+
+_MAX_ARRAY_HOLES = 20
+_MAX_INDEX = 2**32 - 1
+_BRACKETS = re.compile(r"\[(.*?)\]")
+
+type _Token = str | int
+
+
+def _is_index(part: str) -> bool:
+    value = parse_digits(part, unpadded=True)
+    return value is not None and value < _MAX_INDEX
+
+
+def _tokens(path: str) -> list[_Token]:
+    if path == "":
+        return [""]
+    replaced = _BRACKETS.sub(r".\1", path)
+    parts = replaced.split(".")[1 if replaced.startswith(".") else 0 :]
+    return [int(part) if _is_index(part) else part for part in parts]
+
+
+@dataclass(slots=True)
+class _Indexed:
+    parent: dict[_Token, object]
+    key: _Token
+    length: int = 0
+
+
+class _Builder:
+    def __init__(self) -> None:
+        self.out: dict[_Token, object] = {}
+        # Keyed by id(); ``made`` keeps each container alive so ids stay unique.
+        self.made: list[object] = []
+        self.containers: set[int] = set()
+        self.duplicates: set[int] = set()
+        self.indexed: dict[int, tuple[dict[_Token, object], _Indexed]] = {}
+
+    def _state(self, value: object) -> _Indexed | None:
+        found = self.indexed.get(id(value))
+        return None if found is None or found[0] is not value else found[1]
+
+    def add(self, path: str, value: object) -> None:
+        tokens = _tokens(path)
+        cur = self.out
+        for i, raw in enumerate(tokens):
+            state = self._state(cur)
+            token: _Token = state.length if raw == "" and state is not None else raw
+            if state is not None and isinstance(token, int):
+                state.length = max(state.length, token + 1)
+            if state is None and isinstance(token, int):
+                token = str(token)
+            has = token in cur
+            current = cur.get(token)
+            if i == len(tokens) - 1:
+                self._leaf(cur, token, current, has=has, value=value)
+            else:
+                cur = self._descend(cur, token, current, array=_is_array_token(tokens[i + 1]))
+
+    def _leaf(
+        self, cur: dict[_Token, object], token: _Token, current: object, *, has: bool, value: object
+    ) -> None:
+        current_state = self._state(current)
+        if current_state is not None:
+            cast("dict[_Token, object]", current)[current_state.length] = value
+            current_state.length += 1
+        elif id(current) in self.duplicates and isinstance(current, list):
+            cast("list[object]", current).append(value)
+        elif has:
+            values: list[object] = [current, value]
+            self.made.append(values)
+            self.duplicates.add(id(values))
+            cur[token] = values
+        else:
+            cur[token] = value
+
+    def _descend(
+        self, cur: dict[_Token, object], token: _Token, current: object, *, array: bool
+    ) -> dict[_Token, object]:
+        if id(current) in self.containers and (self._state(current) is not None) == array:
+            return cast("dict[_Token, object]", current)
+        container: dict[_Token, object] = {}
+        self.made.append(container)
+        self.containers.add(id(container))
+        if array:
+            self.indexed[id(container)] = (container, _Indexed(cur, token))
+        cur[token] = container
+        return container
+
+    def finish(self) -> dict[str, object]:
+        # Children are made after their parents: materializing in reverse
+        # order replaces each nested container before its parent is copied.
+        for builder, state in reversed(self.indexed.values()):
+            parent, key = state.parent, state.key
+            if parent.get(key) is not builder:
+                continue  # a later conflicting path replaced it
+            if state.length - len(builder) <= _MAX_ARRAY_HOLES:
+                parent[key] = [builder.get(i) for i in range(state.length)]
+            else:
+                parent[key] = {str(k): v for k, v in builder.items()}
+        return cast("dict[str, object]", self.out)
+
+
+def _is_array_token(token: _Token) -> bool:
+    return isinstance(token, int) or token == ""
+
+
+def make_tree_record[A](entries: Iterable[tuple[str, A]], /) -> dict[str, TreeValue[A | None]]:
+    """The tree of bracket-path ``entries`` (Effect's ``makeTreeRecord``)."""
+    builder = _Builder()
+    for path, value in entries:
+        builder.add(path, value)
+    return cast("dict[str, TreeValue[A | None]]", builder.finish())
+
+
+def collect_bracket_path_entries[A](
+    is_leaf: Callable[[object], TypeIs[A]], /
+) -> Callable[[Mapping[str, object]], list[tuple[str, A]]]:
+    """A tree flattened to bracket-path entries (Effect's
+    ``collectBracketPathEntries``): a list of leaves repeats its key, any
+    other list indexes ``key[i]``, a mapping ``key[k]``; values that are
+    neither leaves nor containers are dropped."""
+
+    def collect(tree: Mapping[str, object]) -> list[tuple[str, A]]:
+        entries: list[tuple[str, A]] = []
+
+        def append(key: str, value: object) -> None:
+            if is_leaf(value):
+                entries.append((key, value))
+            elif isinstance(value, Sequence) and not isinstance(value, str | bytes):
+                items = cast("Sequence[object]", value)
+                if all(is_leaf(item) for item in items):
+                    entries.extend((key, cast("A", item)) for item in items)
+                else:
+                    for i, item in enumerate(items):
+                        append(f"{key}[{i}]", item)
+            elif isinstance(value, Mapping):
+                for k, v in cast("Mapping[object, object]", value).items():
+                    append(f"{key}[{k}]", v)
+
+        for key, value in tree.items():
+            append(key, value)
+        return entries
+
+    return collect

pyfect/schema/issue.py

@@ -0,0 +1,420 @@
+"""Why a value was rejected (Effect's ``SchemaIssue``): a tree of issues.
+
+Leaves say what went wrong (``InvalidType``: not a value of the expected
+kind; ``InvalidValue``: the right kind, a wrong value; ``MissingKey``,
+``UnexpectedKey``, ``Forbidden``, ``OneOf``: several union members matched).
+``Pointer`` says where (a path below the enclosing value), ``Composite``
+groups several issues of one value, ``Filter`` wraps the issue of a failed
+check, ``AnyOf`` the issues of a union's members, and ``Encoding`` an issue
+raised while transforming a value.
+
+``input`` is ``Some(value)`` only when parsing ran with ``report_input=True``
+(the rejected value is then kept and printed); otherwise ``None``.
+``format_issue`` is Effect's default formatter: each leaf's message, with
+``\\n  at ["key"][0]`` below the root.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypedDict, TypeIs
+
+from pyfect.logger._text import format_unknown, json_quote
+from pyfect.option import Option, Some
+
+if TYPE_CHECKING:
+    from pyfect.schema._options import ParseOptions
+    from pyfect.schema.ast import AST, Check, Union
+    from pyfect.schema.ast import Filter as AstFilter
+
+type PathKey = Hashable
+"""A key of a path: a mapping key (a ``str`` in decoded JSON) or an index."""
+type Path = tuple[PathKey, ...]
+type IssueAnnotations = Mapping[str, object]
+"""Annotations of a leaf issue; ``message`` replaces its text, ``expected``
+fills ``"Expected <...>"``."""
+
+
+def reported(input: object, options: ParseOptions) -> Option[object]:
+    """``input`` as an issue keeps it: only under ``report_input``."""
+    return Some(input) if options.get("report_input") else None
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidType:
+    """``input`` is not a value of the kind ``ast`` expects."""
+
+    ast: AST
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidValue:
+    """A value of the right kind that is not allowed."""
+
+    annotations: IssueAnnotations | None = None
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class MissingKey:
+    """A required key is absent; ``annotations`` are the key's."""
+
+    annotations: IssueAnnotations | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class UnexpectedKey:
+    """A key the schema does not declare (``on_excess_property="error"``)."""
+
+    ast: AST
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class Forbidden:
+    """An operation that is not allowed at all."""
+
+    annotations: IssueAnnotations | None = None
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class Pointer:
+    """``issue`` at ``path``, relative to the enclosing value."""
+
+    path: Path
+    issue: Issue
+
+
+@dataclass(frozen=True, slots=True)
+class Composite:
+    """Several issues of one value (``ast``'s), printed one after another."""
+
+    ast: AST
+    issues: tuple[Issue, *tuple[Issue, ...]]
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class Encoding:
+    """``issue`` raised while transforming a value of ``ast``."""
+
+    ast: AST
+    issue: Issue
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class Filter:
+    """``issue`` raised by the check ``filter`` on a value."""
+
+    filter: AstFilter[Any]
+    issue: Issue
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class AnyOf:
+    """No member of the union ``ast`` matched; ``issues`` are the tried
+    members' (none when no member could take the value)."""
+
+    ast: Union
+    issues: tuple[Issue, ...]
+    input: Option[object] = None
+
+
+@dataclass(frozen=True, slots=True)
+class OneOf:
+    """Several members of the ``"one_of"`` union ``ast`` matched."""
+
+    ast: Union
+    successes: tuple[AST, ...]
+    input: Option[object] = None
+
+
+type Leaf = InvalidType | InvalidValue | MissingKey | UnexpectedKey | Forbidden | OneOf
+type Issue = Leaf | Filter | Pointer | Composite | Encoding | AnyOf
+
+
+def is_issue(value: object) -> TypeIs[Issue]:
+    return isinstance(
+        value,
+        InvalidType
+        | InvalidValue
+        | MissingKey
+        | UnexpectedKey
+        | Forbidden
+        | OneOf
+        | Filter
+        | Pointer
+        | Composite
+        | Encoding
+        | AnyOf,
+    )
+
+
+type Formatter[F] = Callable[[Issue], F]
+"""Turns an issue into a report (Effect's ``SchemaIssue.Formatter``)."""
+type LeafHook = Callable[[Leaf], str]
+"""The text of a leaf issue (Effect's ``LeafHook``)."""
+type CheckHook = Callable[[Filter], str | None]
+"""The text of a failed check, ``None`` for the default one (Effect's
+``CheckHook``)."""
+
+
+class StandardIssue(TypedDict):
+    """One issue of a Standard Schema failure: its text and where it is."""
+
+    message: str
+    path: Path
+
+
+class StandardFailure(TypedDict):
+    """A Standard Schema failure result (``StandardSchemaV1.FailureResult``)."""
+
+    issues: list[StandardIssue]
+
+
+def has_input(issue: Issue) -> bool:
+    """``issue`` keeps the rejected value (Effect's ``hasInput``): parsing
+    ran with ``report_input=True``. A ``Pointer`` and a ``MissingKey``
+    never do."""
+    match issue:
+        case Pointer() | MissingKey():
+            return False
+        case _:
+            return issue.input is not None
+
+
+def format_issue(issue: Issue) -> str:
+    """Effect's default formatter (``SchemaIssue.defaultFormatter``): one
+    message per leaf, each followed by ``\\n  at <path>`` below the root."""
+    return "\n".join(
+        "" if message is None else f"{message}\n  at {format_path(path)}" if path else message
+        for path, message in _messages(issue, leaf_message, default_check_hook)
+    )
+
+
+def make_formatter_default() -> Formatter[str]:
+    """``format_issue`` (Effect's ``makeFormatterDefault``)."""
+    return format_issue
+
+
+def make_formatter_standard_schema_v1(
+    *, leaf_hook: LeafHook | None = None, check_hook: CheckHook | None = None
+) -> Formatter[StandardFailure]:
+    """A formatter writing an issue as a Standard Schema failure: one
+    ``{"message", "path"}`` per leaf (Effect's
+    ``makeFormatterStandardSchemaV1``). ``leaf_hook`` writes a leaf
+    (``leaf_message`` by default), ``check_hook`` a failed check
+    (``default_check_hook``)."""
+    leaf = leaf_hook or leaf_message
+    check = check_hook or default_check_hook
+
+    def format(issue: Issue) -> StandardFailure:
+        return {
+            "issues": [
+                StandardIssue(message=message, path=path)
+                for path, message in _messages(issue, leaf, check)
+                if message is not None
+            ]
+        }
+
+    return format
+
+
+def format_path(path: Path) -> str:
+    """``["a"][1]``: string keys as JSON strings, any other key (an index)
+    as ``format_unknown`` prints it."""
+    return "".join(f"[{_format_key(key)}]" for key in path)
+
+
+def _format_key(key: PathKey) -> str:
+    return json_quote(key) if isinstance(key, str) else format_unknown(key)
+
+
+def _messages(
+    issue: Issue, leaf_hook: LeafHook, check_hook: CheckHook
+) -> list[tuple[Path, str | None]]:
+    """Each leaf's path and text, in order; an empty ``Composite`` is
+    ``None`` (an empty line in ``format_issue``, nothing in a Standard
+    Schema failure)."""
+    # A loop over an explicit stack: an issue tree is as deep as the input.
+    out: list[tuple[Path, str | None]] = []
+    stack: list[tuple[Issue, Path, str | None]] = [(issue, (), None)]
+    while stack:
+        issue, path, override = stack.pop()
+        match issue:
+            case Filter(issue=inner):
+                found = override if override is not None else filter_message(issue, check_hook)
+                stack.append((inner, path, found))
+                continue
+            case Encoding(issue=inner):
+                stack.append((inner, path, override))
+                continue
+            case Pointer(segments, inner):
+                stack.append((inner, (*path, *segments), override))
+                continue
+            case Composite(issues=issues) | AnyOf(issues=issues) if issues:
+                stack.extend((i, path, override) for i in reversed(issues))
+                continue
+            case Composite():
+                out.append((path, None))
+                continue
+            case AnyOf(ast=ast):
+                found = override if override is not None else _find_message(issue)
+                message = (
+                    found if found is not None else _expected_message(ast.expected(), issue.input)
+                )
+            case _:
+                message = override if override is not None else leaf_hook(issue)
+        out.append((path, message))
+    return out
+
+
+def leaf_message(issue: Leaf) -> str:
+    """A leaf's text: its ``message`` annotation, else the default one
+    (Effect's ``defaultLeafHook``)."""
+    message = _find_message(issue)
+    return message if message is not None else _default_leaf_message(issue)
+
+
+_WITH_INPUT: dict[type, tuple[str, str]] = {
+    UnexpectedKey: ("Expected no excess property", "Unexpected key with value"),
+    OneOf: (
+        "Expected exactly one member to match",
+        "Expected exactly one member to match the input",
+    ),
+}
+
+
+def _default_leaf_message(issue: Leaf) -> str:
+    match issue:
+        case InvalidType(ast=ast):
+            return _expected_message(ast.expected(), issue.input)
+        case InvalidValue():
+            expected = _find_expected(issue)
+            if expected is not None:
+                return _expected_message(expected, issue.input)
+            return _with_input("Expected a valid value", "Invalid data", issue.input)
+        case MissingKey():
+            return "Missing key"
+        case Forbidden():
+            return "Forbidden operation"
+        case UnexpectedKey() | OneOf():
+            return _with_input(*_WITH_INPUT[type(issue)], issue.input)
+
+
+def _with_input(without: str, prefix: str, input: Option[object]) -> str:
+    return without if input is None else f"{prefix} {_show(input)}"
+
+
+def default_check_hook(issue: Filter) -> str | None:
+    """The ``message`` of the failed check, else of its inner issue
+    (Effect's ``defaultCheckHook``)."""
+    message = _find_message(issue)
+    return message if message is not None else _find_message(issue.issue)
+
+
+def filter_message(issue: Filter, check_hook: CheckHook = default_check_hook) -> str | None:
+    """The text of a failed check: ``check_hook``'s, then for an
+    ``InvalidValue`` ``"Expected <expected>"`` from the inner issue or the
+    check."""
+    message = check_hook(issue)
+    if message is not None or not isinstance(issue.issue, InvalidValue):
+        return message
+    expected = _find_expected(issue.issue)
+    if expected is None:
+        return _expected_message(format_check(issue.filter), issue.input)
+    return _expected_message(expected, issue.issue.input)
+
+
+def format_check(check: Check[Any]) -> str:
+    """What a check expects: its ``expected`` annotation, ``<filter>``, or a
+    group's members joined by ``" & "``."""
+    expected = (check.annotations or {}).get("expected")
+    if isinstance(expected, str):
+        return expected
+    from pyfect.schema.ast import FilterGroup
+
+    if isinstance(check, FilterGroup):
+        return " & ".join(format_check(c) for c in check.checks)
+    return "<filter>"
+
+
+def _find_expected(issue: InvalidValue) -> str | None:
+    expected = (issue.annotations or {}).get("expected")
+    return expected if isinstance(expected, str) else None
+
+
+def _find_message(issue: Issue) -> str | None:
+    """The issue's own ``message`` annotation (``message_missing_key`` /
+    ``message_unexpected_key`` for those leaves)."""
+    match issue:
+        case Pointer() | Composite():
+            return None
+        case Encoding(issue=inner):
+            return _find_message(inner)
+        case Filter(filter=check):
+            annotations = check.annotations
+        case InvalidType(ast=ast) | UnexpectedKey(ast=ast) | AnyOf(ast=ast) | OneOf(ast=ast):
+            annotations = ast.annotations
+        case InvalidValue(annotations=annotations) | Forbidden(annotations=annotations):
+            pass
+        case MissingKey(annotations=annotations):
+            pass
+    key = (
+        "message_missing_key"
+        if isinstance(issue, MissingKey)
+        else "message_unexpected_key"
+        if isinstance(issue, UnexpectedKey)
+        else "message"
+    )
+    message = (annotations or {}).get(key)
+    return message if isinstance(message, str) else None
+
+
+def _expected_message(expected: str, input: Option[object]) -> str:
+    return f"Expected {expected}" if input is None else f"Expected {expected}, got {_show(input)}"
+
+
+def _show(input: Some[object]) -> str:
+    return format_unknown(input.value)
+
+
+__all__ = [
+    "AnyOf",
+    "CheckHook",
+    "Composite",
+    "Encoding",
+    "Filter",
+    "Forbidden",
+    "Formatter",
+    "InvalidType",
+    "InvalidValue",
+    "Issue",
+    "IssueAnnotations",
+    "Leaf",
+    "LeafHook",
+    "MissingKey",
+    "OneOf",
+    "Path",
+    "PathKey",
+    "Pointer",
+    "StandardFailure",
+    "StandardIssue",
+    "UnexpectedKey",
+    "default_check_hook",
+    "filter_message",
+    "format_check",
+    "format_issue",
+    "format_path",
+    "has_input",
+    "is_issue",
+    "leaf_message",
+    "make_formatter_default",
+    "make_formatter_standard_schema_v1",
+    "reported",
+]

pyfect/schema/model/__init__.py

@@ -0,0 +1,120 @@
+"""Models (Effect's ``effect/schema/Model``): one class for a table's row
+and the variants a database and a JSON API read and write::
+
+    from pyfect.schema import model as Model
+
+
+    class UserInsert(TypedDict):
+        name: str
+        created_at: NotRequired[datetime]
+
+
+    class User(Model.Class[UserInsert]):
+        id: int = Model.field(Model.GeneratedByDb(S.Int))
+        name: str
+        created_at: datetime = Model.field(Model.DateTimeInsert)
+        password: str = Model.field(Model.Sensitive(S.String))  # left out of the JSON variants
+
+
+    User  # the select variant
+    User.insert.make({"name": "Ada"})  # created_at set to now
+    User.json  # what a JSON API sends
+
+The variants are ``select``, ``insert``, ``update``, ``json``,
+``json_create`` and ``json_update``. A field annotated plainly is in every
+variant; ``Model.field(...)`` gives a variant field (``GeneratedByDb``,
+``Sensitive``, ``FieldOption``, ``DateTimeInsert``, ``field_only([...])``,
+...), whose ``select`` Type the annotation must be. A field the
+``select`` variant leaves out is assigned without an annotation.
+``pyfect.sql.model`` makes repositories of models. The variants' Types are
+the TypedDicts given as ``Model.Class``'s type arguments (see ``Class``).
+"""
+
+from pyfect.schema.model._class import Class, ModelVariants, extract, fields
+from pyfect.schema.model._dates import (
+    Date,
+    DateTimeFromDateWithNow,
+    DateTimeFromNumberWithNow,
+    DateTimeInsert,
+    DateTimeInsertFromDate,
+    DateTimeInsertFromNumber,
+    DateTimeUpdate,
+    DateTimeUpdateFromDate,
+    DateTimeUpdateFromNumber,
+    DateTimeWithNow,
+    DateWithNow,
+)
+from pyfect.schema.model._fields import (
+    BooleanSqlite,
+    FieldOption,
+    GeneratedByApp,
+    GeneratedByDb,
+    JsonFromString,
+    Sensitive,
+    optional_option,
+)
+from pyfect.schema.model._toolkit import (
+    Field,
+    NotSelected,
+    Struct,
+    Union,
+    Variant,
+    VariantsDatabase,
+    VariantsJson,
+    field_evolve,
+    field_except,
+    field_only,
+)
+from pyfect.schema.model._uuid import (
+    UuidV4BytesInsert,
+    UuidV4BytesWithGenerate,
+    UuidV4Insert,
+    UuidV4WithGenerate,
+    UuidV7Insert,
+    UuidV7WithGenerate,
+)
+from pyfect.schema.variant_schema import Overrideable, field, override
+
+__all__ = [
+    "BooleanSqlite",
+    "Class",
+    "Date",
+    "DateTimeFromDateWithNow",
+    "DateTimeFromNumberWithNow",
+    "DateTimeInsert",
+    "DateTimeInsertFromDate",
+    "DateTimeInsertFromNumber",
+    "DateTimeUpdate",
+    "DateTimeUpdateFromDate",
+    "DateTimeUpdateFromNumber",
+    "DateTimeWithNow",
+    "DateWithNow",
+    "Field",
+    "FieldOption",
+    "GeneratedByApp",
+    "GeneratedByDb",
+    "JsonFromString",
+    "ModelVariants",
+    "NotSelected",
+    "Overrideable",
+    "Sensitive",
+    "Struct",
+    "Union",
+    "UuidV4BytesInsert",
+    "UuidV4BytesWithGenerate",
+    "UuidV4Insert",
+    "UuidV4WithGenerate",
+    "UuidV7Insert",
+    "UuidV7WithGenerate",
+    "Variant",
+    "VariantsDatabase",
+    "VariantsJson",
+    "extract",
+    "field",
+    "field_evolve",
+    "field_except",
+    "field_only",
+    "fields",
+    "optional_option",
+    "override",
+]