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

def await_input — Wait for a correlated typed response.
class EventStream — Exchange input and output events across the runtime boundary.
def failure_exit_event_already_pushed — Report whether a nested app has emitted a failure exit event.
def is_restricted_stream — Report whether the current event stream restricts available blocks.
def push_input — Push a correlated input event to the current event stream.
def push_output — Push an output event to the current event stream.

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

request_id
type: str

Block ID of the request awaiting a response.

expected_type
type: type[_InputDataT]

Typed input model expected for the request.

value_type
type: type[_InputValueT]

Python type represented by the serialized payload.

timeout
type: float | None = None

Maximum seconds to wait, or None to wait indefinitely.

Returns

type: tuple[_InputDataT, _InputValueT]

The typed input envelope and its deserialised payload value.

Raises

InputRequestMismatchError

If the response targets another request.

InputTypeMismatchError

If the response carries another input type.

InputValueError

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

__init__ — Initialize a bidirectional stream over caller-owned event queues.
push_output — Enqueue an output event for consumption by the host.
push_input — Enqueue an input event for consumption by the app.
pop_output — Remove and return the next output event.
close — Wake blocked output consumers with an idempotent close signal.
pop_input — Remove and return the next input event.
iter_output_blocking — Yield output events reliably across process boundaries.
set_current — Bind this stream to the current context.
get_current — Return the stream bound to the current context.
build — Return the current stream, creating and binding one if necessary.
new — Create a fresh stream without changing the current context.
drain_output — Remove all output events that are immediately available.

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

out_event_queue
type: queue.Queue[_OutputQueueItem]

Queue carrying output events from the app runtime.

in_event_queue
type: queue.Queue[InputEvent]

Queue carrying correlated user input into the runtime.

EventStream.push_output

push_output(
    event: OutputEvent,
) → None

Enqueue an output event for consumption by the host.

Parameters

event
type: OutputEvent

Output event to enqueue.

Raises

TypeError

If event is not an OutputEvent.

EventStream.push_input

push_input(
    in_event: InputEvent,
) → None

Enqueue an input event for consumption by the app.

Parameters

in_event
type: InputEvent

Correlated input event to enqueue.

Raises

TypeError

If in_event is not an InputEvent.

EventStream.pop_output

pop_output(
    timeout: float | None = None,
) → OutputEvent

Remove and return the next output event.

Parameters

timeout
type: float | None = None

Maximum seconds to wait, or None to wait indefinitely.

Returns

type: OutputEvent

The next output event from the queue.

Raises

queue.Empty

If no event becomes available before timeout expires.

EventStream.close

close() → None

Wake 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,
) → InputEvent

Remove and return the next input event.

Parameters

timeout
type: float | None = None

Maximum seconds to wait, or None to wait indefinitely.

Returns

type: InputEvent

The next input event from the queue.

Raises

queue.Empty

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

timeout
type: float = 0.5

Seconds to wait for each output event before checking whether iteration should continue.

should_continue
type: Callable[[], bool] | None = None

Optional callback evaluated after an empty read. Return False to stop iteration.

EventStream.set_current

set_current() → None

Bind this stream to the current context.

Raises

RuntimeError

If an event stream is already bound to the current context.

EventStream.get_current

get_current() → EventStream

Return the stream bound to the current context.

Returns

type: EventStream

The current context's event stream.

Raises

RuntimeError

If no event stream is bound to the current context.

EventStream.build

build() → EventStream

Return the current stream, creating and binding one if necessary.

Returns

type: EventStream

The existing context-bound stream, or a newly created stream that has been bound to the current context.

EventStream.new

new() → EventStream

Create a fresh stream without changing the current context.

Returns

type: EventStream

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

timeout
type: float = 0.1

Maximum seconds to wait for each successive event.

Returns

type: list[OutputEvent]

The events read from the queue, in queue order.

failure_exit_event_already_pushed

failure_exit_event_already_pushed() → bool

Report whether a nested app has emitted a failure exit event.

Returns

type: bool

Whether the current event stream has already emitted a failure exit event.

Raises

RuntimeError

If no event stream is bound to the current context.

is_restricted_stream

is_restricted_stream() → bool

Report whether the current event stream restricts available blocks.

Returns

type: bool

Whether only the restricted set of block types may be emitted.

Raises

RuntimeError

If no event stream is bound to the current context.

push_input

push_input(
    request_id: str,
    data: InputData,
) → None

Push a correlated input event to the current event stream.

Parameters

request_id
type: str

Identifier of the input request being answered.

data
type: InputData

Typed input data submitted for the request.

Raises

RuntimeError

If no event stream is bound to the current context.

push_output

push_output(
    event: OutputEvent,
) → None

Push an output event to the current event stream.

Failure exit events also mark the current stream as having emitted its terminal failure event.

Parameters

event
type: OutputEvent

Output event to enqueue.

Raises

RuntimeError

If no event stream is bound to the current context.

TypeError

If event is not an OutputEvent.