Module

utils.terminal_probe

Terminal character width probing for Kida template engine.

Probes the actual terminal to determine how wide ambiguous-width Unicode characters render. This gives pixel-accurate width measurement for the user's specific terminal + font combination.

The probe works by:

  1. Saving cursor position
  2. Writing a test character
  3. Querying cursor position via ANSI DSR (Device Status Report)
  4. Measuring how many columns the cursor advanced

Thread-Safety: Probe functions are not thread-safe (they manipulate terminal state). Call once during Environment init, then use the cached result.

2Functions

Functions

probe_ambiguous_width 1 int | None ▼
Probe the terminal to determine the rendered width of ambiguous characters. Wr…
def probe_ambiguous_width(timeout: float = 0.1) -> int | None

Probe the terminal to determine the rendered width of ambiguous characters.

Writes a known ambiguous-width character and measures cursor movement using ANSI escape codes. Returns 1 or 2 on success, orNoneif probing is not possible (non-TTY, non-Unix, timeout, etc.).

Parameters
Name Type Description
timeout float

Maximum seconds to wait for terminal response.

Default:0.1
Returns
int | None
_probe_tty 4 int | None ▼
TTY-dependent probe internals. Requires a real terminal to exercise.
def _probe_tty(select, termios, tty, timeout: float) -> int | None
Parameters
Name Type Description
select —
termios —
tty —
timeout float
Returns
int | None