API Reference

ANSI terminal emulation and conversion library. The main entry point is Terminal.

class ANSIParser(terminal: Terminal, warn_unknown: bool = False)

Parser for ANSI control characters and escape sequences.

feed(data: str, collapse_capture_updates: bool = False) → None

Parse and apply terminal updates for the provided text.

class AnsiConverter(esc_char: str = '\x1b')

Converter to compact ANSI-encoded text output.

convert(screen: ScreenBuffer) → str

Convert the full screen + history into a serialized output format.

class Character(text: str = ' ', style: CharacterStyle = CharacterStyle(bold=False, dim=False, italic=False, underline=False, blink=False, reverse=False, hidden=False, strike=False, foreground=None, background=None), width: int = 1, continuation: bool = False)

A single terminal cell character plus formatting state.

classmethod blank() → Character

Create a blank cell with default style.

class CharacterStyle(bold: bool = False, dim: bool = False, italic: bool = False, underline: bool = False, blink: bool = False, reverse: bool = False, hidden: bool = False, strike: bool = False, foreground: str | None = None, background: str | None = None)

A complete style state for one terminal cell.

with_updates(**kwargs: object) → CharacterStyle

Return a copied style with updated fields.

html_classes() → list[str]

Return a compact list of style class suffixes.

class Converter

Base class for terminal state converters.

abstractmethod convert(screen: ScreenBuffer) → str

Convert the full screen + history into a serialized output format.

class Cursor(x: int = 0, y: int = 0, style: CharacterStyle = CharacterStyle(bold=False, dim=False, italic=False, underline=False, blink=False, reverse=False, hidden=False, strike=False, foreground=None, background=None), visible: bool = True)

The active cursor and style state.

copy() → Cursor

Return a shallow copy of this cursor state.

class HtmlConverter(class_prefix: str = 'erbsland-ansi')

Converter to compact HTML using reusable CSS classes.

convert(screen: ScreenBuffer) → str

Convert the full screen + history into a serialized output format.

class ScreenBuffer(width: int, height: int, back_buffer_height: int)

A visible screen with an attached scroll-back buffer.

property history: tuple[list[Character], ...]

Return the current scroll-back history rows.

property rows: tuple[list[Character], ...]

Return the visible rows.

all_rows() → list[list[Character]]

Return history followed by visible screen rows.

snapshot() → ScreenSnapshot

Create a deep copy snapshot of this screen state.

restore(snapshot: ScreenSnapshot) → None

Restore a previously captured snapshot.

clear() → None

Clear visible rows and keep history unchanged.

clear_history() → None

Clear the scroll-back history.

scroll_up(lines: int = 1) → None

Scroll visible content up and append blank lines at the bottom.

reverse_index() → None

ESC M behavior for a screen at row 0 (scroll down one line).

set_character(x: int, y: int, character: str, style: CharacterStyle, width: int = 1) → None

Write one character at the given visible coordinates.

append_combining(x: int, y: int, combining_mark: str) → None

Append a combining mark to the base cell at the given coordinates.

erase_in_display(mode: int, cursor_x: int, cursor_y: int) → None

Execute CSI J erase behavior.

erase_in_line(mode: int, cursor_x: int, cursor_y: int) → None

Execute CSI K erase behavior.

class Terminal(width: int = 120, height: int = 40, back_buffer_height: int = 2000, warn_unknown_sequences: bool = False)

ANSI terminal emulator with scroll-back history and converters.

property screen: ScreenBuffer

Return the currently active screen buffer.

write(data: str, collapse_capture_updates: bool = False) → None

Process terminal output text including ANSI escape sequences.

Parameters:

• data – Terminal output text.

• collapse_capture_updates – Apply a heuristic for text captures where carriage returns were normalized to newlines.

writeFile(capture_file: str | Path, encoding: str = 'utf-8', errors: str = 'replace', collapse_capture_updates: bool | None = None) → None

Read and process terminal output from a capture file.

The file is read as bytes to preserve raw carriage returns. If the capture appears to be a transcript with CR-only line endings (for example from script), it is normalized to newlines automatically.

Parameters:

• capture_file – Path to the capture file.

• encoding – Encoding used to decode bytes into text.

• errors – Decoder error handling strategy.

• collapse_capture_updates – Optional heuristic to collapse progress update lines when CR was normalized before parsing. If omitted, auto-detection is used for transcript-style captures.

to_text() → str

Convert current screen + history to plain text.

to_ansi(esc_char: str = '\x1b') → str

Convert current screen + history to compact ANSI encoded text.

to_html(class_prefix: str = 'erbsland-ansi') → str

Convert current screen + history to compact HTML.

clear() → None

Reset the active screen and cursor position.

move_cursor_to(x: int, y: int) → None

Move cursor to an absolute position within visible screen bounds.

move_cursor_to_column(x: int) → None

Move cursor to a column in the current row.

cursor_up(lines: int) → None

Move cursor up by a number of rows.

cursor_down(lines: int) → None

Move cursor down by a number of rows.

cursor_right(columns: int) → None

Move cursor right by a number of columns.

cursor_left(columns: int) → None

Move cursor left by a number of columns.

carriage_return() → None

Move cursor to beginning of current line.

line_feed() → None

Move cursor down one line and scroll if needed.

reverse_index() → None

ESC M: move cursor one line up, scrolling the screen down if needed.

horizontal_tab() → None

Move cursor to next 8-column tab stop.

put_character(character: str) → None

Write one printable character at the cursor position.

erase_in_display(mode: int) → None

Execute CSI J with the active cursor position.

erase_in_line(mode: int) → None

Execute CSI K with the active cursor position.

save_cursor_dec() → None

ESC 7: save cursor and style state.

restore_cursor_dec() → None

ESC 8: restore cursor and style state.

save_cursor_sco() → None

CSI s: save cursor and style state.

restore_cursor_sco() → None

CSI u: restore cursor and style state.

report_cursor_position() → None

CSI 6n response emulation stored in responses.

enable_alternate_buffer(save_cursor: bool = True) → None

Enable alternate screen mode (?47h / ?1049h).

disable_alternate_buffer(restore_cursor: bool = True) → None

Disable alternate screen mode (?47l / ?1049l).

class TextConverter

Converter to plain text with all ANSI formatting removed.

convert(screen: ScreenBuffer) → str

Convert the full screen + history into a serialized output format.