yera.runtime.stream
Exchange typed events between an app runtime and its host process.
Output events travel from the app to the host for routing and rendering. Input events travel back to the app and carry the request identity needed to match a response to its prompt. A stream can be bound to the current context so block and input helpers can use it without receiving it explicitly.
Symbols
await_input
await_input(
request_id: str,
expected_type: type[_InputDataT],
value_type: type[_InputValueT],
timeout: float | None = None,
) → tuple[_InputDataT, _InputValueT]Wait for a correlated typed response.
Parameters
Block ID of the request awaiting a response.
Typed input model expected for the request.
Python type represented by the serialized payload.
Maximum seconds to wait, or None to wait indefinitely.
Returns
The typed input envelope and its deserialised payload value.
Raises
If the response targets another request.
If the response carries another input type.
If the submitted payload cannot be deserialized.
EventStream
Exchange input and output events across the runtime boundary.
Each stream owns two multiprocessing-compatible queues. The app writes ordered output events to one queue, while the host writes correlated input events to the other. Binding a stream to the current context makes that boundary available to block factories and input helpers.
Closing a stream wakes blocked output consumers. It does not discard queued events or manufacture an application exit event.
Methods
EventStream.__init__
__init__(
out_event_queue: queue.Queue[_OutputQueueItem],
in_event_queue: queue.Queue[InputEvent],
)Initialize a bidirectional stream over caller-owned event queues.
Parameters
Queue carrying output events from the app runtime.
Queue carrying correlated user input into the runtime.
EventStream.push_output
push_output(
event: OutputEvent,
) → NoneEnqueue an output event for consumption by the host.
Parameters
Output event to enqueue.
Raises
If event is not an OutputEvent.
EventStream.push_input
push_input(
in_event: InputEvent,
) → NoneEnqueue an input event for consumption by the app.
Parameters
Correlated input event to enqueue.
Raises
If in_event is not an InputEvent.
EventStream.pop_output
pop_output(
timeout: float | None = None,
) → OutputEventRemove and return the next output event.
Parameters
Maximum seconds to wait, or None to wait indefinitely.
Returns
The next output event from the queue.
Raises
If no event becomes available before timeout expires.
EventStream.close
close() → NoneWake blocked output consumers with an idempotent close signal.
Closing the stream does not discard queued events and does not close the input queue. Repeated calls do not enqueue additional close signals.
EventStream.pop_input
pop_input(
timeout: float | None = None,
) → InputEventRemove and return the next input event.
Parameters
Maximum seconds to wait, or None to wait indefinitely.
Returns
The next input event from the queue.
Raises
If no event becomes available before timeout expires.
EventStream.iter_output_blocking
iter_output_blocking(
timeout: float = 0.5,
should_continue: Callable[[], bool] | None = None,
) → Iterator[OutputEvent]Yield output events reliably across process boundaries.
The iterator uses blocking queue reads because Queue.empty() is not
reliable when the producer runs in another process. It stops when the
stream is closed or when should_continue returns False after a
read times out.
Parameters
Seconds to wait for each output event before checking whether iteration should continue.
Optional callback evaluated after an empty read.
Return False to stop iteration.
EventStream.set_current
set_current() → NoneBind this stream to the current context.
Raises
If an event stream is already bound to the current context.
EventStream.get_current
get_current() → EventStreamReturn the stream bound to the current context.
Returns
The current context's event stream.
Raises
If no event stream is bound to the current context.
EventStream.build
build() → EventStreamReturn the current stream, creating and binding one if necessary.
Returns
The existing context-bound stream, or a newly created stream that has been bound to the current context.
EventStream.new
new() → EventStreamCreate a fresh stream without changing the current context.
Returns
A new event stream backed by multiprocessing queues.
EventStream.drain_output
drain_output(
timeout: float = 0.1,
) → list[OutputEvent]Remove all output events that are immediately available.
A producer in another process may still be flushing events after this method returns, so the result is only a snapshot of currently readable output.
Parameters
Maximum seconds to wait for each successive event.
Returns
The events read from the queue, in queue order.
failure_exit_event_already_pushed
failure_exit_event_already_pushed() → boolReport whether a nested app has emitted a failure exit event.
Returns
Whether the current event stream has already emitted a failure exit event.
Raises
If no event stream is bound to the current context.
is_restricted_stream
is_restricted_stream() → boolReport whether the current event stream restricts available blocks.
Returns
Whether only the restricted set of block types may be emitted.
Raises
If no event stream is bound to the current context.
push_input
push_input(
request_id: str,
data: InputData,
) → NonePush a correlated input event to the current event stream.
Parameters
Identifier of the input request being answered.
Typed input data submitted for the request.
Raises
If no event stream is bound to the current context.
push_output
push_output(
event: OutputEvent,
) → NonePush an output event to the current event stream.
Failure exit events also mark the current stream as having emitted its terminal failure event.
Parameters
Output event to enqueue.
Raises
If no event stream is bound to the current context.
If event is not an OutputEvent.