yera.runtime.publisher

Publish rendered HTML fragments to live or replay consumers.

HTMX handlers render strings through a common publisher boundary. A live publisher transfers fragments from synchronous handler calls into an asynchronous consumer. A replay publisher records the same fragments in memory so stored sessions can be rendered without opening a live stream.

Symbols

class BasePublisher — Define fragment, pause, and completion signals for web rendering.
class Publisher — Transfer rendered fragments safely into an asynchronous consumer.
class ReplayPublisher — Collect rendered fragments synchronously for stored-session replay.
class WebRenderContext — Provide the web transport required by HTMX handlers.

BasePublisher

Inherits: ABC

Define fragment, pause, and completion signals for web rendering.

Concrete publishers may deliver fragments asynchronously or collect them synchronously, but expose the same interface to HTMX handlers.

Methods

push — Push a fragment to the sink.
push_eof — Signal the end of the fragment stream.
push_pause — Signal a temporary pause without closing the stream.

BasePublisher.push

push(
    chunk: str,
) → None

Push a fragment to the sink.

Parameters

chunk
type: str

The string fragment to be published.

BasePublisher.push_eof

push_eof() → None

Signal the end of the fragment stream.

BasePublisher.push_pause

push_pause() → None

Signal a temporary pause without closing the stream.

Publisher

Inherits: BasePublisher

Transfer rendered fragments safely into an asynchronous consumer.

Synchronous handler calls may publish from another thread. Each operation is therefore scheduled onto the owning event loop. Consumers iterate stream() until completion; pause signals are yielded so the caller can suspend a response without closing the publisher. Completion remains observable by later consumers.

Methods

__init__ — Initialize an asynchronous fragment publisher.
push — Push a fragment onto the asynchronous queue from any thread.
push_eof — Signal completion from any thread.
push_pause — Signal a temporary pause from any thread.
stream — Yield fragments and pause signals until completion.

Publisher.__init__

__init__(
    loop: asyncio.AbstractEventLoop | None = None,
)

Initialize an asynchronous fragment publisher.

Parameters

loop
type: asyncio.AbstractEventLoop | None = None

The event loop to use. If None, the running loop is retrieved.

Publisher.push

push(
    chunk: str,
) → None

Push a fragment onto the asynchronous queue from any thread.

Parameters

chunk
type: str

The string fragment to publish.

Publisher.push_eof

push_eof() → None

Signal completion from any thread.

Publisher.push_pause

push_pause() → None

Signal a temporary pause from any thread.

Publisher.stream

stream() → AsyncIterator[str | object]

Yield fragments and pause signals until completion.

ReplayPublisher

Inherits: BasePublisher

Collect rendered fragments synchronously for stored-session replay.

Replay consumes a bounded event sequence, so fragments are appended to frames and pause or completion signals require no queue sentinel.

Methods

__init__ — Initialize an empty replay frame collection.
push — Append a fragment to the replay frame collection.
push_eof — No-op: replay collects a bounded list, no EOF sentinel.
push_pause — No-op: replay supplies its own close after the collected frames.

ReplayPublisher.__init__

__init__() → None

Initialize an empty replay frame collection.

ReplayPublisher.push

push(
    chunk: str,
) → None

Append a fragment to the replay frame collection.

Parameters

chunk
type: str

The string fragment to collect.

ReplayPublisher.push_eof

push_eof() → None

No-op: replay collects a bounded list, no EOF sentinel.

ReplayPublisher.push_pause

push_pause() → None

No-op: replay supplies its own close after the collected frames.

WebRenderContext

Provide the web transport required by HTMX handlers.

Fields

publisher
type: yera.runtime.publisher.BasePublisher (required)

Destination for rendered HTML fragments.

input_url
type: str (required)

Endpoint used by interactive fragments to submit responses.

Methods


WebRenderContext.__init__

__init__(
    publisher: BasePublisher,
    input_url: str,
) → None