libtodraw 1.0.0__py3-none-any.whl

libtodraw/__init__.py

@@ -0,0 +1,58 @@
+"""libtodraw — Rich on steroids. Full-featured terminal rendering library."""
+
+__version__ = "1.0.0"
+
+from .color import Color
+from .style import Style, StyleType
+from .text import Text
+from .segment import Segment
+from .measure import Measurement
+from .options import ConsoleOptions, JustifyMethod
+from .console import Console
+from .live import Live
+from .status import Status
+from .capture import Capture
+from .syntax import Syntax, SyntaxTheme
+from .markdown_render import Markdown
+from .inspector import inspect as pretty_inspect
+from .traceback_handler import install as install_traceback
+from .highlighter import Highlighter
+from .theme import Theme, DEFAULT_THEME
+from .markup import parse as parse_markup
+from .terminal import get_size, detect_truecolor, detect_unicode
+from .export import export_text, export_html
+
+from .renderables.table import Table, Column
+from .renderables.panel import Panel, Borders
+from .renderables.tree import Tree, TreeNode
+from .renderables.columns import Columns
+from .renderables.layout import Layout
+from .renderables.rule import Rule
+from .renderables.progress import Progress, TaskID, BarColumn, SpinnerColumn, TextColumn, TimeRemainingColumn
+from .renderables.spinner import Spinner
+from .canvas import Canvas, Cell, CanvasRegion
+
+console = Console()
+
+print = console.print
+log = console.log
+input = console.input
+clear = console.clear
+rule = console.rule
+status = console.status
+
+__all__ = [
+    "Console", "ConsoleOptions", "Measurement", "Capture", "Status",
+    "Color", "Style", "Text", "Segment",
+    "Table", "Column", "Panel", "Borders",
+    "Tree", "TreeNode", "Columns", "Layout", "Rule",
+    "Progress", "TaskID", "BarColumn", "SpinnerColumn", "TextColumn", "TimeRemainingColumn",
+    "Spinner", "Live",
+    "Canvas", "Cell", "CanvasRegion",
+    "Markdown", "Syntax", "SyntaxTheme",
+    "Theme", "DEFAULT_THEME", "Highlighter",
+    "parse_markup", "get_size", "detect_truecolor", "detect_unicode",
+    "export_text", "export_html",
+    "pretty_inspect", "install_traceback",
+    "console", "print", "log", "input", "clear", "rule", "status",
+]

libtodraw/canvas.py

@@ -0,0 +1,530 @@
+"""Canvas — pixel-level control over every character in the terminal."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from typing import Optional, Tuple, List
+
+from .style import Style
+from .color import Color
+
+
+def _visible_len(s: str) -> int:
+    return len(re.sub(r'\033\[[0-9;]*m', '', s))
+
+
+class Cell:
+    """A single terminal cell with full style control."""
+
+    __slots__ = ("char", "style", "z_index")
+
+    def __init__(self, char: str = " ", style: Optional[Style] = None, z_index: int = 0):
+        self.char = char
+        self.style = style
+        self.z_index = z_index
+
+    def __repr__(self):
+        return f"Cell({self.char!r}, {self.style!r})"
+
+
+class Canvas:
+    """Full character-level terminal buffer. Control every cell."""
+
+    def __init__(self, width: int = 80, height: int = 24):
+        self.width = width
+        self.height = height
+        self._cells: List[List[Cell]] = [
+            [Cell() for _ in range(width)] for _ in range(height)
+        ]
+
+    def _in_bounds(self, x: int, y: int) -> bool:
+        return 0 <= x < self.width and 0 <= y < self.height
+
+    # ── Pixel-level control ──
+
+    def set(self, x: int, y: int, char: str, style: Optional[Style] = None) -> Canvas:
+        """Set a single cell. Returns self for chaining."""
+        if self._in_bounds(x, y):
+            self._cells[y][x].char = char
+            self._cells[y][x].style = style
+        return self
+
+    def get(self, x: int, y: int) -> Cell:
+        """Get a single cell."""
+        if self._in_bounds(x, y):
+            return self._cells[y][x]
+        return Cell()
+
+    def set_style(self, x: int, y: int, style: Style) -> Canvas:
+        """Set style on a cell without changing its character."""
+        if self._in_bounds(x, y):
+            self._cells[y][x].style = style
+        return self
+
+    def set_char(self, x: int, y: int, char: str) -> Canvas:
+        """Set a character without changing its style."""
+        if self._in_bounds(x, y):
+            self._cells[y][x].char = char
+        return self
+
+    def clear_cell(self, x: int, y: int) -> Canvas:
+        """Reset a cell to blank with no style."""
+        if self._in_bounds(x, y):
+            self._cells[y][x] = Cell()
+        return self
+
+    # ── Bulk operations ──
+
+    def fill(self, x: int, y: int, w: int, h: int, char: str = " ",
+             style: Optional[Style] = None) -> Canvas:
+        """Fill a rectangular region."""
+        for dy in range(h):
+            for dx in range(w):
+                self.set(x + dx, y + dy, char, style)
+        return self
+
+    def clear(self, x: int = 0, y: int = 0, w: Optional[int] = None,
+              h: Optional[int] = None) -> Canvas:
+        """Clear a region (or entire canvas if no args)."""
+        w = w or self.width
+        h = h or self.height
+        for dy in range(h):
+            for dx in range(w):
+                if self._in_bounds(x + dx, y + dy):
+                    self._cells[y + dy][x + dx] = Cell()
+        return self
+
+    def clear_all(self) -> Canvas:
+        """Clear entire canvas."""
+        return self.clear(0, 0, self.width, self.height)
+
+    # ── Drawing primitives ──
+
+    def draw_rect(self, x: int, y: int, w: int, h: int,
+                  border: Optional[Style] = None, fill: Optional[Style] = None,
+                  chars: Optional[dict] = None) -> Canvas:
+        """Draw a rectangle with optional border and fill.
+
+        chars: override border characters.
+            keys: tl, tr, bl, br, hor, ver, fill
+        """
+        c = chars or {}
+        tl = c.get("tl", "┌")
+        tr = c.get("tr", "┐")
+        bl = c.get("bl", "└")
+        br = c.get("br", "┘")
+        hor = c.get("hor", "─")
+        ver = c.get("ver", "│")
+        fill_ch = c.get("fill", " ")
+
+        # Corners
+        self.set(x, y, tl, border)
+        self.set(x + w - 1, y, tr, border)
+        self.set(x, y + h - 1, bl, border)
+        self.set(x + w - 1, y + h - 1, br, border)
+
+        # Horizontal edges
+        for i in range(1, w - 1):
+            self.set(x + i, y, hor, border)
+            self.set(x + i, y + h - 1, hor, border)
+
+        # Vertical edges
+        for i in range(1, h - 1):
+            self.set(x, y + i, ver, border)
+            self.set(x + w - 1, y + i, ver, border)
+
+        # Fill interior
+        if fill:
+            for dy in range(1, h - 1):
+                for dx in range(1, w - 1):
+                    self.set(x + dx, y + dy, fill_ch, fill)
+
+        return self
+
+    def draw_hline(self, x: int, y: int, length: int, char: str = "─",
+                   style: Optional[Style] = None) -> Canvas:
+        """Draw a horizontal line."""
+        for i in range(length):
+            self.set(x + i, y, char, style)
+        return self
+
+    def draw_vline(self, x: int, y: int, length: int, char: str = "│",
+                   style: Optional[Style] = None) -> Canvas:
+        """Draw a vertical line."""
+        for i in range(length):
+            self.set(x, y + i, char, style)
+        return self
+
+    def draw_box(self, x: int, y: int, w: int, h: int,
+                 style: Optional[Style] = None, box_type: str = "simple") -> Canvas:
+        """Draw a box using predefined box types.
+
+        box_type: simple, rounded, heavy, double, dashed, none
+        """
+        boxes = {
+            "simple":  {"tl": "┌", "tr": "┐", "bl": "└", "br": "┘", "hor": "─", "ver": "│"},
+            "rounded": {"tl": "╭", "tr": "╮", "bl": "╰", "br": "╯", "hor": "─", "ver": "│"},
+            "heavy":   {"tl": "┏", "tr": "┓", "bl": "┗", "br": "┛", "hor": "━", "ver": "┃"},
+            "double":  {"tl": "╔", "tr": "╗", "bl": "╚", "br": "╝", "hor": "═", "ver": "║"},
+            "dashed":  {"tl": "┌", "tr": "┐", "bl": "└", "br": "┘", "hor": "╌", "ver": "╎"},
+            "dotted":  {"tl": "•", "tr": "•", "bl": "•", "br": "•", "hor": "·", "ver": "⋮"},
+        }
+        chars = boxes.get(box_type, boxes["simple"])
+        return self.draw_rect(x, y, w, h, border=style, chars=chars)
+
+    # ── Text placement ──
+
+    def put(self, x: int, y: int, text: str, style: Optional[Style] = None) -> Canvas:
+        """Place text at position, character by character. Handles newlines."""
+        cx, cy = x, y
+        for ch in text:
+            if ch == "\n":
+                cx = x
+                cy += 1
+                continue
+            self.set(cx, cy, ch, style)
+            cx += 1
+        return self
+
+    def put_centered(self, y: int, text: str, style: Optional[Style] = None) -> Canvas:
+        """Place text centered horizontally on row y."""
+        tw = _visible_len(text)
+        x = max(0, (self.width - tw) // 2)
+        return self.put(x, y, text, style)
+
+    def put_right(self, y: int, text: str, style: Optional[Style] = None) -> Canvas:
+        """Place text right-aligned on row y."""
+        tw = _visible_len(text)
+        x = max(0, self.width - tw)
+        return self.put(x, y, text, style)
+
+    def put_at(self, x: int, y: int, text: str, style: Optional[Style] = None,
+               align: str = "left", max_width: Optional[int] = None) -> Canvas:
+        """Place text with alignment control.
+
+        align: left, center, right
+        max_width: if set, pad/truncate to this width
+        """
+        tw = _visible_len(text)
+        if max_width and tw > max_width:
+            text = text[:max_width]
+            tw = max_width
+
+        if align == "center":
+            pad = (max_width or self.width) // 2 - tw // 2
+            x = x + pad
+        elif align == "right":
+            pad = (max_width or self.width) - tw
+            x = x + max(0, pad)
+
+        return self.put(x, y, text, style)
+
+    def write_line(self, y: int, x: int, text: str, style: Optional[Style] = None,
+                   justify: str = "left", width: Optional[int] = None) -> Canvas:
+        """Write a full line with justification and padding.
+
+        justify: left, center, right, full
+        width: line width for justification
+        """
+        w = width or self.width
+        tw = _visible_len(text)
+
+        if justify == "center":
+            pad = (w - tw) // 2
+            full = " " * pad + text + " " * (w - tw - pad)
+        elif justify == "right":
+            full = " " * (w - tw) + text
+        elif justify == "full":
+            words = text.split()
+            if len(words) <= 1:
+                full = text.ljust(w)
+            else:
+                total_chars = sum(len(w) for w in words)
+                total_spaces = w - total_chars
+                space_each = total_spaces // (len(words) - 1) if len(words) > 1 else 0
+                extra = total_spaces % (len(words) - 1) if len(words) > 1 else 0
+                parts = []
+                for i, word in enumerate(words):
+                    parts.append(word)
+                    if i < len(words) - 1:
+                        spaces = space_each + (1 if i < extra else 0)
+                        parts.append(" " * spaces)
+                full = "".join(parts)
+        else:
+            full = text.ljust(w)
+
+        return self.put(x, y, full, style)
+
+    # ── Gradient fill ──
+
+    def gradient_fill(self, x: int, y: int, w: int, h: int,
+                      color_start: Color, color_end: Color,
+                      char: str = "█", horizontal: bool = True) -> Canvas:
+        """Fill a region with a color gradient."""
+        length = w if horizontal else h
+        for i in range(length):
+            t = i / max(length - 1, 1)
+            color = color_start.lerp(color_end, t)
+            style = Style(color=color)
+            if horizontal:
+                for dy in range(h):
+                    self.set(x + i, y + dy, char, style)
+            else:
+                for dx in range(w):
+                    self.set(x + dx, y + i, char, style)
+        return self
+
+    def gradient_border(self, x: int, y: int, w: int, h: int,
+                        color_start: Color, color_end: Color,
+                        box_type: str = "simple") -> Canvas:
+        """Draw a box border with gradient colors along the perimeter."""
+        boxes = {
+            "simple":  {"tl": "┌", "tr": "┐", "bl": "└", "br": "┘", "hor": "─", "ver": "│"},
+            "rounded": {"tl": "╭", "tr": "╮", "bl": "╰", "br": "╯", "hor": "─", "ver": "│"},
+            "heavy":   {"tl": "┏", "tr": "┓", "bl": "┗", "br": "┛", "hor": "━", "ver": "┃"},
+            "double":  {"tl": "╔", "tr": "╗", "bl": "╚", "br": "╝", "hor": "═", "ver": "║"},
+        }
+        c = boxes.get(box_type, boxes["simple"])
+
+        # Horizontal gradient for top/bottom
+        for i in range(w):
+            t = i / max(w - 1, 1)
+            color = color_start.lerp(color_end, t)
+            style = Style(color=color)
+            ch = c["hor"] if 0 < i < w - 1 else (c["tl"] if i == 0 else c["tr"])
+            self.set(x + i, y, ch, style)
+            ch = c["hor"] if 0 < i < w - 1 else (c["bl"] if i == 0 else c["br"])
+            self.set(x + i, y + h - 1, ch, style)
+
+        # Vertical gradient for sides
+        for i in range(1, h - 1):
+            t = i / max(h - 1, 1)
+            color = color_start.lerp(color_end, t)
+            style = Style(color=color)
+            self.set(x, y + i, c["ver"], style)
+            self.set(x + w - 1, y + i, c["ver"], style)
+
+        return self
+
+    # ── Circle / ellipse ──
+
+    def draw_circle(self, cx: int, cy: int, radius: int,
+                    char: str = "●", style: Optional[Style] = None,
+                    filled: bool = False) -> Canvas:
+        """Draw a circle (or filled circle)."""
+        if filled:
+            for y in range(-radius, radius + 1):
+                for x in range(-radius, radius + 1):
+                    if x * x + y * y <= radius * radius:
+                        self.set(cx + x, cy + y, char, style)
+        else:
+            x, y = radius, 0
+            err = 1 - radius
+            while x >= y:
+                for dx, dy in [(x, y), (y, x), (-y, x), (-x, y),
+                               (-x, -y), (-y, -x), (y, -x), (x, -y)]:
+                    self.set(cx + dx, cy + dy, char, style)
+                y += 1
+                if err < 0:
+                    err += 2 * y + 1
+                else:
+                    x -= 1
+                    err += 2 * (y - x) + 1
+        return self
+
+    def draw_line(self, x0: int, y0: int, x1: int, y1: int,
+                  char: str = "·", style: Optional[Style] = None) -> Canvas:
+        """Draw a line between two points using Bresenham's algorithm."""
+        dx = abs(x1 - x0)
+        dy = abs(y1 - y0)
+        sx = 1 if x0 < x1 else -1
+        sy = 1 if y0 < y1 else -1
+        err = dx - dy
+
+        while True:
+            self.set(x0, y0, char, style)
+            if x0 == x1 and y0 == y1:
+                break
+            e2 = 2 * err
+            if e2 > -dy:
+                err -= dy
+                x0 += sx
+            if e2 < dx:
+                err += dx
+                y0 += sy
+        return self
+
+    # ── Resize ──
+
+    def resize(self, width: int, height: int) -> Canvas:
+        """Resize the canvas, preserving existing content where possible."""
+        new_cells = [
+            [Cell() for _ in range(width)] for _ in range(height)
+        ]
+        for y in range(min(self.height, height)):
+            for x in range(min(self.width, width)):
+                new_cells[y][x] = self._cells[y][x]
+        self.width = width
+        self.height = height
+        self._cells = new_cells
+        return self
+
+    # ── Overlay / compositing ──
+
+    def overlay(self, other: Canvas, x: int = 0, y: int = 0,
+                overwrite: bool = True) -> Canvas:
+        """Overlay another canvas onto this one.
+
+        overwrite: if False, only paint non-blank cells.
+        """
+        for oy in range(other.height):
+            for ox in range(other.width):
+                tx, ty = x + ox, y + oy
+                if self._in_bounds(tx, ty):
+                    src = other._cells[oy][ox]
+                    if overwrite or src.char != " ":
+                        self._cells[ty][tx] = Cell(src.char, src.style)
+        return self
+
+    def copy(self) -> Canvas:
+        """Create a deep copy of this canvas."""
+        c = Canvas(self.width, self.height)
+        for y in range(self.height):
+            for x in range(self.width):
+                src = self._cells[y][x]
+                c._cells[y][x] = Cell(src.char, src.style, src.z_index)
+        return c
+
+    # ── Inspection ──
+
+    def get_row(self, y: int) -> List[Cell]:
+        """Get all cells in a row."""
+        if 0 <= y < self.height:
+            return list(self._cells[y])
+        return []
+
+    def get_col(self, x: int) -> List[Cell]:
+        """Get all cells in a column."""
+        if 0 <= x < self.width:
+            return [self._cells[y][x] for y in range(self.height)]
+        return []
+
+    def get_region(self, x: int, y: int, w: int, h: int) -> List[List[Cell]]:
+        """Get a rectangular region of cells."""
+        result = []
+        for dy in range(h):
+            row = []
+            for dx in range(w):
+                if self._in_bounds(x + dx, y + dy):
+                    row.append(self._cells[y + dy][x + dx])
+                else:
+                    row.append(Cell())
+            result.append(row)
+        return result
+
+    def find(self, char: str) -> List[Tuple[int, int]]:
+        """Find all positions of a character."""
+        positions = []
+        for y in range(self.height):
+            for x in range(self.width):
+                if self._cells[y][x].char == char:
+                    positions.append((x, y))
+        return positions
+
+    def to_text(self) -> str:
+        """Convert canvas to plain text (no ANSI)."""
+        lines = []
+        for y in range(self.height):
+            line = "".join(self._cells[y][x].char for x in range(self.width))
+            lines.append(line.rstrip())
+        return "\n".join(lines)
+
+    # ── Render ──
+
+    def render(self) -> str:
+        """Render canvas to ANSI string for terminal output."""
+        lines = []
+        for y in range(self.height):
+            parts = []
+            last_style = None
+            for x in range(self.width):
+                cell = self._cells[y][x]
+                if cell.style != last_style:
+                    if last_style is not None:
+                        parts.append(Style.RESET)
+                    if cell.style is not None:
+                        parts.append(cell.style.to_ansi())
+                    last_style = cell.style
+                parts.append(cell.char)
+            if last_style is not None:
+                parts.append(Style.RESET)
+            lines.append("".join(parts))
+        return "\n".join(lines)
+
+    def print(self, file=None) -> None:
+        """Print canvas to file (or stdout)."""
+        import sys
+        f = file or sys.stdout
+        f.write("\033[H")
+        f.write(self.render())
+        f.write("\n")
+        f.flush()
+
+    # ── Context ──
+
+    def region(self, x: int, y: int, w: int, h: int) -> "CanvasRegion":
+        """Get a sub-region for scoped drawing."""
+        return CanvasRegion(self, x, y, w, h)
+
+    def __getitem__(self, pos: Tuple[int, int]) -> Cell:
+        x, y = pos
+        return self.get(x, y)
+
+    def __setitem__(self, pos: Tuple[int, int], value):
+        x, y = pos
+        if isinstance(value, tuple):
+            char, style = value
+            self.set(x, y, char, style)
+        else:
+            self.set_char(x, y, str(value))
+
+    def __repr__(self):
+        return f"Canvas({self.width}x{self.height})"
+
+
+class CanvasRegion:
+    """A sub-region of a canvas for scoped drawing."""
+
+    def __init__(self, canvas: Canvas, x: int, y: int, width: int, height: int):
+        self._canvas = canvas
+        self._ox = x
+        self._oy = y
+        self.width = width
+        self.height = height
+
+    def set(self, x: int, y: int, char: str, style: Optional[Style] = None) -> CanvasRegion:
+        self._canvas.set(self._ox + x, self._oy + y, char, style)
+        return self
+
+    def put(self, x: int, y: int, text: str, style: Optional[Style] = None) -> CanvasRegion:
+        self._canvas.put(self._ox + x, self._oy + y, text, style)
+        return self
+
+    def fill(self, char: str = " ", style: Optional[Style] = None) -> CanvasRegion:
+        for y in range(self.height):
+            for x in range(self.width):
+                self._canvas.set(self._ox + x, self._oy + y, char, style)
+        return self
+
+    def clear(self) -> CanvasRegion:
+        return self.fill()
+
+    def draw_box(self, style: Optional[Style] = None,
+                 box_type: str = "simple") -> CanvasRegion:
+        self._canvas.draw_box(self._ox, self._oy, self.width, self.height,
+                              style=style, box_type=box_type)
+        return self
+
+    def __repr__(self):
+        return f"CanvasRegion({self._ox},{self._oy} {self.width}x{self.height})"

libtodraw/capture.py

@@ -0,0 +1,37 @@
+"""Output capture context manager."""
+
+import sys
+from io import StringIO
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .console import Console
+
+
+class Capture:
+    """Context manager for capturing console output."""
+
+    def __init__(self, console: "Console"):
+        self._console = console
+        self._buffer: Optional[StringIO] = None
+        self._original_capture: Optional[StringIO] = None
+
+    def __enter__(self) -> "Capture":
+        self._buffer = StringIO()
+        self._original_capture = self._console._capture_buffer
+        self._console._capture_buffer = self._buffer
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        self._console._capture_buffer = self._original_capture
+
+    def get(self) -> str:
+        """Get captured output."""
+        if self._buffer is not None:
+            return self._buffer.getvalue()
+        return ""
+
+    @property
+    def text(self) -> str:
+        """Get captured text."""
+        return self.get()