Skip to content
hikari-risa hikari-risa

risa.state.schema

A view's durable fields, and how their values are packed into state.

Fields are durable by default. risa.Prop[T] marks a field that is rebuilt fresh on every click instead: it is never saved, costs nothing on the wire, must have a default, and is typically filled in load.

Prop 

Prop = Annotated[T, _PropMarker]

Marks a view field as a per-dispatch prop: refilled in load() and never written to state.

DurableField 

DurableField(name: str, annotation: object, has_default: bool)

Bases: Struct

One durable field of a view.

Attributes:

  • name (str) –

    The field's name.

  • annotation (object) –

    The field's type.

  • has_default (bool) –

    Whether the field has a default, which lets state written before it was added still be read.

StateSchema 

StateSchema(fields: Sequence[DurableField], *, view_name: str)

The durable fields of a view, in declaration order, and their packing.

risa builds one per view at registration. State is packed as the values of the durable fields in order, so appending a field that has a default leaves earlier state readable.

durable property 

durable: bool

Whether the view has any durable fields.

empty_fingerprint property 

empty_fingerprint: str

The fingerprint of a view without durable fields.

fields property 

fields: Sequence[DurableField]

The durable fields, in declaration order.

fingerprint property 

fingerprint: str

The hash of the durable fields' names and types, which state is tagged with.

accepts 

accepts(fingerprint: str) -> bool

Whether state tagged fingerprint can be read into this schema.

Parameters:

  • fingerprint (str) –

    The fingerprint the state was tagged with when it was saved.

Returns:

  • bool –

    Whether this schema can read that state.

adopt 

adopt(view: Struct, source: Struct) -> None

Copy the durable fields of source onto view.

Parameters:

  • view (Struct) –

    The view that takes the values; it is changed in place.

  • source (Struct) –

    The view the values come from; it needs the same durable fields.

field_sizes 

field_sizes(packed: bytes) -> Mapping[str, int]

Return the bytes each durable field takes in state this schema packed, by name.

Parameters:

  • packed (bytes) –

    State this schema packed, as pack returned it.

Returns:

  • Mapping[str, int] –

    The bytes taken by each field's value, keyed by field name.

of classmethod 

of(view_cls: type[Struct], *, view_name: str) -> StateSchema

Read the schema of a view class from its fields.

Parameters:

  • view_cls (type[Struct]) –

    The view class, a msgspec.Struct, whose annotated fields are read.

  • view_name (str) –

    The view's name, for error messages.

Returns:

  • StateSchema –

    The schema of the class's durable fields.

Raises:

  • ViewDeclarationError –

    If a prop has no default, a risa.Prop marker sits inside an annotation instead of around it, or a field's type cannot be described.

pack 

pack(values: Sequence[object]) -> bytes

Pack the values of the durable fields, in order, into state.

Parameters:

  • values (Sequence[object]) –

    The value of each durable field, in field order.

Returns:

  • bytes –

    The packed state, empty for a view without durable fields.

Raises:

pack_view 

pack_view(view: Struct) -> bytes

Pack the durable fields of view into state.

Parameters:

  • view (Struct) –

    The view whose durable fields are packed.

Returns:

  • bytes –

    The packed state.

Raises:

unpack 

unpack(fingerprint: str, raw: bytes) -> Sequence[object] | None

Unpack state tagged fingerprint, or return None if this schema cannot read it.

Parameters:

  • fingerprint (str) –

    The fingerprint the state was tagged with when it was saved.

  • raw (bytes) –

    The packed bytes saved under that fingerprint.

Returns:

  • Sequence[object] | None –

    The values of the durable fields, or None if this schema cannot read the state. State saved before a field was added holds only the fields it had, so the sequence stops short of those added since.

values 

values(view: Struct) -> Sequence[object]

Return the values of view's durable fields, in order.

Parameters:

  • view (Struct) –

    The view to read, an instance of the class this schema was read from.

Returns:

structural_type_id 

structural_type_id(annotation: object) -> str

Describe a field type by its structure, for the schema fingerprint.

An enum or Literal counts by the kinds of its values, so a new value of a kind it already has leaves old state readable, and a removed one fails only for the state that holds it. A Literal that gains a kind, or loses its last value of one, changes the shape.

Parameters:

  • annotation (object) –

    The field's type annotation.

Returns:

  • str –

    The same text for types of the same structure, whatever they are named.

Raises:

  • ValueError –

    If msgspec cannot describe the type.