pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/_decimal_regexp.py

@@ -0,0 +1,243 @@
+"""``BigDecimal`` and ``RegExp`` declarations (Effect's), with the
+``BigDecimal`` order checks.
+
+A ``BigDecimal`` is a ``pyfect.big_decimal.BigDecimal``, written in JSON as
+its text. A ``RegExp`` is a compiled ``re.Pattern[str]``, written in JSON as
+``{"source": ..., "flags": ...}`` with JavaScript's flag letters: Python
+patterns carry ``i``, ``m`` and ``s`` (``re.IGNORECASE``, ``re.MULTILINE``,
+``re.DOTALL``); other letters, or a source Python cannot compile, are
+``Expected valid RegExp source and flags``, and a pattern with other flags
+(``re.VERBOSE``, ``re.ASCII``) cannot be encoded.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import TypedDict, TypeIs, cast
+
+from pyfect import big_decimal as bd
+from pyfect.exit import Exit, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.schema import ast
+from pyfect.schema import transformation as T
+from pyfect.schema._arbitrary_constraint import ArbitraryConstraint
+from pyfect.schema._checks_order import (
+    Annotate,
+    Between,
+    Bound,
+    make_is_between,
+    make_is_greater_than,
+    make_is_greater_than_or_equal_to,
+    make_is_less_than,
+    make_is_less_than_or_equal_to,
+)
+from pyfect.schema._codec_links import link
+from pyfect.schema._declare import declare
+from pyfect.schema._options import ParseOptions
+from pyfect.schema._primitives import String
+from pyfect.schema._schema import Bottom
+from pyfect.schema._struct import Struct
+from pyfect.schema._transform import DecodeToSchema, decode_to
+from pyfect.schema._value_codecs import string_codec
+from pyfect.schema.issue import InvalidValue, Issue, reported
+
+
+def _format(value: bd.BigDecimal) -> str:
+    return value.format()
+
+
+def _is_big_decimal(value: object) -> TypeIs[bd.BigDecimal]:
+    return isinstance(value, bd.BigDecimal)
+
+
+def _formatter(_: tuple[object, ...]) -> object:
+    return _format
+
+
+BigDecimal: Bottom[bd.BigDecimal] = declare(
+    _is_big_decimal,
+    expected="BigDecimal",
+    representation={"id": "effect/schema/BigDecimal", "payload": None},
+    to_codec_json=string_codec(T.big_decimal_from_string),
+    to_formatter=_formatter,
+)
+"""A ``big_decimal.BigDecimal`` (Effect's ``BigDecimal``)."""
+BigDecimalFromString: DecodeToSchema[bd.BigDecimal, str] = String.annotate(
+    expected="a string that will be decoded as a BigDecimal"
+).pipe(decode_to(BigDecimal, T.big_decimal_from_string))
+"""A ``BigDecimal`` read from its text (Effect's ``BigDecimalFromString``)."""
+
+
+def _bounded(constraint: ArbitraryConstraint) -> Mapping[str, object]:
+    """The bounds ``to_strategy`` builds ``BigDecimal`` values within."""
+    return {"arbitrary_constraint": constraint}
+
+
+def _above(exclusive: bool) -> Annotate[bd.BigDecimal]:
+    return lambda bound: _bounded(ArbitraryConstraint(minimum=bound, exclusive_minimum=exclusive))
+
+
+def _below(exclusive: bool) -> Annotate[bd.BigDecimal]:
+    return lambda bound: _bounded(ArbitraryConstraint(maximum=bound, exclusive_maximum=exclusive))
+
+
+def _within(
+    minimum: bd.BigDecimal, maximum: bd.BigDecimal, exclusive_minimum: bool, exclusive_maximum: bool
+) -> Mapping[str, object]:
+    constraint = ArbitraryConstraint(
+        minimum=minimum,
+        exclusive_minimum=exclusive_minimum,
+        maximum=maximum,
+        exclusive_maximum=exclusive_maximum,
+    )
+    return _bounded(constraint)
+
+
+is_greater_than_big_decimal: Bound[bd.BigDecimal] = make_is_greater_than(
+    formatter=_format, annotate=_above(True)
+)
+is_greater_than_or_equal_to_big_decimal: Bound[bd.BigDecimal] = make_is_greater_than_or_equal_to(
+    formatter=_format, annotate=_above(False)
+)
+is_less_than_big_decimal: Bound[bd.BigDecimal] = make_is_less_than(
+    formatter=_format, annotate=_below(True)
+)
+is_less_than_or_equal_to_big_decimal: Bound[bd.BigDecimal] = make_is_less_than_or_equal_to(
+    formatter=_format, annotate=_below(False)
+)
+is_between_big_decimal: Between[bd.BigDecimal] = make_is_between(
+    formatter=_format, annotate=_within
+)
+
+# ------------------------------------------------------------------- RegExp
+
+_FLAGS = (("i", re.IGNORECASE), ("m", re.MULTILINE), ("s", re.DOTALL))
+"""JavaScript's flag letters Python patterns carry, in JavaScript's order."""
+_VALID_FLAGS = re.compile(r"(?!.*(.).*\1)[ims]*")
+_WRITTEN_FLAGS = re.IGNORECASE | re.MULTILINE | re.DOTALL | re.UNICODE
+"""The flags ``{source, flags}`` carries (``re.UNICODE`` is every ``str`` pattern's)."""
+
+
+def _is_pattern(value: object) -> TypeIs[re.Pattern[str]]:
+    if not isinstance(value, re.Pattern):
+        return False
+    pattern = cast("re.Pattern[str] | re.Pattern[bytes]", value)
+    return isinstance(pattern.pattern, str)
+
+
+def flags_of(pattern: re.Pattern[str]) -> str:
+    """``pattern``'s flags as JavaScript's letters (``RegExp.flags``)."""
+    return "".join(letter for letter, flag in _FLAGS if pattern.flags & flag)
+
+
+def _compile(source: str, flags: str) -> re.Pattern[str] | None:
+    known = dict(_FLAGS)
+    # Each known letter at most once, as JavaScript's ``RegExp`` requires.
+    if _VALID_FLAGS.fullmatch(flags) is None:
+        return None
+    value = 0
+    for letter in flags:
+        value |= known[letter]
+    try:
+        return re.compile(source, value)
+    except re.error:
+        return None
+
+
+def _decode(input: RegExpJson, options: ParseOptions) -> Exit[re.Pattern[str], Issue]:
+    pattern = _compile(input["source"], input["flags"])
+    if pattern is None:
+        shown = reported(input, options)
+        return fail_exit(InvalidValue({"expected": "valid RegExp source and flags"}, shown))
+    return Success(pattern)
+
+
+def _encode(pattern: re.Pattern[str], options: ParseOptions) -> Exit[RegExpJson, Issue]:
+    if pattern.flags & ~_WRITTEN_FLAGS:
+        expected = "a pattern whose flags are among i, m and s"
+        return fail_exit(InvalidValue({"expected": expected}, reported(pattern, options)))
+    return Success(RegExpJson(source=pattern.pattern, flags=flags_of(pattern)))
+
+
+class RegExpJson(TypedDict):
+    """A ``RegExp`` in JSON."""
+
+    source: str
+    flags: str
+
+
+_REG_EXP_JSON = Struct(RegExpJson).ast
+
+
+def _reg_exp_codec(_: tuple[ast.AST, ...]) -> ast.Link:
+    return ast.Link(_REG_EXP_JSON, T.transform_effect(decode=_decode, encode=_encode))
+
+
+def _format_reg_exp(pattern: re.Pattern[str]) -> str:
+    return f"/{pattern.pattern}/{flags_of(pattern)}"
+
+
+def _reg_exp_formatter(_: tuple[object, ...]) -> object:
+    return _format_reg_exp
+
+
+def _same_reg_exp(a: re.Pattern[str], b: re.Pattern[str]) -> bool:
+    return a.pattern == b.pattern and a.flags == b.flags
+
+
+def _reg_exp_equivalence(_: tuple[object, ...]) -> object:
+    return _same_reg_exp
+
+
+_SOURCES = (
+    "",
+    ".",
+    ".*",
+    "\\d+",
+    "\\w+",
+    "[a-z]+",
+    "[A-Z]+",
+    "[0-9]+",
+    "^[a-zA-Z0-9]+$",
+    "^\\d{4}-\\d{2}-\\d{2}$",
+)
+"""Effect's generated sources."""
+_DRAWN_REG_EXP = ast.Objects(
+    (
+        ast.PropertySignature("source", ast.Union(tuple(map(ast.Literal, _SOURCES)))),
+        *(ast.PropertySignature(letter, ast.boolean) for letter, _ in _FLAGS),
+    )
+)
+
+
+def _drawn_pattern(drawn: Mapping[str, object]) -> re.Pattern[str]:
+    flags = 0
+    for letter, flag in _FLAGS:
+        if drawn[letter]:
+            flags |= flag
+    return re.compile(cast("str", drawn["source"]), flags)
+
+
+def _drawn_parts(pattern: re.Pattern[str]) -> Mapping[str, object]:
+    return {
+        "source": pattern.pattern,
+        **{letter: bool(pattern.flags & flag) for letter, flag in _FLAGS},
+    }
+
+
+def _reg_exp_arbitrary(_: tuple[ast.AST, ...], __: ArbitraryConstraint) -> ast.Link:
+    """Effect's: a source of a few shapes and each flag on or off."""
+    return link(_DRAWN_REG_EXP, decode=_drawn_pattern, encode=_drawn_parts)
+
+
+RegExp: Bottom[re.Pattern[str]] = declare(
+    _is_pattern,
+    expected="RegExp",
+    representation={"id": "effect/schema/RegExp", "payload": None},
+    to_codec_arbitrary=_reg_exp_arbitrary,
+    to_codec_json=_reg_exp_codec,
+    to_formatter=_reg_exp_formatter,
+    to_equivalence=_reg_exp_equivalence,
+)
+"""A compiled ``re.Pattern[str]`` (Effect's ``RegExp``)."""

pyfect/schema/_declare.py

@@ -0,0 +1,68 @@
+"""Declared schemas: values a guard or a parser accepts (Effect's
+``declare``, ``declareConstructor`` and ``instanceOf``)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, Never, TypeIs
+
+from pyfect._core import Effect
+from pyfect.exit import Exit, Success
+from pyfect.schema import ast
+from pyfect.schema._options import ParseOptions
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema.issue import Issue
+
+type Parse[T = object] = Callable[
+    [object, ast.Declaration, ParseOptions], Exit[T, Issue] | Effect[T, Issue, Any]
+]
+"""A declaration's parser: the input, the declaration (for its issues) and
+the parse options. It gives an ``Exit``, or an ``Effect`` when a part's
+parse is one (``ast.then`` / ``ast.map_value`` keep either)."""
+
+
+def declare[T](guard: Callable[[object], TypeIs[T]], /, **annotations: object) -> Bottom[T]:
+    """The values ``guard`` accepts, unchanged (Effect's ``declare``);
+    anything else is ``Expected <expected>``, the ``expected`` annotation
+    (default ``<Declaration>``)."""
+
+    def run(_: tuple[ast.AST, ...]) -> Parse:
+        def parse(
+            input: object, node: ast.Declaration, options: ParseOptions
+        ) -> Exit[object, Issue]:
+            return Success(input) if guard(input) else ast.invalid_type(node, input, options)
+
+        return parse
+
+    return Bottom(ast.Declaration((), run, annotations=annotations or None))
+
+
+def instance_of[T](cls: type[T], /, **annotations: object) -> Bottom[T]:
+    """Instances of ``cls`` (Effect's ``instanceOf``), expected as the class
+    name unless annotated."""
+
+    def guard(input: object) -> TypeIs[T]:
+        return isinstance(input, cls)
+
+    return declare(guard, **{"expected": cls.__name__, **annotations})
+
+
+def declare_constructor[T, RD, RE](
+    type_parameters: Sequence[Codec[Any, Any, RD, RE]],
+    run: Callable[[tuple[Bottom[Any, Any, Never, Never], ...]], Parse[T]],
+    /,
+    **annotations: object,
+) -> Bottom[T, Any, RD, RE]:
+    """A schema of a container of ``type_parameters``' values (Effect's
+    ``declareConstructor``). ``run`` gets the type parameters' schemas
+    (flipped when encoding) and returns the parser; it parses a part with
+    ``schema.ast.parse(part, options)`` and reports its issue with
+    ``ast.parse_at_key``. The Type is what the parser returns; write the
+    Encoded type out (Python cannot compute it from the type parameters):
+    ``boxes: S.Bottom[Box[int], Box[str]] = S.declare_constructor(...)``."""
+
+    def make_parser(nodes: tuple[ast.AST, ...]) -> Parse[T]:
+        return run(tuple(Bottom(node) for node in nodes))
+
+    nodes = tuple(p.__codec__().ast for p in type_parameters)
+    return Bottom(ast.Declaration(nodes, make_parser, annotations=annotations or None))

pyfect/schema/_derive.py

@@ -0,0 +1,292 @@
+"""The schema an annotation stands for, used by ``Struct`` and the schema
+classes: ``str`` String, ``int`` Int, ``float`` Number, ``bool`` Boolean,
+``None`` Null, ``object`` Unknown, ``Any`` Any, ``Literal[x]`` Literal, ``Literal[x, y]`` Literals,
+``X | Y`` Union, an ``Enum`` Enum, a ``TypedDict`` Struct, ``dict[K, V]`` /
+``Mapping[K, V]`` Record, ``list[X]`` List, ``tuple[X, ...]`` /
+``Sequence[X]`` Array, ``tuple[X, Y]`` Tuple, ``frozenset[X]`` /
+``AbstractSet[X]`` FrozenSet, ``Redacted[X]`` Redacted, ``timedelta``
+Duration, ``JsonValue`` Json, a schema class itself; ``Annotated[T, ...]`` and
+a ``NewType`` stand for ``T``, a ``type`` alias for its value. Anything
+else raises ``TypeError``: give such a field its schema explicitly.
+"""
+
+from __future__ import annotations
+
+import collections.abc
+import datetime
+import enum
+import sys
+import types
+import typing
+from collections.abc import Callable, Mapping
+from typing import Any, cast, get_args, get_origin, get_type_hints, is_typeddict
+from weakref import WeakKeyDictionary
+
+from pyfect.redacted import Redacted as _Redacted
+from pyfect.schema import ast
+from pyfect.schema._arrays import Array, List, Tuple
+from pyfect.schema._assignable import assignable
+from pyfect.schema._collections import FrozenSet
+from pyfect.schema._data import Redacted
+from pyfect.schema._literals import Enum, Literal, Literals, Union
+from pyfect.schema._primitives import Any as AnySchema
+from pyfect.schema._primitives import Boolean, Int, Null, Number, String, Unknown
+from pyfect.schema._record import Record
+from pyfect.schema._schema import Bottom, Codec
+from pyfect.schema._values import Duration, Json, JsonValue
+
+type AnyBottom = Bottom[Any, Any, Any, Any]
+
+_SIMPLE: dict[object, AnyBottom] = {
+    str: String,
+    int: Int,
+    float: Number,
+    bool: Boolean,
+    None: Null,
+    type(None): Null,
+    object: Unknown,
+    Any: AnySchema,
+    datetime.timedelta: Duration,
+    JsonValue: Json,
+}
+
+_MAPPINGS = frozenset({dict, collections.abc.Mapping, collections.abc.MutableMapping})
+_OF_ONE: dict[object, Callable[[AnyBottom], AnyBottom]] = {
+    list: List,
+    collections.abc.Sequence: Array,
+    frozenset: FrozenSet,
+    collections.abc.Set: FrozenSet,
+    _Redacted: Redacted,
+}
+"""The schemas of the one-argument generic forms (``list[X]``, ...)."""
+
+
+def schema_of(annotation: object, expanding: frozenset[object] = frozenset()) -> AnyBottom:
+    """The schema ``annotation`` stands for; ``TypeError`` when none does.
+    ``expanding`` holds the type aliases this annotation sits inside: one
+    that refers to itself has no derived schema."""
+    aliases, annotation = _unwrap(annotation)
+    for alias in aliases:
+        if alias in expanding:
+            raise TypeError(f"The type alias {alias!r} refers to itself: give the field its schema")
+    inner = expanding.union(aliases)
+    simple = _SIMPLE.get(annotation) if _hashable(annotation) else None
+    found = simple or _of_form(annotation, inner) or _of_class(annotation)
+    if found is None:
+        raise TypeError(f"No schema for the annotation {annotation!r}: give the field its schema")
+    return found
+
+
+def _of_form(annotation: object, expanding: frozenset[object]) -> AnyBottom | None:
+    """The schema of a generic form (``Literal[...]``, ``X | Y``, ...)."""
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    def of(arg: object) -> AnyBottom:
+        return schema_of(arg, expanding)
+
+    if origin is typing.Literal:
+        return Literal(args[0]) if len(args) == 1 else Literals(*args)
+    if origin is typing.Union or origin is types.UnionType:
+        return Union(*map(of, args))
+    if origin in _MAPPINGS and len(args) == 2:
+        return Record(of(args[0]), of(args[1]))
+    if origin is tuple:
+        return _of_tuple(args, of)
+    one = _OF_ONE.get(origin) if _hashable(origin) else None
+    if one is not None and len(args) == 1:
+        return one(of(args[0]))
+    return None
+
+
+def _of_tuple(args: tuple[object, ...], of: Callable[[object], AnyBottom]) -> AnyBottom | None:
+    """``tuple[X, ...]`` an Array, ``tuple[X, Y]`` / ``tuple[()]`` a Tuple."""
+    if len(args) == 2 and args[1] is Ellipsis:
+        return Array(of(args[0]))
+    if any(_unpacked(a) or a is Ellipsis for a in args):
+        return None
+    return Tuple(*map(of, args))
+
+
+def _unpacked(annotation: object) -> bool:
+    """``*tuple[X, ...]`` or ``Unpack[...]`` (a rest: no schema is derived)."""
+    return (
+        bool(getattr(annotation, "__unpacked__", False)) or get_origin(annotation) is typing.Unpack
+    )
+
+
+def _unwrap(annotation: object) -> tuple[tuple[object, ...], object]:
+    """The type ``Annotated[T, ...]``, a ``NewType`` or a ``type`` alias
+    stands for, and the aliases passed through. An alias with a schema of
+    its own (``JsonValue``) is kept."""
+    aliases: list[object] = []
+    while True:
+        if get_origin(annotation) is typing.Annotated:
+            annotation = get_args(annotation)[0]
+        elif isinstance(annotation, typing.NewType):
+            annotation = annotation.__supertype__
+        elif isinstance(annotation, typing.TypeAliasType) and annotation not in _SIMPLE:
+            aliases.append(annotation)
+            annotation = annotation.__value__
+        else:
+            return tuple(aliases), annotation
+
+
+def _of_class(annotation: object) -> AnyBottom | None:
+    if not isinstance(annotation, type):
+        return None
+    annotation = cast("type[object]", annotation)
+    if issubclass(annotation, enum.Enum):
+        return Enum(annotation)
+    if is_typeddict(annotation):
+        return Bottom(typed_dict_ast(cast("type[Mapping[str, object]]", annotation)))
+    if hasattr(annotation, "__codec__"):
+        return cast("Codec[Any, Any, Any, Any]", annotation).__codec__()
+    return None
+
+
+def _hashable(value: object) -> bool:
+    try:
+        hash(value)
+    except TypeError:
+        return False
+    return True
+
+
+_STRUCTS: WeakKeyDictionary[type, ast.Objects] = WeakKeyDictionary()
+_BUILDING: set[type] = set()
+
+
+def typed_dict_ast(
+    typed_dict: type[Mapping[str, object]], fields: Mapping[str, AnyBottom] | None = None
+) -> ast.AST:
+    """The struct node of a TypedDict, its fields derived from its
+    annotations unless given in ``fields``. A TypedDict met again while
+    deriving its own fields becomes a ``Suspend`` of it."""
+    if fields is None:
+        cached = _STRUCTS.get(typed_dict)
+        if cached is not None:
+            return cached
+        if typed_dict in _BUILDING:
+            return ast.Suspend(lambda: _STRUCTS[typed_dict])
+        _BUILDING.add(typed_dict)
+        try:
+            node = objects_of(typed_dict, typed_dict_fields(typed_dict, {}))
+        finally:
+            _BUILDING.discard(typed_dict)
+        _STRUCTS[typed_dict] = node
+        return node
+    return objects_of(typed_dict, fields)
+
+
+def typed_dict_fields(
+    typed_dict: type[Mapping[str, object]], overrides: Mapping[str, AnyBottom]
+) -> dict[str, AnyBottom]:
+    """The schema of each key: the given one, else its annotation's."""
+    hints = get_type_hints(typed_dict)
+    unknown = [name for name in overrides if name not in hints]
+    if unknown:
+        raise TypeError(f"{typed_dict.__name__} has no key {unknown[0]!r}")
+    for name, schema in overrides.items():
+        _require_fits(typed_dict, name, hints[name], schema)
+    return {
+        name: overrides[name] if name in overrides else schema_of(hint)
+        for name, hint in hints.items()
+    }
+
+
+def _require_fits(
+    typed_dict: type[Mapping[str, object]], name: str, hint: object, schema: AnyBottom
+) -> None:
+    """``schema``'s decoded values must be values of the key's annotation
+    (pyright cannot check a keyword argument against a TypedDict key). An
+    annotation with no schema of its own, or a pair ``assignable`` cannot
+    judge, passes."""
+    try:
+        declared = schema_of(hint)
+    except TypeError:
+        return
+    if assignable(schema.ast, declared.ast) is False:
+        raise TypeError(
+            f"{typed_dict.__name__}[{name!r}] is {_type_name(hint)}, but its schema decodes to "
+            f"{schema.ast.to_type().expected()}"
+        )
+
+
+def _type_name(hint: object) -> str:
+    return hint.__name__ if isinstance(hint, type) else repr(hint).replace("typing.", "")
+
+
+def optional_keys(typed_dict: type[Mapping[str, object]]) -> frozenset[str]:
+    """The keys that may be missing. Python's ``__optional_keys__`` misses a
+    ``NotRequired`` / ``Required`` written as a string (``from __future__
+    import annotations``), so the evaluated annotations decide."""
+    optional = set(getattr(typed_dict, "__optional_keys__", frozenset[str]()))
+    for name, hint in get_type_hints(typed_dict, include_extras=True).items():
+        match _requiredness(hint):
+            case "required":
+                optional.discard(name)
+            case "not_required":
+                optional.add(name)
+            case None:
+                pass
+    return frozenset(optional)
+
+
+def _requiredness(hint: object) -> typing.Literal["required", "not_required"] | None:
+    """The ``Required`` / ``NotRequired`` wrapper of a key's annotation,
+    looking through ``ReadOnly`` and ``Annotated``."""
+    origin = get_origin(hint)
+    if origin is typing.NotRequired:
+        return "not_required"
+    if origin is typing.Required:
+        return "required"
+    if origin is typing.ReadOnly or origin is typing.Annotated:
+        return _requiredness(get_args(hint)[0])
+    return None
+
+
+def objects_of(
+    typed_dict: type[Mapping[str, object]], fields: Mapping[str, AnyBottom]
+) -> ast.Objects:
+    optional = optional_keys(typed_dict)
+    extra = extra_items(typed_dict)
+    return ast.Objects(
+        tuple(
+            ast.PropertySignature(name, schema.ast, optional=name in optional)
+            for name, schema in fields.items()
+        ),
+        () if extra is None else (_extra_items_signature(frozenset(fields), extra),),
+    )
+
+
+def _extra_items_signature(declared: frozenset[str], extra: object) -> ast.IndexSignature:
+    """The keys ``declared`` leaves out, with values of ``extra`` (PEP 728:
+    unlike a TypeScript index signature, it does not cover the declared
+    keys)."""
+
+    def undeclared(key: str) -> bool:
+        return key not in declared
+
+    key = ast.append_checks(
+        ast.string, (ast.make_filter(undeclared, expected="an undeclared key"),)
+    )
+    return ast.IndexSignature(key, schema_of(extra).ast)
+
+
+def _no_extra_items() -> tuple[object, ...]:
+    """PEP 728's ``NoExtraItems`` markers (``typing`` from Python 3.15, else
+    ``typing_extensions``, when loaded)."""
+    modules = (typing, sys.modules.get("typing_extensions"))
+    markers = (getattr(m, "NoExtraItems", None) for m in modules)
+    return tuple(marker for marker in markers if marker is not None)
+
+
+def extra_items(typed_dict: type[Mapping[str, object]]) -> object | None:
+    """The type of the keys ``typed_dict`` does not declare (PEP 728's
+    ``extra_items=``, Effect's ``StructWithRest`` of a string record), or
+    ``None`` when it declares none (or is ``closed``)."""
+    extra = getattr(typed_dict, "__extra_items__", None)
+    if extra is None or extra is typing.Never or extra in _no_extra_items():
+        return None
+    return get_args(extra)[0] if get_origin(extra) is typing.ReadOnly else extra

pyfect/schema/_duration_codecs.py

@@ -0,0 +1,27 @@
+"""``DurationFromString``, ``DurationFromNanos`` and ``DurationFromMillis``
+(Effect's), decoding into pyfect's ``Duration`` schema, a ``timedelta``,
+through ``T.duration_from_string`` / ``_nanos`` / ``_millis`` (their
+limits are in ``schema/transformation/_durations.py``).
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from pyfect.schema import transformation as T
+from pyfect.schema._primitives import BigInt, Number, String
+from pyfect.schema._transform import DecodeToSchema, decode_to
+from pyfect.schema._values import Duration
+
+DurationFromString: DecodeToSchema[timedelta, str] = String.annotate(
+    expected="a string that will be decoded as a Duration"
+).pipe(decode_to(Duration, T.duration_from_string))
+"""A ``timedelta`` read from Effect's ``Duration`` text (``"5 seconds"``)."""
+DurationFromNanos: DecodeToSchema[timedelta, int] = BigInt.pipe(
+    decode_to(Duration, T.duration_from_nanos)
+)
+"""A ``timedelta`` read from a count of nanoseconds."""
+DurationFromMillis: DecodeToSchema[timedelta, float] = Number.pipe(
+    decode_to(Duration, T.duration_from_millis)
+)
+"""A ``timedelta`` read from a count of milliseconds."""