GitHub

API reference for model.

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 sends

The 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

AttributeTypeDescription
DateDecodeToSchema[datetime, str]

A date (YYYY-MM-DD) as the UTC datetime of its midnight.

DateTimeFromDateWithNowWithConstructorDefault[datetime, datetime, Never, Never]
DateTimeFromNumberWithNowWithConstructorDefault[datetime, int, Never, Never]
DateTimeInsertField[datetime]

A creation timestamp stored as ISO text: set to now when inserted.

DateTimeInsertFromDateField[datetime]

A creation timestamp the driver reads as a datetime.

DateTimeInsertFromNumberField[datetime]

A creation timestamp stored as epoch milliseconds.

DateTimeUpdateField[datetime]

An update timestamp stored as ISO text: set to now when inserted or updated.

DateTimeUpdateFromDateField[datetime]

An update timestamp the driver reads as a datetime.

DateTimeUpdateFromNumberField[datetime]

An update timestamp stored as epoch milliseconds.

DateTimeWithNowWithConstructorDefault[datetime, str, Never, Never]
DateWithNowWithConstructorDefault[datetime, str, Never, Never]
BooleanSqliteField[bool]

A boolean stored as 0 / 1 (SQLite has no boolean type), a boolean in JSON.

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 None, as an Option (Effect's Model.optionalOption; Python has one None, so it is S.OptionFromOptionalNullOr).

Types

TypeDefinitionDescription
Varianttype Variant = Literal['select', 'insert', 'update', 'json', 'json_create', 'json_update']

A model variant: select (the class), insert / update (what is written to the database), json / json_create / json_update (what a JSON API reads and writes). Effect's jsonCreate / jsonUpdate are snake_case.

VariantsDatabasetype VariantsDatabase = Literal['select', 'insert', 'update']
VariantsJsontype 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.

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

ParameterTypeDescription
selfHasVariants

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.

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

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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).

ParameterTypeDescription
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) -> VariantStruct

Model field definitions without a class (Effect's Model.Struct).

ParameterTypeDescription
fieldsMapping[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) -> VariantUnionSchema

The union of the members' select variants, with variants holding the union of each variant (Effect's Model.Union).

ParameterTypeDescription
membersSequence[_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) -> FieldEvolve

field_evolve({"json": f})(field): the named variants' schemas mapped (Effect's fieldEvolve); a variant the field lacks stays out.

ParameterTypeDescription
mappingMapping[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) -> FieldOnly

field_except(["insert"])(schema): a field in every variant but those (Effect's FieldExcept).

ParameterTypeDescription
keysSequence[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) -> FieldOnly

field_only(["select", "json"])(schema): a field in those variants only (Effect's FieldOnly).

ParameterTypeDescription
keysSequence[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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).

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
schemaCodec[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))