API reference¶

Auto-generated from docstrings via mkdocstrings.

Top-level¶

tuiwright ¶

tuiwright — Playwright-style end-to-end testing for TUI applications.

Drives any TUI binary under a real PTY + terminal emulator, with cell-grid and PNG snapshot regression.

Quick start:

async def test_app(tui, snapshot):
    await tui.start("myapp")
    await tui.wait_for_text("Ready")
    await tui.type("hello")
    await tui.press("enter")
    assert tui.screen == snapshot

Cell `dataclass` ¶

A single rendered terminal cell.

Source code in src/tuiwright/screen.py

@dataclass(frozen=True, slots=True)
class Cell:
    """A single rendered terminal cell."""

    char: str = " "
    fg: Color = _DEFAULT_COLOR
    bg: Color = _DEFAULT_COLOR
    bold: bool = False
    italic: bool = False
    underline: bool = False
    reverse: bool = False
    strike: bool = False
    blink: bool = False

    def has_default_attrs(self) -> bool:
        return (
            self.fg.is_default
            and self.bg.is_default
            and not (self.bold or self.italic or self.underline or self.reverse or self.strike or self.blink)
        )

Color `dataclass` ¶

A foreground or background colour.

name is one of "default", "black", "red" … or the empty string if rgb is set. rgb is a hex triple "ff8800" (no leading #) for true-colour cells, or None otherwise.

Source code in src/tuiwright/screen.py

@dataclass(frozen=True, slots=True)
class Color:
    """A foreground or background colour.

    ``name`` is one of ``"default"``, ``"black"``, ``"red"`` … or the empty
    string if ``rgb`` is set. ``rgb`` is a hex triple ``"ff8800"`` (no
    leading ``#``) for true-colour cells, or ``None`` otherwise.
    """

    name: str = "default"
    rgb: str | None = None

    @classmethod
    def from_pyte(cls, value: str) -> Color:
        # pyte uses "default" sentinel and 6-char hex for true colour.
        if value == "default":
            return _DEFAULT_COLOR
        if len(value) == 6 and all(c in "0123456789abcdefABCDEF" for c in value):
            return cls(name="", rgb=value.lower())
        return cls(name=value)

    @property
    def is_default(self) -> bool:
        return self.name == "default" and self.rgb is None

Region `dataclass` ¶

A rectangular sub-view of a :class:Screen.

Bounds are inclusive on top/left and exclusive on bottom/right (standard Python slice convention).

Source code in src/tuiwright/screen.py

@dataclass(frozen=True)
class Region:
    """A rectangular sub-view of a :class:`Screen`.

    Bounds are *inclusive* on top/left and *exclusive* on bottom/right
    (standard Python slice convention).
    """

    screen: Screen
    top: int
    bottom: int
    left: int
    right: int
    title: str | None = None

    @property
    def rows(self) -> int:
        return self.bottom - self.top

    @property
    def cols(self) -> int:
        return self.right - self.left

    @property
    def text(self) -> str:
        return "\n".join(self.row(i) for i in range(self.rows))

    def row(self, i: int) -> str:
        cells = self.screen.cells[self.top + i][self.left : self.right]
        return "".join(c.char for c in cells).rstrip()

    def contains(self, needle: str | re.Pattern[str], *, regex: bool = False) -> bool:
        pat = needle if isinstance(needle, re.Pattern) else (
            re.compile(needle) if regex else re.compile(re.escape(needle))
        )
        return any(pat.search(self.row(i)) for i in range(self.rows))

Screen `dataclass` ¶

An immutable snapshot of the terminal grid.

Source code in src/tuiwright/screen.py

@dataclass(frozen=True)
class Screen:
    """An immutable snapshot of the terminal grid."""

    rows: int
    cols: int
    cells: tuple[tuple[Cell, ...], ...]
    cursor: Cursor
    modes: frozenset[int] = field(default_factory=frozenset)

    # -- construction --------------------------------------------------

    @classmethod
    def from_emulator(cls, emu: Emulator) -> Screen:
        from tuiwright._emulator import Emulator as _Emu  # noqa: F401

        pyte_cells = emu.cells()
        rows = tuple(
            tuple(
                Cell(
                    char=pc.data or " ",
                    fg=Color.from_pyte(pc.fg),
                    bg=Color.from_pyte(pc.bg),
                    bold=bool(pc.bold),
                    italic=bool(pc.italics),
                    underline=bool(pc.underscore),
                    reverse=bool(pc.reverse),
                    strike=bool(pc.strikethrough),
                    blink=bool(pc.blink),
                )
                for pc in row
            )
            for row in pyte_cells
        )
        pyte_cursor = emu.screen.cursor
        cursor = Cursor(row=pyte_cursor.y, col=pyte_cursor.x, hidden=bool(pyte_cursor.hidden))
        return cls(
            rows=emu.rows,
            cols=emu.cols,
            cells=rows,
            cursor=cursor,
            modes=emu.private_modes,
        )

    # -- text views ----------------------------------------------------

    @property
    def text(self) -> str:
        """All rows joined with ``\\n``, trailing spaces stripped per row."""
        return "\n".join(self.row(i) for i in range(self.rows))

    def row(self, i: int) -> str:
        return "".join(c.char for c in self.cells[i]).rstrip()

    def row_padded(self, i: int) -> str:
        return "".join(c.char for c in self.cells[i])

    def cell(self, row: int, col: int) -> Cell:
        return self.cells[row][col]

    # -- search --------------------------------------------------------

    def find(self, needle: str | re.Pattern[str], *, regex: bool = False) -> list[Position]:
        pattern = needle if isinstance(needle, re.Pattern) else (
            re.compile(needle) if regex else re.compile(re.escape(needle))
        )
        out: list[Position] = []
        for r in range(self.rows):
            for m in pattern.finditer(self.row_padded(r)):
                out.append(Position(r, m.start()))
        return out

    def row_containing(
        self, needle: str | re.Pattern[str], *, regex: bool = False
    ) -> int | None:
        hits = self.find(needle, regex=regex)
        return hits[0].row if hits else None

    def contains(self, needle: str | re.Pattern[str], *, regex: bool = False) -> bool:
        return bool(self.find(needle, regex=regex))

    # -- regions -------------------------------------------------------

    def region(
        self,
        *,
        title: str | None = None,
        rows: tuple[int, int] | None = None,
        cols: tuple[int, int] | None = None,
    ) -> Region:
        if title is not None:
            found = _find_titled_region(self, title)
            if found is None:
                raise LookupError(f"no titled region matching {title!r}")
            return found
        if rows is None or cols is None:
            raise ValueError("either title= or both rows= and cols= must be given")
        r0, r1 = rows
        c0, c1 = cols
        return Region(screen=self, top=r0, bottom=r1, left=c0, right=c1, title=None)

text `property` ¶

text: str

All rows joined with \n, trailing spaces stripped per row.

TuiSession ¶

Drives a TUI binary under a PTY.

Use it as an async context manager or call :meth:start / :meth:stop explicitly. After start, every method that injects input is sync from the caller's perspective (no awaiting on the child) but async because most flows interleave with await wait_for_*.