term: Shared Terminal Primitives#

Houses the single canonical implementations of terminal-capability detection, OSC 11 / Kitty-graphics escape emission, dark/light mode resolution, and CLI version reporting – primitives that colorcode, pathcode, kittyhud, and presence each grew independently and let drift.

I Capability Detection#

irix.term.is_kitty(environment: Mapping[str, str] | None = None) → bool#

Return whether environment identifies the current terminal as Kitty.

This is the canonical “is this Kitty?” check: $TERM == 'xterm-kitty' OR a truthy $KITTY_WINDOW_ID. It is deliberately more permissive than a bare $KITTY_WINDOW_ID check.

Two colorcode call sites keep their own narrower, $KITTY_WINDOW_ID-only checks instead of this function: colorcode.ColorCoder._window_override_path and colorcode.ColorCoder.multiset. Both genuinely need the window ID value (for the per-pane override filename and kitty-tab window ordering), not just a yes/no signal, so a truthy $TERM alone is not enough for them – that asymmetry is preserved intentionally.

Parameters:

environment – Environment mapping to check. Defaults to os.environ.

II OSC 11 / Escape Emission#

irix.term.osc11_sequence(hex_color: str) → str#

Build the OSC 11 (set terminal background color) escape sequence for hex_color.

Pure string construction – callers decide how and where to write it. This is the shared format shared by emit_osc11 (device-selecting) and irix.presence.osc11 (deliberately device-agnostic; see that module’s docstring for why it does not write anywhere itself).

Parameters:

hex_color – The hex color value (e.g. '#1A2B3C').

irix.term.enable_vt_win32() → None#

Best-effort enable of ANSI/VT escape processing on a Windows console.

Silently swallows any failure and is a no-op on non-Windows platforms – this is a courtesy for legacy Windows consoles that don’t already interpret VT escapes; POSIX terminals need no such step. The sys.platform guard lives inside this function (rather than at each call site) so a type checker’s platform-based dead-code elimination sees ctypes.windll – Windows-only – as unreachable directly within this function’s own body.

irix.term.emit_osc11(hex_color: str) → None#

Write an OSC 11 escape sequence to the terminal device.

Uses /dev/tty on POSIX systems (robust against stdout redirection) and falls back to sys.stdout on Windows or when the device is unavailable.

Parameters:

hex_color – The hex color value (e.g. '#1A2B3C').

irix.term.write_tty_bytes(payload: bytes) → bool#

Write raw payload bytes to /dev/tty, falling back to sys.stdout.buffer.

This is kittyhud’s original _write_to_tty helper (its binary-payload twin of emit_osc11), EXTENDED with the same Windows VT-enable attempt emit_osc11 makes – the original had no such branch. That’s a deliberate behavior improvement made while unifying the two, not a preserved wart.

Parameters:

payload – Raw bytes to write (e.g. a Kitty graphics-protocol frame sequence).

Returns:

True if the write went to /dev/tty, False if it fell back to standard output.

III Paths and Mode#

irix.term.expand_path_expr(expr: str, warn: Callable[[str], None] | None = None) → str#

Expand ~/ and $VAR/${VAR} prefixes in a directory pattern expression.

Originally colorcode.ColorCoder._expand_path_expr; moved here so pathcode can share it for places: entries without an import cycle (colorcode already imports pathcode.PathCoder, so the reverse direction would cycle). pathcode’s places: entries previously supported only ~/, not $VAR/${VAR} – real drift from colorcode’s directories:/places: entries, fixed by this share.

Parameters:

  • expr – Raw pattern expression from the config file.

  • warn – Optional callback invoked with a warning message when a referenced env var is unset. Callers that have no diagnostic channel (e.g. pathcode, which has no verbose flag) may omit it.

Returns:

The expression with home directory and environment variables expanded.

Raises:

ValueError – If more than 5 consecutive $VAR substitutions occur.

irix.term.DEFAULT_MODE = 'dark'#

The default rendering mode when neither --mode nor $IRIX_MODE specifies one.

irix.term.resolve_mode(explicit: str | None, env: Mapping[str, str] | None = None) → str#

Resolve the dark/light rendering mode.

Precedence: explicit (an already-parsed --mode flag value) wins; else $IRIX_MODE; else DEFAULT_MODE ('dark'). An invalid value – from either source – prints one warning to stderr (never stdout: several callers, e.g. pathcode, pipe stdout as the literal rendered output) and falls back to DEFAULT_MODE rather than raising; color-mode selection must never crash a shell prompt.

Parameters:

  • explicit – The --mode CLI flag value, or None when the flag was omitted. CLIs that restrict the flag with choices=('dark', 'light') never pass an invalid value here; the invalid-value path mainly guards direct/programmatic callers.

  • env – Environment mapping to read $IRIX_MODE from. Defaults to os.environ.

Returns:

'dark' or 'light'.

IV Versioning#

irix.term.package_version() → str#

Return the installed irix distribution version, resolved once per process.

class irix.term._LazyVersionAction(option_strings: list[str], dest: str = '==SUPPRESS==', default: str = '==SUPPRESS==', help: str = "show the program's version and exit")#

Print <prog> <version> and exit, resolving the version lazily.

Standard argparse “version” actions format their string eagerly, at add_argument() time – so importlib.metadata.version() (a real dist-info disk read) would run on every invocation of these CLIs, even when --version is never passed. Since colorcode/promptcode run fresh on every shell prompt (see irix’s package docstring on lazy imports for the same concern), that cost is worth avoiding: this action resolves the version only when --version is actually given.

irix.term.add_version_argument(parser: ArgumentParser) → None#

Add a lazily-resolved --version flag to parser.

Parameters:

parser – The CLI’s argument parser.