claudewheel v0.24.2 /claudewheel.terminal
Updated Edit
On this page

Terminal class for raw-mode input handling and screen management.

#claudewheel.terminal

#claudewheel.terminal

Raw terminal I/O: cbreak mode, escape sequence decoding, and alt screen.

#Terminal

Low-level terminal I/O: raw mode, key reading, alt screen, and size detection.

#get_size

python
def get_size(self) -> tuple[int, int]

Return the current terminal size as (rows, cols).

#enter_raw

python
def enter_raw(self, alt_screen: bool=True) -> None

Enter cbreak mode, optionally switching to the alt screen.

#subscribe_mode2031

python
def subscribe_mode2031(self) -> None

Subscribe to Mode 2031 theme-change notifications.

#exit_raw

python
def exit_raw(self) -> None

Restore the terminal to its pre-raw state.

#cooked

python
def cooked(self) -> Iterator[Terminal]

Temporarily leave raw mode for the duration of the with-block.

If the terminal is currently raw, exits raw mode on entry and re-enters it on exit with the same alt_screen flag it had before. If already cooked, this is a no-op passthrough (so nesting is safe). Raw mode is restored even if the body raises.

#read_key

python
def read_key(self) -> str

Read a single keypress, decoding escape sequences for arrow keys etc.

#read_masked_line

python
def read_masked_line(self, prompt: str='', mask: str='*') -> str

Read a line of input with echo suppressed, showing a mask per key.

Manages raw mode itself: if the terminal is not already raw it enters cbreak (alt-screen off) for the duration of the read and restores the prior mode afterward. Because :meth:enter_raw uses cbreak (not full raw), output newline translation stays on, so any surrounding prints still render correctly.

Key handling (over :meth:read_key semantics):

  • a printable single character accumulates and echoes mask;
  • BACKSPACE removes the last character and erases one mask glyph;
  • ENTER terminates and returns the accumulated string;
  • CTRL_C (also CTRL_D / ESC) raises KeyboardInterrupt;
  • any other key (arrows, function keys, paste-embedded control keys)

is ignored.

The typed characters are NEVER echoed and NEVER written to the tty in clear -- only mask glyphs are emitted -- so a secret can be entered without it appearing on screen or in captured output.

#_write_tty

python
def _write_tty(self, text: str) -> None

Write directly to the TTY device.

#write

python
def write(self, text: str) -> None

Write text to the terminal.

#flush

python
def flush(self) -> None

Flush the terminal output buffer.

#close

python
def close(self) -> None

Close the /dev/tty file handle.

#detect_terminal_background

python
def detect_terminal_background() -> str | None

Detect whether the terminal has a light or dark background.

Uses the OSC 11 query (background color request) with a DA1 sentinel to detect terminals that do not support OSC 11. Returns "light", "dark", or None (unsupported / timeout / error).

Must be called BEFORE entering the TUI (before raw mode, before user input can race with the response).

#detect_mode2031_support

python
def detect_mode2031_support() -> str | None

Detect whether the terminal supports Mode 2031 (theme-change notifications).

Sends CSI ?996n (Mode 2031 query) + DA1 sentinel. If the terminal responds with CSI ?997;Xn (where X=1 for dark, X=2 for light), Mode 2031 is supported. Returns "dark", "light", or None.

Must be called BEFORE entering the TUI.

#_parse_mode2031_response

python
def _parse_mode2031_response(fd: int) -> str | None

Read and parse the Mode 2031 query response from the terminal.

Returns "dark" (mode=1), "light" (mode=2), or None (unsupported/timeout).

#_parse_osc11_response

python
def _parse_osc11_response(fd: int) -> str | None

Read and parse the OSC 11 response from the terminal.

Returns "light", "dark", or None.

#_classify_rgb

python
def _classify_rgb(rgb_str: str) -> str | None

Parse an rgb:RR/GG/BB (1-4 hex digits per channel) string and classify as light or dark.

Returns "light" if perceived luminance > 0.5, "dark" otherwise, or None on parse error.

Search