Models (Effect's effect/schema/Model): one class for a table's row
and the variants a database and a JSON API read and write::
from pyfect.schema import model as Model
class UserInsert(TypedDict):
name: str
created_at: NotRequired[datetime]
class User(Model.Class[UserInsert]):
id: int = Model.field(Model.GeneratedByDb(S.Int))
name: str
created_at: datetime = Model.field(Model.DateTimeInsert)
password: str = Model.field(Model.Sensitive(S.String)) # left out of the JSON variants
User # the select variant
User.insert.make({"name": "Ada"}) # created_at set to now
User.json # what a JSON API sendsThe variants are select, insert, update, json,
json_create and json_update. A field annotated plainly is in every
variant; Model.field(...) gives a variant field (GeneratedByDb,
Sensitive, FieldOption, DateTimeInsert, field_only([...]),
...), whose select Type the annotation must be. A field the
select variant leaves out is assigned without an annotation.
pyfect.sql.model makes repositories of models. The variants' Types are
the TypedDicts given as Model.Class's type arguments (see Class).
Re-exports#
Values#
| Attribute | Type | Description |
|---|---|---|
Date | DecodeToSchema[datetime, str] | A date ( |
DateTimeFromDateWithNow | WithConstructorDefault[datetime, datetime, Never, Never] | |
DateTimeFromNumberWithNow | WithConstructorDefault[datetime, int, Never, Never] | |
DateTimeInsert | Field[datetime] | A creation timestamp stored as ISO text: set to now when inserted. |
DateTimeInsertFromDate | Field[datetime] | A creation timestamp the driver reads as a |
DateTimeInsertFromNumber | Field[datetime] | A creation timestamp stored as epoch milliseconds. |
DateTimeUpdate | Field[datetime] | An update timestamp stored as ISO text: set to now when inserted or updated. |
DateTimeUpdateFromDate | Field[datetime] | An update timestamp the driver reads as a |
DateTimeUpdateFromNumber | Field[datetime] | An update timestamp stored as epoch milliseconds. |
DateTimeWithNow | WithConstructorDefault[datetime, str, Never, Never] | |
DateWithNow | WithConstructorDefault[datetime, str, Never, Never] | |
BooleanSqlite | Field[bool] | A boolean stored as |
optional_option | (schema: Codec[A@OptionFromOptionalNullOr, I@OptionFromOptionalNullOr, RD@OptionFromOptionalNullOr, RE@OptionFromOptionalNullOr], /, *, on_none_encoding: Literal['omit'] | None = "omit") -> DecodeToSchema[Some[A@OptionFromOptionalNullOr] | None, I@OptionFromOptionalNullOr | None, RD@OptionFromOptionalNullOr, RE@OptionFromOptionalNullOr] | A key that may be missing or |
Types#
| Type | Definition | Description |
|---|---|---|
Variant | type Variant = Literal['select', 'insert', 'update', 'json', 'json_create', 'json_update'] | A model variant: |
VariantsDatabase | type VariantsDatabase = Literal['select', 'insert', 'update'] | |
VariantsJson | type VariantsJson = Literal['json', 'json_create', 'json_update'] |
Classes#
Functions#
extract#
extract[C: VariantClass](self: type[C], variant: Literal['select'], /) -> type[C]
extract[X: _TD](self: type[Class[X, Any, Any, Any, Any]], variant: Literal['insert'], /) -> VariantStructSchema[X]
extract[X: _TD](self: type[Class[Any, X, Any, Any, Any]], variant: Literal['update'], /) -> VariantStructSchema[X]
extract[X: _TD](self: type[Class[Any, Any, X, Any, Any]], variant: Literal['json'], /) -> VariantStructSchema[X]
extract[X: _TD](self: type[Class[Any, Any, Any, X, Any]], variant: Literal['json_create'], /) -> VariantStructSchema[X]
extract[X: _TD](self: type[Class[Any, Any, Any, Any, X]], variant: Literal['json_update'], /) -> VariantStructSchema[X]
extract(self: Struct, variant: Variant, /) -> VariantStructSchema[_TD]variant's struct schema of a model or a model struct (Effect's
Model.extract); a model's select variant is the class itself.
| Parameter | Type | Description |
|---|---|---|
self | ||
variant |
@overload
def extract[C: VariantClass](self: type[C], variant: Literal["select"], /) -> type[C]: ...
@overload
def extract[X: _TD](
self: type[Class[X, Any, Any, Any, Any]], variant: Literal["insert"], /
) -> VariantStructSchema[X]: ...
@overload
def extract[X: _TD](
self: type[Class[Any, X, Any, Any, Any]], variant: Literal["update"], /
) -> VariantStructSchema[X]: ...
@overload
def extract[X: _TD](
self: type[Class[Any, Any, X, Any, Any]], variant: Literal["json"], /
) -> VariantStructSchema[X]: ...
@overload
def extract[X: _TD](
self: type[Class[Any, Any, Any, X, Any]], variant: Literal["json_create"], /
) -> VariantStructSchema[X]: ...
@overload
def extract[X: _TD](
self: type[Class[Any, Any, Any, Any, X]], variant: Literal["json_update"], /
) -> VariantStructSchema[X]: ...
@overload
def extract(self: Struct, variant: Variant, /) -> VariantStructSchema[_TD]: ...
def extract(self: HasVariants, variant: Variant, /) -> Any:
"""``variant``'s struct schema of a model or a model struct (Effect's
``Model.extract``); a model's ``select`` variant is the class itself."""
return TOOLKIT.extract(self, variant)fields#
fields(self) -> Mapping[str, object]The field definitions of a model or a model struct (Effect's
Model.fields).
| Parameter | Type | Description |
|---|---|---|
self | HasVariants |
Returns Mapping[str, object]
def fields(self: HasVariants, /) -> Mapping[str, object]:
"""The field definitions of a model or a model struct (Effect's
``Model.fields``)."""
return self.__variant_fields__()FieldOption#
FieldOption[A](self: Field[A], /) -> Field[Option[A]]
FieldOption[A](self: Codec[A, Any, Any, Any], /) -> Field[Option[A]]An optional value as an Option: None in the database
variants, a missing key or None in the JSON ones. A field keeps its
variants; a schema is in all of them.
| Parameter | Type | Description |
|---|---|---|
self |
@overload
def FieldOption[A](self: Field[A], /) -> Field[Option[A]]: ...
@overload
def FieldOption[A](self: Codec[A, Any, Any, Any], /) -> Field[Option[A]]: ...
def FieldOption(self: Field[Any] | AnyCodec, /) -> Field[Any]:
"""An optional value as an ``Option``: ``None`` in the database
variants, a missing key or ``None`` in the JSON ones. A field keeps its
variants; a schema is in all of them."""
schemas = self.schemas if isinstance(self, Field) else dict.fromkeys(VARIANTS, self)
return Field({variant: _option_of(variant, s) for variant, s in schemas.items()})GeneratedByApp#
GeneratedByApp[A](schema) -> Field[A]A value the application makes, never a JSON API's client: in every
variant but json_create / json_update.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[A, Any, Any, Any] |
Returns Field[A]
def GeneratedByApp[A](schema: Codec[A, Any, Any, Any], /) -> Field[A]:
"""A value the application makes, never a JSON API's client: in every
variant but ``json_create`` / ``json_update``."""
return Field({"select": schema, "insert": schema, "update": schema, "json": schema})GeneratedByDb#
GeneratedByDb[A](schema) -> Field[A]A value the database makes (an auto-increment id): in select and
json only.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[A, Any, Any, Any] |
Returns Field[A]
def GeneratedByDb[A](schema: Codec[A, Any, Any, Any], /) -> Field[A]:
"""A value the database makes (an auto-increment id): in ``select`` and
``json`` only."""
return Field({"select": schema, "json": schema})JsonFromString#
JsonFromString[A](schema) -> Field[A]A value stored as JSON text in the database, the value itself in JSON.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[A, Any, Any, Any] |
Returns Field[A]
def JsonFromString[A](schema: Codec[A, Any, Any, Any], /) -> Field[A]:
"""A value stored as JSON text in the database, the value itself in
JSON."""
parsed = _from_json_string(to_codec_json(schema))
return Field(
{
**dict.fromkeys(DATABASE, parsed),
**dict.fromkeys(("json", "json_create", "json_update"), schema),
}
)Sensitive#
Sensitive[A](schema) -> Field[A]A value never sent through a JSON API: in the database variants only.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[A, Any, Any, Any] |
Returns Field[A]
def Sensitive[A](schema: Codec[A, Any, Any, Any], /) -> Field[A]:
"""A value never sent through a JSON API: in the database variants
only."""
return Field(dict.fromkeys(DATABASE, schema))Field#
Field[A](*, select: Codec[A, Any, Any, Any], insert: AnyCodec | None = None, update: AnyCodec | None = None, json: AnyCodec | None = None, json_create: AnyCodec | None = None, json_update: AnyCodec | None = None) -> VariantField[A]
Field(*, insert: AnyCodec | None = None, update: AnyCodec | None = None, json: AnyCodec | None = None, json_create: AnyCodec | None = None, json_update: AnyCodec | None = None) -> VariantField[NotSelected]A field's schema per variant (Effect's Model.Field); None
leaves it out of that variant. Without select the field is not the
class's (its Type NotSelected fits no annotation).
| Parameter | Type | Description |
|---|---|---|
select | = None | |
insert | = None | |
update | = None | |
json | = None | |
json_create | = None | |
json_update | = None |
@overload
def Field[A](
*,
select: Codec[A, Any, Any, Any],
insert: AnyCodec | None = None,
update: AnyCodec | None = None,
json: AnyCodec | None = None,
json_create: AnyCodec | None = None,
json_update: AnyCodec | None = None,
) -> VariantField[A]: ...
@overload
def Field(
*,
insert: AnyCodec | None = None,
update: AnyCodec | None = None,
json: AnyCodec | None = None,
json_create: AnyCodec | None = None,
json_update: AnyCodec | None = None,
) -> VariantField[NotSelected]: ...
def Field(
*,
select: AnyCodec | None = None,
insert: AnyCodec | None = None,
update: AnyCodec | None = None,
json: AnyCodec | None = None,
json_create: AnyCodec | None = None,
json_update: AnyCodec | None = None,
) -> VariantField[Any]:
"""A field's schema per variant (Effect's ``Model.Field``); ``None``
leaves it out of that variant. Without ``select`` the field is not the
class's (its Type ``NotSelected`` fits no annotation)."""
return TOOLKIT.Field(
select=select,
insert=insert,
update=update,
json=json,
json_create=json_create,
json_update=json_update,
)Struct#
Struct(fields) -> VariantStructModel field definitions without a class (Effect's Model.Struct).
| Parameter | Type | Description |
|---|---|---|
fields | Mapping[str, Definition | None] |
Returns VariantStruct
def Struct(fields: Mapping[str, Definition | None], /) -> VariantStruct:
"""Model field definitions without a class (Effect's ``Model.Struct``)."""
return TOOLKIT.Struct(fields)Union#
Union(members) -> VariantUnionSchemaThe union of the members' select variants, with variants
holding the union of each variant (Effect's Model.Union).
| Parameter | Type | Description |
|---|---|---|
members | Sequence[_HasVariants] |
Returns VariantUnionSchema
def Union(members: Sequence[_HasVariants], /) -> VariantUnionSchema:
"""The union of the members' ``select`` variants, with ``variants``
holding the union of each variant (Effect's ``Model.Union``)."""
return TOOLKIT.Union(members)field_evolve#
field_evolve(mapping) -> FieldEvolvefield_evolve({"json": f})(field): the named variants' schemas
mapped (Effect's fieldEvolve); a variant the field lacks stays out.
| Parameter | Type | Description |
|---|---|---|
mapping | Mapping[Variant, Callable[[AnyCodec], AnyCodec]] |
Returns FieldEvolve
def field_evolve(mapping: Mapping[Variant, Callable[[AnyCodec], AnyCodec]], /) -> FieldEvolve:
"""``field_evolve({"json": f})(field)``: the named variants' schemas
mapped (Effect's ``fieldEvolve``); a variant the field lacks stays out."""
evolve: dict[str, Callable[[AnyCodec], AnyCodec]] = {**mapping}
return TOOLKIT.field_evolve(evolve)field_except#
field_except(keys) -> FieldOnlyfield_except(["insert"])(schema): a field in every variant but
those (Effect's FieldExcept).
| Parameter | Type | Description |
|---|---|---|
keys | Sequence[Variant] |
Returns FieldOnly
def field_except(keys: Sequence[Variant], /) -> FieldOnly:
"""``field_except(["insert"])(schema)``: a field in every variant but
those (Effect's ``FieldExcept``)."""
return TOOLKIT.field_except(keys)field_only#
field_only(keys) -> FieldOnlyfield_only(["select", "json"])(schema): a field in those variants
only (Effect's FieldOnly).
| Parameter | Type | Description |
|---|---|---|
keys | Sequence[Variant] |
Returns FieldOnly
def field_only(keys: Sequence[Variant], /) -> FieldOnly:
"""``field_only(["select", "json"])(schema)``: a field in those variants
only (Effect's ``FieldOnly``)."""
return TOOLKIT.field_only(keys)UuidV4BytesInsert#
UuidV4BytesInsert[B: bytes](schema) -> Field[B]UuidV4Insert for ids stored as 16 bytes.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, Any, Any, Any] |
Returns Field[B]
def UuidV4BytesInsert[B: bytes](schema: Codec[B, Any, Any, Any], /) -> Field[B]:
"""``UuidV4Insert`` for ids stored as 16 bytes."""
return _insert(schema, UuidV4BytesWithGenerate(schema))UuidV4BytesWithGenerate#
UuidV4BytesWithGenerate[B: bytes, I, RD, RE](schema) -> WithConstructorDefault[B, I, RD, RE]schema defaulting to a new random UUID's 16 bytes.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, I, RD, RE] |
Returns WithConstructorDefault[B, I, RD, RE]
def UuidV4BytesWithGenerate[B: bytes, I, RD, RE](
schema: Codec[B, I, RD, RE], /
) -> WithConstructorDefault[B, I, RD, RE]:
"""``schema`` defaulting to a new random UUID's 16 bytes."""
return _generated(schema, sync(lambda: uuid.uuid4().bytes))UuidV4Insert#
UuidV4Insert[B: str](schema) -> Field[B]An id the application generates on insert: a UUID v4 by default in
insert, required in select, update and json.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, Any, Any, Any] |
Returns Field[B]
def UuidV4Insert[B: str](schema: Codec[B, Any, Any, Any], /) -> Field[B]:
"""An id the application generates on insert: a UUID v4 by default in
``insert``, required in ``select``, ``update`` and ``json``."""
return _insert(schema, UuidV4WithGenerate(schema))UuidV4WithGenerate#
UuidV4WithGenerate[B: str, I, RD, RE](schema) -> WithConstructorDefault[B, I, RD, RE]schema defaulting to a new random UUID's text.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, I, RD, RE] |
Returns WithConstructorDefault[B, I, RD, RE]
def UuidV4WithGenerate[B: str, I, RD, RE](
schema: Codec[B, I, RD, RE], /
) -> WithConstructorDefault[B, I, RD, RE]:
"""``schema`` defaulting to a new random UUID's text."""
return _generated(schema, sync(lambda: str(uuid.uuid4())))UuidV7Insert#
UuidV7Insert[B: str](schema) -> Field[B]UuidV4Insert with time-ordered UUIDs (v7).
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, Any, Any, Any] |
Returns Field[B]
def UuidV7Insert[B: str](schema: Codec[B, Any, Any, Any], /) -> Field[B]:
"""``UuidV4Insert`` with time-ordered UUIDs (v7)."""
return _insert(schema, UuidV7WithGenerate(schema))UuidV7WithGenerate#
UuidV7WithGenerate[B: str, I, RD, RE](schema) -> WithConstructorDefault[B, I, RD, RE]schema defaulting to a new time-ordered UUID's text, its time
read from the Clock; ids strictly increase, also within a
millisecond.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, I, RD, RE] |
Returns WithConstructorDefault[B, I, RD, RE]
def UuidV7WithGenerate[B: str, I, RD, RE](
schema: Codec[B, I, RD, RE], /
) -> WithConstructorDefault[B, I, RD, RE]:
"""``schema`` defaulting to a new time-ordered UUID's text, its time
read from the ``Clock``; ids strictly increase, also within a
millisecond."""
return _generated(schema, current_time_millis().map(_uuid_v7))