pyfect-dev 0.1.0__py3-none-any.whl

pyfect/encoding/base64_url.py

@@ -0,0 +1,19 @@
+"""Base64 with the URL-safe alphabet (Effect's ``encoding/Base64Url``):
+``encode`` leaves the padding out, ``encode_padded`` keeps it, ``decode``
+takes either and returns a ``Result``."""
+
+from __future__ import annotations
+
+from pyfect._binary_codecs import EncodingError, utf8_text
+from pyfect._binary_codecs import base64_url_decode as decode
+from pyfect._binary_codecs import base64_url_encode as encode
+from pyfect._binary_codecs import base64_url_encode_padded as encode_padded
+from pyfect.result import Result
+
+
+def decode_string(text: str) -> Result[str, EncodingError]:
+    """``decode``, then the bytes as UTF-8 (bad bytes replaced)."""
+    return decode(text).map(utf8_text)
+
+
+__all__ = ["decode", "decode_string", "encode", "encode_padded"]

pyfect/encoding/encoding_error.py

@@ -0,0 +1,17 @@
+"""The error of the binary encodings (Effect's ``encoding/EncodingError``)."""
+
+from __future__ import annotations
+
+from typing import TypeIs
+
+from pyfect._binary_codecs import EncodingError
+from pyfect._public import publish
+
+
+def is_encoding_error(value: object) -> TypeIs[EncodingError]:
+    return isinstance(value, EncodingError)
+
+
+__all__ = ["EncodingError", "is_encoding_error"]
+
+publish(globals())

pyfect/encoding/hex.py

@@ -0,0 +1,28 @@
+"""Hexadecimal text (Effect's ``encoding/Hex``): ``encode`` writes lowercase,
+``decode`` reads either case and returns a ``Result``, ``random`` makes
+random lowercase hex (not cryptographically secure: use ``Crypto`` for
+secrets)."""
+
+from __future__ import annotations
+
+import random as random_
+
+from pyfect._binary_codecs import EncodingError, utf8_text
+from pyfect._binary_codecs import hex_decode as decode
+from pyfect._binary_codecs import hex_encode as encode
+from pyfect.result import Result
+
+
+def decode_string(text: str) -> Result[str, EncodingError]:
+    """``decode``, then the bytes as UTF-8 (bad bytes replaced)."""
+    return decode(text).map(utf8_text)
+
+
+def random(length: int) -> str:
+    """``length`` random hex digits, rounded down to a multiple of 8;
+    ``length`` is taken modulo ``2**32`` as Effect's ``length >>> 3``."""
+    words = (length % 2**32) >> 3
+    return "".join(f"{random_.getrandbits(32):08x}" for _ in range(words))
+
+
+__all__ = ["decode", "decode_string", "encode", "random"]

pyfect/encoding/ini.py

@@ -0,0 +1,188 @@
+"""INI text to nested dicts (Effect's ``encoding/Ini``, adapted from the
+``ini`` 7.0.0 package).
+
+``[a.b]`` sections nest (``\\.`` keeps a literal dot), ``key[]`` collects
+values into a list, a key without ``=`` is ``True``, and the values
+``true`` / ``false`` / ``null`` become ``True`` / ``False`` / ``None``.
+Quoted values are read as JSON strings when they parse; ``;`` and ``#``
+start a comment in an unquoted value unless escaped."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, cast
+
+from pyfect import _json_text
+from pyfect._js import LINE_END, SPACE, js_string
+from pyfect._js import trim as js_trim
+
+# JavaScript's ``\s`` and ``trim``, not Python's (U+FEFF is space, U+001C is not).
+_SECTION = re.compile(f"\\[([^\\]]*)\\][{SPACE}]*")
+_PROPERTY = re.compile(f"([^=]+)(=([^{LINE_END}]*))?")
+_LINES = re.compile(r"[\r\n]+")
+_BLANK_OR_COMMENT = re.compile(f"[{SPACE}]*(?:[;#]|$)")
+_PROTO = "__proto__"
+
+
+def _split_sections(value: str) -> list[str]:
+    sections: list[str] = []
+    start = 0
+    index = value.find(".")
+    while index != -1:
+        if index == 0 or value[index - 1] != "\\":
+            sections.append(value[start:index])
+            start = index + 1
+        index = value.find(".", index + 1)
+    sections.append(value[start:])
+    return sections
+
+
+def _key(value: object) -> str:
+    """A parsed key as JavaScript's ``String`` writes it."""
+    return js_string(value) if isinstance(value, str | bool | int | float | None) else str(value)
+
+
+def _is_quoted(value: str) -> bool:
+    return len(value) >= 2 and (
+        (value.startswith('"') and value.endswith('"'))
+        or (value.startswith("'") and value.endswith("'"))
+    )
+
+
+def _unquote(text: str | None) -> object:
+    """The value of ``text``: a quoted one read as JSON when it parses (so
+    ``'5'`` is ``5``, as in Effect), an unquoted one up to its comment."""
+    value = js_trim(text or "")
+    if _is_quoted(value):
+        if value[0] == "'":
+            value = value[1:-1]
+        try:
+            return _json_text.parse(value)
+        except _json_text.PARSE_ERRORS:
+            return value
+    escaped = False
+    output = ""
+    for character in value:
+        if escaped:
+            output += character if character in ";#\\" else f"\\{character}"
+            escaped = False
+        elif character in ";#":
+            break
+        elif character == "\\":
+            escaped = True
+        else:
+            output += character
+    if escaped:
+        output += "\\"
+    return js_trim(output)
+
+
+_LITERALS: dict[str, object] = {"true": True, "false": False, "null": None}
+
+
+def parse(text: str) -> dict[str, Any]:
+    """The sections and properties of ``text``."""
+    return _nest_sections(_parse_lines(text))
+
+
+def _parse_lines(text: str) -> dict[str, Any]:
+    output: dict[str, Any] = {}
+    current = output
+    for line in _LINES.split(text):
+        if len(line) == 0 or _BLANK_OR_COMMENT.match(line):
+            continue
+        section_match = _SECTION.fullmatch(line)
+        if section_match is not None:
+            current = _section(output, _key(_unquote(section_match.group(1))))
+            continue
+        property_match = _PROPERTY.fullmatch(line)
+        if property_match is None:
+            continue
+        raw_key = _key(_unquote(property_match.group(1)))
+        is_list = len(raw_key) > 2 and raw_key.endswith("[]")
+        key = raw_key[:-2] if is_list else raw_key
+        if key == _PROTO:
+            continue
+        raw_value: object = (
+            True if property_match.group(2) is None else _unquote(property_match.group(3))
+        )
+        value = (
+            _LITERALS[raw_value]
+            if isinstance(raw_value, str) and raw_value in _LITERALS
+            else raw_value
+        )
+        if is_list:
+            if key not in current:
+                current[key] = []
+            elif not isinstance(current[key], list):
+                current[key] = [current[key]]
+        existing = current.get(key)
+        if isinstance(existing, list):
+            cast("list[object]", existing).append(value)
+        else:
+            current[key] = value
+    return output
+
+
+class _ValueSection(dict[str, Any]):
+    """A ``[section]`` over a plain value: JavaScript keeps the value and
+    throws only when a property is set on it."""
+
+    def __init__(self, value: object) -> None:
+        super().__init__()
+        self._value = value
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        kind = (
+            "boolean"
+            if isinstance(self._value, bool)
+            else "string"
+            if isinstance(self._value, str)
+            else "number"
+        )
+        raise TypeError(f"Cannot create property '{key}' on {kind} '{js_string(self._value)}'")
+
+
+def _section(output: dict[str, Any], section: str) -> dict[str, Any]:
+    """Where a ``[section]``'s properties go (Effect's
+    ``output[section] ??= {}``): a fresh mapping for ``null`` or a new name,
+    a throwaway one for ``__proto__`` or a list (JavaScript sets them as
+    properties the array does not show); setting a property in a section
+    over any other value raises ``ValueError`` (JavaScript's ``TypeError``)."""
+    existing = output.get(section)
+    if section == _PROTO or isinstance(existing, list):
+        return {}
+    if existing is None:
+        output[section] = {}
+        return cast("dict[str, Any]", output[section])
+    if not isinstance(existing, dict):
+        return _ValueSection(existing)
+    return cast("dict[str, Any]", existing)
+
+
+def _nest_sections(output: dict[str, Any]) -> dict[str, Any]:
+    """Moves each dotted section (``[a.b]``) under its parents."""
+    remove: list[str] = []
+    for section in list(output):
+        if not isinstance(output[section], dict):
+            continue
+        parts = _split_sections(section)
+        last = parts.pop()
+        key = last.replace("\\.", ".")
+        current = output
+        for part in parts:
+            if part == _PROTO:
+                continue
+            if not isinstance(current.get(part), dict):
+                current[part] = {}
+            current = cast("dict[str, Any]", current[part])
+        if current is output and key == last:
+            continue
+        current[key] = output[section]
+        remove.append(section)
+    for section in remove:
+        del output[section]
+    return output
+
+
+__all__ = ["parse"]

pyfect/encoding/json_array.py

@@ -0,0 +1,246 @@
+"""One JSON array as a stream of its elements (Effect's
+``encoding/JsonArray``).
+
+Use it when a large response or file is one JSON document, such as
+``[...]`` or ``{"items": [...], "total": n}``, and its elements should be
+handled without holding the whole document; use ``ndjson`` when the
+producer writes one value per line. The decoders write the elements of
+one array, the root by default or the one an RFC 6901 JSON Pointer
+selects; each element is held only until it is complete. The rest of the
+document is checked and dropped. The encoders write a stream of values as
+one array::
+
+    users = body.pipe_through_channel(json_array.decode(pointer="/data"))
+
+The schema variants (``decode_schema``, ``decode_schema_string``,
+``encode_schema``, ``encode_schema_string``) decode each element with a
+schema, or encode each value before writing it, failing with
+``SchemaError``.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, Unpack
+
+from pyfect import channel_schema
+from pyfect._js import text_encode
+from pyfect._json_text import STRINGIFY_ERRORS, Json, stringify
+from pyfect._primitives import _FailCause, _Succeed, _Suspend, _Sync
+from pyfect._public import publish
+from pyfect.cause import Cause
+from pyfect.cause import fail as fail_cause
+from pyfect.channel import Channel, decode_text, from_transform
+from pyfect.channel._base import AnyPull, end_with
+from pyfect.encoding._json_array_scanner import Config, JsonArrayError, Scanner, make_config
+from pyfect.pull import match_effect
+from pyfect.schema import Codec, ParseOptions, SchemaError
+
+__all__ = [
+    "DEFAULT_MAX_DEPTH",
+    "DEFAULT_MAX_ELEMENT_SIZE",
+    "JsonArrayError",
+    "decode",
+    "decode_schema",
+    "decode_schema_string",
+    "decode_string",
+    "encode",
+    "encode_schema",
+    "encode_schema_string",
+    "encode_string",
+]
+
+DEFAULT_MAX_DEPTH = 1000
+DEFAULT_MAX_ELEMENT_SIZE = 16 * 1024 * 1024
+
+
+def _failed(cause: Cause[Any]) -> AnyPull:
+    return _FailCause(cause)
+
+
+def _decode_pull(upstream: AnyPull, config: Config) -> AnyPull:
+    scanner = Scanner(config)
+    ended: AnyPull | None = None
+
+    def emit(run: Callable[[list[Json]], None]) -> AnyPull:
+        out: list[Json] = []
+        try:
+            run(out)
+        except JsonArrayError as error:
+            return _FailCause(fail_cause(error))
+        return _Succeed(tuple(out)) if out else pull
+
+    def written(texts: tuple[str, ...]) -> AnyPull:
+        def run(out: list[Json]) -> None:
+            for text in texts:
+                scanner.feed(text, out)
+
+        return emit(run)
+
+    def done(leftover: object) -> AnyPull:
+        nonlocal ended
+        ended = end_with(leftover)
+        return emit(lambda _out: scanner.end())
+
+    def next_pull() -> AnyPull:
+        if ended is not None:
+            return ended
+        return match_effect(upstream, on_success=written, on_failure=_failed, on_done=done)
+
+    pull: AnyPull = _Suspend(next_pull)
+    return pull
+
+
+def decode_string[E = Never, D = None](
+    *,
+    pointer: str = "",
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    max_element_size: float = DEFAULT_MAX_ELEMENT_SIZE,
+) -> Channel[tuple[Json, ...], E | JsonArrayError, D, tuple[str, ...], E, D]:
+    """Parse the text of one JSON document and write the elements of the
+    array ``pointer`` selects (``""``: the root), one chunk per input chunk
+    that completes any. A leading byte-order mark is dropped.
+
+    ``max_depth`` bounds the nesting of one value (an element that is an
+    array or object has depth 1); ``max_element_size`` the characters of
+    one value (``math.inf``: unbounded). Both apply to the values outside
+    the array too. Bad options raise ``ValueError`` here.
+
+    The document is checked as it streams, so elements of earlier chunks
+    may be written before a later error fails the channel (the failing
+    chunk's are not). The pointer follows the first occurrence of a key,
+    where ``json.loads`` keeps the last; a repeated followed key is a
+    ``"Pointer"`` error."""
+    config = make_config(pointer, max_depth, max_element_size)
+    channel: Channel[tuple[Json, ...], E | JsonArrayError, D, tuple[str, ...], E, D] = (
+        from_transform(lambda upstream, _scope: _Sync(lambda: _decode_pull(upstream, config)))
+    )
+    return channel
+
+
+def decode[E = Never, D = None](
+    *,
+    pointer: str = "",
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    max_element_size: float = DEFAULT_MAX_ELEMENT_SIZE,
+) -> Channel[tuple[Json, ...], E | JsonArrayError, D, tuple[bytes, ...], E, D]:
+    """``decode_string`` of UTF-8 bytes. A character may span chunks;
+    invalid UTF-8 becomes U+FFFD."""
+    text: Channel[tuple[str, ...], E, D, tuple[bytes, ...], E, D] = decode_text(ignore_bom=True)
+    elements: Channel[tuple[Json, ...], E | JsonArrayError, D, tuple[str, ...], E, D] = (
+        decode_string(pointer=pointer, max_depth=max_depth, max_element_size=max_element_size)
+    )
+    return text.pipe_to(elements)
+
+
+def _stringify(value: object) -> str:
+    try:
+        return stringify(value)
+    except STRINGIFY_ERRORS as cause:
+        raise JsonArrayError("Encode", str(cause), cause=cause) from cause
+
+
+def encode_string[E = Never, D = None]() -> Channel[
+    tuple[str, ...], E | JsonArrayError, D, tuple[object, ...], E, D
+]:
+    """Write a stream of values as the text of one JSON array, one string
+    per input chunk; no values give ``"[]"``. A value with no JSON form (a
+    set, an object, ``NaN``) fails with an ``"Encode"`` error after the
+    text before it is written."""
+
+    def build(upstream: AnyPull) -> AnyPull:
+        started = False
+        ended: AnyPull | None = None
+
+        def written(values: tuple[object, ...]) -> AnyPull:
+            nonlocal started
+            try:
+                text = ("," if started else "[") + ",".join(map(_stringify, values))
+            except JsonArrayError as error:
+                return _FailCause(fail_cause(error))
+            started = True
+            return _Succeed((text,))
+
+        def done(leftover: object) -> AnyPull:
+            nonlocal ended
+            ended = end_with(leftover)
+            return _Succeed(("]" if started else "[]",))
+
+        def next_pull() -> AnyPull:
+            if ended is not None:
+                return ended
+            return match_effect(upstream, on_success=written, on_failure=_failed, on_done=done)
+
+        return _Suspend(next_pull)
+
+    channel: Channel[tuple[str, ...], E | JsonArrayError, D, tuple[object, ...], E, D] = (
+        from_transform(lambda upstream, _scope: _Sync(lambda: build(upstream)))
+    )
+    return channel
+
+
+def encode[E = Never, D = None]() -> Channel[
+    tuple[bytes, ...], E | JsonArrayError, D, tuple[object, ...], E, D
+]:
+    """``encode_string`` as UTF-8 bytes."""
+    strings: Channel[tuple[str, ...], E | JsonArrayError, D, tuple[object, ...], E, D] = (
+        encode_string()
+    )
+    return strings.map(lambda chunk: tuple(text_encode(text) for text in chunk))
+
+
+# --- schemas ----------------------------------------------------------------------
+
+type _AnyChannel = Channel[Any, Any, Any, Any, Any, Any, Any]
+
+
+def decode_schema_string[T, RD, E = Never, D = None](
+    schema: Codec[T, object, RD, object],
+    /,
+    *,
+    pointer: str = "",
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    max_element_size: float = DEFAULT_MAX_ELEMENT_SIZE,
+    **options: Unpack[ParseOptions],
+) -> Channel[tuple[T, ...], E | JsonArrayError | SchemaError, D, tuple[str, ...], E, D, RD]:
+    """``decode_string``, each element then decoded with ``schema``."""
+    elements: _AnyChannel = decode_string(
+        pointer=pointer, max_depth=max_depth, max_element_size=max_element_size
+    )
+    return elements.pipe_to(channel_schema.decode_unknown(schema, **options))
+
+
+def decode_schema[T, RD, E = Never, D = None](
+    schema: Codec[T, object, RD, object],
+    /,
+    *,
+    pointer: str = "",
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    max_element_size: float = DEFAULT_MAX_ELEMENT_SIZE,
+    **options: Unpack[ParseOptions],
+) -> Channel[tuple[T, ...], E | JsonArrayError | SchemaError, D, tuple[bytes, ...], E, D, RD]:
+    """``decode``, each element then decoded with ``schema``."""
+    elements: _AnyChannel = decode(
+        pointer=pointer, max_depth=max_depth, max_element_size=max_element_size
+    )
+    return elements.pipe_to(channel_schema.decode_unknown(schema, **options))
+
+
+def encode_schema_string[T, I, RE, E = Never, D = None](
+    schema: Codec[T, I, object, RE], /
+) -> Channel[tuple[str, ...], E | JsonArrayError | SchemaError, D, tuple[T, ...], E, D, RE]:
+    """``encode_string`` of each value encoded with ``schema`` first."""
+    encoded: _AnyChannel = channel_schema.encode(schema)
+    return encoded.pipe_to(encode_string())
+
+
+def encode_schema[T, I, RE, E = Never, D = None](
+    schema: Codec[T, I, object, RE], /
+) -> Channel[tuple[bytes, ...], E | JsonArrayError | SchemaError, D, tuple[T, ...], E, D, RE]:
+    """``encode`` of each value encoded with ``schema`` first."""
+    encoded: _AnyChannel = channel_schema.encode(schema)
+    return encoded.pipe_to(encode())
+
+
+publish(globals())