GitHub

TaggedUnionSchema

API reference for TaggedUnionSchema.

A union of cases told apart by the literal under tag: discriminants are the literals in member order, cases and guards the case schema and its type guard by literal.

Attributes

AttributeTypeDescription
tagstr
discriminantstuple[LiteralValue, ...]
casesMapping[LiteralValue, Codec[A_co, I_co, RD_co, RE_co]]
guardsMapping[LiteralValue, Callable[[object], TypeGuard[A_co]]]

Functions

__init__

__init__(ast, members, tag, discriminants, cases, guards) -> None
ParameterTypeDescription
astAST
memberstuple[Codec[A_co, I_co, RD_co, RE_co], ...]
tagstr
discriminantstuple[LiteralValue, ...]
casesMapping[LiteralValue, Codec[A_co, I_co, RD_co, RE_co]]
guardsMapping[LiteralValue, Callable[[object], TypeGuard[A_co]]]

is_any_of

is_any_of[A](*literals) -> Callable[[A], bool]

Whether a value of the union is one of the cases of literals.

ParameterTypeDescription
literalsLiteralValue = ()

Returns Callable[[A], bool]

def is_any_of[A](
    self: TaggedUnionSchema[A, Any, Any, Any], *literals: LiteralValue
) -> Callable[[A], bool]:
    """Whether a value of the union is one of the cases of ``literals``."""
    tag = self.tag

    def test(value: A) -> bool:
        found = _tag_of(value, tag)
        return any(type(found) is type(lit) and found == lit for lit in literals)

    return test

match

match[A, T](cases: Mapping[LiteralValue, Callable[[A], T]], /) -> Callable[[A], T]
match[A, T](value: A, cases: Mapping[LiteralValue, Callable[[A], T]], /) -> T

cases' function for the case value is; given the cases alone, the function of the value.

ParameterTypeDescription
args= ()
@overload
def match[A, T](
    self: TaggedUnionSchema[A, Any, Any, Any],
    cases: Mapping[LiteralValue, Callable[[A], T]],
    /,
) -> Callable[[A], T]: ...
@overload
def match[A, T](
    self: TaggedUnionSchema[A, Any, Any, Any],
    value: A,
    cases: Mapping[LiteralValue, Callable[[A], T]],
    /,
) -> T: ...
def match(self, *args: Any) -> Any:
    """``cases``' function for the case ``value`` is; given the cases
    alone, the function of the value."""
    if len(args) == 1:
        cases_only = args[0]

        def apply(value: Any) -> Any:
            return cases_only[_tag_of(value, self.tag)](value)

        return apply
    value, cases = args
    return cases[_tag_of(value, self.tag)](value)

match_or_else

match_or_else[A, T](cases: Mapping[LiteralValue, Callable[[A], T]], or_else: Callable[[A], T], /) -> Callable[[A], T]
match_or_else[A, T](value: A, cases: Mapping[LiteralValue, Callable[[A], T]], or_else: Callable[[A], T], /) -> T

match, with or_else for a case cases leaves out.

ParameterTypeDescription
args= ()
@overload
def match_or_else[A, T](
    self: TaggedUnionSchema[A, Any, Any, Any],
    cases: Mapping[LiteralValue, Callable[[A], T]],
    or_else: Callable[[A], T],
    /,
) -> Callable[[A], T]: ...
@overload
def match_or_else[A, T](
    self: TaggedUnionSchema[A, Any, Any, Any],
    value: A,
    cases: Mapping[LiteralValue, Callable[[A], T]],
    or_else: Callable[[A], T],
    /,
) -> T: ...
def match_or_else(self, *args: Any) -> Any:
    """``match``, with ``or_else`` for a case ``cases`` leaves out."""
    if len(args) == 2:
        cases_only, otherwise = args

        def apply(value: Any) -> Any:
            return cases_only.get(_tag_of(value, self.tag), otherwise)(value)

        return apply
    value, cases, or_else = args
    return cases.get(_tag_of(value, self.tag), or_else)(value)

pipe

pipe[B](f) -> B

f(self). One function per call, as Effect.pipe.

ParameterTypeDescription
fCallable[[Self], B]

Returns B

def pipe[B](self, f: Callable[[Self], B], /) -> B:
    """``f(self)``. One function per call, as ``Effect.pipe``."""
    return f(self)

annotate

annotate(**annotations) -> Self

This schema with annotations merged over its own: identifier names it in messages (Expected <identifier>), message replaces its message, title / description / ... document it. On a schema with checks they annotate the last check.

ParameterTypeDescription
annotationsobject = {}

Returns Self

def annotate(self, /, **annotations: object) -> Self:
    """This schema with annotations merged over its own: ``identifier``
    names it in messages (``Expected <identifier>``), ``message``
    replaces its message, ``title`` / ``description`` / ... document it.
    On a schema with checks they annotate the last check."""
    return replace(self, ast=annotate(self.ast, annotations))

annotate_encoded

annotate_encoded(**annotations) -> Self

This schema with annotations on its encoded side (Effect's annotateEncoded); a schema without a transformation is its own encoded side.

ParameterTypeDescription
annotationsobject = {}

Returns Self

def annotate_encoded(self, /, **annotations: object) -> Self:
    """This schema with annotations on its encoded side (Effect's
    ``annotateEncoded``); a schema without a transformation is its own
    encoded side."""
    return replace(self, ast=annotate(self.ast.flip(), annotations).flip())

override_to_equivalence

override_to_equivalence[A, E, RD, RE](f) -> Bottom[A, E, RD, RE]

This schema compared by f() in S.to_equivalence (Effect's overrideToEquivalence).

ParameterTypeDescription
fCallable[[], Callable[[A, A], bool]]

Returns Bottom[A, E, RD, RE]

def override_to_equivalence[A, E, RD, RE](
    self: Bottom[A, E, RD, RE], f: Callable[[], Callable[[A, A], bool]], /
) -> Bottom[A, E, RD, RE]:
    """This schema compared by ``f()`` in ``S.to_equivalence`` (Effect's
    ``overrideToEquivalence``)."""

    def derive(_: tuple[object, ...]) -> Callable[[A, A], bool]:
        return f()

    return self.annotate(to_equivalence=derive)

override_to_formatter

override_to_formatter[A, E, RD, RE](f) -> Bottom[A, E, RD, RE]

This schema written by f() in S.to_formatter (Effect's overrideToFormatter).

ParameterTypeDescription
fCallable[[], Callable[[A], str]]

Returns Bottom[A, E, RD, RE]

def override_to_formatter[A, E, RD, RE](
    self: Bottom[A, E, RD, RE], f: Callable[[], Callable[[A], str]], /
) -> Bottom[A, E, RD, RE]:
    """This schema written by ``f()`` in ``S.to_formatter`` (Effect's
    ``overrideToFormatter``)."""

    def derive(_: tuple[object, ...]) -> Callable[[A], str]:
        return f()

    return self.annotate(to_formatter=derive)

annotate_key

annotate_key(**annotations) -> Self

This schema with annotations for the struct key holding it (Effect's annotateKey): message_missing_key replaces "Missing key".

ParameterTypeDescription
annotationsobject = {}

Returns Self

def annotate_key(self, /, **annotations: object) -> Self:
    """This schema with annotations for the struct key holding it
    (Effect's ``annotateKey``): ``message_missing_key`` replaces
    ``"Missing key"``."""
    key_annotations = {**(self.ast.key_annotations or {}), **annotations}
    return replace(self, ast=replace_context(self.ast, key_annotations=key_annotations))

check

check(first, *rest) -> Self

This schema with checks run, in order, on each value it accepts (S.is_min_length(3), S.make_filter(...), ...).

ParameterTypeDescription
firstCheck[T_co]
restCheck[T_co] = ()

Returns Self

def check(self, first: Check[T_co], /, *rest: Check[T_co]) -> Self:
    """This schema with checks run, in order, on each value it accepts
    (``S.is_min_length(3)``, ``S.make_filter(...)``, ...)."""
    return replace(self, ast=append_checks(self.ast, (first, *rest)))

make

make[A](input, **options) -> A

input checked against the decoded side, its missing keys and elements filled by their constructor defaults (with_constructor_default); raises SchemaError.

ParameterTypeDescription
inputA
optionsUnpack[ParseOptions] = {}

Returns A

def make[A](
    self: Bottom[A, object, object, object], input: A, /, **options: Unpack[ParseOptions]
) -> A:
    """``input`` checked against the decoded side, its missing keys and
    elements filled by their constructor defaults
    (``with_constructor_default``); raises ``SchemaError``."""
    match run_now(Maker(self.ast.to_type()).parse(input, options, True)):
        case Success(value):
            return cast("A", value)
        case failure:
            raise_schema_failure(failure.cause.map(SchemaError), CONSTRUCTOR)

make_option

make_option[A](input, **options) -> Option[A]

Some(value), or None when input is invalid.

ParameterTypeDescription
inputA
optionsUnpack[ParseOptions] = {}

Returns Option[A]

def make_option[A](
    self: Bottom[A, object, object, object], input: A, /, **options: Unpack[ParseOptions]
) -> Option[A]:
    """``Some(value)``, or ``None`` when ``input`` is invalid."""
    match run_now(Maker(self.ast.to_type()).parse(input, options, True)):
        case Success(value):
            return Some(cast("A", value))
        case failure:
            schema_error_of(failure.cause.map(SchemaError), OPTION)
            return None

make_effect

make_effect[A](input, **options) -> Effect[A, Issue]

make as an effect failing with the bare Issue, as Effect's makeEffect (so an enclosing schema can add its path).

ParameterTypeDescription
inputA
optionsUnpack[ParseOptions] = {}

Returns Effect[A, Issue]

def make_effect[A](
    self: Bottom[A, object, object, object], input: A, /, **options: Unpack[ParseOptions]
) -> Effect[A, Issue]:
    """``make`` as an effect failing with the bare ``Issue``, as Effect's
    ``makeEffect`` (so an enclosing schema can add its path)."""
    parsed = Maker(self.ast.to_type()).parse(input, options, False)
    return cast("Effect[A, Issue]", to_effect(parsed))

map_members

map_members(f, /, *, unsafe_preserve_checks=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).

ParameterTypeDescription
fCallable[[tuple[Codec[A_co, I_co, RD_co, RE_co], ...]], Sequence[Codec[B, J, SD, SE]]]
unsafe_preserve_checksbool = False

Returns UnionSchema[B, J, SD, SE]

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)