GitHub

persistable

API reference for persistable.

Requests whose results can be stored (Effect's effect/persistence/Persistable).

A persistable request names itself with primary_key() and carries the schemas of its success and error, so its Exit can be written as JSON and read back. Class makes the base class from the schemas, and the request's types come from them::

@dataclass(frozen=True)
class GetUser(persistable.Class(success=User, error=S.String)):
    id: int

    def primary_key(self) -> str:
        return f"GetUser:{self.id}"

GetUser(1) is a Request[User, str | PersistenceError | SchemaError]: a store may fail to read or write, or hold a value the schemas reject.

Types

TypeDefinitionDescription
AnyCodectype AnyCodec = S.Codec[Any, Any, Any, Any]
AnyPersistabletype AnyPersistable = Persistable[Any, Any, Any]
TimeToLivetype TimeToLive[K, A, E] = Callable[[Exit[A, E], K], DurationInput]

How long to keep a request's outcome: a function of the Exit and the request. Zero or less keeps nothing; infinity keeps it forever.

Classes

Functions

Class

Class[A = None, E = Never, RR = Never](*, success=None, error=None) -> type[Persistable[A, E, RR]]

The base class of a persistable request succeeding with success's values (default: None) and failing with error's (default: never). Subclass it as a frozen dataclass and define primary_key().

ParameterTypeDescription
successS.Codec[A, Any, RR, RR] | None = None
errorS.Codec[E, Any, RR, RR] | None = None

Returns type[Persistable[A, E, RR]]

def Class[A = None, E = Never, RR = Never](
    *,
    success: S.Codec[A, Any, RR, RR] | None = None,
    error: S.Codec[E, Any, RR, RR] | None = None,
) -> type[Persistable[A, E, RR]]:
    """The base class of a persistable request succeeding with ``success``'s
    values (default: ``None``) and failing with ``error``'s (default:
    never). Subclass it as a frozen dataclass and define
    ``primary_key()``."""
    success_schema: AnyCodec = S.Null if success is None else success
    error_schema: AnyCodec = S.Never if error is None else error

    class Base(Persistable[Any, Any, Any]):
        __slots__ = ()
        _success_schema = success_schema
        _error_schema = error_schema
        _exit_codec = None

    return cast("type[Persistable[A, E, RR]]", Base)

success_schema

success_schema[A](request) -> S.Codec[A, Any, Any, Any]
ParameterTypeDescription
requestPersistable[A, Any, Any]

Returns S.Codec[A, Any, Any, Any]

def success_schema[A](request: Persistable[A, Any, Any]) -> S.Codec[A, Any, Any, Any]:
    return type(request)._success_schema

error_schema

error_schema[E](request) -> S.Codec[E, Any, Any, Any]
ParameterTypeDescription
requestPersistable[Any, E, Any]

Returns S.Codec[E, Any, Any, Any]

def error_schema[E](request: Persistable[Any, E, Any]) -> S.Codec[E, Any, Any, Any]:
    return type(request)._error_schema

exit_schema

exit_schema[A, E](request) -> S.ExitSchema[A, E, Any, Any, Any, Any]

The schema of the request's Exit: its success, its error, or a defect.

ParameterTypeDescription
requestPersistable[A, E, Any]

Returns S.ExitSchema[A, E, Any, Any, Any, Any]

def exit_schema[A, E](
    request: Persistable[A, E, Any],
) -> S.ExitSchema[A, E, Any, Any, Any, Any]:
    """The schema of the request's ``Exit``: its success, its error, or a
    defect."""
    cls = type(request)
    return S.Exit(cls._success_schema, cls._error_schema, S.Defect())

serialize_exit

serialize_exit[A, E, R](request, exit) -> Effect[JsonValue, S.SchemaError, R]

exit as JSON, by the request's schemas.

ParameterTypeDescription
requestPersistable[A, E, R]
exitExit[A, E]

Returns Effect[JsonValue, S.SchemaError, R]

def serialize_exit[A, E, R](
    request: Persistable[A, E, R], exit: Exit[A, E]
) -> Effect[JsonValue, S.SchemaError, R]:
    """``exit`` as JSON, by the request's schemas."""
    return S.encode_effect(_exit_codec(request))(exit)

deserialize_exit

deserialize_exit[A, E, R](request, encoded) -> Effect[Exit[A, E], S.SchemaError, R]

The Exit that encoded holds, by the request's schemas.

ParameterTypeDescription
requestPersistable[A, E, R]
encodedobject

Returns Effect[Exit[A, E], S.SchemaError, R]

def deserialize_exit[A, E, R](
    request: Persistable[A, E, R], encoded: object
) -> Effect[Exit[A, E], S.SchemaError, R]:
    """The ``Exit`` that ``encoded`` holds, by the request's schemas."""
    return S.decode_unknown_effect(_exit_codec(request))(encoded)