Source code for vtterm

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Show a VT100 terminal with ANSI colors on a board's display.

`Terminal` fits a grid of character cells to a display, reads escape codes
from whatever you feed it, and draws the rows that changed. Use it two ways:

* As the board's own console: `Console <vtterm.console.Console>` hands it to
  ``os.dupterm``, so the REPL appears on the display.
* As a terminal for another device: `run <vtterm.session.run>` joins it to a
  link (another board's REPL over Bluetooth LE, a TCP socket, a UART).

Example:
    >>> from board_config import display_drv
    >>> from vtterm import Terminal
    >>> term = Terminal(display_drv)
    >>> term.write(b"\\x1b[1;32mhello\\x1b[0m world\\r\\n")
"""

from pygraphics import Font

from .parser import Parser
from .render import Renderer
from .screen import Screen

__all__ = ["Parser", "Renderer", "Screen", "Terminal"]


[docs] class Terminal: """A screen, its parser and its renderer, sized to a display. Args: display: A 16-bit display driver (``board_config.display_drv``). font_height (int): ``8``, ``14`` or ``16``; the font is 8 pixels wide. cols (int): Columns; default as many as fit. rows (int): Rows; default as many as fit. fg (int): Default foreground, an ANSI palette index. bg (int): Default background, an ANSI palette index. palette (Palette): 16-bit colors for the 256 ANSI indices. hardware_scroll (bool): Scroll with the display's scroll registers; ``None`` (default) uses them when the driver has them. scrollback (int): Bytes to keep of rows that scrolled off the top, four per cell (a 40-column screen keeps about 100 rows in 16 KB). ``0`` keeps none. Attributes: screen (Screen): The grid. parser (Parser): Reads bytes onto the grid. renderer (Renderer): Draws the grid. """ def __init__(self, display, font_height=16, cols=None, rows=None, fg=7, bg=0, palette=None, hardware_scroll=None, scrollback=16384): font = Font(height=font_height) if cols is None: cols = display.width // font.width if rows is None: rows = display.height // font.height self.screen = Screen(cols, rows, fg, bg, scrollback) self._answers = bytearray() self.parser = Parser(self.screen, self._answers.extend) self.renderer = Renderer(display, self.screen, font, palette, hardware_scroll) self.renderer.clear()
[docs] def feed(self, data): """Read ``data`` onto the grid without drawing.""" self.parser.feed(data)
[docs] def render(self): """Draw the rows that changed. Returns how many were drawn.""" return self.renderer.render()
[docs] def scroll_back(self, rows): """Scroll the view back ``rows`` rows into the scrollback (negative goes forward) and draw it. New output returns the view to the live screen. """ self.screen.scroll_view(rows) self.renderer.render()
[docs] def write(self, data): """Read ``data`` onto the grid and draw it.""" self.parser.feed(data) self.renderer.render()
[docs] def answers(self): """Return the bytes the terminal owes the other end (reports), or ``None``.""" if not self._answers: return None out = bytes(self._answers) self._answers[:] = b"" return out