pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/_jsonschema/_objects.py

@@ -0,0 +1,231 @@
+"""Compiling a mapping (Effect's ``compileObjects``): ``properties`` and
+``required`` for its keys, ``patternProperties`` for index signatures whose
+keys a pattern selects, ``additionalProperties`` for the rest."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from pyfect.json_schema import JsonSchema
+from pyfect.schema import ast
+from pyfect.schema._codec_links import NUMBER_KEY_PATTERN
+from pyfect.schema._jsonschema._exact import Exactness, is_exact
+from pyfect.schema._jsonschema._merge import append_json_schema, has_only_keywords
+from pyfect.schema._jsonschema._template import template_pattern
+
+if TYPE_CHECKING:
+    from pyfect.schema._jsonschema._compile import Compiler
+
+_PATTERN_SCHEMA_KEYWORDS = frozenset(
+    {"type", "pattern", "title", "description", "default", "examples", "readOnly", "writeOnly"}
+)
+
+type _Value = JsonSchema | bool
+
+
+def compile_objects(
+    compiler: Compiler, node: ast.Objects, dependencies: list[Exactness]
+) -> JsonSchema:
+    properties_in, indexes_in = node.properties, node.index_signatures
+    if not properties_in and not indexes_in:
+        return {"not": {"type": "null"}}
+    out: JsonSchema = {"type": "object"}
+    _properties(compiler, node, out, dependencies)
+    indexes: list[tuple[_Value, list[str] | None]] = []
+    for index in indexes_in:
+        schema = compiler.recur(index.type, dependencies)
+        value: _Value = False if schema == {"not": {}} else schema
+        patterns = _patterns(compiler, index.parameter, frozenset())
+        if patterns is None:
+            dependencies.append(False)
+        indexes.append((value, patterns))
+    pattern_properties = _pattern_properties(compiler, indexes)
+    if pattern_properties:
+        out["patternProperties"] = pattern_properties
+    _additional(compiler, node, out, indexes, dependencies)
+    additional = out.get("additionalProperties")
+    if isinstance(additional, dict) and not additional:
+        del out["additionalProperties"]
+    return out
+
+
+def _properties(
+    compiler: Compiler, node: ast.Objects, out: JsonSchema, dependencies: list[Exactness]
+) -> None:
+    properties: JsonSchema = {}
+    required: list[str] = []
+    for p in node.properties:
+        if not isinstance(p.name, str):
+            raise ValueError("Objects property names must be strings")
+        properties[p.name] = compiler.member(p.type, p.type.key_annotations, dependencies)
+        if not p.optional_when_encoded():
+            required.append(p.name)
+    if node.properties:
+        out["properties"] = properties
+    if required:
+        out["required"] = required
+
+
+def _pattern_properties(
+    compiler: Compiler, indexes: list[tuple[_Value, list[str] | None]]
+) -> dict[str, _Value]:
+    """Index signatures with a pattern; a key two of them take must fit both."""
+    out: dict[str, _Value] = {}
+    for value, patterns in indexes:
+        for pattern in patterns or ():
+            previous = out.get(pattern)
+            if previous is None:
+                out[pattern] = value
+            elif previous is False or value is False:
+                out[pattern] = False
+            else:
+                merged = append_json_schema(cast("JsonSchema", previous), cast("JsonSchema", value))
+                out[pattern] = compiler.register_one_of(merged)
+    return out
+
+
+def _additional(
+    compiler: Compiler,
+    node: ast.Objects,
+    out: JsonSchema,
+    indexes: list[tuple[_Value, list[str] | None]],
+    dependencies: list[Exactness],
+) -> None:
+    """``additionalProperties`` (and ``propertyNames``) for the keys no
+    property nor pattern takes."""
+    unpatterned = [value for value, patterns in indexes if patterns == []]
+    unrepresentable = any(patterns is None for _, patterns in indexes)
+    error = compiler.options.on_excess_property == "error"
+    if unrepresentable and error:
+        names: list[JsonSchema] = []
+        if node.properties:
+            names.append({"enum": [p.name for p in node.properties]})
+        names.extend(
+            _property_name_schema(compiler, index.parameter, dependencies, frozenset())
+            for index in node.index_signatures
+        )
+        out["propertyNames"] = names[0] if len(names) == 1 else {"anyOf": names}
+        values = [value for value, _ in indexes]
+        out["additionalProperties"] = values[0] if len(values) == 1 else {"anyOf": values}
+        if unpatterned:
+            out["allOf"] = [{"type": "object", "additionalProperties": v} for v in unpatterned]
+    elif not unpatterned:
+        out["additionalProperties"] = unrepresentable or not error
+    elif len(unpatterned) == 1 and not node.properties and "patternProperties" not in out:
+        out["additionalProperties"] = unpatterned[0]
+    else:
+        out["allOf"] = [{"type": "object", "additionalProperties": v} for v in unpatterned]
+
+
+def _property_name_schema(
+    compiler: Compiler,
+    parameter: ast.AST,
+    dependencies: list[Exactness],
+    seen: frozenset[str],
+) -> JsonSchema:
+    candidate = compiler.references.candidate(parameter)
+    reference = candidate.reference
+    if reference is None:
+        return _name_schema(compiler, candidate.ast, dependencies, seen, parameter)
+    if reference in seen:
+        return {"type": "string"}
+    return _name_schema(compiler, candidate.ast, dependencies, seen | {reference}, None)
+
+
+def _name_schema(
+    compiler: Compiler,
+    node: ast.AST,
+    dependencies: list[Exactness],
+    seen: frozenset[str],
+    parameter: ast.AST | None,
+) -> JsonSchema:
+    """``parameter`` is the node as written, ``None`` for a definition's
+    own node (compiled in place, not referenced)."""
+    match node:
+        case ast.Number():
+            return {"type": "string", "pattern": NUMBER_KEY_PATTERN}
+        case ast.Union():
+            return {
+                "anyOf": [
+                    _property_name_schema(compiler, t, dependencies, seen) for t in node.types
+                ]
+            }
+        case _ if parameter is None:
+            return compiler.compile(node, dependencies)
+        case _:
+            return compiler.recur(parameter, dependencies)
+
+
+def _patterns(compiler: Compiler, parameter: ast.AST, seen: frozenset[str]) -> list[str] | None:
+    """The patterns selecting the keys ``parameter`` takes: ``[]`` for any
+    key, ``None`` when no pattern can (an approximation)."""
+    candidate = compiler.references.candidate(parameter)
+    reference = candidate.reference
+    if reference is None:
+        return _local_patterns(compiler, candidate.ast, seen)
+    definition = compiler.definition_of(candidate)
+    if reference in seen:
+        return None
+    compiled = None if definition is None else (definition.schema, definition.dependencies)
+    return _local_patterns(compiler, candidate.ast, seen | {reference}, compiled)
+
+
+def _local_patterns(  # noqa: PLR0911
+    compiler: Compiler,
+    node: ast.AST,
+    seen: frozenset[str],
+    compiled: tuple[JsonSchema, list[Exactness]] | None = None,
+) -> list[str] | None:
+    """``compiled``: the node's definition, already compiled (its
+    callbacks are not run twice)."""
+    match node:
+        case ast.Suspend():
+            return _patterns(compiler, node.target, seen)
+        case ast.String():
+            return _string_patterns(compiler, node, compiled)
+        case ast.Union():
+            if not node.types or node.checks or node.mode == "one_of":
+                return None
+            patterns: list[str] = []
+            for member in node.types:
+                member_patterns = _patterns(compiler, member, seen)
+                if member_patterns is None:
+                    return None
+                if not member_patterns:
+                    return []
+                patterns.extend(member_patterns)
+            return patterns
+        case ast.Number():
+            return None if node.checks else [NUMBER_KEY_PATTERN]
+        case ast.TemplateLiteral():
+            if node.checks:
+                return None
+            pattern, exact = template_pattern(compiler, node)
+            return [pattern] if exact else None
+        case _:
+            raise ValueError(f"Invalid index signature parameter {node.tag}")
+
+
+def _string_patterns(
+    compiler: Compiler, node: ast.String, compiled: tuple[JsonSchema, list[Exactness]] | None
+) -> list[str] | None:
+    checks = node.checks
+    if not checks:
+        return []
+    if len(checks) != 1 or not isinstance(checks[0], ast.Filter):
+        return None
+    if compiled is None:
+        dependencies: list[Exactness] = []
+        schema = compiler.compile(node, dependencies)
+    else:
+        schema, dependencies = compiled
+    if not is_exact(dependencies):
+        return None
+    pattern = schema.get("pattern")
+    if (
+        schema.get("type") == "string"
+        and isinstance(pattern, str)
+        and has_only_keywords(schema, _PATTERN_SCHEMA_KEYWORDS)
+    ):
+        return [pattern]
+    return None

pyfect/schema/_jsonschema/_references.py

@@ -0,0 +1,221 @@
+"""Which nodes become definitions (``$defs``): Effect's reference
+allocation in ``toRepresentation``.
+
+JSON Schema describes the encoded side, so each position is the node at the
+end of its encoding chain (a schema class: its fields' struct). A node with
+an ``identifier`` is a definition under that name (by default; a
+``ReferencePolicy`` decides otherwise); a node reached with no identifier of
+its own from one that has one (a class's struct, a number's JSON form) is
+named after it, ``<identifier>Encoded``. A recursive node is always a
+definition. Repeated names get ``_1``, ``_2``... suffixes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+
+from pyfect.schema import ast
+from pyfect.schema._jsonschema._annotations import ReferenceCandidate, ReferencePolicy
+from pyfect.schema._jsonschema._checks import schemas_of
+
+
+def _class_next(node: ast.AST) -> ast.AST | None:
+    if isinstance(node, ast.Class):
+        if node.side == "decode":
+            return node.shape.fields
+        if node.side == "encoded":
+            return node.shape.encoded
+    return None
+
+
+def _next(node: ast.AST) -> ast.AST | None:
+    if node.encoding is not None:
+        return node.encoding[-1].to
+    return _class_next(node)
+
+
+def encoded_node(node: ast.AST) -> ast.AST:
+    """The node at the end of ``node``'s encoding chain."""
+    while (next_node := _next(node)) is not None:
+        node = next_node
+    return node
+
+
+@dataclass(frozen=True, slots=True)
+class Content:
+    """The document a string holds (JSON text): its media type and the
+    candidate of the values it encodes."""
+
+    media_type: str
+    schema: Candidate | None
+
+
+FALLBACK_KEY = "~identifier"
+"""The annotation naming the node a definition was reached from, kept on
+the definition (``to_representation``) so its name survives a round trip."""
+
+
+def _identifier(node: ast.AST, key: str = "identifier") -> str | None:
+    identifier = (node.resolve() or {}).get(key)
+    return identifier if isinstance(identifier, str) else None
+
+
+@dataclass(eq=False)
+class Candidate:
+    """A node that may become a definition."""
+
+    ast: ast.AST
+    identifier: str | None
+    fallback: str | None
+    """The identifier of the node it was reached from, when it has none."""
+    content: Content | None = None
+    occurrences: int = 0
+    visiting: bool = False
+    recursive: bool = False
+    reference: str | None = None
+
+
+def children(node: ast.AST) -> Iterator[ast.AST]:
+    """The nodes inside ``node`` (an encoded node)."""
+    match node:
+        case ast.Declaration():
+            yield from node.type_parameters
+        case ast.Objects():
+            for p in node.properties:
+                yield p.type
+            for i in node.index_signatures:
+                yield i.parameter
+                yield i.type
+        case ast.Arrays():
+            for e in node.elements:
+                yield e.type
+            yield from node.rest
+        case ast.Union():
+            yield from node.types
+        case ast.Suspend():
+            yield node.target
+        case ast.TemplateLiteral():
+            yield from node.parts
+        case _:
+            pass
+
+
+def default_policy(candidate: ReferenceCandidate) -> str | None:
+    return candidate.identifier
+
+
+class References:
+    """The candidates of some root nodes, with their references decided."""
+
+    def __init__(self, roots: Sequence[ast.AST], policy: ReferencePolicy | None) -> None:
+        self._candidates: dict[int, list[Candidate]] = {}
+        self._used: set[str] = set()
+        self._types: dict[int, tuple[ast.AST, ast.AST]] = {}
+        for root in roots:
+            self._visit(root)
+        decide = policy or default_policy
+        for variants in self._candidates.values():
+            for candidate in variants:
+                self._decide(candidate, decide)
+
+    def _decide(self, candidate: Candidate, policy: ReferencePolicy) -> None:
+        requested = policy(
+            ReferenceCandidate(candidate.ast, candidate.occurrences, candidate.identifier)
+        )
+        if requested is not None:
+            separator = (
+                "_" if requested == candidate.identifier or not requested.endswith("_") else ""
+            )
+            candidate.reference = self._reference(requested, separator)
+        elif candidate.recursive:
+            candidate.reference = self._reference(f"{candidate.ast.tag}_", "")
+
+    def _reference(self, prefix: str, separator: str) -> str:
+        reference = prefix
+        suffix = 0
+        while reference in self._used:
+            suffix += 1
+            reference = f"{prefix}{separator}{suffix}"
+        self._used.add(reference)
+        return reference
+
+    def candidate(self, input: ast.AST, links: int | None = None) -> Candidate:
+        """The candidate of ``input`` through its first ``links`` encoding
+        links (all of them by default)."""
+        node = input
+        length = len(node.encoding or ()) if links is None else links
+        content: Content | None = None
+        while True:
+            if node.encoding is not None and length > 0:
+                last = node.encoding[length - 1]
+                found = getattr(last.transformation, "content", None)
+                # Only the link writing the final string says what it holds.
+                if found is not None and last.to.encoding is None and last.to.tag == "String":
+                    held = self.candidate(node, length - 1) if found.preserve_schema else None
+                    content = Content(found.media_type, held)
+                node = last.to
+                length = len(node.encoding or ())
+                continue
+            following = _class_next(node)
+            if following is None:
+                break
+            node = following
+            length = len(node.encoding or ())
+        if node.encoding is not None and node.body_owner is not None:
+            # Stopped before an encoding: the schema it was added to.
+            node = node.body_owner
+        node = node.owner()
+        identifier = _identifier(node)
+        fallback = None
+        if identifier is None:
+            fallback = _identifier(input) if node is not input else None
+            if fallback is None:
+                fallback = _identifier(node, FALLBACK_KEY)
+            if fallback is not None:
+                identifier = f"{fallback}Encoded"
+        variants = self._candidates.setdefault(id(node), [])
+        for candidate in variants:
+            if candidate.identifier == identifier and candidate.content == content:
+                return candidate
+        candidate = Candidate(node, identifier, fallback, content)
+        variants.append(candidate)
+        return candidate
+
+    def _visit(self, input: ast.AST) -> None:
+        self._visit_candidate(self.candidate(input))
+
+    def _visit_candidate(self, candidate: Candidate) -> None:
+        candidate.occurrences += 1
+        if candidate.visiting:
+            candidate.recursive = True
+            return
+        if candidate.occurrences > 1:
+            return
+        candidate.visiting = True
+        if candidate.content is not None and candidate.content.schema is not None:
+            self._visit_candidate(candidate.content.schema)
+        self._visit_checks(candidate.ast.checks)
+        for child in children(candidate.ast):
+            self._visit(child)
+        candidate.visiting = False
+
+    def check_schemas(self, check: ast.Check[object]) -> list[ast.AST]:
+        """The decoded sides of the schemas a check names, the same nodes
+        each time (a candidate is a node)."""
+        out: list[ast.AST] = []
+        for schema in schemas_of(check.annotations):
+            if isinstance(schema, ast.AST):
+                hit = self._types.get(id(schema))
+                if hit is None:
+                    hit = (schema, schema.to_type())
+                    self._types[id(schema)] = hit
+                out.append(hit[1])
+        return out
+
+    def _visit_checks(self, checks: ast.Checks | None) -> None:
+        for check in checks or ():
+            for schema in self.check_schemas(check):
+                self._visit(schema)
+            if isinstance(check, ast.FilterGroup):
+                self._visit_checks(check.checks)

pyfect/schema/_jsonschema/_template.py

@@ -0,0 +1,69 @@
+"""The pattern of a ``TemplateLiteral`` (Effect's ``getTemplateLiteralPattern``):
+each part's pattern in order, between ``^`` and ``$``. A part with checks,
+or a ``one_of`` union (alternatives do not make one branch exclusive),
+makes the pattern an approximation."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from pyfect.schema import ast
+from pyfect.schema.getter._coerce import to_string
+
+if TYPE_CHECKING:
+    from pyfect.schema._jsonschema._compile import Compiler
+
+_SPECIAL = re.compile(r"[/\\^$*+?.()|\[\]{}]")
+
+
+def escape(text: str) -> str:
+    """JavaScript's ``RegExp.escape`` as Effect writes it."""
+    return _SPECIAL.sub(lambda m: "\\" + m.group(0), text)
+
+
+def template_pattern(compiler: Compiler, node: ast.TemplateLiteral) -> tuple[str, bool]:
+    """The pattern of ``node``'s parts and whether it is exact."""
+    exact = True
+    active: set[str] = set()
+
+    def part(node: ast.AST) -> str:
+        candidate = compiler.references.candidate(node)
+        reference = candidate.reference
+        if reference is None:
+            return local(candidate.ast)
+        compiler.definition_of(candidate)
+        if reference in active:
+            raise ValueError(f"Invalid recursive TemplateLiteral part {reference}")
+        active.add(reference)
+        out = local(candidate.ast)
+        active.discard(reference)
+        return out
+
+    def local(node: ast.AST) -> str:  # noqa: PLR0911
+        nonlocal exact
+        # A segment check cannot be written into the enclosing pattern.
+        if node.checks:
+            exact = False
+        match node:
+            case ast.Literal():
+                return escape(to_string(node.literal))
+            case ast.String():
+                return ast.STRING_PATTERN
+            case ast.Number():
+                return ast.FINITE_PATTERN
+            case ast.BigInt():
+                return ast.BIG_INT_PATTERN
+            case ast.TemplateLiteral():
+                return "".join(map(part, node.parts))
+            case ast.Union():
+                if not node.types:
+                    return "(?!)"
+                if node.mode == "one_of":
+                    exact = False
+                return f"(?:{'|'.join(map(part, node.types))})"
+            case _:
+                raise ValueError(f"Invalid TemplateLiteral part {node.tag}")
+
+    pattern = f"^{''.join(map(part, node.parts))}$"
+    return pattern, exact

pyfect/schema/_literals.py

@@ -0,0 +1,147 @@
+"""Exact-value schemas: ``Literal``, ``Literals``, ``Enum``, and the
+``Union`` that ``Literals`` is.
+
+``Literals("a", "b")`` keeps string literals in its type
+(``LiteralsSchema[Literal["a", "b"]]``); an all-``int`` call widens to
+``int`` and needs the expected type written out
+(``x: S.LiteralsSchema[Literal[1, 2]] = S.Literals(1, 2)``).
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, LiteralString, Never, TypeVar, cast, overload
+
+from pyfect._one_or_many import one_or_many
+from pyfect.schema import ast
+from pyfect.schema._schema import Bottom, Codec
+
+# Explicit covariant parameters: a frozen dataclass's fields would make
+# inferred ones invariant (``tests/test_schema_variance.py``).
+A_co = TypeVar("A_co", covariant=True)
+I_co = TypeVar("I_co", covariant=True)
+RD_co = TypeVar("RD_co", covariant=True)
+RE_co = TypeVar("RE_co", covariant=True)
+B = TypeVar("B")
+J = TypeVar("J")
+SD = TypeVar("SD")
+SE = TypeVar("SE")
+
+type LiteralValue = LiteralString | int | float | bool | None
+"""What a literal may be: a string, a number, a boolean or ``None``."""
+
+L_co = TypeVar("L_co", bound=LiteralValue, covariant=True)
+L_ = TypeVar("L_", bound=LiteralValue)
+"""Invariant: ``LiteralsSchema.pick`` takes literals of the union's type."""
+E_co = TypeVar("E_co", bound=enum.Enum, covariant=True)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class LiteralSchema(Bottom[L_co, L_co, Never, Never], Generic[L_co]):
+    """The schema of one value; ``literal`` is that value."""
+
+    literal: L_co
+
+
+def Literal[L: LiteralValue](literal: L, /) -> LiteralSchema[L]:
+    """Accepts ``literal`` only (a value of its kind: ``1`` is not ``True``
+    nor ``1.0``). A non-finite number raises ``ValueError``."""
+    return LiteralSchema(ast.Literal(literal), literal)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class UnionSchema(Bottom[A_co, I_co, RD_co, RE_co], Generic[A_co, I_co, RD_co, RE_co]):
+    """A union; ``members`` are its schemas, in order."""
+
+    members: tuple[Codec[A_co, I_co, RD_co, RE_co], ...]
+
+    def map_members(
+        self,
+        f: Callable[[tuple[Codec[A_co, I_co, RD_co, RE_co], ...]], Sequence[Codec[B, J, SD, SE]]],
+        /,
+        *,
+        unsafe_preserve_checks: bool = False,
+    ) -> UnionSchema[B, J, SD, SE]:
+        """The union, with the same mode, of the schemas ``f`` makes from the
+        members. Its checks are dropped unless ``unsafe_preserve_checks``
+        (they may not hold for the new members)."""
+        members = tuple(f(self.members))
+        union = cast("ast.Union", self.ast)
+        checks = union.checks if unsafe_preserve_checks else None
+        node = ast.Union(tuple(m.__codec__().ast for m in members), union.mode, checks=checks)
+        return UnionSchema(node, members)
+
+
+@overload
+def Union[A = Never, I = Never, RD = Never, RE = Never](
+    members: list[Codec[A, I, RD, RE]] | tuple[Codec[A, I, RD, RE], ...],
+    /,
+    *,
+    mode: ast.UnionMode = "any_of",
+) -> UnionSchema[A, I, RD, RE]: ...
+@overload
+def Union[A = Never, I = Never, RD = Never, RE = Never](
+    *members: Codec[A, I, RD, RE], mode: ast.UnionMode = "any_of"
+) -> UnionSchema[A, I, RD, RE]: ...
+def Union(*members: Any, mode: ast.UnionMode = "any_of") -> UnionSchema[Any, Any, Any, Any]:
+    """A value of any member, tried in order (``mode="one_of"``: of exactly
+    one, failing when several match). The members are given as arguments
+    or, as in Effect, as one list or tuple."""
+    members = one_or_many(members)
+    node = ast.Union(tuple(m.__codec__().ast for m in members), mode)
+    return UnionSchema(node, members)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class LiteralsSchema(Bottom[L_, L_, Never, Never], Generic[L_]):
+    """A union of literals; ``literals`` are the values, in order."""
+
+    literals: tuple[L_, ...]
+
+    @property
+    def members(self) -> tuple[LiteralSchema[L_], ...]:
+        return tuple(LiteralSchema(ast.Literal(lit), lit) for lit in self.literals)
+
+    @overload
+    def pick(self, literals: list[L_] | tuple[L_, ...], /) -> LiteralsSchema[L_]: ...
+    @overload
+    def pick(self, *literals: L_) -> LiteralsSchema[L_]: ...
+    def pick(self, *literals: Any) -> LiteralsSchema[L_]:
+        """The union of ``literals`` only (each one of this union's), given
+        as arguments or, as in Effect, as one list or tuple."""
+        return Literals(*literals)
+
+    def map_members(
+        self, f: Callable[[tuple[LiteralSchema[L_], ...]], Sequence[Codec[B, J, SD, SE]]], /
+    ) -> UnionSchema[B, J, SD, SE]:
+        """The union of the schemas ``f`` makes from the members."""
+        return Union(*f(self.members))
+
+
+@overload
+def Literals[L: LiteralValue](literals: list[L] | tuple[L, ...], /) -> LiteralsSchema[L]: ...
+@overload
+def Literals[L: LiteralValue](*literals: L) -> LiteralsSchema[L]: ...
+def Literals(*literals: Any) -> LiteralsSchema[Any]:
+    """Accepts any of ``literals`` (Effect's ``Literals``, a union of
+    ``Literal`` members): ``Expected "a" | "b"`` otherwise. The literals are
+    given as arguments or, as in Effect, as one list or tuple."""
+    literals = one_or_many(literals)
+    return LiteralsSchema(ast.Union(tuple(ast.Literal(lit) for lit in literals)), literals)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class EnumSchema(Bottom[E_co, str | int | float, Never, Never], Generic[E_co]):
+    """The members of the Python enum ``enums``, encoded as their values."""
+
+    enums: type[E_co]
+
+
+def Enum[E: enum.Enum](enums: type[E], /) -> EnumSchema[E]:
+    """Decodes a value of ``enums`` (or a member) to its member and encodes
+    a member to its value (Effect's ``Enum``, whose members are their
+    values). Values must be strings or finite numbers, else ``TypeError`` /
+    ``ValueError``."""
+    return EnumSchema(ast.Enum(enums), enums)