GitHub

variant_schema

API reference for variant_schema.

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).

Re-exports

Types

TypeDefinitionDescription
Definitiontype Definition = AnyCodec | Field[Any] | HasVariants

What a variant struct's field may be.

Classes

Functions

field

field[A](spec: Field[A], /) -> A
field(spec: Struct, /) -> Mapping[str, object]
field[A](spec: Codec[A, Any, Any, Any], /) -> A

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.

ParameterTypeDescription
spec
@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})

Overrideable

Overrideable[T, E, RD, RE](schema, /, *, default_value) -> 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).

ParameterTypeDescription
schemaCodec[T, E, RD, RE]
default_valueEffect[T, Never, Never]

Returns WithConstructorDefault[T, E, RD, RE]

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)

override

override[A](value) -> 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.

ParameterTypeDescription
valueA

Returns A

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

is_field

is_field(value) -> TypeIs[Field[Any]]

value is a variant field (Effect's isField).

ParameterTypeDescription
valueobject

Returns TypeIs[Field[Any]]

def is_field(value: object) -> TypeIs[Field[Any]]:
    """``value`` is a variant field (Effect's ``isField``)."""
    return isinstance(value, Field)

extract

extract(self, variant, *, is_default=False) -> Any

variant's struct schema. With is_default, a variant class is its own schema, and so is a variant class nested in it.

ParameterTypeDescription
selfHasVariants
variantstr
is_defaultbool = False

Returns Any

def extract(self: HasVariants, variant: str, *, is_default: bool = False) -> Any:
    """``variant``'s struct schema. With ``is_default``, a variant class is
    its own schema, and so is a variant class nested in it."""
    if is_default and is_schema(self):
        return self
    cache = self.__variant_cache__(is_default)
    found = cache.get(variant)
    if found is not None:
        return found
    selected: dict[str, AnyCodec] = {}
    for key, value in self.__variant_fields__().items():
        if isinstance(value, HasVariants):
            keep = is_default and is_schema(value)
            selected[key] = cast("AnyCodec", value) if keep else extract(value, variant)
        elif isinstance(value, Field):
            schema = value.schemas.get(variant)
            if schema is not None:
                selected[key] = schema
        else:
            selected[key] = value
    schema = variant_struct_schema(selected)
    cache[variant] = schema
    return schema

fields

fields(self) -> Mapping[str, Definition]

The field definitions of a variant struct or class (Effect's fields).

ParameterTypeDescription
selfHasVariants

Returns Mapping[str, Definition]

def fields(self: HasVariants, /) -> Mapping[str, Definition]:
    """The field definitions of a variant struct or class (Effect's
    ``fields``)."""
    return self.__variant_fields__()

is_struct

is_struct(value) -> TypeIs[HasVariants]

value is a variant struct or a variant class (Effect's isStruct).

ParameterTypeDescription
valueobject

Returns TypeIs[HasVariants]

def is_struct(value: object) -> TypeIs[HasVariants]:
    """``value`` is a variant struct or a variant class (Effect's
    ``isStruct``)."""
    return isinstance(value, HasVariants)

make

make(*, variants, default_variant) -> VariantSchema

A toolkit for variants (Effect's VariantSchema.make).

ParameterTypeDescription
variantsSequence[str]
default_variantstr

Returns VariantSchema

def make(*, variants: Sequence[str], default_variant: str) -> VariantSchema:
    """A toolkit for ``variants`` (Effect's ``VariantSchema.make``)."""
    if isinstance(variants, str) or default_variant not in variants:
        raise ValueError(f"default_variant {default_variant!r} is not one of {variants!r}")
    return VariantSchema(tuple(variants), default_variant)