py-sparcli 0.3.0__py3-none-any.whl

sparcli/core/terminal.py

@@ -0,0 +1,127 @@
+"""
+sparcli.core.terminal
+=====================
+
+Detects terminal capabilities and size.
+
+The functions here answer three questions the renderer and prompts need: how
+wide is the terminal, is standard output (or input) an interactive TTY, and how
+much color can be emitted. Behaviour honours the widely supported environment
+variables ``NO_COLOR``, ``CLICOLOR_FORCE`` and ``COLORTERM``, plus the test-only
+override ``SPARCLI_NO_TTY``.
+"""
+
+from __future__ import annotations
+
+import enum
+import os
+import shutil
+import sys
+
+DEFAULT_WIDTH = 80
+DEFAULT_HEIGHT = 24
+
+_NO_COLOR = "NO_COLOR"
+_CLICOLOR_FORCE = "CLICOLOR_FORCE"
+_COLORTERM = "COLORTERM"
+_NO_TTY_OVERRIDE = "SPARCLI_NO_TTY"
+
+
+class ColorSupport(enum.Enum):
+    """How much color the current output stream can display."""
+
+    NONE = enum.auto()
+    ANSI16 = enum.auto()
+    TRUECOLOR = enum.auto()
+
+
+def terminal_size() -> tuple[int, int]:
+    """
+    Returns the terminal size as a ``(width, height)`` column/row pair.
+
+    Returns
+    -------
+    tuple[int, int]
+        The terminal width and height, falling back to ``(80, 24)`` when the
+        size cannot be determined.
+    """
+    try:
+        size = shutil.get_terminal_size(
+            fallback=(DEFAULT_WIDTH, DEFAULT_HEIGHT)
+        )
+    except (ValueError, OSError):
+        return (DEFAULT_WIDTH, DEFAULT_HEIGHT)
+    return (size.columns, size.lines)
+
+
+def term_width() -> int:
+    """Returns the terminal width in columns."""
+    return terminal_size()[0]
+
+
+def term_height() -> int:
+    """Returns the terminal height in rows."""
+    return terminal_size()[1]
+
+
+def is_output_tty() -> bool:
+    """Returns whether standard output is an interactive terminal."""
+    return not _no_tty_override() and _isatty(sys.stdout)
+
+
+def is_input_tty() -> bool:
+    """
+    Returns whether both standard input and output are interactive terminals.
+
+    Prompts require input and output to be a TTY; either being redirected means
+    the prompt cannot run interactively.
+    """
+    return not _no_tty_override() and _isatty(sys.stdin) and _isatty(sys.stdout)
+
+
+def color_support() -> ColorSupport:
+    """
+    Returns the color support level for the current output stream.
+
+    Returns
+    -------
+    ColorSupport
+        ``NONE`` when color is disabled (``NO_COLOR`` or a non-TTY without
+        ``CLICOLOR_FORCE``), ``TRUECOLOR`` when ``COLORTERM`` advertises 24-bit
+        color, otherwise ``ANSI16``.
+    """
+    if _NO_COLOR in os.environ:
+        return ColorSupport.NONE
+    if not _env_enabled(_CLICOLOR_FORCE) and not is_output_tty():
+        return ColorSupport.NONE
+    if _colorterm_truecolor():
+        return ColorSupport.TRUECOLOR
+    return ColorSupport.ANSI16
+
+
+def _isatty(stream: object) -> bool:
+    """Returns whether a stream reports itself as a TTY, defensively."""
+    isatty = getattr(stream, "isatty", None)
+    if not callable(isatty):
+        return False
+    try:
+        return bool(isatty())
+    except (ValueError, OSError):
+        return False
+
+
+def _no_tty_override() -> bool:
+    """Returns whether the SPARCLI_NO_TTY test override forces a non-TTY."""
+    return _env_enabled(_NO_TTY_OVERRIDE)
+
+
+def _env_enabled(key: str) -> bool:
+    """Returns whether an env var is set to a non-empty value other than '0'."""
+    value = os.environ.get(key)
+    return value is not None and value != "" and value != "0"
+
+
+def _colorterm_truecolor() -> bool:
+    """Returns whether COLORTERM advertises truecolor / 24-bit support."""
+    value = os.environ.get(_COLORTERM, "").lower()
+    return "truecolor" in value or "24bit" in value

sparcli/core/text.py

@@ -0,0 +1,143 @@
+"""
+sparcli.core.text
+=================
+
+Defines the rich-text primitives :class:`Span`, :class:`Line` and
+:class:`Text`.
+
+A :class:`Span` is a run of text with a single style and an optional hyperlink.
+A :class:`Line` is a sequence of spans; a :class:`Text` is a sequence of lines.
+Together they mirror ratatui's text vocabulary. The ``into_*`` helpers coerce
+plain strings into these types, so widget APIs can accept either.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from sparcli.core.style import Style
+from sparcli.core.width import visible_width
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    """
+    A styled run of text with an optional hyperlink target.
+
+    Attributes
+    ----------
+    content : str
+        The text of the span.
+    style : Style
+        The style applied to the text.
+    link : str | None
+        An OSC-8 hyperlink target, or ``None``.
+    """
+
+    content: str = ""
+    style: Style = field(default_factory=Style)
+    link: str | None = None
+
+    @classmethod
+    def raw(cls, content: str) -> Span:
+        """Returns an unstyled span with no link."""
+        return cls(content=content)
+
+    @classmethod
+    def styled(cls, content: str, style: Style) -> Span:
+        """Returns a span with the given style."""
+        return cls(content=content, style=style)
+
+    def with_link(self, url: str) -> Span:
+        """Returns a copy of the span carrying an OSC-8 hyperlink."""
+        return replace(self, link=url)
+
+    def width(self) -> int:
+        """Returns the display width of the span in columns."""
+        return visible_width(self.content)
+
+
+@dataclass(slots=True)
+class Line:
+    """A single line of text made of one or more :class:`Span` objects."""
+
+    spans: list[Span] = field(default_factory=list)
+
+    @classmethod
+    def raw(cls, content: str) -> Line:
+        """Returns a line holding a single unstyled span."""
+        return cls([Span.raw(content)])
+
+    @classmethod
+    def styled(cls, content: str, style: Style) -> Line:
+        """Returns a line holding a single styled span."""
+        return cls([Span.styled(content, style)])
+
+    def width(self) -> int:
+        """Returns the total display width of the line in columns."""
+        return sum(span.width() for span in self.spans)
+
+    def plain(self) -> str:
+        """Returns the line's text without any styling."""
+        return "".join(span.content for span in self.spans)
+
+
+@dataclass(slots=True)
+class Text:
+    """A block of styled text made of zero or more :class:`Line` objects."""
+
+    lines: list[Line] = field(default_factory=list)
+
+    @classmethod
+    def raw(cls, content: str) -> Text:
+        """Returns text with ``content`` split into lines on newlines."""
+        return cls([Line.raw(part) for part in content.split("\n")])
+
+    @classmethod
+    def styled(cls, content: str, style: Style) -> Text:
+        """Returns styled text with ``content`` split on newlines."""
+        return cls([Line.styled(part, style) for part in content.split("\n")])
+
+    def push_line(self, line: IntoLine) -> None:
+        """Appends a line to the text."""
+        self.lines.append(into_line(line))
+
+    def width(self) -> int:
+        """Returns the width of the widest line in columns."""
+        return max((line.width() for line in self.lines), default=0)
+
+    def height(self) -> int:
+        """Returns the number of lines."""
+        return len(self.lines)
+
+
+IntoSpan = str | Span
+IntoLine = str | Span | Line
+IntoText = str | Span | Line | Text
+
+
+def into_span(value: IntoSpan) -> Span:
+    """Coerces a string or span into a :class:`Span`."""
+    if isinstance(value, Span):
+        return value
+    return Span.raw(value)
+
+
+def into_line(value: IntoLine) -> Line:
+    """Coerces a string, span or line into a :class:`Line`."""
+    if isinstance(value, Line):
+        return value
+    if isinstance(value, Span):
+        return Line([value])
+    return Line.raw(value)
+
+
+def into_text(value: IntoText) -> Text:
+    """Coerces a string, span, line or text into a :class:`Text`."""
+    if isinstance(value, Text):
+        return value
+    if isinstance(value, Line):
+        return Text([value])
+    if isinstance(value, Span):
+        return Text([Line([value])])
+    return Text.raw(value)

sparcli/core/theme.py

@@ -0,0 +1,117 @@
+"""
+sparcli.core.theme
+=================
+
+Defines the unified :class:`Theme` shared by output widgets and input prompts.
+
+A single process-wide theme drives accent color, semantic styles (success,
+error, ...), the default border and whether Unicode or ASCII glyphs are used.
+Read the active theme with :func:`theme` and replace it with :func:`set_theme`;
+per-call widget options still override individual theme values.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+from sparcli.core.border import BorderType
+from sparcli.core.color import Color
+from sparcli.core.style import Style
+
+DEFAULT_ACCENT = Color.rgb(137, 180, 250)
+
+_TITLE = Style.from_color(DEFAULT_ACCENT).bold()
+_SECONDARY = Style.new().dim()
+_SELECTION = Style.from_color(DEFAULT_ACCENT).bold()
+_CURSOR = Style.new().with_fg(Color.BLACK).with_bg(DEFAULT_ACCENT)
+
+# Two-step glyphs: (unicode, ascii). ASCII is the fallback for plain terminals.
+_BULLET = ("•", "*")
+_CURSOR_MARKER = ("‣ ", "> ")
+_MARKER = ("  ", "  ")
+_CHECKBOX_ON = ("◉ ", "[x] ")
+_CHECKBOX_OFF = ("◯ ", "[ ] ")
+
+
+@dataclass(frozen=True, slots=True)
+class Theme:
+    """
+    The look shared across output and input.
+
+    Attributes
+    ----------
+    accent : Color
+        The single highlight color for titles, selections and active items.
+    title, heading, secondary, success, error, warning, info, debug, hint : Style
+        Semantic styles applied throughout the library.
+    selection, cursor : Style
+        Styles for the highlighted item and the text cursor.
+    border : BorderType
+        The default border look.
+    unicode : bool
+        When ``False``, glyph accessors return their ASCII fallbacks.
+    """
+
+    accent: Color = DEFAULT_ACCENT
+    title: Style = _TITLE
+    heading: Style = _TITLE
+    secondary: Style = _SECONDARY
+    success: Style = Style.from_color(Color.GREEN)
+    error: Style = Style.from_color(Color.RED)
+    warning: Style = Style.from_color(Color.YELLOW)
+    info: Style = Style.from_color(DEFAULT_ACCENT)
+    debug: Style = Style.from_color(Color.MAGENTA)
+    hint: Style = _SECONDARY
+    selection: Style = _SELECTION
+    cursor: Style = _CURSOR
+    border: BorderType = BorderType.ROUNDED
+    unicode: bool = True
+
+    def bullet(self) -> str:
+        """Returns the list bullet glyph."""
+        return self._glyph(_BULLET)
+
+    def cursor_marker(self) -> str:
+        """Returns the marker shown next to the active list item."""
+        return self._glyph(_CURSOR_MARKER)
+
+    def marker(self) -> str:
+        """Returns the blank marker aligning non-active list items."""
+        return self._glyph(_MARKER)
+
+    def checkbox_on(self) -> str:
+        """Returns the checked checkbox glyph."""
+        return self._glyph(_CHECKBOX_ON)
+
+    def checkbox_off(self) -> str:
+        """Returns the unchecked checkbox glyph."""
+        return self._glyph(_CHECKBOX_OFF)
+
+    def _glyph(self, pair: tuple[str, str]) -> str:
+        """Returns the unicode or ascii glyph based on the theme setting."""
+        return pair[0] if self.unicode else pair[1]
+
+
+_lock = threading.Lock()
+_current = Theme()
+
+
+def theme() -> Theme:
+    """Returns the active process-wide theme."""
+    with _lock:
+        return _current
+
+
+def set_theme(new_theme: Theme) -> None:
+    """
+    Replaces the active process-wide theme.
+
+    Parameters
+    ----------
+    new_theme : Theme
+        The theme to install. Widget options still override individual values.
+    """
+    global _current
+    with _lock:
+        _current = new_theme

sparcli/core/width.py

@@ -0,0 +1,244 @@
+"""
+sparcli.core.width
+==================
+
+Computes display width and reflows text, aware of Unicode and ANSI escapes.
+
+Wide glyphs (CJK, many emoji) count as two columns, zero-width combining marks
+as zero, and ANSI escape sequences as nothing. These helpers are the basis for
+every alignment, truncation and wrapping decision in the library. Width is
+derived from the standard library's :mod:`unicodedata`, so no third-party
+dependency is required.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+_ESC = "\x1b"
+_BELL = "\x07"
+_CSI_FINAL_MIN = 0x40
+_CSI_FINAL_MAX = 0x7E
+_ZERO_WIDTH_CATEGORIES = frozenset({"Mn", "Me", "Cf"})
+_WIDE_EAST_ASIAN = frozenset({"W", "F"})
+
+
+def char_width(char: str) -> int:
+    """
+    Returns the display width of a single character in terminal columns.
+
+    Parameters
+    ----------
+    char : str
+        A single character.
+
+    Returns
+    -------
+    int
+        ``0`` for combining or control characters, ``2`` for wide East Asian
+        glyphs, otherwise ``1``. An empty string is ``0`` and a multi-character
+        string sums its characters, so the function never raises on bad input.
+    """
+    if len(char) != 1:
+        return sum(char_width(part) for part in char)
+    if char == "\x00" or unicodedata.combining(char):
+        return 0
+    category = unicodedata.category(char)
+    if category in _ZERO_WIDTH_CATEGORIES or category == "Cc":
+        return 0
+    if unicodedata.east_asian_width(char) in _WIDE_EAST_ASIAN:
+        return 2
+    return 1
+
+
+def visible_width(text: str) -> int:
+    """
+    Returns the column width of ``text``, ignoring ANSI escape sequences.
+
+    Parameters
+    ----------
+    text : str
+        The text to measure. May contain ANSI escapes.
+
+    Returns
+    -------
+    int
+        The number of terminal columns the text occupies.
+    """
+    if _ESC not in text:
+        return sum(char_width(char) for char in text)
+    return sum(char_width(char) for char in strip_ansi(text))
+
+
+def strip_ansi(text: str) -> str:
+    """
+    Removes CSI and OSC escape sequences from ``text``.
+
+    Parameters
+    ----------
+    text : str
+        The text to clean.
+
+    Returns
+    -------
+    str
+        ``text`` with ANSI control sequences removed.
+    """
+    if _ESC not in text:
+        return text
+    out: list[str] = []
+    index = 0
+    length = len(text)
+    while index < length:
+        char = text[index]
+        if char == _ESC:
+            index = _skip_escape(text, index)
+            continue
+        out.append(char)
+        index += 1
+    return "".join(out)
+
+
+def truncate(text: str, max_cols: int, ellipsis: str = "…") -> str:
+    """
+    Truncates ``text`` to ``max_cols`` columns, appending an ellipsis.
+
+    Parameters
+    ----------
+    text : str
+        The text to truncate. Assumed to contain no ANSI escapes.
+    max_cols : int
+        The maximum number of columns the result may occupy.
+    ellipsis : str
+        The marker appended when content is dropped.
+
+    Returns
+    -------
+    str
+        The original text if it fits, otherwise a truncated copy ending in the
+        ellipsis.
+    """
+    if max_cols <= 0:
+        return ""
+    if visible_width(text) <= max_cols:
+        return text
+    budget = max_cols - visible_width(ellipsis)
+    if budget <= 0:
+        return ellipsis[:max_cols]
+    kept: list[str] = []
+    used = 0
+    for char in text:
+        width = char_width(char)
+        if used + width > budget:
+            break
+        kept.append(char)
+        used += width
+    return "".join(kept) + ellipsis
+
+
+def wrap(text: str, width: int) -> list[str]:
+    """
+    Wraps ``text`` to ``width`` columns on word boundaries.
+
+    Parameters
+    ----------
+    text : str
+        The text to wrap. Newlines split paragraphs first.
+    width : int
+        The maximum column width per line. A width of ``0`` disables wrapping.
+
+    Returns
+    -------
+    list[str]
+        The wrapped lines. Empty input yields a single empty line.
+    """
+    if width <= 0:
+        return [text]
+    lines: list[str] = []
+    for paragraph in text.split("\n"):
+        lines.extend(_wrap_paragraph(paragraph, width))
+    return lines or [""]
+
+
+def _wrap_paragraph(text: str, width: int) -> list[str]:
+    """Wraps a single newline-free paragraph to ``width`` columns."""
+    lines: list[str] = []
+    current = ""
+    current_width = 0
+    for word in text.split():
+        word_width = visible_width(word)
+        gap = 1 if current else 0
+        if current and current_width + gap + word_width > width:
+            lines.append(current)
+            current = ""
+            current_width = 0
+            gap = 0
+        if word_width > width:
+            if current:
+                lines.append(current)
+                current = ""
+                current_width = 0
+            lines.extend(_split_long_word(word, width))
+            if lines:
+                current = lines.pop()
+                current_width = visible_width(current)
+            continue
+        current = f"{current} {word}" if current else word
+        current_width += gap + word_width
+    lines.append(current)
+    return lines
+
+
+def _split_long_word(word: str, width: int) -> list[str]:
+    """Hard-splits a word wider than ``width`` into column-sized chunks."""
+    chunks: list[str] = []
+    current = ""
+    current_width = 0
+    for char in word:
+        char_w = char_width(char)
+        if current_width + char_w > width and current:
+            chunks.append(current)
+            current = ""
+            current_width = 0
+        current += char
+        current_width += char_w
+    if current:
+        chunks.append(current)
+    return chunks
+
+
+def _skip_escape(text: str, index: int) -> int:
+    """Returns the index just past the escape sequence starting at ``index``."""
+    length = len(text)
+    if index + 1 >= length:
+        return index + 1
+    marker = text[index + 1]
+    if marker == "[":
+        return _skip_csi(text, index + 2)
+    if marker == "]":
+        return _skip_osc(text, index + 2)
+    return index + 2
+
+
+def _skip_csi(text: str, index: int) -> int:
+    """Returns the index past a CSI sequence body starting at ``index``."""
+    length = len(text)
+    while index < length:
+        code = ord(text[index])
+        if _CSI_FINAL_MIN <= code <= _CSI_FINAL_MAX:
+            return index + 1
+        index += 1
+    return length
+
+
+def _skip_osc(text: str, index: int) -> int:
+    """Returns the index past an OSC sequence starting at ``index``."""
+    length = len(text)
+    while index < length:
+        char = text[index]
+        if char == _BELL:
+            return index + 1
+        if char == _ESC and index + 1 < length and text[index + 1] == "\\":
+            return index + 2
+        index += 1
+    return length

sparcli/errors.py

@@ -0,0 +1,38 @@
+"""
+sparcli.errors
+==============
+
+Defines the exception hierarchy raised across the library.
+
+All errors derive from :class:`SparcliError`, so callers can catch the whole
+family with a single ``except SparcliError``. More specific subclasses carry
+context about what went wrong: terminal I/O, a missing interactive terminal or
+invalid configuration.
+"""
+
+from __future__ import annotations
+
+
+class SparcliError(Exception):
+    """Base class for every error raised by sparcli."""
+
+
+class TerminalError(SparcliError):
+    """Raised when reading from or writing to the terminal fails."""
+
+
+class NoTerminalError(SparcliError):
+    """Raised when an interactive prompt runs without a usable terminal."""
+
+    def __init__(
+        self, message: str = "no interactive terminal available"
+    ) -> None:
+        super().__init__(message)
+
+
+class ConfigError(SparcliError):
+    """Raised when a widget or prompt is configured with invalid options."""
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(f"invalid configuration: {detail}")
+        self.detail = detail