yera.runtime.handlers.registry

Select a render target and construct its block-handler registry.

Console and notebook targets are detected from the process environment. Browser rendering is selected explicitly by supplying a web rendering context.

Symbols

def detect_render_env — Detect the rendering environment for the current process.
class EventHandlerRegistry — Maps block-type names to factories that construct their handlers.
class RenderEnv — Identify console and notebook targets selected by environment detection.

detect_render_env

detect_render_env() → RenderEnv

Detect the rendering environment for the current process.

Checks, in order: YERA_RENDERER env-var override, Jupyter kernel, Kitty-protocol terminal, then falls back to plain ANSI.

Returns

type: RenderEnv

The detected RenderEnv.

EventHandlerRegistry

Maps block-type names to factories that construct their handlers.

Methods

__init__ — Initialize a registry from block-specific and fallback factories.
create — Construct a fresh handler for a single block.
build — Build a registry for the given target, auto-detecting if unspecified.

EventHandlerRegistry.__init__

__init__(
    factories: dict[str, HandlerFactory],
    fallback: HandlerFactory,
)

Initialize a registry from block-specific and fallback factories.

Parameters

factories
type: dict[str, HandlerFactory]

Block types mapped to factories that create fresh handlers.

fallback
type: HandlerFactory

Factory used for block types absent from the mapping.

EventHandlerRegistry.create

create(
    block_type: str,
) → BaseHandler

Construct a fresh handler for a single block.

A handler's lifetime is one block: the router constructs it when the block opens and discards it when the block ends. Handlers therefore hold per-block state directly rather than resetting it in __enter__.

Parameters

block_type
type: str

The event block type to look up.

Returns

type: BaseHandler

A new handler, or a new fallback handler if unregistered.

EventHandlerRegistry.build

build(
    env: RenderEnv | None = None,
    console: Console | None = None,
    web_render: WebRenderContext | None = None,
) → EventHandlerRegistry

Build a registry for the given target, auto-detecting if unspecified.

Parameters

env
type: RenderEnv | None = None

Force a target. Defaults to auto-detection (env var override, then Jupyter, then Kitty, then ANSI).

console
type: Console | None = None

The rich console object to use when printing to screen etc.

web_render
type: WebRenderContext | None = None

The render context to use when handling events -> HTMX.

Returns

type: EventHandlerRegistry

A registry populated with handlers for the selected environment.

Raises

ValueError

If an unsupported rendering environment is requested.

RenderEnv

Inherits: Enum

Identify console and notebook targets selected by environment detection.

Browser rendering is selected separately when the registry receives a web rendering context.