Terminal

curtaincall.terminal.Terminal

A terminal session backed by a real PTY and VT100 emulator.

Spawns the given command in a pseudo-terminal, reads its output in a background thread, and feeds it through pyte for accurate screen state.

Uses pyte.HistoryScreen for scrollback buffer support so that content scrolled off the visible viewport is still searchable by locators.

is_alive property

Whether the child process is still running.

exit_code property

The exit code of the child process, or None if still running.

start()

Spawn the child process and start reading its output.

write(text)

Send raw text to the PTY.

submit(text)

Send text followed by Enter.

get_by_text(text, *, full=False)

Create a locator that matches text on the screen.

Parameters:

Name	Type	Description	Default
text	str | Pattern[str]	String or compiled regex to search for.	required
full	bool	If True, match the entire line (stripped) instead of substring.	False

Returns:

Type	Description
Locator	A Locator instance (lazy -- doesn't search until used).

get_cursor()

Return the current cursor position.

get_buffer()

Return the full buffer (scrollback + viewport) as a 2D list of characters.

Scrollback lines come first (oldest at index 0), followed by the visible viewport rows. This means get_by_text() and other locator searches will find text that has scrolled off the top of the screen.

get_viewable_buffer()

Return the visible viewport only (no scrollback).

wait(*, timeout=10.0)

Block until the child process exits and return its exit code.

Raises TimeoutError if the process doesn't exit within timeout seconds.

set_size(*, rows, cols)

Resize the terminal.

kill()

Terminate the child process and stop the reader thread.

to_snapshot()

Render the current screen as a box-drawn snapshot string.