blockether.vis.views

Immutable input-form, live-view and view-event records.

For reading receipts, see the SDK guide. For creating interfaces, use the human-input guide or live-view guide.

@dataclass(frozen=True, slots=True)

class InputView(_ViewRecord):

An open input form, including field schemas and engine-owned timeout metadata.

This describes the form, not a person's answers. Submitted values are not included in public close events; they belong to the waiting extension.

InputView( id: str, title: str, fields: tuple[Mapping[str, typing.Any], ...], submit_label: str, cancel_label: str, is_cancellable: bool, timeout_ms: int, created_at: int, description: str | None = None, source: str | None = None, session_id: str | None = None)

id: str

title: str

fields: tuple[Mapping[str, typing.Any], ...]

submit_label: str

cancel_label: str

is_cancellable: bool

timeout_ms: int

created_at: int

description: str | None

source: str | None

session_id: str | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping violates this record's canonical View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LiveView(_ViewRecord):

An open live interface at sequence seq, with immutable semantic nodes.

Apply subsequent LivePatch operations in sequence order in your consumer; this snapshot does not mutate itself when another event arrives.

LiveView( id: str, title: str, nodes: tuple[Mapping[str, typing.Any], ...], timeout_ms: int, channel_ids: tuple[str, ...], seq: int, created_at: int, description: str | None = None, source: str | None = None, session_id: str | None = None, owner: Mapping[str, typing.Any] | None = None)

id: str

title: str

nodes: tuple[Mapping[str, typing.Any], ...]

timeout_ms: int

channel_ids: tuple[str, ...]

seq: int

created_at: int

description: str | None

source: str | None

session_id: str | None

owner: Mapping[str, typing.Any] | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping violates this record's canonical View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class ViewSnapshot(_ViewRecord):

A retained view document without open-session IDs or timeout metadata.

ViewSnapshot( title: str, nodes: tuple[Mapping[str, typing.Any], ...], description: str | None = None)

title: str

nodes: tuple[Mapping[str, typing.Any], ...]

description: str | None

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping violates this record's canonical View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LivePatch(_ViewRecord):

Ordered semantic updates for view_id, ending at sequence seq.

The containing ViewEvent.first_seq identifies the first sequence covered by a patch event. Operations remain immutable schema-validated mappings.

LivePatch(view_id: str, seq: int, ops: tuple[Mapping[str, typing.Any], ...])

view_id: str

seq: int

ops: tuple[Mapping[str, typing.Any], ...]

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping violates this record's canonical View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class InputResult(_ViewRecord):

Public close receipt; submitted values belong only to the waiting extension.

InputResult(reason: str)

reason: str

Inherited methods and attributes

@classmethod

def from_wire(cls, value: Any):

Validate a raw mapping and return an immutable record.

Raises:

ValueError: The mapping violates this record's canonical View schema.

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class LiveResult(_ViewRecord):

A live interface's final outcome and optional retained document.

Check is_completed and reason rather than assuming every close succeeds. is_from_human distinguishes a person's closure from a programmatic one; view, summary, error and attachment metadata may be absent.

view_id: str

is_completed: bool

reason: str

is_from_human: bool

view: ViewSnapshot | None

note: str | None

elided: tuple[Mapping[str, typing.Any], ...] | None

summary: str | None

artifact_id: str | None

error: str | None

@classmethod

def from_wire(cls, value: Any) -> LiveResult:

Validate a close receipt and decode its optional ViewSnapshot.

Raises:

ValueError: The receipt or its retained view violates the View schema.

Inherited methods and attributes

def to_wire(self) -> dict[str, typing.Any]:

Return a fresh JSON-compatible copy, including nested mappings and lists.

@dataclass(frozen=True, slots=True)

class ViewEvent:

Typed payload of view.open, view.patch or view.close, not its SSE envelope.

kind: str

view_id: str

view: InputView | LiveView | None

patch: LivePatch | None

result: InputResult | LiveResult | None

first_seq: int | None

@classmethod

def from_wire(cls, event_type: str, value: Any) -> ViewEvent:

Decode a View event payload, separate from its stream envelope.

Arguments:

event_type: "view.open", "view.patch" or "view.close".
value: The corresponding JSON payload, including its kind and view ID.

Raises:

KeyError: The event type is unsupported.
ValueError: The payload, view identity or patch sequence is invalid.

def to_wire(self) -> dict[str, typing.Any]:

Return this typed View payload as fresh JSON-compatible data.