py-sparcli 0.3.0__py3-none-any.whl

sparcli/core/border.py

@@ -0,0 +1,160 @@
+"""
+sparcli.core.border
+===================
+
+Defines border styles and their glyph sets.
+
+:class:`BorderType` selects a look (rounded, single, double, thick, ASCII or
+none); :meth:`BorderType.chars` returns the concrete :class:`BorderChars` glyph
+set used to draw boxes, tables and rules. The ASCII set is the fallback for
+terminals without Unicode line-drawing support.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class BorderChars:
+    """
+    The glyphs used to draw a border.
+
+    Attributes
+    ----------
+    top_left, top_right, bottom_left, bottom_right : str
+        Corner glyphs.
+    horizontal, vertical : str
+        Edge glyphs.
+    cross : str
+        The four-way junction glyph.
+    tee_down, tee_up, tee_right, tee_left : str
+        T-junction glyphs used by tables.
+    """
+
+    top_left: str
+    top_right: str
+    bottom_left: str
+    bottom_right: str
+    horizontal: str
+    vertical: str
+    cross: str
+    tee_down: str
+    tee_up: str
+    tee_right: str
+    tee_left: str
+
+
+_SPACE = BorderChars(
+    top_left=" ",
+    top_right=" ",
+    bottom_left=" ",
+    bottom_right=" ",
+    horizontal=" ",
+    vertical=" ",
+    cross=" ",
+    tee_down=" ",
+    tee_up=" ",
+    tee_right=" ",
+    tee_left=" ",
+)
+
+_ASCII = BorderChars(
+    top_left="+",
+    top_right="+",
+    bottom_left="+",
+    bottom_right="+",
+    horizontal="-",
+    vertical="|",
+    cross="+",
+    tee_down="+",
+    tee_up="+",
+    tee_right="+",
+    tee_left="+",
+)
+
+_SINGLE = BorderChars(
+    top_left="┌",
+    top_right="┐",
+    bottom_left="└",
+    bottom_right="┘",
+    horizontal="─",
+    vertical="│",
+    cross="┼",
+    tee_down="┬",
+    tee_up="┴",
+    tee_right="├",
+    tee_left="┤",
+)
+
+_DOUBLE = BorderChars(
+    top_left="╔",
+    top_right="╗",
+    bottom_left="╚",
+    bottom_right="╝",
+    horizontal="═",
+    vertical="║",
+    cross="╬",
+    tee_down="╦",
+    tee_up="╩",
+    tee_right="╠",
+    tee_left="╣",
+)
+
+_ROUNDED = BorderChars(
+    top_left="╭",
+    top_right="╮",
+    bottom_left="╰",
+    bottom_right="╯",
+    horizontal="─",
+    vertical="│",
+    cross="┼",
+    tee_down="┬",
+    tee_up="┴",
+    tee_right="├",
+    tee_left="┤",
+)
+
+_THICK = BorderChars(
+    top_left="┏",
+    top_right="┓",
+    bottom_left="┗",
+    bottom_right="┛",
+    horizontal="━",
+    vertical="┃",
+    cross="╋",
+    tee_down="┳",
+    tee_up="┻",
+    tee_right="┣",
+    tee_left="┫",
+)
+
+
+class BorderType(enum.Enum):
+    """A border look; :meth:`chars` returns its glyph set."""
+
+    NONE = enum.auto()
+    ASCII = enum.auto()
+    SINGLE = enum.auto()
+    DOUBLE = enum.auto()
+    ROUNDED = enum.auto()
+    THICK = enum.auto()
+
+    def chars(self) -> BorderChars:
+        """Returns the concrete glyph set for this border type."""
+        return _BORDER_CHARS[self]
+
+    def is_none(self) -> bool:
+        """Returns whether this border type draws nothing."""
+        return self is BorderType.NONE
+
+
+_BORDER_CHARS: dict[BorderType, BorderChars] = {
+    BorderType.NONE: _SPACE,
+    BorderType.ASCII: _ASCII,
+    BorderType.SINGLE: _SINGLE,
+    BorderType.DOUBLE: _DOUBLE,
+    BorderType.ROUNDED: _ROUNDED,
+    BorderType.THICK: _THICK,
+}

sparcli/core/color.py

@@ -0,0 +1,306 @@
+"""
+sparcli.core.color
+==================
+
+Defines the :class:`Color` type and its downgrade to lower color depths.
+
+Colors are authored abstractly (named ANSI colors, 24-bit RGB or 256-color
+indices) and only turned into concrete escape codes at render time via
+:meth:`Color.resolve`, which downgrades to the available
+:class:`~sparcli.core.terminal.ColorSupport`. The named-color set mirrors the
+Rust original, including the quirk that ``GRAY`` is standard ANSI 7 and
+``WHITE`` is bright ANSI 15.
+"""
+
+from __future__ import annotations
+
+import enum
+from typing import ClassVar, Literal
+
+from sparcli.core.terminal import ColorSupport
+
+# Downgrade thresholds for mapping an RGB channel onto the 16-color palette.
+_CHANNEL_ON = 0x60
+_CHANNEL_BRIGHT = 0xC0
+
+# 256-color index boundaries used when collapsing to the 16-color palette.
+_GRAYSCALE_LIGHT = 244
+_GRAYSCALE_DARK = 232
+
+# Resolved-color shapes handed to the renderer, tagged by their first element.
+ResetColor = tuple[Literal["reset"]]
+Ansi16Color = tuple[Literal["ansi16"], int]
+RgbColor = tuple[Literal["rgb"], int, int, int]
+IndexedColor = tuple[Literal["indexed"], int]
+ResolvedColor = ResetColor | Ansi16Color | RgbColor | IndexedColor
+
+
+class ColorName(enum.Enum):
+    """The named ANSI colors, including reset and the eight bright variants."""
+
+    RESET = enum.auto()
+    BLACK = enum.auto()
+    RED = enum.auto()
+    GREEN = enum.auto()
+    YELLOW = enum.auto()
+    BLUE = enum.auto()
+    MAGENTA = enum.auto()
+    CYAN = enum.auto()
+    GRAY = enum.auto()
+    DARK_GRAY = enum.auto()
+    LIGHT_RED = enum.auto()
+    LIGHT_GREEN = enum.auto()
+    LIGHT_YELLOW = enum.auto()
+    LIGHT_BLUE = enum.auto()
+    LIGHT_MAGENTA = enum.auto()
+    LIGHT_CYAN = enum.auto()
+    WHITE = enum.auto()
+
+
+# Each named color's index in the standard 16-color palette (0..15).
+_ANSI16_INDEX: dict[ColorName, int] = {
+    ColorName.BLACK: 0,
+    ColorName.RED: 1,
+    ColorName.GREEN: 2,
+    ColorName.YELLOW: 3,
+    ColorName.BLUE: 4,
+    ColorName.MAGENTA: 5,
+    ColorName.CYAN: 6,
+    ColorName.GRAY: 7,
+    ColorName.DARK_GRAY: 8,
+    ColorName.LIGHT_RED: 9,
+    ColorName.LIGHT_GREEN: 10,
+    ColorName.LIGHT_YELLOW: 11,
+    ColorName.LIGHT_BLUE: 12,
+    ColorName.LIGHT_MAGENTA: 13,
+    ColorName.LIGHT_CYAN: 14,
+    ColorName.WHITE: 15,
+}
+
+# Accepted spellings for :meth:`Color.from_name`, including common aliases.
+_NAME_ALIASES: dict[str, ColorName] = {
+    "reset": ColorName.RESET,
+    "default": ColorName.RESET,
+    "black": ColorName.BLACK,
+    "red": ColorName.RED,
+    "green": ColorName.GREEN,
+    "yellow": ColorName.YELLOW,
+    "blue": ColorName.BLUE,
+    "magenta": ColorName.MAGENTA,
+    "purple": ColorName.MAGENTA,
+    "cyan": ColorName.CYAN,
+    "gray": ColorName.GRAY,
+    "grey": ColorName.GRAY,
+    "white": ColorName.GRAY,
+    "darkgray": ColorName.DARK_GRAY,
+    "darkgrey": ColorName.DARK_GRAY,
+    "lightred": ColorName.LIGHT_RED,
+    "lightgreen": ColorName.LIGHT_GREEN,
+    "lightyellow": ColorName.LIGHT_YELLOW,
+    "lightblue": ColorName.LIGHT_BLUE,
+    "lightmagenta": ColorName.LIGHT_MAGENTA,
+    "lightcyan": ColorName.LIGHT_CYAN,
+    "brightwhite": ColorName.WHITE,
+}
+
+_HEX_DIGITS = 6
+
+
+class Color:
+    """
+    A terminal color: a named ANSI color, an RGB triple or a 256-color index.
+
+    Construct named colors via the class constants (``Color.RED``), true color
+    via :meth:`rgb`, and palette colors via :meth:`indexed`. Instances are
+    immutable and compare by value.
+    """
+
+    RESET: ClassVar[Color]
+    BLACK: ClassVar[Color]
+    RED: ClassVar[Color]
+    GREEN: ClassVar[Color]
+    YELLOW: ClassVar[Color]
+    BLUE: ClassVar[Color]
+    MAGENTA: ClassVar[Color]
+    CYAN: ClassVar[Color]
+    GRAY: ClassVar[Color]
+    DARK_GRAY: ClassVar[Color]
+    LIGHT_RED: ClassVar[Color]
+    LIGHT_GREEN: ClassVar[Color]
+    LIGHT_YELLOW: ClassVar[Color]
+    LIGHT_BLUE: ClassVar[Color]
+    LIGHT_MAGENTA: ClassVar[Color]
+    LIGHT_CYAN: ClassVar[Color]
+    WHITE: ClassVar[Color]
+
+    __slots__ = ("_name", "_rgb", "_index")
+
+    def __init__(
+        self,
+        *,
+        name: ColorName | None = None,
+        rgb: tuple[int, int, int] | None = None,
+        index: int | None = None,
+    ) -> None:
+        self._name = name
+        self._rgb = rgb
+        self._index = index
+
+    @classmethod
+    def named(cls, name: ColorName) -> Color:
+        """Returns the color for a :class:`ColorName` member."""
+        return cls(name=name)
+
+    @classmethod
+    def rgb(cls, red: int, green: int, blue: int) -> Color:
+        """
+        Returns a 24-bit true color.
+
+        Parameters
+        ----------
+        red, green, blue : int
+            Channel values, each clamped to the ``0..255`` range.
+
+        Returns
+        -------
+        Color
+            The RGB color.
+        """
+        return cls(
+            rgb=(_clamp_byte(red), _clamp_byte(green), _clamp_byte(blue))
+        )
+
+    @classmethod
+    def indexed(cls, index: int) -> Color:
+        """Returns a 256-color palette color for ``index`` (clamped 0..255)."""
+        return cls(index=_clamp_byte(index))
+
+    @classmethod
+    def from_name(cls, text: str) -> Color | None:
+        """
+        Parses a color name (case-insensitive), returning ``None`` if unknown.
+
+        Parameters
+        ----------
+        text : str
+            A color name such as ``"red"`` or an alias such as ``"purple"``.
+
+        Returns
+        -------
+        Color | None
+            The matching color, or ``None`` when the name is not recognized.
+        """
+        name = _NAME_ALIASES.get(text.strip().lower())
+        return cls(name=name) if name is not None else None
+
+    @classmethod
+    def from_hex(cls, text: str) -> Color | None:
+        """
+        Parses ``#rrggbb`` or ``rrggbb`` into an RGB color.
+
+        Parameters
+        ----------
+        text : str
+            A six-digit hex color, optionally prefixed with ``#``.
+
+        Returns
+        -------
+        Color | None
+            The RGB color, or ``None`` when the string is malformed.
+        """
+        digits = text.strip().removeprefix("#")
+        if len(digits) != _HEX_DIGITS:
+            return None
+        try:
+            value = int(digits, 16)
+        except ValueError:
+            return None
+        return cls.rgb(value >> 16 & 0xFF, value >> 8 & 0xFF, value & 0xFF)
+
+    def resolve(self, support: ColorSupport) -> ResolvedColor | None:
+        """
+        Resolves the color for a given support level, downgrading if needed.
+
+        Parameters
+        ----------
+        support : ColorSupport
+            The color depth the output stream can display.
+
+        Returns
+        -------
+        ResolvedColor | None
+            A tagged tuple the renderer turns into an escape code, or ``None``
+            when no color should be emitted (``ColorSupport.NONE``).
+        """
+        if support is ColorSupport.NONE:
+            return None
+        if self._name is ColorName.RESET:
+            return ("reset",)
+        if self._name is not None:
+            return ("ansi16", _ANSI16_INDEX[self._name])
+        if self._rgb is not None:
+            if support is ColorSupport.TRUECOLOR:
+                return ("rgb", *self._rgb)
+            return ("ansi16", _nearest_ansi16(*self._rgb))
+        if self._index is not None:
+            if support is ColorSupport.TRUECOLOR:
+                return ("indexed", self._index)
+            return ("ansi16", _indexed_to_ansi16(self._index))
+        return None
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Color):
+            return NotImplemented
+        return (
+            self._name == other._name
+            and self._rgb == other._rgb
+            and self._index == other._index
+        )
+
+    def __hash__(self) -> int:
+        return hash((self._name, self._rgb, self._index))
+
+    def __repr__(self) -> str:
+        if self._name is not None:
+            return f"Color.{self._name.name}"
+        if self._rgb is not None:
+            return f"Color.rgb{self._rgb}"
+        return f"Color.indexed({self._index})"
+
+
+def _clamp_byte(value: int) -> int:
+    """Clamps an integer into the ``0..255`` byte range."""
+    return max(0, min(255, value))
+
+
+def _nearest_ansi16(red: int, green: int, blue: int) -> int:
+    """Maps an RGB triple onto the nearest 16-color palette index."""
+    base = 0
+    if red >= _CHANNEL_ON:
+        base |= 1
+    if green >= _CHANNEL_ON:
+        base |= 2
+    if blue >= _CHANNEL_ON:
+        base |= 4
+    bright = max(red, green, blue) >= _CHANNEL_BRIGHT
+    return base + 8 if bright else base
+
+
+def _indexed_to_ansi16(index: int) -> int:
+    """Collapses a 256-color index onto the 16-color palette."""
+    if index < 16:
+        return index
+    if index >= _GRAYSCALE_LIGHT:
+        return 15
+    if index >= _GRAYSCALE_DARK:
+        return 8
+    return 7
+
+
+def _install_named_colors() -> None:
+    """Attaches a class constant for every named color after class creation."""
+    for name in ColorName:
+        setattr(Color, name.name, Color(name=name))
+
+
+_install_named_colors()

sparcli/core/cursor.py

@@ -0,0 +1,59 @@
+"""
+sparcli.core.cursor
+==================
+
+Hides and restores the terminal hardware cursor around in-place redraws.
+
+During spinner and progress animations, and during interactive prompts, the
+library rewrites frames in place; a blinking hardware cursor at the end of a
+frame is distracting, and prompts draw their own styled cursor anyway. These
+helpers hide the cursor on the first request and restore it on the last, both
+idempotently, and register an :mod:`atexit` handler so the cursor is always
+shown again when the process exits (even after an unhandled exception).
+"""
+
+from __future__ import annotations
+
+import atexit
+import sys
+
+_HIDE = "\x1b[?25l"
+_SHOW = "\x1b[?25h"
+
+_hidden = False
+_atexit_registered = False
+
+
+def hide() -> None:
+    """Hides the terminal cursor once; a no-op if already hidden."""
+    global _hidden, _atexit_registered
+    if _hidden:
+        return
+    _write(_HIDE)
+    _hidden = True
+    if not _atexit_registered:
+        atexit.register(show)
+        _atexit_registered = True
+
+
+def show() -> None:
+    """Restores the terminal cursor if it was hidden; a no-op otherwise."""
+    global _hidden
+    if not _hidden:
+        return
+    _write(_SHOW)
+    _hidden = False
+
+
+def is_hidden() -> bool:
+    """Returns whether the cursor is currently hidden by this module."""
+    return _hidden
+
+
+def _write(escape: str) -> None:
+    """Writes an escape to stdout, ignoring closed-stream errors at shutdown."""
+    try:
+        sys.stdout.write(escape)
+        sys.stdout.flush()
+    except (OSError, ValueError):
+        pass

sparcli/core/geometry.py

@@ -0,0 +1,141 @@
+"""
+sparcli.core.geometry
+=====================
+
+Defines layout primitives: alignment enums, box spacing and titles.
+
+:class:`Align` and :class:`VAlign` control horizontal and vertical placement,
+:class:`Position` selects which edge a title sits on, :class:`Edges` models
+box-model spacing (padding/margins), and :class:`Title` is a positioned,
+aligned label used by panels, rules and tables.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field, replace
+
+from sparcli.core.style import Style
+from sparcli.core.text import IntoText, Line, Span, Text, into_text
+
+
+class Align(enum.Enum):
+    """Horizontal alignment within an available width."""
+
+    LEFT = enum.auto()
+    CENTER = enum.auto()
+    RIGHT = enum.auto()
+
+
+class VAlign(enum.Enum):
+    """Vertical alignment within an available height."""
+
+    TOP = enum.auto()
+    MIDDLE = enum.auto()
+    BOTTOM = enum.auto()
+
+
+class Position(enum.Enum):
+    """Which edge a title is placed on."""
+
+    TOP = enum.auto()
+    BOTTOM = enum.auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Edges:
+    """
+    Box-model spacing for the four edges.
+
+    Attributes
+    ----------
+    top, right, bottom, left : int
+        The spacing on each edge, in cells.
+    """
+
+    top: int = 0
+    right: int = 0
+    bottom: int = 0
+    left: int = 0
+
+    @classmethod
+    def all(cls, value: int) -> Edges:
+        """Returns edges with the same spacing on every side."""
+        return cls(top=value, right=value, bottom=value, left=value)
+
+    @classmethod
+    def symmetric(cls, vertical: int, horizontal: int) -> Edges:
+        """Returns edges with matching vertical and horizontal spacing."""
+        return cls(
+            top=vertical,
+            right=horizontal,
+            bottom=vertical,
+            left=horizontal,
+        )
+
+    def horizontal(self) -> int:
+        """Returns the combined left and right spacing."""
+        return self.left + self.right
+
+    def vertical(self) -> int:
+        """Returns the combined top and bottom spacing."""
+        return self.top + self.bottom
+
+
+@dataclass(slots=True)
+class Title:
+    """
+    A positioned, aligned label rendered inside a border or rule.
+
+    Attributes
+    ----------
+    content : Text
+        The title text.
+    align : Align
+        Horizontal alignment along the edge.
+    position : Position
+        Which edge the title sits on.
+    pad : int
+        Horizontal padding around the title text, in cells.
+    """
+
+    content: Text = field(default_factory=Text)
+    align: Align = Align.LEFT
+    position: Position = Position.TOP
+    pad: int = 1
+
+    @classmethod
+    def new(cls, content: IntoText) -> Title:
+        """Returns a top-left title with default padding."""
+        return cls(content=into_text(content))
+
+    def with_align(self, align: Align) -> Title:
+        """Returns a copy with the alignment set."""
+        return replace(self, align=align)
+
+    def with_position(self, position: Position) -> Title:
+        """Returns a copy with the edge position set."""
+        return replace(self, position=position)
+
+    def with_pad(self, pad: int) -> Title:
+        """Returns a copy with the horizontal padding set."""
+        return replace(self, pad=pad)
+
+    def with_style(self, style: Style) -> Title:
+        """Returns a copy with ``style`` patched onto every span."""
+        styled = Text(
+            [
+                Line(
+                    [
+                        Span(
+                            content=span.content,
+                            style=span.style.patch(style),
+                            link=span.link,
+                        )
+                        for span in line.spans
+                    ]
+                )
+                for line in self.content.lines
+            ]
+        )
+        return replace(self, content=styled)