pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/transformation/_durations.py

@@ -0,0 +1,150 @@
+"""The ``Duration`` transformations (Effect's ``durationFromString``,
+``durationFromNanos``, ``durationFromMillis``) between a ``timedelta`` and
+its text, nanoseconds or milliseconds.
+
+A ``timedelta`` counts whole microseconds within about 2.7 million years,
+so a duration it cannot hold once rounded to whole nanoseconds as Effect
+rounds it (infinite, ``1 nano``, out of range) fails to decode with
+``Expected a duration a timedelta can hold``, where Effect's ``Duration``
+would take it; a ``timedelta`` a float of milliseconds cannot hold
+exactly (past about 285 years, with microseconds) fails to encode. Text
+is Effect's ``Duration`` text: ``"<n> <unit>"`` with ``nanos``,
+``micros``, ``millis``, ``seconds``, ``minutes``, ``hours``, ``days`` or
+``weeks`` (singular too), written back as ``"<n> millis"``, or
+``"<n> nanos"`` when it is not whole milliseconds.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from datetime import timedelta
+from fractions import Fraction
+from typing import cast
+
+from pyfect._digits import digits_value
+from pyfect._js import js_number
+from pyfect.exit import Exit, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.issue import InvalidValue, Issue, reported
+from pyfect.schema.transformation._transformation import Transformation, transform_effect
+
+_PATTERN = re.compile(
+    r"(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|minutes?|hours?|days?|weeks?)\Z",
+    re.ASCII,
+)
+_NANOS_PER = {
+    "nano": 1,
+    "micro": 1_000,
+    "milli": 1_000_000,
+    "second": 1_000_000_000,
+    "minute": 60_000_000_000,
+    "hour": 3_600_000_000_000,
+    "day": 86_400_000_000_000,
+    "week": 604_800_000_000_000,
+}
+_HOLDS = "a duration a timedelta can hold"
+
+
+_INFINITIES = frozenset({"Infinity", "-Infinity"})
+
+
+def _from_nanos(nanos: int) -> timedelta | None:
+    micros, rest = divmod(nanos, 1000)
+    if rest:
+        return None
+    try:
+        return timedelta(microseconds=micros)
+    except OverflowError:
+        return None
+
+
+def _exact(text: str) -> Fraction:
+    """``-?digits(.digits)?`` exactly, however long."""
+    negative = text.startswith("-")
+    whole, _, fraction = text.removeprefix("-").partition(".")
+    numerator = cast("int", digits_value(whole + fraction))
+    value = Fraction(numerator, 10 ** len(fraction))
+    return -value if negative else value
+
+
+def _round_nanos(nanos: Fraction) -> int:
+    """Whole nanoseconds, ties away from zero (Effect's ``parseNanos``)."""
+    rounded = math.floor(abs(nanos) + Fraction(1, 2))
+    return -rounded if nanos < 0 else rounded
+
+
+def _millis_nanos(millis: float) -> int:
+    """Whole nanoseconds, ties away from zero, of the float's shortest text
+    (``0.1`` is 0.1 ms, not its binary value). Effect rounds the float
+    product ``millis * 1e6``, which agrees but where its error crosses half
+    a nanosecond; the text keeps every encoded ``timedelta`` decodable."""
+    exact = Fraction(millis) if isinstance(millis, int) else Fraction(js_number(millis))
+    return _round_nanos(exact * 1_000_000)
+
+
+def _nanos_of(duration: timedelta) -> int:
+    return (duration // timedelta(microseconds=1)) * 1000
+
+
+def _invalid(expected: str, input: object, options: ParseOptions) -> Exit[timedelta, Issue]:
+    return fail_exit(InvalidValue({"expected": expected}, reported(input, options)))
+
+
+def _decode_text(text: str, options: ParseOptions) -> Exit[timedelta, Issue]:
+    if text in _INFINITIES:
+        return _invalid(_HOLDS, text, options)
+    match = _PATTERN.match(text)
+    if match is None:
+        return _invalid("a valid Duration string", text, options)
+    value, unit = match.groups()
+    duration = _from_nanos(_round_nanos(_exact(value) * _NANOS_PER[unit.removesuffix("s")]))
+    return _invalid(_HOLDS, text, options) if duration is None else Success(duration)
+
+
+def _encode_text(duration: timedelta, _: ParseOptions) -> Exit[str, Issue]:
+    nanos = _nanos_of(duration)
+    millis, rest = divmod(nanos, 1_000_000)
+    return Success(f"{nanos} nanos" if rest else f"{millis} millis")
+
+
+def _decode_nanos(nanos: int, options: ParseOptions) -> Exit[timedelta, Issue]:
+    duration = _from_nanos(nanos)
+    return _invalid(_HOLDS, nanos, options) if duration is None else Success(duration)
+
+
+def _encode_nanos(duration: timedelta, _: ParseOptions) -> Exit[int, Issue]:
+    return Success(_nanos_of(duration))
+
+
+def _decode_millis(millis: float, options: ParseOptions) -> Exit[timedelta, Issue]:
+    if isinstance(millis, float) and math.isnan(millis):  # NaN is zero, as Effect's.
+        return Success(timedelta(0))
+    finite = isinstance(millis, int) or math.isfinite(millis)
+    duration = _from_nanos(_millis_nanos(millis)) if finite else None
+    return _invalid(_HOLDS, millis, options) if duration is None else Success(duration)
+
+
+def _encode_millis(duration: timedelta, options: ParseOptions) -> Exit[float, Issue]:
+    nanos = _nanos_of(duration)
+    millis = nanos / 1_000_000
+    if _millis_nanos(millis) != nanos:
+        # Past about 285 years a float has no room for the microseconds.
+        expected = "a duration a number of milliseconds can hold exactly"
+        return fail_exit(InvalidValue({"expected": expected}, reported(duration, options)))
+    return Success(int(millis) if millis.is_integer() else millis)
+
+
+duration_from_string: Transformation[timedelta, str] = transform_effect(
+    decode=_decode_text, encode=_encode_text
+)
+"""A ``timedelta`` from Effect's ``Duration`` text (``"5 seconds"``)."""
+duration_from_nanos: Transformation[timedelta, int] = transform_effect(
+    decode=_decode_nanos, encode=_encode_nanos
+)
+"""A ``timedelta`` from a count of nanoseconds."""
+duration_from_millis: Transformation[timedelta, float] = transform_effect(
+    decode=_decode_millis, encode=_encode_millis
+)
+"""A ``timedelta`` from a count of milliseconds."""

pyfect/schema/transformation/_transformation.py

@@ -0,0 +1,177 @@
+"""``Transformation`` (a getter each way) and ``Middleware`` (a function of
+the whole parse each way), Effect's ``SchemaTransformation``. A schema made
+with ``decode_to`` holds one in its encoding."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, Never, Self, TypeIs, TypeVar, cast
+
+from pyfect._core import Effect
+from pyfect.option import Option, Some
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.ast import MISSING, ParseResult, call, map_value, to_effect
+from pyfect.schema.getter import (
+    Getter,
+    Outcome,
+)
+from pyfect.schema.getter import (
+    passthrough as passthrough_getter,
+)
+from pyfect.schema.getter import (
+    transform as transform_getter,
+)
+from pyfect.schema.getter import (
+    transform_effect as transform_effect_getter,
+)
+from pyfect.schema.getter import (
+    transform_optional as transform_optional_getter,
+)
+from pyfect.schema.getter._getter import apply_result
+from pyfect.schema.issue import Issue
+
+T = TypeVar("T")
+E = TypeVar("E")
+RD_co = TypeVar("RD_co", covariant=True, default=Never)
+RE_co = TypeVar("RE_co", covariant=True, default=Never)
+
+
+@dataclass(frozen=True, slots=True)
+class Content:
+    """The document a getter writes: its ``media_type``, and whether the
+    schema of its content is that of the values it encodes
+    (``preserve_schema``)."""
+
+    media_type: str
+    preserve_schema: bool
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Transformation(Generic[T, E, RD_co, RE_co]):
+    """``decode`` turns an ``E`` into a ``T``, ``encode`` back, needing the
+    services ``RD`` / ``RE`` (Effect's ``Transformation``)."""
+
+    decode: Getter[T, E, RD_co]
+    encode: Getter[E, T, RE_co]
+    content: Content | None = None
+    """What ``encode`` writes, when it writes a document of a media type
+    (JSON text): JSON Schema says it with ``contentMediaType``."""
+    decode_content: Content | None = None
+    """``content`` of ``decode``, carried for ``flip``."""
+
+    @property
+    def sees_failures(self) -> bool:
+        return False
+
+    def flip(self) -> Transformation[E, T, RE_co, RD_co]:
+        """The transformation the other way."""
+        return Transformation(self.encode, self.decode, self.decode_content, self.content)
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        return f(self)
+
+    def compose[T2, RD2 = Never, RE2 = Never](
+        self, other: Transformation[T2, T, RD2, RE2], /
+    ) -> Transformation[T2, E, RD_co | RD2, RE_co | RE2]:
+        """This transformation, then ``other`` (Effect's
+        ``composeTransformation``)."""
+        return Transformation(self.decode.compose(other.decode), other.encode.compose(self.encode))
+
+    def decode_result(self, result: ParseResult, options: ParseOptions) -> ParseResult:
+        return apply_result(self.decode, result, options)
+
+
+type _Parse[A, R] = Effect[Option[A], Issue, R]
+
+
+def unchanged[A, R](parse: _Parse[A, R], options: ParseOptions, /) -> _Parse[A, R]:
+    """The side of a ``Middleware`` that leaves the parse as it is (Effect's
+    ``identity`` in ``middlewareDecoding`` / ``middlewareEncoding``)."""
+    return parse
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Middleware(Generic[T, E, RD_co, RE_co]):
+    """A function of the whole parse each way: ``decode(effect, options)``
+    gets the source's parse (an effect giving ``Some(value)``, or ``None``
+    for a missing value, or failing with its issue) and gives the target's
+    (Effect's ``Middleware``). It sees failures, so it can recover from
+    them (``catch_decoding``)."""
+
+    decode: Callable[[_Parse[E, Any], ParseOptions], _Parse[T, RD_co]]
+    encode: Callable[[_Parse[T, Any], ParseOptions], _Parse[E, RE_co]]
+
+    @property
+    def sees_failures(self) -> bool:
+        return self.decode is not unchanged
+
+    def flip(self) -> Middleware[E, T, RE_co, RD_co]:
+        return Middleware(self.encode, self.decode)
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        return f(self)
+
+    def decode_result(self, result: ParseResult, options: ParseOptions) -> ParseResult:
+        source = cast("_Parse[E, Any]", to_effect(map_value(result, _option)))
+        return map_value(call(self.decode, source, options), _value)
+
+
+def _option(value: object) -> Option[object]:
+    return None if value is MISSING else Some(value)
+
+
+def _value(option: object) -> object:
+    return MISSING if option is None else cast("Some[object]", option).value
+
+
+def is_transformation(value: object) -> TypeIs[Transformation[Any, Any, Any, Any]]:
+    """``value`` is a ``Transformation`` (Effect's ``isTransformation``)."""
+    return isinstance(value, Transformation)
+
+
+def transform[T2, E2](
+    *, decode: Callable[[E2], T2], encode: Callable[[T2], E2]
+) -> Transformation[T2, E2]:
+    """A function each way (Effect's ``transform``)."""
+    return Transformation(transform_getter(decode), transform_getter(encode))
+
+
+def transform_effect[T2, E2, RD = Never, RE = Never](
+    *,
+    decode: Callable[[E2, ParseOptions], Outcome[T2, RD]],
+    encode: Callable[[T2, ParseOptions], Outcome[E2, RE]],
+) -> Transformation[T2, E2, RD, RE]:
+    """An effectful function each way, failing with an ``Issue`` (Effect's
+    ``transformEffect``)."""
+    return Transformation(transform_effect_getter(decode), transform_effect_getter(encode))
+
+
+def transform_optional[T2, E2](
+    *,
+    decode: Callable[[Option[E2]], Option[T2]],
+    encode: Callable[[Option[T2]], Option[E2]],
+) -> Transformation[T2, E2]:
+    """A function of an ``Option`` each way (Effect's ``transformOptional``)."""
+    return Transformation(transform_optional_getter(decode), transform_optional_getter(encode))
+
+
+_PASSTHROUGH: Transformation[Any, Any] = Transformation(passthrough_getter(), passthrough_getter())
+
+
+def passthrough[T2]() -> Transformation[T2, T2]:
+    """The value unchanged each way (Effect's ``passthrough``)."""
+    return _PASSTHROUGH
+
+
+def passthrough_supertype() -> Transformation[Any, Any]:
+    """The value unchanged each way, from a supertype ``E`` to its subtype
+    ``T`` (Effect's ``passthroughSupertype``). Python cannot say that ``T``
+    is a subtype of ``E``, so it is typed ``Any``."""
+    return _PASSTHROUGH
+
+
+def passthrough_subtype() -> Transformation[Any, Any]:
+    """The value unchanged each way, from a subtype ``E`` to its supertype
+    ``T`` (Effect's ``passthroughSubtype``)."""
+    return _PASSTHROUGH

pyfect/schema/variant_schema/__init__.py

@@ -0,0 +1,69 @@
+"""Variant schemas (Effect's ``effect/schema/VariantSchema``): related
+schemas for named variants built from one set of field definitions::
+
+    from pyfect.schema import variant_schema as VS
+
+    Test = VS.make(variants=["a", "b"], default_variant="a")
+    struct = Test.Struct({"common": S.String, "only_b": Test.field_only(["b"])(S.Number)})
+    Test.extract(struct, "b")  # the struct schema of common and only_b
+
+    class User(Test.Class):
+        id: int = VS.field(Test.field_only(["a"])(S.Int))
+        name: str
+
+    Test.extract(User, "b")  # the struct schema of name; User is the "a" schema
+
+``pyfect.schema.model`` is the toolkit for database and JSON API models.
+Pyright cannot compute a variant's keys from the definitions (no mapped
+types), so an extracted struct's Type is a ``Mapping``; ``Model.Class``
+takes TypedDicts for its variants (see there).
+"""
+
+from pyfect.schema.variant_schema._class import Class, VariantAttribute, field
+from pyfect.schema.variant_schema._defaults import (
+    Overrideable,
+    WithConstructorDefault,
+    override,
+    with_constructor_default,
+)
+from pyfect.schema.variant_schema._field import Field, is_field
+from pyfect.schema.variant_schema._struct import (
+    Definition,
+    HasVariants,
+    Struct,
+    VariantStructSchema,
+    extract,
+    fields,
+    is_struct,
+)
+from pyfect.schema.variant_schema._toolkit import (
+    FieldEvolve,
+    FieldOnly,
+    VariantSchema,
+    VariantUnionSchema,
+    make,
+)
+
+__all__ = [
+    "Class",
+    "Definition",
+    "Field",
+    "FieldEvolve",
+    "FieldOnly",
+    "HasVariants",
+    "Overrideable",
+    "Struct",
+    "VariantAttribute",
+    "VariantSchema",
+    "VariantStructSchema",
+    "VariantUnionSchema",
+    "WithConstructorDefault",
+    "extract",
+    "field",
+    "fields",
+    "is_field",
+    "is_struct",
+    "make",
+    "override",
+    "with_constructor_default",
+]

pyfect/schema/variant_schema/_class.py

@@ -0,0 +1,188 @@
+"""Variant classes (Effect's ``VariantSchema.Class``): a schema class of
+the default variant whose other variants are extracted from the same
+field definitions::
+
+    class User(Model.Class):
+        id: int = Model.field(Model.GeneratedByDb(S.Int))  # select and json only
+        name: str                                          # every variant
+        password = Model.Sensitive(S.String)  # not in select: no annotation
+
+An annotated field is a field of the class (the default variant), its
+schema given by ``field(...)`` or derived from the annotation; a variant
+field that the default variant leaves out is assigned without an
+annotation, so the class does not have it. A subclass extends: a field it
+redefines replaces the inherited one in every variant.
+"""
+
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, ClassVar, Protocol, cast, dataclass_transform, overload
+
+from pyfect.schema._class import _SCHEMA, _annotation, _shape_of
+from pyfect.schema._class import Class as SchemaClass
+from pyfect.schema._class import field as schema_field
+from pyfect.schema._schema import Codec
+from pyfect.schema.variant_schema._field import AnyCodec, Field
+from pyfect.schema.variant_schema._struct import (
+    Definition,
+    Struct,
+    VariantStructSchema,
+    extract,
+)
+
+_VARIANT = "pyfect.schema.variant_schema"
+"""The ``dataclasses.Field.metadata`` key of a field's variant definition."""
+
+
+@overload
+def field[A](spec: Field[A], /) -> A: ...
+@overload
+def field(spec: Struct, /) -> Mapping[str, object]: ...
+@overload
+def field[A](spec: Codec[A, Any, Any, Any], /) -> A: ...
+def field(spec: Field[Any] | Struct | AnyCodec, /) -> Any:
+    """A variant class field defined by a variant field, a nested variant
+    struct or a schema (one that may need services); the class's
+    annotation must be its Type in the default variant."""
+    return dataclasses.field(metadata={_VARIANT: spec})
+
+
+class VariantSet(Protocol):
+    """The variants a toolkit defines."""
+
+    @property
+    def variants(self) -> tuple[str, ...]: ...
+
+    @property
+    def default_variant(self) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class _Annotated:
+    """A field defined by its annotation, read on first use (so it may
+    refer to classes defined later)."""
+
+    owner: type[Class]
+    name: str
+
+    def resolve(self) -> Definition:
+        annotation = _annotation(self.owner, self.name)
+        if isinstance(annotation, type) and issubclass(annotation, Class):
+            return annotation
+        return _shape_of(self.owner).schemas[self.name]
+
+
+@dataclass_transform(
+    kw_only_default=True, frozen_default=True, field_specifiers=(field, schema_field)
+)
+class Class(SchemaClass):
+    """A variant class base; a toolkit's ``Class`` (``Model.Class``) is the
+    one to subclass. See ``pyfect.schema.variant_schema``."""
+
+    __variant_set__: ClassVar[VariantSet]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        variant_set = cast("VariantSet | None", getattr(cls, "__variant_set__", None))
+        if variant_set is None:
+            raise TypeError(f"{cls.__name__}: subclass a toolkit's Class (Model.Class, ...)")
+        default = variant_set.default_variant
+        annotated = inspect.get_annotations(cls)
+        unannotated = _take_unannotated(cls, annotated, default)
+        _set_default_schemas(cls, annotated, default)
+        super().__init_subclass__(**kwargs)
+        own: dict[str, object] = {}
+        for f in dataclasses.fields(cast("Any", cls)):
+            if f.name in annotated:
+                own[f.name] = f.metadata.get(_VARIANT) or _Annotated(cls, f.name)
+        own.update(unannotated)
+        type.__setattr__(cls, "_variant_own", own)
+
+    @classmethod
+    def __variant_fields__(cls) -> Mapping[str, Definition]:
+        merged: dict[str, object] = {}
+        for klass in reversed(cls.__mro__):
+            merged.update(klass.__dict__.get("_variant_own", {}))
+        return {
+            name: value.resolve() if isinstance(value, _Annotated) else cast("Definition", value)
+            for name, value in merged.items()
+        }
+
+    @classmethod
+    def __variant_cache__(cls, is_default: bool) -> dict[str, Any]:
+        name = "_variant_default_cache" if is_default else "_variant_cache"
+        cache = cls.__dict__.get(name)
+        if cache is None:
+            cache = {}
+            type.__setattr__(cls, name, cache)
+        return cast("dict[str, Any]", cache)
+
+
+def _take_unannotated(
+    cls: type, annotated: Mapping[str, object], default: str
+) -> dict[str, object]:
+    """The variant fields assigned without an annotation, removed from the
+    class (it does not have them)."""
+    found: dict[str, object] = {}
+    for name, value in list(vars(cls).items()):
+        if name in annotated or not isinstance(value, Field | Struct):
+            continue
+        if isinstance(value, Struct) or default in value.schemas:
+            raise TypeError(
+                f"{cls.__name__}.{name} is in the {default!r} variant: annotate it with its type"
+            )
+        found[name] = value
+        delattr(cls, name)
+    return found
+
+
+def _set_default_schemas(cls: type, annotated: Mapping[str, object], default: str) -> None:
+    """Give each ``field(...)`` field its default variant's schema, the one
+    the class itself decodes with."""
+    for name in annotated:
+        value = vars(cls).get(name)
+        if not isinstance(value, dataclasses.Field):
+            continue
+        spec = cast("dataclasses.Field[Any]", value).metadata.get(_VARIANT)
+        if spec is None:
+            continue
+        if isinstance(spec, Field):
+            schema = cast("Field[Any]", spec).schemas.get(default)
+            if schema is None:
+                raise TypeError(
+                    f"{cls.__name__}.{name} is not in the {default!r} variant: "
+                    "assign it without an annotation"
+                )
+        elif isinstance(spec, Struct):
+            schema = extract(spec, default)
+        else:
+            schema = spec
+        setattr(cls, name, dataclasses.field(metadata={_SCHEMA: schema, _VARIANT: spec}))
+
+
+class VariantAttribute:
+    """``Cls.<variant>``: the variant's struct, annotated with the class's
+    identifier (``User.insert``)."""
+
+    __slots__ = ("variant",)
+
+    def __init__(self, variant: str) -> None:
+        self.variant = variant
+
+    def __get__(self, instance: object, owner: type[Class]) -> VariantStructSchema[Any]:
+        attributes = owner.__dict__.get("_variant_attributes")
+        if attributes is None:
+            attributes = {}
+            type.__setattr__(owner, "_variant_attributes", attributes)
+        found = cast("dict[str, VariantStructSchema[Any]]", attributes).get(self.variant)
+        if found is None:
+            name = f"{_shape_of(owner).identifier}.{self.variant}"
+            schema = cast("VariantStructSchema[Any]", extract(owner, self.variant))
+            found = schema.annotate(identifier=name, title=name)
+            attributes[self.variant] = found
+        return found

pyfect/schema/variant_schema/_defaults.py

@@ -0,0 +1,30 @@
+"""Constructor defaults for variant fields (``S.with_constructor_default``,
+and Effect's ``VariantSchema.Overrideable``): a value a variant struct's
+``make`` fills in for a missing key. Decoding never uses it: a missing key
+stays an error there."""
+
+from __future__ import annotations
+
+from typing import Never
+
+from pyfect._core import Effect
+from pyfect._effect_args import require_effect
+from pyfect.schema._constructor_default import WithConstructorDefault, with_constructor_default
+from pyfect.schema._schema import Codec
+
+
+def Overrideable[T, E, RD, RE](
+    schema: Codec[T, E, RD, RE], /, *, default_value: Effect[T, Never, Never]
+) -> WithConstructorDefault[T, E, RD, RE]:
+    """``schema`` with ``default_value`` as its constructor default, for
+    values the application makes (timestamps) but a caller may set with
+    ``override`` (Effect's ``Overrideable``)."""
+    require_effect(default_value, "default_value")
+    return with_constructor_default(default_value)(schema)
+
+
+def override[A](value: A, /) -> A:
+    """An explicit value for an ``Overrideable`` field (Effect's
+    ``Override``). Python has no phantom brand for any ``A``, so it marks the
+    intent and returns ``value``."""
+    return value

pyfect/schema/variant_schema/_field.py

@@ -0,0 +1,32 @@
+"""Variant fields (Effect's ``VariantSchema.Field``): one logical field's
+schema in each variant that has it."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeIs, TypeVar
+
+from pyfect.schema._schema import Codec
+
+A_co = TypeVar("A_co", covariant=True)
+
+type AnyCodec = Codec[Any, Any, Any, Any]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Field(Generic[A_co]):
+    """A field's schema per variant; a variant missing from ``schemas``
+    leaves the field out of that variant. ``A`` is the field's Type in the
+    default variant (the annotation a class field must have)."""
+
+    schemas: Mapping[str, AnyCodec]
+
+    def pipe[B](self, f: Callable[[Field[A_co]], B], /) -> B:
+        """``f(self)``: ``S.Int.pipe(model.field_only(["select"]))`` and so on."""
+        return f(self)
+
+
+def is_field(value: object) -> TypeIs[Field[Any]]:
+    """``value`` is a variant field (Effect's ``isField``)."""
+    return isinstance(value, Field)