bittty 0.0.1__py3-none-any.whl

bittty/__init__.py

@@ -0,0 +1,34 @@
+"""
+bittty: A fast, pure Python terminal emulator library.
+
+bittty (bitplane-tty) is a high-performance terminal emulator engine
+that provides comprehensive ANSI sequence parsing and terminal state management.
+"""
+
+from .terminal import Terminal
+from .buffer import Buffer
+from .parser import Parser
+from .color import (
+    get_color_code,
+    get_rgb_code,
+    get_style_code,
+    get_combined_code,
+    reset_code,
+    get_cursor_code,
+    get_clear_line_code,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Terminal",
+    "Buffer",
+    "Parser",
+    "get_color_code",
+    "get_rgb_code",
+    "get_style_code",
+    "get_combined_code",
+    "reset_code",
+    "get_cursor_code",
+    "get_clear_line_code",
+]

bittty/buffer.py

@@ -0,0 +1,272 @@
+"""
+Terminal Buffer: Grid-based terminal content storage.
+
+This module provides the Buffer class that manages terminal screen content
+as a 2D grid of (ansi_code, character) tuples.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+from . import constants
+from .color import get_cursor_code, reset_code
+
+
+# Type alias for a cell: (ANSI code, character)
+Cell = Tuple[str, str]
+
+
+class Buffer:
+    """
+    A buffer that stores terminal content as a 2D grid.
+
+    Each cell contains a tuple of (ansi_code, character) where:
+    - ansi_code: ANSI escape sequence for styling (empty string for no styling)
+    - character: The actual character to display
+    """
+
+    def __init__(self, width: int, height: int) -> None:
+        """Initialize buffer with given dimensions."""
+        self.width = width
+        self.height = height
+        # Initialize grid with empty cells
+        self.grid: List[List[Cell]] = [[("", " ") for _ in range(width)] for _ in range(height)]
+
+    def get_content(self) -> List[List[Cell]]:
+        """Get buffer content as a 2D grid."""
+        return [row[:] for row in self.grid]
+
+    def get_cell(self, x: int, y: int) -> Cell:
+        """Get cell at position."""
+        if 0 <= y < self.height and 0 <= x < self.width:
+            return self.grid[y][x]
+        return ("", " ")
+
+    def set_cell(self, x: int, y: int, char: str, ansi_code: str = "") -> None:
+        """Set a single cell at position."""
+        if 0 <= y < self.height and 0 <= x < self.width:
+            self.grid[y][x] = (ansi_code, char)
+
+    def set(self, x: int, y: int, text: str, ansi_code: str = "") -> None:
+        """Set text at position, overwriting existing content."""
+        if not (0 <= y < self.height):
+            return
+
+        for i, char in enumerate(text):
+            if x + i >= self.width:
+                break
+            self.grid[y][x + i] = (ansi_code, char)
+
+    def insert(self, x: int, y: int, text: str, ansi_code: str = "") -> None:
+        """Insert text at position, shifting existing content right."""
+        if not (0 <= y < self.height) or x >= self.width:
+            return
+
+        # Get the current row
+        row = self.grid[y]
+
+        # Create new cells for the inserted text
+        new_cells = [(ansi_code, char) for char in text]
+
+        # Insert at position
+        if x < len(row):
+            # Split row and insert
+            new_row = row[:x] + new_cells + row[x:]
+            # Truncate to width
+            self.grid[y] = new_row[: self.width]
+        else:
+            # Pad with spaces if needed
+            padding_needed = x - len(row)
+            if padding_needed > 0:
+                row.extend([("", " ")] * padding_needed)
+            row.extend(new_cells)
+            # Truncate to width
+            self.grid[y] = row[: self.width]
+
+    def delete(self, x: int, y: int, count: int = 1) -> None:
+        """Delete characters at position."""
+        if not (0 <= y < self.height) or x >= self.width:
+            return
+
+        row = self.grid[y]
+
+        # Delete characters and shift left
+        if x < len(row):
+            end_pos = min(x + count, len(row))
+            new_row = row[:x] + row[end_pos:]
+            # Pad with spaces to maintain width
+            while len(new_row) < self.width:
+                new_row.append(("", " "))
+            self.grid[y] = new_row
+
+    def clear_region(self, x1: int, y1: int, x2: int, y2: int, ansi_code: str = "") -> None:
+        """Clear a rectangular region."""
+        for y in range(max(0, y1), min(self.height, y2 + 1)):
+            for x in range(max(0, x1), min(self.width, x2 + 1)):
+                self.grid[y][x] = (ansi_code, " ")
+
+    def clear_line(
+        self, y: int, mode: int = constants.ERASE_FROM_CURSOR_TO_END, cursor_x: int = 0, ansi_code: str = ""
+    ) -> None:
+        """Clear line content."""
+        if not (0 <= y < self.height):
+            return
+
+        if mode == constants.ERASE_FROM_CURSOR_TO_END:
+            # Clear from cursor to end of line
+            for x in range(cursor_x, self.width):
+                self.grid[y][x] = (ansi_code, " ")
+        elif mode == constants.ERASE_FROM_START_TO_CURSOR:
+            # Clear from start to cursor
+            for x in range(0, min(cursor_x + 1, self.width)):
+                self.grid[y][x] = (ansi_code, " ")
+        elif mode == constants.ERASE_ALL:
+            # Clear entire line
+            self.grid[y] = [(ansi_code, " ") for _ in range(self.width)]
+
+    def scroll_up(self, count: int) -> None:
+        """Scroll content up, removing top lines and adding blank lines at bottom."""
+        for _ in range(count):
+            self.grid.pop(0)
+            self.grid.append([("", " ") for _ in range(self.width)])
+
+    def scroll_down(self, count: int) -> None:
+        """Scroll content down, removing bottom lines and adding blank lines at top."""
+        for _ in range(count):
+            self.grid.pop()
+            self.grid.insert(0, [("", " ") for _ in range(self.width)])
+
+    def resize(self, width: int, height: int) -> None:
+        """Resize buffer to new dimensions."""
+        # Adjust number of rows
+        if len(self.grid) < height:
+            # Add new rows
+            for _ in range(height - len(self.grid)):
+                self.grid.append([("", " ") for _ in range(width)])
+        elif len(self.grid) > height:
+            # Remove excess rows
+            self.grid = self.grid[:height]
+
+        # Adjust width of each row
+        for y in range(len(self.grid)):
+            row = self.grid[y]
+            if len(row) < width:
+                # Extend row
+                row.extend([("", " ")] * (width - len(row)))
+            elif len(row) > width:
+                # Truncate row
+                self.grid[y] = row[:width]
+
+        # Update dimensions
+        self.width = width
+        self.height = height
+
+    def get_line_text(self, y: int) -> str:
+        """Get plain text content of a line (for debugging/testing)."""
+        if 0 <= y < self.height:
+            return "".join(cell[1] for cell in self.grid[y])
+        return ""
+
+    def get_line(
+        self,
+        y: int,
+        width: int = None,
+        cursor_x: int = -1,
+        cursor_y: int = -1,
+        show_cursor: bool = False,
+        mouse_x: int = -1,
+        mouse_y: int = -1,
+        show_mouse: bool = False,
+    ) -> str:
+        """Get full ANSI sequence for a line (like tmux capture-pane)."""
+        if not (0 <= y < self.height):
+            return ""
+
+        # Use buffer width if not specified
+        if width is None:
+            width = self.width
+
+        parts = []
+        row = self.grid[y]
+
+        # Process each cell up to specified width
+        for x in range(min(len(row), width)):
+            ansi_code, char = row[x]
+
+            # Handle mouse cursor (convert to 0-based, as original code does mouse_x - 1)
+            if show_mouse and x == (mouse_x - 1) and y == (mouse_y - 1):
+                char = "↖"
+
+            # Handle text cursor position
+            if show_cursor and x == cursor_x and y == cursor_y:
+                # Add cursor style
+                parts.append(ansi_code)
+                parts.append(get_cursor_code())
+                parts.append(char)
+                parts.append("\033[27m")  # Turn off reverse video only
+            else:
+                # Normal cell
+                parts.append(ansi_code)
+                parts.append(char)
+
+        # Pad to width if needed
+        current_width = min(len(row), width)
+        if current_width < width:
+            # Reset all attributes for padding (including background)
+            parts.append(reset_code())
+            parts.append(" " * (width - current_width))
+
+        # Always end with a reset to prevent bleeding to next line
+        parts.append(reset_code())
+
+        return "".join(parts)
+
+    def get_line_tuple(
+        self,
+        y: int,
+        width: int = None,
+        cursor_x: int = -1,
+        cursor_y: int = -1,
+        show_cursor: bool = False,
+        mouse_x: int = -1,
+        mouse_y: int = -1,
+        show_mouse: bool = False,
+    ) -> tuple:
+        """Get line as hashable tuple for caching: (ansi_code, char, ansi_code, char, ...)"""
+        if not (0 <= y < self.height):
+            return tuple()
+
+        # Use buffer width if not specified
+        if width is None:
+            width = self.width
+
+        parts = []
+        row = self.grid[y]
+
+        # Process each cell up to specified width
+        for x in range(min(len(row), width)):
+            ansi_code, char = row[x]
+
+            # Handle mouse cursor (convert to 0-based, as original code does mouse_x - 1)
+            if show_mouse and x == (mouse_x - 1) and y == (mouse_y - 1):
+                char = "↖"
+
+            # Handle text cursor position
+            if show_cursor and x == cursor_x and y == cursor_y:
+                # Add cursor style
+                parts.extend(("ansi", ansi_code, "cursor", get_cursor_code(), "char", char, "cursor_end", "\033[27m"))
+            else:
+                # Normal cell
+                parts.extend(("ansi", ansi_code, "char", char))
+
+        # Pad to width if needed
+        current_width = min(len(row), width)
+        if current_width < width:
+            # Reset all attributes for padding (including background)
+            parts.extend(("reset", reset_code(), "pad", " " * (width - current_width)))
+
+        # Always end with a reset to prevent bleeding to next line
+        parts.extend(("final_reset", reset_code()))
+
+        return tuple(parts)

bittty/color.py

@@ -0,0 +1,225 @@
+"""
+ANSI Sequence Cache: LRU-cached functions for generating ANSI escape sequences.
+
+This module provides high-performance ANSI sequence generation by caching
+commonly used combinations of colors and styles.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Optional, Tuple
+
+
+@lru_cache(maxsize=1024)
+def get_color_code(fg: Optional[int] = None, bg: Optional[int] = None) -> str:
+    """
+    Generate ANSI color code for 256-color palette.
+
+    Args:
+        fg: Foreground color (0-255) or None
+        bg: Background color (0-255) or None
+
+    Returns:
+        ANSI escape sequence for the colors
+    """
+    if fg is None and bg is None:
+        return ""
+
+    codes = []
+    if fg is not None:
+        codes.append(f"38;5;{fg}")
+    if bg is not None:
+        codes.append(f"48;5;{bg}")
+
+    return f"\033[{';'.join(codes)}m"
+
+
+@lru_cache(maxsize=512)
+def get_rgb_code(fg_rgb: Optional[Tuple[int, int, int]] = None, bg_rgb: Optional[Tuple[int, int, int]] = None) -> str:
+    """
+    Generate ANSI color code for RGB colors.
+
+    Args:
+        fg_rgb: Foreground RGB tuple (r, g, b) or None
+        bg_rgb: Background RGB tuple (r, g, b) or None
+
+    Returns:
+        ANSI escape sequence for the RGB colors
+    """
+    if fg_rgb is None and bg_rgb is None:
+        return ""
+
+    codes = []
+    if fg_rgb is not None:
+        r, g, b = fg_rgb
+        codes.append(f"38;2;{r};{g};{b}")
+    if bg_rgb is not None:
+        r, g, b = bg_rgb
+        codes.append(f"48;2;{r};{g};{b}")
+
+    return f"\033[{';'.join(codes)}m"
+
+
+@lru_cache(maxsize=256)
+def get_style_code(
+    bold: bool = False,
+    dim: bool = False,
+    italic: bool = False,
+    underline: bool = False,
+    blink: bool = False,
+    reverse: bool = False,
+    strike: bool = False,
+    conceal: bool = False,
+) -> str:
+    """
+    Generate ANSI style code for text attributes.
+
+    Returns:
+        ANSI escape sequence for the styles
+    """
+    codes = []
+    if bold:
+        codes.append("1")
+    if dim:
+        codes.append("2")
+    if italic:
+        codes.append("3")
+    if underline:
+        codes.append("4")
+    if blink:
+        codes.append("5")
+    if reverse:
+        codes.append("7")
+    if conceal:
+        codes.append("8")
+    if strike:
+        codes.append("9")
+
+    if not codes:
+        return ""
+
+    return f"\033[{';'.join(codes)}m"
+
+
+@lru_cache(maxsize=2048)
+def get_combined_code(
+    fg: Optional[int] = None,
+    bg: Optional[int] = None,
+    fg_rgb: Optional[Tuple[int, int, int]] = None,
+    bg_rgb: Optional[Tuple[int, int, int]] = None,
+    bold: bool = False,
+    dim: bool = False,
+    italic: bool = False,
+    underline: bool = False,
+    blink: bool = False,
+    reverse: bool = False,
+    strike: bool = False,
+    conceal: bool = False,
+) -> str:
+    """
+    Generate a combined ANSI code for colors and styles.
+
+    This is the main function to use for complete styling.
+    RGB colors take precedence over palette colors.
+
+    Returns:
+        Complete ANSI escape sequence or empty string
+    """
+    codes = []
+
+    # Style attributes first
+    if bold:
+        codes.append("1")
+    if dim:
+        codes.append("2")
+    if italic:
+        codes.append("3")
+    if underline:
+        codes.append("4")
+    if blink:
+        codes.append("5")
+    if reverse:
+        codes.append("7")
+    if conceal:
+        codes.append("8")
+    if strike:
+        codes.append("9")
+
+    # Colors (RGB takes precedence)
+    if fg_rgb is not None:
+        r, g, b = fg_rgb
+        codes.append(f"38;2;{r};{g};{b}")
+    elif fg is not None:
+        codes.append(f"38;5;{fg}")
+
+    if bg_rgb is not None:
+        r, g, b = bg_rgb
+        codes.append(f"48;2;{r};{g};{b}")
+    elif bg is not None:
+        codes.append(f"48;5;{bg}")
+
+    if not codes:
+        return ""
+
+    return f"\033[{';'.join(codes)}m"
+
+
+@lru_cache(maxsize=1)
+def reset_code() -> str:
+    """Get the ANSI reset code."""
+    return "\033[0m"
+
+
+@lru_cache(maxsize=16)
+def get_basic_color_code(color: int, is_bg: bool = False) -> str:
+    """
+    Generate ANSI code for basic 16 colors (0-15).
+
+    Args:
+        color: Color index (0-7 for normal, 8-15 for bright)
+        is_bg: True for background, False for foreground
+
+    Returns:
+        ANSI escape sequence
+    """
+    if 0 <= color <= 7:
+        # Normal colors
+        code = 40 + color if is_bg else 30 + color
+    elif 8 <= color <= 15:
+        # Bright colors
+        code = 100 + (color - 8) if is_bg else 90 + (color - 8)
+    else:
+        return ""
+
+    return f"\033[{code}m"
+
+
+@lru_cache(maxsize=1)
+def get_cursor_code() -> str:
+    """Get ANSI code for cursor display (reverse video)."""
+    return "\033[7m"
+
+
+@lru_cache(maxsize=1)
+def get_clear_line_code() -> str:
+    """Get ANSI code to clear to end of line."""
+    return "\033[K"
+
+
+@lru_cache(maxsize=1)
+def reset_foreground_code() -> str:
+    """Get ANSI code to reset foreground color only."""
+    return "\033[39m"
+
+
+@lru_cache(maxsize=1)
+def reset_background_code() -> str:
+    """Get ANSI code to reset background color only."""
+    return "\033[49m"
+
+
+@lru_cache(maxsize=1)
+def reset_text_attributes() -> str:
+    """Reset text attributes but preserve background color."""
+    return "\033[0;22;23;24;25;27;28;29;39m"

bittty/constants.py

@@ -0,0 +1,152 @@
+"""
+Constants for the terminal parser and emulator.
+
+This module contains constants used in the terminal parsing and emulation logic,
+following standards like VT100, VT220, and xterm.
+"""
+
+# --- Parser States ---
+GROUND = "GROUND"
+ESCAPE = "ESCAPE"
+CSI_ENTRY = "CSI_ENTRY"
+CSI_PARAM = "CSI_PARAM"
+CSI_INTERMEDIATE = "CSI_INTERMEDIATE"
+OSC_STRING = "OSC_STRING"
+OSC_ESC = "OSC_ESC"
+DCS_STRING = "DCS_STRING"
+DCS_ESC = "DCS_ESC"
+CHARSET_G0 = "CHARSET_G0"
+CHARSET_G1 = "CHARSET_G1"
+
+# --- C0 Control Characters ---
+BEL = "\x07"  # Bell
+BS = "\x08"  # Backspace
+HT = "\x09"  # Horizontal Tab
+LF = "\x0a"  # Line Feed
+CR = "\x0d"  # Carriage Return
+ESC = "\x1b"  # Escape
+DEL = "\x7f"  # Delete
+
+# --- Erase Modes (for ED and EL) ---
+ERASE_FROM_CURSOR_TO_END = 0
+ERASE_FROM_START_TO_CURSOR = 1
+ERASE_ALL = 2
+
+# --- Private Modes (DECSET/DECRST) ---
+# Used with CSI ? ... h/l
+DECCKM_CURSOR_KEYS_APPLICATION = 1
+DECAWM_AUTOWRAP = 7
+DECTCEM_SHOW_CURSOR = 25
+ALT_SCREEN_BUFFER_OLDER = 47
+ALT_SCREEN_BUFFER = 1049
+MOUSE_TRACKING_BASIC = 1000
+MOUSE_TRACKING_BUTTON_EVENT = 1002
+MOUSE_TRACKING_ANY_EVENT = 1003
+MOUSE_SGR_MODE = 1006
+MOUSE_EXTENDED_MODE = 1015
+BRACKETED_PASTE = 2004
+
+# --- ANSI Modes (SM/RM) ---
+# Used with CSI ... h/l
+DECKPAM_APPLICATION_KEYPAD = 1
+IRM_INSERT_REPLACE = 4
+
+# --- SGR (Select Graphic Rendition) Parameters ---
+SGR_RESET = 0
+SGR_BOLD = 1
+SGR_DIM = 2
+SGR_ITALIC = 3
+SGR_UNDERLINE = 4
+SGR_BLINK = 5
+SGR_REVERSE = 7
+SGR_CONCEAL = 8
+SGR_STRIKE = 9
+SGR_NOT_BOLD_OR_DOUBLE_UNDERLINE = 21
+SGR_NOT_BOLD_NOR_FAINT = 22
+SGR_NOT_ITALIC = 23
+SGR_NOT_UNDERLINED = 24
+SGR_NOT_BLINKING = 25
+SGR_NOT_REVERSED = 27
+SGR_NOT_CONCEALED = 28
+SGR_NOT_STRIKETHROUGH = 29
+SGR_FG_BLACK = 30
+SGR_FG_RED = 31
+SGR_FG_GREEN = 32
+SGR_FG_YELLOW = 33
+SGR_FG_BLUE = 34
+SGR_FG_MAGENTA = 35
+SGR_FG_CYAN = 36
+SGR_FG_WHITE = 37
+SGR_EXTENDED_COLOR = 38
+SGR_DEFAULT_FG = 39
+SGR_BG_BLACK = 40
+SGR_BG_RED = 41
+SGR_BG_GREEN = 42
+SGR_BG_YELLOW = 43
+SGR_BG_BLUE = 44
+SGR_BG_MAGENTA = 45
+SGR_BG_CYAN = 46
+SGR_BG_WHITE = 47
+SGR_EXTENDED_BG_COLOR = 48
+SGR_DEFAULT_BG = 49
+SGR_BRIGHT_FG_BLACK = 90
+SGR_BRIGHT_FG_RED = 91
+SGR_BRIGHT_FG_GREEN = 92
+SGR_BRIGHT_FG_YELLOW = 93
+SGR_BRIGHT_FG_BLUE = 94
+SGR_BRIGHT_FG_MAGENTA = 95
+SGR_BRIGHT_FG_CYAN = 96
+SGR_BRIGHT_FG_WHITE = 97
+SGR_BRIGHT_BG_BLACK = 100
+SGR_BRIGHT_BG_RED = 101
+SGR_BRIGHT_BG_GREEN = 102
+SGR_BRIGHT_BG_YELLOW = 103
+SGR_BRIGHT_BG_BLUE = 104
+SGR_BRIGHT_BG_MAGENTA = 105
+SGR_BRIGHT_BG_CYAN = 106
+SGR_BRIGHT_BG_WHITE = 107
+
+# --- OSC (Operating System Command) Commands ---
+OSC_SET_TITLE_AND_ICON = 0
+OSC_SET_ICON_TITLE = 1
+OSC_SET_TITLE = 2
+
+# --- Mouse Button Modifiers ---
+MOUSE_MOD_SHIFT = 4
+MOUSE_MOD_META = 8
+MOUSE_MOD_CTRL = 16
+
+# --- Mouse Buttons ---
+MOUSE_BUTTON_LEFT = 0
+MOUSE_BUTTON_MIDDLE = 1
+MOUSE_BUTTON_RIGHT = 2
+MOUSE_BUTTON_WHEEL_UP = 64
+MOUSE_BUTTON_WHEEL_DOWN = 65
+MOUSE_BUTTON_MOVEMENT = 35
+
+# --- Keyboard Modifier Codes (for CSI sequences) ---
+KEY_MOD_NONE = 1
+KEY_MOD_SHIFT = 2
+KEY_MOD_ALT = 3
+KEY_MOD_SHIFT_ALT = 4
+KEY_MOD_CTRL = 5
+KEY_MOD_SHIFT_CTRL = 6
+KEY_MOD_ALT_CTRL = 7
+KEY_MOD_SHIFT_ALT_CTRL = 8
+
+# --- Cursor Key Mappings ---
+CURSOR_KEYS = {"up": "A", "down": "B", "right": "C", "left": "D"}
+
+# --- Navigation Key Mappings ---
+NAV_KEYS = {"home": "H", "end": "F"}
+
+# --- PTY and System Constants ---
+DEFAULT_TERMINAL_WIDTH = 80
+DEFAULT_TERMINAL_HEIGHT = 24
+DEFAULT_PTY_BUFFER_SIZE = 4096
+PTY_POLL_INTERVAL = 0.1
+DEFAULT_EXIT_CODE = 0
+
+# --- Error Numbers ---
+EBADF = 9  # Bad file descriptor
+EINVAL = 22  # Invalid argument