# live URL: /kida/api/terminal/live/ Section: terminal Description: Live terminal rendering — progressive output and in-place re-rendering. Provides three public symbols: - ``stream_to_terminal`` — write ``render_stream()`` chunks progressively - ``Spinner`` — animated frame-cycling spinner for live templates - ``LiveRenderer`` — context manager for in-place re-rendering --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/terminal/live/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fterminal%2Flive%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fterminal%2Flive%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fterminal%2Flive%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fterminal%2Flive%2Findex.txt) Module # `terminal.live` Live terminal rendering — progressive output and in-place re-rendering. Provides three public symbols: - `stream_to_terminal` — write `render_stream()`chunks progressively - `Spinner`— animated frame-cycling spinner for live templates - `LiveRenderer`— context manager for in-place re-rendering 2Classes1Function ## Classes `Spinner` 8 ▼ Animated spinner that advances one frame per call. Use inside live-rendered templates — each ``Liv… Animated spinner that advances one frame per call. Use inside live-rendered templates — each`LiveRenderer.update()` re-renders the template, calling the spinner again to advance the frame. The spinner implements the`__terminal__`protocol so its output bypasses ANSI sanitization, consistent with`Styled` and `IconSet`. Usage in templates:: ``` {{ spinner() }} Building project... ``` Usage in Python:: ``` spinner = Spinner() context["spinner"] = spinner # Each template.render(**context) call advances the frame ``` #### Attributes Name Type Description `BRAILLE` `ClassVar[tuple[str, ...]]` — `DOTS` `ClassVar[tuple[str, ...]]` — `LINE` `ClassVar[tuple[str, ...]]` — `ARROW` `ClassVar[tuple[str, ...]]` — #### Methods `reset` 0 ▼ Reset the frame counter to the beginning. `def reset(self) -> None` Internal Methods 3 ▼ `__init__` 1 ▼ `def __init__(self, frames: tuple[str, ...] | None = None) -> None` ##### Parameters Name Type Description `frames` `—` Default:`None` `__call__` 0 `Styled` ▼ Return the current frame and advance. `def __call__(self) -> Styled` ##### Returns `Styled` `__terminal__` 0 `str` ▼ Protocol method — return current frame as safe string. `def __terminal__(self) -> str` ##### Returns `str` `LiveRenderer` 10 ▼ Context manager for in-place terminal re-rendering. Uses ANSI cursor movement to overwrite previou… Context manager for in-place terminal re-rendering. Uses ANSI cursor movement to overwrite previously rendered output, creating smooth animation effects. Each call to`update()`re-renders the template with fresh context and replaces the on-screen output. When the output is not a TTY, falls back to appending each render separated by a blank line (log-style trace). Usage:: ``` from kida.terminal import terminal_env, LiveRenderer env = terminal_env() tpl = env.from_string(template_str, name="live") with LiveRenderer(tpl) as live: live.update(status="building", progress=0.0) time.sleep(1) live.update(status="testing", progress=0.5) time.sleep(1) live.update(status="done", progress=1.0) ``` #### Methods `update` 1 ▼ Re-render the template with updated context. Merges *context* into the accumul… `def update(self, **context: Any) -> None` Re-render the template with updated context. Merges context into the accumulated context from previous `update()`calls, then renders and replaces the on-screen output. ##### Parameters Name Type Description `**context` `—` `start_auto` 1 ▼ Start auto-refreshing in a background thread. The template is re-rendered at `… `def start_auto(self, **context: Any) -> None` Start auto-refreshing in a background thread. The template is re-rendered at`refresh_rate`intervals using the current context. This is useful for animating spinners without explicit`update()` calls. Call `stop_auto()`or exit the context manager to stop. ##### Parameters Name Type Description `**context` `—` `stop_auto` 0 ▼ Stop the auto-refresh background thread. `def stop_auto(self) -> None` Internal Methods 7 ▼ `__init__` 4 ▼ `def __init__(self, template: Template, *, refresh_rate: float = 0.1, file: TextIO | None = None, transient: bool = False) -> None` ##### Parameters Name Type Description `template` `—` `refresh_rate` `—` Default:`0.1` `file` `—` Default:`None` `transient` `—` Default:`False` `__enter__` 0 `LiveRenderer` ▼ `def __enter__(self) -> LiveRenderer` ##### Returns `LiveRenderer` `__exit__` 3 ▼ `def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None` ##### Parameters Name Type Description `exc_type` `—` `exc_val` `—` `exc_tb` `—` `_clear_previous` 0 ▼ Move cursor up and erase all previously rendered lines. `def _clear_previous(self) -> None` `_write_output` 1 ▼ Write rendered output and track line count. `def _write_output(self, output: str) -> None` ##### Parameters Name Type Description `output` `—` `_show_cursor` 0 ▼ Safety net: ensure cursor is visible. `def _show_cursor(self) -> None` `_handle_sigint` 2 ▼ Handle Ctrl+C: clean up and re-raise. `def _handle_sigint(self, signum: int, frame: Any) -> None` ##### Parameters Name Type Description `signum` `—` `frame` `—` ## Functions `stream_to_terminal` 4 `None` ▼ Write ``render_stream()`` chunks to the terminal progressively. Each chunk (de… `def stream_to_terminal(template: Template, context: dict[str, Any] | None = None, *, delay: float = 0.02, file: TextIO | None = None) -> None` Write`render_stream()`chunks to the terminal progressively. Each chunk (delimited by statement boundaries or`{% flush %}`) is written to file with an optional delay between chunks, creating a typewriter-style reveal effect. When file is not a TTY (piped output, CI, etc.), the delay is skipped and all chunks are written immediately. ##### Parameters Name Type Description `template` `Template` A compiled Kida template. `context` `dict[str, Any] | None` Template context variables. Default:`None` `delay` `float` Seconds to sleep between chunks (0 = no delay). Default:`0.02` `file` `TextIO | None` Output stream (defaults to`sys.stdout`). Default:`None`