bittty 0.0.1__tar.gz

bittty-0.0.1/LICENSE.md

@@ -0,0 +1,7 @@
+# WTFPL + Warranty
+
+Licensed under the WTFPL with one additional clause:
+
+1. Don't blame me.
+
+Do whatever the fuck you want, just don't blame me.

bittty-0.0.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: bittty
+Version: 0.0.1
+Summary: a pure python tty
+Author-email: Gareth Davidson <gaz@bitplane.net>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pre-commit ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: coverage ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: pytest-asyncio ; extra == "dev"
+Requires-Dist: build ; extra == "dev"
+Requires-Dist: twine ; extra == "dev"
+Requires-Dist: ruff ; extra == "dev"
+Provides-Extra: dev
+
+# bittty
+
+A pure Python terminal emulator.
+
+Currently buggy and a bit slow, but it's still somewhat usable.
+
+## Demo
+
+Run the standalone demo:
+
+```bash
+python ./demo/terminal.py
+```
+
+Or use the textual demo to see it in a TUI:
+
+```bash
+uvx textual-tty
+```
+
+## Usage
+
+There's 3 main classes:
+
+1. `Terminal`, a standalone terminal that doesn't need Textual.
+2. `TextualTerminal`, a tty widget subclass.
+3. `TerminalApp`, a terminal emulator in a window.
+
+Read the demo code for more info.
+
+## Links
+
+* [🏠 home](https://bitplane.net/dev/python/bittty)
+* [🐍 pypi](https://pypi.org/project/bittty)
+* [🐱 github](https://github.com/bitplane/bittty)
+
+## License
+
+WTFPL with one additional clause
+
+1. Don't blame me
+
+Do wtf you want, but don't blame me when it rips a hole in your trousers.
+
+## todo / ideas
+
+- [ ] split pty out into a cross platform package
+- [x] break terminal project out from Textual deps
+  - [x] write a minimal demo that doesn't need textual
+  - [ ] gui
+    - [ ] make `framebuffer.py`
+    - [ ] choose a backend
+- [ ] performance improvements
+  - [ ] parse with regex over large buffer sizes
+- [ ] scrollback buffer
+  - [ ] implement `logloglog` for scrollback with wrapping
+- [ ] bugs
+  - [ ] blank background to end of line
+  - [ ] corruption in stream - debug it
+  - [ ] scroll region: scroll up in `vim` corrupts outside scroll region
+- [ ] reduce redundancy redundancy of repeated repeated code code
+  - [ ] code code of of redundancy redundancy
+- [ ] add terminal visuals
+  - [ ] bell flash effect
+- [ ] Support themes
+

bittty-0.0.1/README.md

@@ -0,0 +1,65 @@
+# bittty
+
+A pure Python terminal emulator.
+
+Currently buggy and a bit slow, but it's still somewhat usable.
+
+## Demo
+
+Run the standalone demo:
+
+```bash
+python ./demo/terminal.py
+```
+
+Or use the textual demo to see it in a TUI:
+
+```bash
+uvx textual-tty
+```
+
+## Usage
+
+There's 3 main classes:
+
+1. `Terminal`, a standalone terminal that doesn't need Textual.
+2. `TextualTerminal`, a tty widget subclass.
+3. `TerminalApp`, a terminal emulator in a window.
+
+Read the demo code for more info.
+
+## Links
+
+* [🏠 home](https://bitplane.net/dev/python/bittty)
+* [🐍 pypi](https://pypi.org/project/bittty)
+* [🐱 github](https://github.com/bitplane/bittty)
+
+## License
+
+WTFPL with one additional clause
+
+1. Don't blame me
+
+Do wtf you want, but don't blame me when it rips a hole in your trousers.
+
+## todo / ideas
+
+- [ ] split pty out into a cross platform package
+- [x] break terminal project out from Textual deps
+  - [x] write a minimal demo that doesn't need textual
+  - [ ] gui
+    - [ ] make `framebuffer.py`
+    - [ ] choose a backend
+- [ ] performance improvements
+  - [ ] parse with regex over large buffer sizes
+- [ ] scrollback buffer
+  - [ ] implement `logloglog` for scrollback with wrapping
+- [ ] bugs
+  - [ ] blank background to end of line
+  - [ ] corruption in stream - debug it
+  - [ ] scroll region: scroll up in `vim` corrupts outside scroll region
+- [ ] reduce redundancy redundancy of repeated repeated code code
+  - [ ] code code of of redundancy redundancy
+- [ ] add terminal visuals
+  - [ ] bell flash effect
+- [ ] Support themes

bittty-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "bittty"
+description = "a pure python tty"
+version = "0.0.1"
+authors = [
+    { name = "Gareth Davidson", email = "gaz@bitplane.net" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+
+dependencies = [
+
+]
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit",
+    "pytest",
+    "coverage",
+    "pytest-cov",
+    "pytest-asyncio",
+    "build",
+    "twine",
+    "ruff"
+]
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = ["flit_core >=3.2,<4"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.format]
+docstring-code-format = true

bittty-0.0.1/src/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-0.0.1/src/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)