Classes
Spinner
8
▼
Animated spinner that advances one frame per call.
Use inside live-rendered templates — each ``Liv…
Spinner
8
▼
Animated spinner that advances one frame per call.
Use inside live-rendered templates — eachLiveRenderer.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 withStyled 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.
reset
0
▼
def reset(self) -> None
Internal Methods 3 ▼
__init__
1
▼
__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.
__call__
0
Styled
▼
def __call__(self) -> Styled
Returns
Styled
__terminal__
0
str
▼
Protocol method — return current frame as safe string.
__terminal__
0
str
▼
def __terminal__(self) -> str
Returns
str
LiveRenderer
10
▼
Context manager for in-place terminal re-rendering.
Uses ANSI cursor movement to overwrite previou…
LiveRenderer
10
▼
Context manager for in-place terminal re-rendering.
Uses ANSI cursor movement to overwrite previously rendered output,
creating smooth animation effects. Each call toupdate()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…
update
1
▼
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 `…
start_auto
1
▼
def start_auto(self, **context: Any) -> None
Start auto-refreshing in a background thread.
The template is re-rendered atrefresh_rateintervals using the
current context. This is useful for animating spinners without
explicitupdate() 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.
stop_auto
0
▼
def stop_auto(self) -> None
Internal Methods 7 ▼
__init__
4
▼
__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
▼
__enter__
0
LiveRenderer
▼
def __enter__(self) -> LiveRenderer
Returns
LiveRenderer
__exit__
3
▼
__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.
_clear_previous
0
▼
def _clear_previous(self) -> None
_write_output
1
▼
Write rendered output and track line count.
_write_output
1
▼
def _write_output(self, output: str) -> None
Parameters
| Name | Type | Description |
|---|---|---|
output |
— |
_show_cursor
0
▼
Safety net: ensure cursor is visible.
_show_cursor
0
▼
def _show_cursor(self) -> None
_handle_sigint
2
▼
Handle Ctrl+C: clean up and re-raise.
_handle_sigint
2
▼
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…
stream_to_terminal
4
None
▼
def stream_to_terminal(template: Template, context: dict[str, Any] | None = None, *, delay: float = 0.02, file: TextIO | None = None) -> None
Writerender_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 None
|