pyfect-dev 0.1.0__py3-none-any.whl

pyfect/schema/representation/_to.py

@@ -0,0 +1,249 @@
+"""``to_representation`` / ``to_representations``: a schema's encoded side
+as a document (Effect's ``toRepresentation``).
+
+Each position is the node at the end of its encoding chain (a class: its
+fields' struct), so the document describes what the schema decodes from;
+``S.to_type(schema)`` gives the decoded side instead. Which nodes become
+named ``references`` is decided as for JSON Schema definitions (shared
+with ``to_json_schema_document``): by default a node with an
+``identifier``, and every recursive node.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import cast
+
+from pyfect.schema import ast
+from pyfect.schema._jsonschema._annotations import ReferencePolicy
+from pyfect.schema._jsonschema._checks import schemas_of
+from pyfect.schema._jsonschema._references import FALLBACK_KEY, Candidate, Content, References
+from pyfect.schema._schema import Top
+from pyfect.schema._undefined import OBJECT_KEYWORD_ID, UNDEFINED_ID, VOID_ID
+from pyfect.schema.representation import _model as R
+
+
+def to_representation(
+    schema: Top, /, *, reference_policy: ReferencePolicy | None = None
+) -> R.Document:
+    """The document of ``schema``'s encoded side. ``reference_policy``
+    names the nodes that become references (default: their
+    ``identifier``); a recursive node is one whatever it says."""
+    multi = to_representations((schema,), reference_policy=reference_policy)
+    return R.Document(multi.representations[0], multi.references)
+
+
+def to_representations(
+    schemas: tuple[Top, *tuple[Top, ...]], /, *, reference_policy: ReferencePolicy | None = None
+) -> R.MultiDocument:
+    """The documents of several schemas, sharing their references."""
+    roots = [schema.__codec__().ast for schema in schemas]
+    lowering = _Lowering(References(roots, reference_policy))
+    first, *rest = (lowering.recur(root) for root in roots)
+    return R.MultiDocument((first, *rest), lowering.references)
+
+
+class _Lowering:
+    def __init__(self, candidates: References) -> None:
+        self.candidates = candidates
+        self.references: dict[str, R.Representation] = {}
+        self._emitted: set[int] = set()
+
+    def recur(self, node: ast.AST) -> R.Representation:
+        return self.recur_candidate(self.candidates.candidate(node))
+
+    def recur_candidate(self, candidate: Candidate) -> R.Representation:
+        reference = candidate.reference
+        if reference is None:
+            return self.on(candidate.ast, candidate.content)
+        if id(candidate) not in self._emitted:
+            self._emitted.add(id(candidate))
+            node = candidate.ast
+            if candidate.identifier is not None:
+                node = _annotate_reference(node, candidate, reference)
+            # Inserted after lowering: a recursive body's references come
+            # first, as in Effect.
+            self.references[reference] = self.on(node, candidate.content)
+        return R.Reference(reference)
+
+    def on(self, node: ast.AST, content: Content | None) -> R.Representation:  # noqa: PLR0911, PLR0912
+        checks = tuple(self.check(c) for c in node.checks or ())
+        annotations = _annotations(node.annotations)
+        match node:
+            case ast.Null():
+                return R.Null(annotations=annotations, checks=checks)
+            case ast.Never():
+                return R.Never(annotations=annotations, checks=checks)
+            case ast.Unknown():
+                return R.Unknown(annotations=annotations, checks=checks)
+            case ast.Any():
+                return R.Any(annotations=annotations, checks=checks)
+            case ast.String():
+                held = None
+                if content is not None:
+                    schema = content.schema
+                    inner = None if schema is None else self.recur_candidate(schema)
+                    held = R.Content(content.media_type, inner)
+                return R.String(annotations=annotations, checks=checks, content=held)
+            case ast.Number():
+                return R.Number(annotations=annotations, checks=checks)
+            case ast.Boolean():
+                return R.Boolean(annotations=annotations, checks=checks)
+            case ast.BigInt():
+                return R.BigInt(annotations=annotations, checks=checks)
+            case ast.Literal(literal=None):
+                return R.Null(annotations=annotations, checks=checks)
+            case ast.Literal(literal=literal) if literal is not None:
+                return R.Literal(literal, annotations=annotations, checks=checks)
+            case ast.Enum():
+                enums = tuple((m.name, cast("R.EnumValue", m.value)) for m in node.enum)
+                return R.Enum(enums, annotations=annotations, checks=checks)
+            case ast.TemplateLiteral():
+                parts = tuple(self.recur(p) for p in node.parts)
+                return R.TemplateLiteral(parts, annotations=annotations, checks=checks)
+            case ast.Arrays():
+                elements = tuple(
+                    R.Element(
+                        self.recur(e.type),
+                        e.optional_when_encoded(),
+                        _annotations(e.type.key_annotations),
+                    )
+                    for e in node.elements
+                )
+                rest = tuple(self.recur(r) for r in node.rest)
+                return R.Arrays(elements, rest, annotations=annotations, checks=checks)
+            case ast.Objects():
+                return self.objects(node, annotations, checks)
+            case ast.Union():
+                types = tuple(self.recur(t) for t in node.types)
+                return R.Union(types, node.mode, annotations=annotations, checks=checks)
+            case ast.Suspend():
+                return R.Suspend(self.recur(node.target), annotations)
+            case ast.Declaration():
+                keyword = _keyword_of(node.annotations)
+                if keyword is not None:
+                    return keyword(annotations=_without_builtin(node.annotations), checks=checks)
+                return self.declaration(node.type_parameters, node.annotations, checks)
+            case ast.Class():
+                # A class's instances (its decoded side): a declaration of
+                # its fields.
+                fields = node.shape.fields.to_type()
+                return self.declaration((fields,), node.annotations, checks)
+            case _:
+                raise TypeError(f"Cannot represent a {node.tag} node")
+
+    def objects(
+        self, node: ast.Objects, annotations: R.Annotations | None, checks: tuple[R.Check, ...]
+    ) -> R.Objects:
+        properties: list[R.PropertySignature] = []
+        for p in node.properties:
+            name = p.name
+            if not isinstance(name, str | int | float) or isinstance(name, bool):
+                raise TypeError(f"Cannot represent the property name {name!r}")
+            optional = p.optional_when_encoded()
+            key_annotations = _annotations(p.type.key_annotations)
+            properties.append(
+                R.PropertySignature(name, self.recur(p.type), optional, key_annotations)
+            )
+        indexes = tuple(
+            R.IndexSignature(self.recur(i.parameter), self.recur(i.type))
+            for i in node.index_signatures
+        )
+        return R.Objects(tuple(properties), indexes, annotations=annotations, checks=checks)
+
+    def declaration(
+        self,
+        parameters: Sequence[ast.AST],
+        annotations: ast.Annotations | None,
+        checks: tuple[R.Check, ...],
+    ) -> R.Declaration:
+        representation, ordinary = _split(annotations)
+        declared = None
+        if representation is not None:
+            declared = R.RepresentationAnnotation(
+                cast("str", representation.get("id")), cast("R.Json", representation.get("payload"))
+            )
+        return R.Declaration(
+            tuple(self.recur(p) for p in parameters),
+            annotations=ordinary,
+            checks=checks,
+            representation=declared,
+        )
+
+    def check(self, check: ast.Check[object]) -> R.Check:
+        representation, ordinary = _split(check.annotations)
+        identity = None
+        if representation is not None:
+            schemas = (
+                tuple(self.recur(s) for s in self.candidates.check_schemas(check))
+                if "schemas" in representation and schemas_of(check.annotations)
+                else None
+            )
+            identity = R.CheckRepresentationAnnotation(
+                cast("str", representation.get("id")),
+                cast("R.Json", representation.get("payload")),
+                schemas,
+            )
+        if isinstance(check, ast.Filter):
+            return R.Filter(identity, ordinary, check.aborted)
+        first, *rest = (self.check(c) for c in check.checks)
+        return R.FilterGroup((first, *rest), identity, ordinary)
+
+
+def _annotations(annotations: ast.Annotations | None) -> R.Annotations | None:
+    return annotations or None
+
+
+_KEYWORD_DECLARATIONS: Mapping[object, type[R.Undefined | R.Void | R.ObjectKeyword]] = {
+    UNDEFINED_ID: R.Undefined,
+    VOID_ID: R.Void,
+    OBJECT_KEYWORD_ID: R.ObjectKeyword,
+}
+"""What pyfect declares (Python's AST has no such keywords) and Effect has as nodes."""
+
+_BUILTIN_ANNOTATIONS = frozenset(
+    {"expected", "representation", "to_arbitrary", "to_codec_json", "to_codec_string_tree"}
+)
+
+
+def _keyword_of(
+    annotations: ast.Annotations | None,
+) -> type[R.Undefined | R.Void | R.ObjectKeyword] | None:
+    representation = (annotations or {}).get("representation")
+    if not isinstance(representation, Mapping):
+        return None
+    return _KEYWORD_DECLARATIONS.get(cast("Mapping[str, object]", representation).get("id"))
+
+
+def _without_builtin(annotations: ast.Annotations | None) -> R.Annotations | None:
+    return {k: v for k, v in (annotations or {}).items() if k not in _BUILTIN_ANNOTATIONS} or None
+
+
+def _split(
+    annotations: ast.Annotations | None,
+) -> tuple[Mapping[str, object] | None, R.Annotations | None]:
+    """A check's or a declaration's ``representation`` annotation apart
+    from its other annotations."""
+    if not annotations:
+        return None, None
+    representation = annotations.get("representation")
+    ordinary = {k: v for k, v in annotations.items() if k != "representation"}
+    found = (
+        cast("Mapping[str, object]", representation)
+        if isinstance(representation, Mapping)
+        else None
+    )
+    return found, ordinary or None
+
+
+def _annotate_reference(node: ast.AST, candidate: Candidate, reference: str) -> ast.AST:
+    """``node`` annotated with the name its reference got (or, when it is
+    named after the node it was reached from, that node's identifier)."""
+    fallback = candidate.fallback
+    if fallback is not None:
+        if (node.resolve() or {}).get(FALLBACK_KEY) == fallback:
+            return node
+        return ast.annotate(node, {FALLBACK_KEY: fallback})
+    if reference == candidate.identifier:
+        return node
+    return ast.annotate(node, {"identifier": reference})

pyfect/schema/transformation/__init__.py

@@ -0,0 +1,99 @@
+"""Transformations (Effect's ``SchemaTransformation``): a decoding getter
+and an encoding one, which ``S.decode_to`` puts between two schemas::
+
+    from pyfect.schema import transformation as T
+
+    S.String.pipe(S.decode_to(S.Number, T.number_from_string))
+    T.transform(decode=int, encode=str)
+
+A ``Middleware`` instead takes the source's whole parse, failures
+included (``S.middleware_decoding``, ``S.catch_decoding``).
+"""
+
+from pyfect.schema.transformation._builtins import (
+    big_decimal_from_string,
+    big_int_from_string,
+    byte_size_from_big_int,
+    byte_size_from_number,
+    byte_size_from_string,
+    bytes_from_base64_string,
+    capitalize,
+    date_time_utc_from_string,
+    date_time_zoned_from_string,
+    from_json_string,
+    number_from_string,
+    option_from_null_or,
+    option_from_optional_key,
+    snake_to_camel,
+    split_key_value,
+    string_from_base64_string,
+    string_from_base64_url_string,
+    string_from_hex_string,
+    string_from_uri_component,
+    time_zone_from_string,
+    time_zone_named_from_string,
+    time_zone_offset_from_number,
+    to_lower_case,
+    to_upper_case,
+    trim,
+    uncapitalize,
+    url_from_string,
+)
+from pyfect.schema.transformation._durations import (
+    duration_from_millis,
+    duration_from_nanos,
+    duration_from_string,
+)
+from pyfect.schema.transformation._transformation import (
+    Middleware,
+    Transformation,
+    is_transformation,
+    passthrough,
+    passthrough_subtype,
+    passthrough_supertype,
+    transform,
+    transform_effect,
+    transform_optional,
+)
+
+__all__ = [
+    "Middleware",
+    "Transformation",
+    "big_decimal_from_string",
+    "big_int_from_string",
+    "byte_size_from_big_int",
+    "byte_size_from_number",
+    "byte_size_from_string",
+    "bytes_from_base64_string",
+    "capitalize",
+    "date_time_utc_from_string",
+    "date_time_zoned_from_string",
+    "duration_from_millis",
+    "duration_from_nanos",
+    "duration_from_string",
+    "from_json_string",
+    "is_transformation",
+    "number_from_string",
+    "option_from_null_or",
+    "option_from_optional_key",
+    "passthrough",
+    "passthrough_subtype",
+    "passthrough_supertype",
+    "snake_to_camel",
+    "split_key_value",
+    "string_from_base64_string",
+    "string_from_base64_url_string",
+    "string_from_hex_string",
+    "string_from_uri_component",
+    "time_zone_from_string",
+    "time_zone_named_from_string",
+    "time_zone_offset_from_number",
+    "to_lower_case",
+    "to_upper_case",
+    "transform",
+    "transform_effect",
+    "transform_optional",
+    "trim",
+    "uncapitalize",
+    "url_from_string",
+]

pyfect/schema/transformation/_builtins.py

@@ -0,0 +1,314 @@
+"""The built-in transformations of Effect's ``SchemaTransformation``.
+
+Python mappings: bytes are ``bytes`` (Effect's ``Uint8Array``), a URL is a
+``Url`` (a ``urllib.parse.SplitResult``), a UTC date-time an aware ``datetime`` in UTC,
+a zone a ``ZoneInfo`` / ``timezone``, an ``Option`` is ``Some | None``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime, timedelta, timezone, tzinfo
+from typing import Any
+from urllib.parse import urlunsplit
+from zoneinfo import ZoneInfo
+
+from pyfect import big_decimal, byte_size
+from pyfect._url import Url, parse_url
+from pyfect.date_time import (
+    format_iso,
+    format_iso_zoned,
+    make_zoned_from_string,
+    zone_from_string,
+    zone_named,
+    zone_to_string,
+)
+from pyfect.exit import Exit, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.option import Option, Some
+from pyfect.schema._options import ParseOptions
+from pyfect.schema.getter import (
+    big_int,
+    camel_to_snake,
+    decode_base64,
+    decode_base64_string,
+    decode_base64_url_string,
+    decode_hex_string,
+    decode_uri_component,
+    encode_base64,
+    encode_base64_url,
+    encode_hex,
+    encode_uri_component,
+    join_key_value,
+    number,
+    parse_json,
+    string,
+    stringify_json,
+)
+from pyfect.schema.getter import (
+    capitalize as capitalize_getter,
+)
+from pyfect.schema.getter import (
+    passthrough as passthrough_getter,
+)
+from pyfect.schema.getter import (
+    snake_to_camel as snake_to_camel_getter,
+)
+from pyfect.schema.getter import (
+    split_key_value as split_key_value_getter,
+)
+from pyfect.schema.getter import (
+    to_lower_case as to_lower_case_getter,
+)
+from pyfect.schema.getter import (
+    to_upper_case as to_upper_case_getter,
+)
+from pyfect.schema.getter import (
+    transform_optional as transform_optional_getter,
+)
+from pyfect.schema.getter import (
+    trim as trim_getter,
+)
+from pyfect.schema.getter import (
+    uncapitalize as uncapitalize_getter,
+)
+from pyfect.schema.getter._coerce import to_utc
+from pyfect.schema.issue import InvalidValue, Issue, reported
+from pyfect.schema.transformation._transformation import (
+    Content,
+    Transformation,
+    transform,
+    transform_effect,
+)
+
+
+def _decoded_only(decode: Any) -> Transformation[str, str]:
+    return Transformation(decode, passthrough_getter())
+
+
+def trim() -> Transformation[str, str]:
+    """Trims when decoding, keeps the value when encoding."""
+    return _decoded_only(trim_getter())
+
+
+def snake_to_camel() -> Transformation[str, str]:
+    """``snake_case`` to ``camelCase``, and back."""
+    return Transformation(snake_to_camel_getter(), camel_to_snake())
+
+
+def to_lower_case() -> Transformation[str, str]:
+    return _decoded_only(to_lower_case_getter())
+
+
+def to_upper_case() -> Transformation[str, str]:
+    return _decoded_only(to_upper_case_getter())
+
+
+def capitalize() -> Transformation[str, str]:
+    return _decoded_only(capitalize_getter())
+
+
+def uncapitalize() -> Transformation[str, str]:
+    return _decoded_only(uncapitalize_getter())
+
+
+def split_key_value(
+    *, separator: str = ",", key_value_separator: str = "="
+) -> Transformation[dict[str, str], str]:
+    """``"a=1,b=2"`` and ``{"a": "1", "b": "2"}``."""
+    split = split_key_value_getter(separator=separator, key_value_separator=key_value_separator)
+    join = join_key_value(separator=separator, key_value_separator=key_value_separator)
+    return Transformation(split, join)
+
+
+number_from_string: Transformation[float, str] = Transformation(number(), string())
+"""JavaScript's ``Number(text)`` and ``String(number)``."""
+
+big_int_from_string: Transformation[int, str] = Transformation(big_int(), string())
+"""JavaScript's ``BigInt(text)`` and ``String(bigint)``."""
+
+
+def _invalid[A](expected: str, input: object, options: ParseOptions) -> Exit[A, Issue]:
+    return fail_exit(InvalidValue({"expected": expected}, reported(input, options)))
+
+
+def _parsed[A](
+    parse: Callable[[str], A | None], expected: str
+) -> Callable[[str, ParseOptions], Exit[A, Issue]]:
+    def run(text: str, options: ParseOptions) -> Exit[A, Issue]:
+        out = parse(text)
+        return _invalid(expected, text, options) if out is None else Success(out)
+
+    return run
+
+
+def _done[A](f: Callable[[Any], A]) -> Callable[[Any, ParseOptions], Exit[A, Issue]]:
+    return lambda value, _: Success(f(value))
+
+
+url_from_string: Transformation[Url, str] = transform_effect(
+    decode=_parsed(parse_url, "a valid URL string"), encode=_done(urlunsplit)
+)
+"""A URL and its text (Effect's ``urlFromString``)."""
+
+
+def _format_big_decimal(value: big_decimal.BigDecimal) -> str:
+    return value.format()
+
+
+big_decimal_from_string: Transformation[big_decimal.BigDecimal, str] = transform_effect(
+    decode=_parsed(big_decimal.from_string, "a valid BigDecimal string"),
+    encode=_done(_format_big_decimal),
+)
+"""A ``BigDecimal`` and its text (Effect's ``bigDecimalFromString``)."""
+
+
+def _utc_from_string(text: str) -> datetime | None:
+    return to_utc(text)
+
+
+date_time_utc_from_string: Transformation[datetime, str] = transform_effect(
+    decode=_parsed(_utc_from_string, "a valid UTC DateTime string"), encode=_done(format_iso)
+)
+"""A UTC ``datetime`` and its ISO 8601 text, in milliseconds as
+``DateTime.formatIso`` (Effect's ``dateTimeUtcFromString``)."""
+
+date_time_zoned_from_string: Transformation[datetime, str] = transform_effect(
+    decode=_parsed(make_zoned_from_string, "a valid Zoned DateTime string"),
+    encode=_done(format_iso_zoned),
+)
+"""A zoned ``datetime`` and its RFC 9557 text (Effect's
+``dateTimeZonedFromString``)."""
+
+
+def _zone_id(zone: ZoneInfo) -> str:
+    return zone.key
+
+
+time_zone_named_from_string: Transformation[ZoneInfo, str] = transform_effect(
+    decode=_parsed(zone_named, "a valid IANA time zone"), encode=_done(_zone_id)
+)
+"""A named zone and its IANA identifier (Effect's ``timeZoneNamedFromString``)."""
+
+
+time_zone_from_string: Transformation[tzinfo, str] = transform_effect(
+    decode=_parsed(zone_from_string, "a valid time zone"), encode=_done(zone_to_string)
+)
+"""A zone and its text: an IANA identifier or an offset like ``+03:00``
+(Effect's ``timeZoneFromString``)."""
+
+
+_DAY_MS = 86_400_000
+
+
+def _offset_of(millis: int) -> timezone | None:
+    # Python's offsets are strictly inside a day (Effect's are not bounded).
+    return timezone(timedelta(milliseconds=millis)) if abs(millis) < _DAY_MS else None
+
+
+def _offset_millis(zone: timezone) -> int:
+    return (zone.utcoffset(None) // timedelta(microseconds=1)) // 1000
+
+
+def _decode_offset(millis: int, options: ParseOptions) -> Exit[timezone, Issue]:
+    out = _offset_of(millis)
+    expected = "an offset strictly between -24 and +24 hours"
+    return _invalid(expected, millis, options) if out is None else Success(out)
+
+
+time_zone_offset_from_number: Transformation[timezone, int] = transform_effect(
+    decode=_decode_offset, encode=_done(_offset_millis)
+)
+"""A fixed-offset zone and its offset in milliseconds (Effect's
+``timeZoneOffsetFromNumber``); the offset is strictly inside a day."""
+
+
+def _byte_size_text(size: int) -> str:
+    return f"{size} {'byte' if size == 1 else 'bytes'}"
+
+
+byte_size_from_string: Transformation[byte_size.ByteSize, str] = transform_effect(
+    decode=_parsed(byte_size.from_string, "a valid ByteSize string"),
+    encode=_done(_byte_size_text),
+)
+"""A ``ByteSize`` and its text, ``"1 byte"`` / ``"<n> bytes"``."""
+
+byte_size_from_big_int: Transformation[byte_size.ByteSize, int] = transform_effect(
+    decode=lambda n, options: _sized(n, "a non-negative bigint byte count", options),
+    encode=_done(int),
+)
+"""A ``ByteSize`` and its count, an ``int``."""
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _sized(value: float, expected: str, options: ParseOptions) -> Exit[byte_size.ByteSize, Issue]:
+    out = byte_size.from_input(value)
+    return _invalid(expected, value, options) if out is None else Success(out)
+
+
+def _safe_count(size: byte_size.ByteSize, options: ParseOptions) -> Exit[float, Issue]:
+    if size > _MAX_SAFE_INTEGER:
+        return _invalid("a ByteSize representable as a safe integer", size, options)
+    return Success(size)
+
+
+def _sized_number(value: float, options: ParseOptions) -> Exit[byte_size.ByteSize, Issue]:
+    # A Python ``int`` is also a JavaScript number here: only a safe one counts.
+    if isinstance(value, int) and value > _MAX_SAFE_INTEGER:
+        return _invalid("a non-negative safe-integer byte count", value, options)
+    return _sized(value, "a non-negative safe-integer byte count", options)
+
+
+byte_size_from_number: Transformation[byte_size.ByteSize, float] = transform_effect(
+    decode=_sized_number, encode=_safe_count
+)
+"""A ``ByteSize`` and its count as a number (a safe integer)."""
+
+bytes_from_base64_string: Transformation[bytes, str] = Transformation(
+    decode_base64(), encode_base64()
+)
+"""Bytes and their Base64 text (Effect's ``uint8ArrayFromBase64String``)."""
+
+string_from_base64_string: Transformation[str, str] = Transformation(
+    decode_base64_string(), encode_base64()
+)
+string_from_base64_url_string: Transformation[str, str] = Transformation(
+    decode_base64_url_string(), encode_base64_url()
+)
+string_from_hex_string: Transformation[str, str] = Transformation(decode_hex_string(), encode_hex())
+string_from_uri_component: Transformation[str, str] = Transformation(
+    decode_uri_component(), encode_uri_component()
+)
+
+
+def from_json_string(*, space: int | str | None = None) -> Transformation[object, str]:
+    """A JSON value and its text, indented by ``space`` (Effect's
+    ``fromJsonString``)."""
+    return Transformation(
+        parse_json(), stringify_json(space=space), Content("application/json", preserve_schema=True)
+    )
+
+
+def option_from_null_or[T]() -> Transformation[Option[T], T | None]:
+    """``None`` is an empty ``Option``; a value is ``Some``. Python's one
+    ``None`` makes the decoded side ``Some(value)`` or ``None``."""
+    return transform(decode=_some_unless_none, encode=_value_or_none)
+
+
+def _some_unless_none[T](value: T | None) -> Option[T]:
+    return None if value is None else Some(value)
+
+
+def _value_or_none[T](option: Option[T]) -> T | None:
+    return None if option is None else option.value
+
+
+def option_from_optional_key[T]() -> Transformation[Option[T], T]:
+    """A missing key is ``None``, a present one ``Some(value)``; encoding
+    leaves the key out for ``None`` (Effect's ``optionFromOptionalKey``)."""
+    return Transformation(transform_optional_getter(Some), transform_optional_getter(_flatten))
+
+
+def _flatten[T](option: Option[Option[T]]) -> Option[T]:
+    return None if option is None else option.value