pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_js.py

@@ -0,0 +1,263 @@
+"""JavaScript's text and number rules for ports that must give Effect's
+exact results: arithmetic that gives infinities and NaN where Python raises
+(``divide``, ``floor``, ``ceil``), and the text rules:
+``String(number)`` (``2`` not ``2.0``, ``1e+21``, ``1.5e-7``), and the
+character sets behind JavaScript's regex ``\\s`` and line terminators,
+which differ from Python's (a regex copied from Effect must spell them with
+these, not ``\\s``, ``.``, ``^`` or ``$``)."""
+
+from __future__ import annotations
+
+import codecs
+import math
+import re
+from decimal import Decimal
+
+
+def or_default[A, B](value: A | None, default: B) -> A | B:
+    """``value`` unless it is ``None``: JavaScript's ``value ?? default``.
+    Python's ``value or default`` is JavaScript's ``||`` (it replaces an
+    empty string too), so a port of ``??`` uses this."""
+    return default if value is None else value
+
+
+def js_length(text: str) -> int:
+    """``text.length``: UTF-16 code units, so a character outside the BMP
+    counts twice (Python's ``len`` counts code points). A port comparing a
+    string's length with a limit from Effect uses this."""
+    return len(text.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def js_sort_key(text: str) -> bytes:
+    """The key sorting strings as JavaScript's ``sort()`` does: by UTF-16
+    code units, not code points (``"\\U00010000"`` before ``"\\uffff"``)."""
+    return text.encode("utf-16-be", "surrogatepass")
+
+
+def to_well_formed(text: str) -> str:
+    """``String.prototype.toWellFormed``: a surrogate pair becomes its
+    character and a lone surrogate U+FFFD."""
+    try:
+        text.encode()
+    except UnicodeEncodeError:
+        return text.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "replace")
+    return text
+
+
+def text_encode(text: str) -> bytes:
+    """``TextEncoder.encode``: UTF-8 where a surrogate pair is one character
+    and a lone surrogate becomes U+FFFD (Python's ``encode`` raises)."""
+    try:
+        return text.encode()
+    except UnicodeEncodeError:
+        return to_well_formed(text).encode()
+
+
+def text_decoder(
+    encoding: str = "utf-8", *, fatal: bool = False, ignore_bom: bool = False
+) -> codecs.IncrementalDecoder:
+    """``new TextDecoder(encoding, { fatal, ignoreBOM })`` as an incremental
+    decoder: bad bytes become U+FFFD (or raise with ``fatal``), and a UTF-8
+    byte-order mark is dropped unless ``ignore_bom``, again after each
+    ``reset``."""
+    name = codecs.lookup(encoding).name
+    if name == "utf-8" and not ignore_bom:
+        name = "utf-8-sig"
+    return codecs.getincrementaldecoder(name)("strict" if fatal else "replace")
+
+
+_SHORT_INT_BITS = 3000
+"""Ints below ``2 ** 3000`` (about 900 digits) are well under Python's
+4300-digit ``str`` limit."""
+
+
+def int_text(value: int) -> str:
+    """``str(value)`` for an ``int`` of any size: JavaScript's ``BigInt``
+    prints in full, where Python's ``str`` raises past 4300 digits. The
+    digits are split in halves until each part is short."""
+    if value < 0:
+        return "-" + int_text(-value)
+    if value.bit_length() <= _SHORT_INT_BITS:
+        return str(int(value))
+    half = int(value.bit_length() * 0.30102999566398) // 2  # log10(2): digits / 2
+    high, low = divmod(value, 10**half)
+    return int_text(high) + int_text(low).rjust(half, "0")
+
+
+def js_number(value: float) -> str:
+    """``value`` as JavaScript prints it (``String(value)``): ``2`` not
+    ``2.0``, ``1e-7``, ``0`` for ``-0.0``. An ``int`` (Effect's ``bigint``)
+    prints in full, however long."""
+    if isinstance(value, int):
+        return int_text(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0.0:
+        return "0"
+    text = repr(value)  # the shortest round-tripping decimal, as JavaScript's
+    if "e" not in text:
+        # Python writes 1e-4 <= |value| < 1e16 without an exponent, as
+        # JavaScript does, but with ``.0`` on a whole number.
+        return text.removesuffix(".0")
+    sign = "-" if value < 0 else ""
+    exact = Decimal(text.removeprefix("-")).normalize().as_tuple()
+    digits = "".join(map(str, exact.digits))
+    k = len(digits)
+    n = k + int(exact.exponent)  # value = 0.digits * 10**n
+    if k <= n <= 21:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * -n + digits
+    else:
+        mantissa = digits[0] + ("." + digits[1:] if k > 1 else "")
+        body = f"{mantissa}e{'+' if n - 1 >= 0 else '-'}{abs(n - 1)}"
+    return sign + body
+
+
+def js_string(value: object) -> str:
+    """``String(value)`` for Python values: ``true`` / ``false``, ``null``
+    for ``None``, numbers as ``js_number``, a string as it is, anything else
+    ``str(value)``."""
+    match value:
+        case str():
+            return value
+        case bool():
+            return "true" if value else "false"
+        case None:
+            return "null"
+        case int() | float():
+            return js_number(value)
+        case _:
+            return str(value)
+
+
+def divide(dividend: float, divisor: float) -> float:
+    """JavaScript's ``/``: dividing by zero gives a signed infinity, or NaN
+    for ``0 / 0`` (Python raises ``ZeroDivisionError``)."""
+    if divisor != 0:
+        return dividend / divisor
+    if dividend == 0 or math.isnan(dividend):
+        return math.nan
+    return math.copysign(math.inf, dividend) * math.copysign(1.0, divisor)
+
+
+def power(base: float, exponent: float) -> float:
+    """``Math.pow`` / ``**``: a result past float range is a signed
+    infinity, ``0 ** -n`` is an infinity, ``(-8) ** 0.5`` and
+    ``1 ** Infinity`` are NaN (Python raises, returns a complex, or 1)."""
+    if math.isnan(exponent) or (abs(base) == 1 and math.isinf(exponent)):
+        return math.nan
+    odd = math.isfinite(exponent) and exponent % 2 == 1
+    sign = -1.0 if odd and math.copysign(1.0, base) < 0 else 1.0
+    try:
+        return math.pow(base, exponent)
+    except OverflowError:
+        return sign * math.inf
+    except ValueError:
+        return sign * math.inf if base == 0 else math.nan
+
+
+def floor(value: float) -> float:
+    """``Math.floor``: an infinity or NaN stays as it is (Python raises)."""
+    return float(math.floor(value)) if math.isfinite(value) else value
+
+
+def round(value: float) -> float:
+    """``Math.round``: halves go up, ``-0.5 <= x < 0`` gives ``-0``.
+    ``floor(x + 0.5)`` is not it: the sum rounds (``0.49999999999999994``
+    goes to 1, odd numbers past 2**52 to even)."""
+    if not math.isfinite(value):
+        return value
+    whole = math.floor(value)
+    rounded = whole + 1.0 if value - whole >= 0.5 else float(whole)
+    return math.copysign(rounded, value) if rounded == 0 else rounded
+
+
+def ceil(value: float) -> float:
+    """``Math.ceil``: an infinity or NaN stays as it is (Python raises)."""
+    return float(math.ceil(value)) if math.isfinite(value) else value
+
+
+SPACE = "\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+"""The characters of JavaScript's ``\\s`` (and ``String.prototype.trim``), as a
+regex class body. Python's ``\\s`` also takes ``\\x1c``-``\\x1f`` and ``\\x85``
+and misses the byte-order mark."""
+
+LINE_END = "\n\r\u2028\u2029"
+"""JavaScript's line terminators, as a regex class body: what ``.`` excludes
+and where multiline ``^`` / ``$`` match."""
+
+_TRIM = SPACE.replace("\u2000-\u200a", "".join(map(chr, range(0x2000, 0x200B))))
+
+
+def trim(text: str) -> str:
+    """``String.prototype.trim``: strips JavaScript's whitespace only."""
+    return text.strip(_TRIM)
+
+
+def trim_start(text: str) -> str:
+    """``String.prototype.trimStart``."""
+    return text.lstrip(_TRIM)
+
+
+def trim_end(text: str) -> str:
+    """``String.prototype.trimEnd``."""
+    return text.rstrip(_TRIM)
+
+
+def same_value(a: object, b: object) -> bool:
+    """JavaScript's ``Object.is``: the same object, or numbers, strings or
+    bytes of one type with one value. ``-0.0`` is not ``0.0``, NaN is NaN,
+    and ``1`` is not ``1.0`` or ``True``."""
+    if a is b:
+        return True
+    if type(a) is not type(b) or not isinstance(a, str | int | float | bytes):
+        return False
+    if isinstance(a, float) and isinstance(b, float):
+        if math.isnan(a):
+            return math.isnan(b)
+        return a == b and math.copysign(1.0, a) == math.copysign(1.0, b)
+    return a == b
+
+
+_ESCAPES = re.compile(r"(?:%[0-9A-Fa-f]{2})+")
+_URI_RESERVED = frozenset(";/?:@&=+$,#")
+
+
+def _decode_escapes(text: str, keep: frozenset[str]) -> str:
+    if "%" in _ESCAPES.sub("", text):
+        raise ValueError("URI malformed")
+
+    def run(match: re.Match[str]) -> str:
+        escaped = match.group(0)
+        data = bytes.fromhex(escaped.replace("%", ""))
+        out: list[str] = []
+        index = 0
+        while index < len(data):
+            lead = data[index]
+            width = 1 if lead < 0x80 else 2 if lead >> 5 == 6 else 3 if lead >> 4 == 14 else 4
+            try:
+                char = data[index : index + width].decode()
+            except UnicodeDecodeError as error:
+                raise ValueError("URI malformed") from error
+            out.append(escaped[index * 3 : index * 3 + 3] if char in keep else char)
+            index += width
+        return "".join(out)
+
+    return _ESCAPES.sub(run, text)
+
+
+def decode_uri_component(text: str) -> str:
+    """``decodeURIComponent``: a stray ``%`` or bad UTF-8 raises
+    ``ValueError`` (JavaScript's ``URIError``)."""
+    return _decode_escapes(text, frozenset())
+
+
+def decode_uri(text: str) -> str:
+    """``decodeURI``: as ``decode_uri_component``, but escapes of the
+    reserved characters ``;/?:@&=+$,#`` stay escaped."""
+    return _decode_escapes(text, _URI_RESERVED)

pyfect/_js_date.py

@@ -0,0 +1,87 @@
+"""Dates as JavaScript's ``Date`` reads them from the ECMAScript date-time
+string format: every Effect API that parses with ``new Date(text)`` (the
+CLI's ``Date`` primitive, ``DateTime.makeZonedFromString``) parses here,
+never with ``datetime.fromisoformat``, which takes and rejects different
+text (``tests/test_js_date_guard.py``).
+
+``YYYY``, ``YYYY-MM`` or ``YYYY-MM-DD`` (or a signed six-digit year), then
+optionally ``THH:mm``, ``:ss`` and a fraction, then ``Z`` or an offset. A
+date alone is midnight UTC; a date-time without an offset is local time.
+V8 also takes a space for ``T``, lowercase ``t`` / ``z``, ``+HHmm``
+offsets, a ``Z`` after a date alone, and any day up to 31 (``02-30`` is
+March 1st), so these are read too. Its other, implementation-defined
+formats (``Jan 15 2024``) are not.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta, timezone
+
+_FORMAT = re.compile(
+    r"(?P<year>[0-9]{4}|[+-][0-9]{6})(?:-(?P<month>[0-9]{2})(?:-(?P<day>[0-9]{2}))?)?"
+    r"(?:[Tt ](?P<hour>[0-9]{2}):(?P<minute>[0-9]{2})"
+    r"(?::(?P<second>[0-9]{2})(?:\.(?P<fraction>[0-9]+))?)?"
+    r"(?P<zone>[Zz]|[+-][0-9]{2}:?[0-9]{2})?|[Zz])?"
+)
+
+
+def _offset(zone: str) -> timezone | None:
+    """``Z`` / ``±HH:mm`` / ``±HHmm`` as a fixed offset; ``None`` when out of range."""
+    if zone in ("Z", "z"):
+        return UTC
+    digits = zone[1:].replace(":", "")
+    hours, minutes = int(digits[:2]), int(digits[2:])
+    if hours > 23 or minutes > 59:
+        return None
+    delta = timedelta(hours=hours, minutes=minutes)
+    return timezone(-delta if zone[0] == "-" else delta)
+
+
+_HAS_ZONE = re.compile(r"Z|GMT|[+-][0-9]{2}$|[+-][0-9]{2}:?[0-9]{2}$|\]$")
+_ENDS_IN_ZONE = re.compile(r"(?:z|gmt)$", re.IGNORECASE)
+
+
+def parse_input(text: str) -> datetime | None:
+    """A ``DateTime.Input`` string, as Effect's ``DateTime.makeUnsafe``
+    reads it: ``parse``, with a ``Z`` added when ``text`` names no zone,
+    so a date-time without an offset is UTC rather than local time."""
+    has_zone = _HAS_ZONE.search(text) is not None or _ENDS_IN_ZONE.search(text) is not None
+    return parse(text if has_zone else text + "Z")
+
+
+def parse(text: str) -> datetime | None:
+    """``text`` as an aware ``datetime``, or ``None`` when JavaScript's
+    ``Date`` would be invalid (or the instant, in UTC too, is outside years
+    1 to 9999, so every caller can convert it)."""
+    match = _FORMAT.fullmatch(text)
+    if match is None or match["year"] == "-000000":
+        return None
+    hour = int(match["hour"] or 0)
+    minute = int(match["minute"] or 0)
+    second = int(match["second"] or 0)
+    micro = int((match["fraction"] or "0")[:6].ljust(6, "0"))
+    end_of_day = hour == 24 and minute == second == micro == 0
+    zone = match["zone"]
+    tz = UTC if match["hour"] is None else (None if zone is None else _offset(zone))
+    if zone is not None and tz is None:
+        return None
+    day = int(match["day"] or 1)
+    if not 1 <= day <= 31:
+        return None
+    try:
+        parsed = datetime(
+            int(match["year"]),
+            int(match["month"] or 1),
+            1,
+            0 if end_of_day else hour,
+            minute,
+            second,
+            micro,
+            tzinfo=tz,
+        ) + timedelta(days=day - 1 + end_of_day)
+        aware = parsed if parsed.tzinfo is not None else parsed.astimezone()
+        aware.astimezone(UTC)
+    except (ValueError, OverflowError):
+        return None
+    return aware

pyfect/_json_text.py

@@ -0,0 +1,286 @@
+"""JSON text as Effect reads and writes it: ``JSON.parse`` and
+``JSON.stringify``.
+
+Every JSON text pyfect reads or writes goes through this module (a guard
+test bans ``json.dumps`` / ``json.loads`` elsewhere): Python's ``json``
+writes ``1.0``, ``1e-07``, ``1e+16`` and ``-0.0`` where JavaScript writes
+``1``, ``1e-7``, ``10000000000000000`` and ``0``, raises past 4300 digits,
+escapes non-ASCII by default and reads ``NaN`` / ``Infinity``. Numbers here
+are JavaScript's (``pyfect._js.js_number``), so the bytes, hashes and
+signatures of a value match Effect's.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Callable, Mapping
+from json.encoder import encode_basestring as _encode_string
+from typing import Never, cast
+
+from pyfect._js import int_text, js_number
+from pyfect._stack import with_fresh_stack
+
+type Json = bool | int | float | str | list[Json] | dict[str, Json] | None
+"""A parsed JSON value."""
+
+PARSE_ERRORS = (ValueError, RecursionError)
+"""What ``parse`` raises for text that is not JSON (``JSONDecodeError`` is a
+``ValueError``)."""
+
+STRINGIFY_ERRORS = (TypeError, ValueError, RecursionError)
+"""What ``stringify`` raises for a value with no JSON form."""
+
+
+def _reject_constant(name: str) -> Never:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def parse(text: str | bytes | bytearray) -> Json:
+    """``JSON.parse``: ``json.loads`` without the ``NaN`` / ``Infinity``
+    extensions (bytes are read as ``json.loads`` reads them). Text that is
+    not JSON raises ``ValueError``, also when it nests too deeply to decode
+    (where ``json.loads`` raises ``RecursionError``)."""
+    try:
+        value: Json = json.loads(text, parse_constant=_reject_constant)
+    except RecursionError as cause:
+        raise ValueError("JSON is nested too deeply") from cause
+    return value
+
+
+_SAFE_INTEGER = 2**53 - 1
+
+
+def whole_numbers_as_ints(value: Json) -> Json:
+    """``value`` with each whole float within the safe integers as an
+    ``int`` (``1.0`` as ``1``, ``-0.0`` as ``0``): JavaScript has one number,
+    so ``1.0`` from the wire is an integer to Effect's ``Schema.Int``."""
+    if type(value) is float:
+        return int(value) if value.is_integer() and abs(value) <= _SAFE_INTEGER else value
+    if type(value) is list:
+        return [whole_numbers_as_ints(item) for item in cast("list[Json]", value)]
+    if type(value) is dict:
+        pairs = cast("dict[str, Json]", value).items()
+        return {key: whole_numbers_as_ints(item) for key, item in pairs}
+    return value
+
+
+_LONE_SURROGATE = re.compile("[\ud800-\udfff]")
+_FLOAT_TOKEN = re.compile("[0-9][.eE]")
+
+
+def _escape_surrogate(match: re.Match[str]) -> str:
+    return f"\\u{ord(match.group()):04x}"
+
+
+def quote(text: str) -> str:
+    """``JSON.stringify(text)``: the string in double quotes, non-ASCII kept
+    as is, lone surrogates escaped (``"\\ud83d"``) so the text encodes to
+    UTF-8."""
+    encoded = _encode_string(text)
+    return encoded if text.isascii() else _LONE_SURROGATE.sub(_escape_surrogate, encoded)
+
+
+def _number(value: int | float, null_non_finite: bool = False) -> str:
+    if isinstance(value, int):
+        return int_text(value)
+    if not math.isfinite(value):
+        if null_non_finite:
+            return "null"
+        raise ValueError(f"{js_number(value)} is not JSON")
+    return js_number(value)
+
+
+def _key(key: object) -> str:
+    match key:
+        case str():
+            return key
+        case bool():
+            return "true" if key else "false"
+        case int() | float():
+            return js_number(key)
+        case None:
+            return "null"
+        case _:
+            raise TypeError(f"keys must be str, int, float, bool or None, not {type(key).__name__}")
+
+
+_STACK_CHECK = 64
+"""Containers nested between two checks of the stack (``with_fresh_stack``)."""
+
+
+class _Writer:
+    __slots__ = ("ancestors", "default", "indent", "null_non_finite", "out", "sort_keys")
+
+    def __init__(
+        self,
+        indent: str | None,
+        sort_keys: bool,
+        default: Callable[[object], object] | None,
+        null_non_finite: bool = False,
+    ) -> None:
+        self.out: list[str] = []
+        self.indent = indent
+        self.sort_keys = sort_keys
+        self.default = default
+        self.null_non_finite = null_non_finite
+        self.ancestors: set[int] = set()
+
+    def write(self, value: object, depth: int) -> None:
+        kind = type(value)
+        if kind is str:
+            self.out.append(quote(cast("str", value)))
+        elif kind is dict or kind is list or kind is tuple:
+            self._container(value, depth)
+        elif value is None:
+            self.out.append("null")
+        elif kind is bool:
+            self.out.append("true" if value else "false")
+        elif kind is int or kind is float:
+            self.out.append(_number(cast("float", value), self.null_non_finite))
+        else:
+            self._other(value, depth)
+
+    def _other(self, value: object, depth: int) -> None:
+        match value:
+            case str():
+                self.out.append(quote(value))
+            case bool():
+                self.out.append("true" if value else "false")
+            case int() | float():
+                self.out.append(_number(value, self.null_non_finite))
+            case list() | tuple() | Mapping():
+                self._container(cast("object", value), depth)
+            case _ if self.default is not None:
+                self.write(self.default(value), depth)
+            case _:
+                raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+    def _container(self, value: object, depth: int) -> None:
+        if id(value) in self.ancestors:
+            raise ValueError("Circular reference detected")
+        self.ancestors.add(id(value))
+        if depth % _STACK_CHECK == _STACK_CHECK - 1:
+            with_fresh_stack(lambda: self._items(value, depth))
+        else:
+            self._items(value, depth)
+        self.ancestors.discard(id(value))
+
+    def _items(self, value: object, depth: int) -> None:
+        out = self.out
+        indent = self.indent
+        inner = "" if indent is None else "\n" + indent * (depth + 1)
+        separator = "," + inner
+        if isinstance(value, Mapping):
+            pairs = [(_key(k), v) for k, v in cast("Mapping[object, object]", value).items()]
+            if not pairs:
+                out.append("{}")
+                return
+            if self.sort_keys:
+                pairs.sort(key=lambda pair: pair[0])
+            colon = ":" if indent is None else ": "
+            out.append("{" + inner)
+            for i, (key, item) in enumerate(pairs):
+                if i:
+                    out.append(separator)
+                out.append(quote(key) + colon)
+                self.write(item, depth + 1)
+            close = "}"
+        else:
+            items = cast("list[object] | tuple[object, ...]", value)
+            if not items:
+                out.append("[]")
+                return
+            out.append("[" + inner)
+            for i, item in enumerate(items):
+                if i:
+                    out.append(separator)
+                self.write(item, depth + 1)
+            close = "]"
+        out.append(close if indent is None else "\n" + indent * depth + close)
+
+
+def stringify(
+    value: object,
+    *,
+    indent: int | str | None = None,
+    sort_keys: bool = False,
+    default: Callable[[object], object] | None = None,
+    null_non_finite: bool = False,
+) -> str:
+    """``JSON.stringify(value, null, indent)``: compact unless ``indent`` (a
+    number of spaces, at most 10, or the text itself, as JavaScript's
+    ``space``), numbers as JavaScript writes them, ints in full, non-ASCII
+    kept and lone surrogates escaped; keys sorted when ``sort_keys``; any
+    other object written as ``default`` of it (when given).
+    ``NaN`` and infinities raise ``ValueError``, or are written ``null`` as
+    JavaScript writes them when ``null_non_finite``; a value with no JSON
+    form raises ``TypeError``, a cycle ``ValueError``."""
+    space = (" " * min(indent, 10) if isinstance(indent, int) else (indent or "")[:10]) or None
+
+    # Python's own encoder writes what JavaScript writes, but for floats
+    # (every float it writes has a digit before ``.`` or ``e``), ints past
+    # 4300 digits and mappings that are not dicts: those take a second try
+    # with floats it writes as JavaScript does, then the writer.
+    def dumps(value: object) -> str:
+        return json.dumps(
+            value,
+            ensure_ascii=False,
+            allow_nan=False,
+            indent=space,
+            separators=(",", ":" if space is None else ": "),
+            sort_keys=sort_keys,
+            default=default,
+        )
+
+    try:
+        text = dumps(value)
+        if _FLOAT_TOKEN.search(text) is not None:
+            text = dumps(_plain(value))
+    except (*STRINGIFY_ERRORS, _NeedsWriter):
+        writer = _Writer(space, sort_keys, default, null_non_finite)
+        writer.write(value, 0)
+        return "".join(writer.out)
+    return text if text.isascii() else _LONE_SURROGATE.sub(_escape_surrogate, text)
+
+
+def js_stringify(value: object) -> str:
+    """Exactly ``JSON.stringify(value)``: ``stringify`` with ``NaN`` and the
+    infinities written ``null``. For JSON sent where Effect sends
+    ``JSON.stringify``'s text (request bodies, protocol frames)."""
+    return stringify(value, null_non_finite=True)
+
+
+class _NeedsWriter(Exception):
+    """A value ``json.dumps`` would not write as JavaScript does."""
+
+
+def _plain(value: object) -> object:
+    """``value`` with each float ``json.dumps`` writes as JavaScript does:
+    whole ones below ``1e16`` as ints (``2``, ``0`` for ``-0.0``), others
+    from ``1e-4`` to ``1e16`` as they are (``repr`` matches JavaScript there);
+    anything else raises ``_NeedsWriter``."""
+    kind = type(value)
+    if kind is float:
+        number = cast("float", value)
+        if number.is_integer():
+            if -1e16 < number < 1e16:
+                return int(number)
+        elif 1e-4 <= abs(number) < 1e16:
+            return number
+        raise _NeedsWriter
+    if kind is dict:
+        pairs = cast("dict[object, object]", value).items()
+        return {k if type(k) is str else _plain_key(k): _plain(x) for k, x in pairs}
+    if kind is list or kind is tuple:
+        return [_plain(x) for x in cast("list[object]", value)]
+    if kind is str or kind is int or kind is bool or value is None:
+        return value
+    raise _NeedsWriter
+
+
+def _plain_key(key: object) -> str:
+    if type(key) is float:
+        raise _NeedsWriter
+    return _key(key)

pyfect/_json_value.py

@@ -0,0 +1,9 @@
+"""The JSON value type shared by the schema, JSON Patch and JSON Schema
+modules."""
+
+from collections.abc import Mapping, Sequence
+
+type JsonValue = bool | int | float | str | Sequence[JsonValue] | Mapping[str, JsonValue] | None
+"""A JSON value (Effect's ``Json`` type): a list or tuple for an array, a
+string-keyed mapping for an object. ``pyfect.encoding.Json`` (what
+``json.loads`` returns) is one."""