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" schemapyfect.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#
| Type | Definition | Description |
|---|---|---|
Definition | type 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], /) -> AA 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.
| Parameter | Type | Description |
|---|---|---|
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).
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, E, RD, RE] | |
default_value | Effect[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) -> AAn 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.
| Parameter | Type | Description |
|---|---|---|
value | A |
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 valueis_field#
is_field(value) -> TypeIs[Field[Any]]value is a variant field (Effect's isField).
| Parameter | Type | Description |
|---|---|---|
value | object |
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) -> Anyvariant's struct schema. With is_default, a variant class is
its own schema, and so is a variant class nested in it.
| Parameter | Type | Description |
|---|---|---|
self | HasVariants | |
variant | str | |
is_default | bool = 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 schemafields#
fields(self) -> Mapping[str, Definition]The field definitions of a variant struct or class (Effect's
fields).
| Parameter | Type | Description |
|---|---|---|
self | HasVariants |
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).
| Parameter | Type | Description |
|---|---|---|
value | object |
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) -> VariantSchemaA toolkit for variants (Effect's VariantSchema.make).
| Parameter | Type | Description |
|---|---|---|
variants | Sequence[str] | |
default_variant | str |
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)