py-sparcli 0.3.0__py3-none-any.whl

sparcli/output/kv.py

@@ -0,0 +1,175 @@
+"""
+sparcli.output.kv
+=================
+
+Defines :class:`KeyValue`, an aligned list of key-value pairs.
+
+Keys are padded to a common column width (the widest key, or a fixed width) and
+joined to their values by a separator. Keys are bold by default and values use
+the secondary style; long values can be wrapped across several rows, with the
+key shown only on the first row. Both a keyword constructor and fluent builders
+are provided.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sparcli.core.geometry import Edges
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import IntoText, Line, Span, Text, into_text
+from sparcli.core.theme import theme
+from sparcli.core.width import visible_width, wrap
+from sparcli.output.compose import pad
+
+_DEFAULT_SEPARATOR = "  "
+_MIN_VALUE_WIDTH = 1
+
+
+@dataclass(frozen=True, slots=True)
+class _Pair:
+    """One key-value pair with a plain key and rich value."""
+
+    key: str
+    value: Text = field(default_factory=Text)
+
+
+class KeyValue(Renderable):
+    """A list of aligned key-value pairs."""
+
+    __slots__ = (
+        "_pairs",
+        "_separator",
+        "_key_width",
+        "_key_style",
+        "_value_style",
+        "_item_gap",
+        "_wrap_values",
+        "_margin",
+    )
+
+    def __init__(
+        self,
+        *,
+        separator: str = _DEFAULT_SEPARATOR,
+        key_width: int | None = None,
+        key_style: Style | None = None,
+        value_style: Style | None = None,
+        item_gap: int = 0,
+        wrap_values: bool = False,
+        margin: Edges | None = None,
+    ) -> None:
+        self._pairs: list[_Pair] = []
+        self._separator = separator
+        self._key_width = key_width
+        self._key_style = (
+            key_style if key_style is not None else Style.new().bold()
+        )
+        self._value_style = (
+            value_style if value_style is not None else theme().secondary
+        )
+        self._item_gap = item_gap
+        self._wrap_values = wrap_values
+        self._margin = margin if margin is not None else Edges()
+
+    def add(self, key: str, value: IntoText) -> KeyValue:
+        """Adds a key-value pair and returns the list."""
+        self._pairs.append(_Pair(key=key, value=into_text(value)))
+        return self
+
+    def separator(self, separator: str) -> KeyValue:
+        """Sets the separator between key and value and returns the list."""
+        self._separator = separator
+        return self
+
+    def key_width(self, width: int) -> KeyValue:
+        """Sets a fixed key column width and returns the list."""
+        self._key_width = width
+        return self
+
+    def key_style(self, style: Style) -> KeyValue:
+        """Sets the key style and returns the list."""
+        self._key_style = style
+        return self
+
+    def value_style(self, style: Style) -> KeyValue:
+        """Sets the value style and returns the list."""
+        self._value_style = style
+        return self
+
+    def item_gap(self, gap: int) -> KeyValue:
+        """Sets the number of blank lines between pairs and returns the list."""
+        self._item_gap = gap
+        return self
+
+    def wrap_values(self, wrap_values: bool) -> KeyValue:
+        """Enables or disables value wrapping and returns the list."""
+        self._wrap_values = wrap_values
+        return self
+
+    def margin(self, margin: Edges) -> KeyValue:
+        """Sets the outer margin and returns the list."""
+        self._margin = margin
+        return self
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the aligned pairs into at most ``max_width`` columns."""
+        key_width = self._resolved_key_width()
+        prefix_width = key_width + visible_width(self._separator)
+        value_width = max(_MIN_VALUE_WIDTH, max_width - prefix_width)
+        lines: list[Line] = []
+        for index, pair in enumerate(self._pairs):
+            if index > 0:
+                _push_gap(lines, self._item_gap)
+            self._push_pair(lines, pair, key_width, value_width)
+        return pad(Rendered(lines), self._margin)
+
+    def _resolved_key_width(self) -> int:
+        """Returns the effective key column width."""
+        if self._key_width is not None:
+            return self._key_width
+        return max((visible_width(pair.key) for pair in self._pairs), default=0)
+
+    def _push_pair(
+        self,
+        lines: list[Line],
+        pair: _Pair,
+        key_width: int,
+        value_width: int,
+    ) -> None:
+        """Renders one pair, wrapping the value into rows when enabled."""
+        for row, value_line in enumerate(self._value_lines(pair, value_width)):
+            key_cell = pair.key if row == 0 else ""
+            lines.append(self._compose_line(key_cell, key_width, value_line))
+
+    def _value_lines(self, pair: _Pair, value_width: int) -> list[Line]:
+        """Splits a pair's value into one or more display lines."""
+        if not self._wrap_values:
+            return list(pair.value.lines)
+        out: list[Line] = []
+        for line in pair.value.lines:
+            for chunk in wrap(line.plain(), value_width):
+                out.append(Line.styled(chunk, self._value_style))
+        return out
+
+    def _compose_line(self, key: str, key_width: int, value_line: Line) -> Line:
+        """Composes a padded key cell, separator and value into one line."""
+        key_pad = max(0, key_width - visible_width(key))
+        spans = [
+            Span.styled(key, self._key_style),
+            Span.raw(" " * key_pad),
+            Span.raw(self._separator),
+        ]
+        for span in value_line.spans:
+            style = self._value_style.patch(span.style)
+            spans.append(
+                Span(content=span.content, style=style, link=span.link)
+            )
+        return Line(spans)
+
+
+def _push_gap(lines: list[Line], count: int) -> None:
+    """Pushes ``count`` blank lines onto ``lines``."""
+    for _ in range(max(0, count)):
+        lines.append(Line())

sparcli/output/layout.py

@@ -0,0 +1,77 @@
+"""
+sparcli.output.layout
+=====================
+
+Internal line-building helpers shared by the output widgets.
+
+These small functions create blank lines and runs of spaces, and pad a line to
+a target width with a fill style. They keep the widget code focused on layout
+decisions instead of span bookkeeping.
+"""
+
+from __future__ import annotations
+
+from sparcli.core.geometry import Align
+from sparcli.core.style import Style
+from sparcli.core.text import Line, Span
+
+
+def space_span(count: int, style: Style | None = None) -> Span:
+    """Returns a span of ``count`` spaces with an optional fill style."""
+    width = max(0, count)
+    return Span(content=" " * width, style=style or Style.new())
+
+
+def blank_line(width: int = 0, style: Style | None = None) -> Line:
+    """Returns an empty line, optionally filled with ``width`` spaces."""
+    if width <= 0:
+        return Line()
+    return Line([space_span(width, style)])
+
+
+def pad_line(
+    line: Line,
+    width: int,
+    align: Align = Align.LEFT,
+    style: Style | None = None,
+) -> Line:
+    """
+    Pads a line to ``width`` columns using ``align`` and a fill style.
+
+    Parameters
+    ----------
+    line : Line
+        The line to pad. Lines wider than ``width`` are returned unchanged.
+    width : int
+        The target width in columns.
+    align : Align
+        How to distribute the padding.
+    style : Style | None
+        The style applied to the padding spaces.
+
+    Returns
+    -------
+    Line
+        A new line padded to ``width``.
+    """
+    deficit = width - line.width()
+    if deficit <= 0:
+        return Line(list(line.spans))
+    left, right = _split_padding(deficit, align)
+    spans: list[Span] = []
+    if left:
+        spans.append(space_span(left, style))
+    spans.extend(line.spans)
+    if right:
+        spans.append(space_span(right, style))
+    return Line(spans)
+
+
+def _split_padding(deficit: int, align: Align) -> tuple[int, int]:
+    """Splits a padding deficit into left and right amounts for an alignment."""
+    if align is Align.LEFT:
+        return (0, deficit)
+    if align is Align.RIGHT:
+        return (deficit, 0)
+    left = deficit // 2
+    return (left, deficit - left)

sparcli/output/list.py

@@ -0,0 +1,274 @@
+"""
+sparcli.output.list
+===================
+
+Defines :class:`List` and the :class:`Marker` enum: bulleted and ordered lists
+with nesting and hanging indents.
+
+A list prefixes each item with a marker (a bullet or an ordered label such as
+``1.``, ``a.`` or ``iv.``). Continuation rows of a multi-line item align under
+the content with a hanging indent, and nested sub-lists added via
+:meth:`List.item_with` are indented beneath their parent item.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from sparcli.core.geometry import Align, Edges
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import IntoText, Line, Span, Text, into_text
+from sparcli.core.theme import theme
+from sparcli.core.width import visible_width
+from sparcli.output.layout import blank_line, pad_line, space_span
+
+# Alphabet size for bijective base-26 alphabetic markers.
+_ALPHA_BASE = 26
+
+# Roman-numeral values paired with their lowercase symbols, high to low.
+_NUMERALS: tuple[tuple[int, str], ...] = (
+    (1000, "m"),
+    (900, "cm"),
+    (500, "d"),
+    (400, "cd"),
+    (100, "c"),
+    (90, "xc"),
+    (50, "l"),
+    (40, "xl"),
+    (10, "x"),
+    (9, "ix"),
+    (5, "v"),
+    (4, "iv"),
+    (1, "i"),
+)
+
+
+class Marker(enum.Enum):
+    """The marker style used to label list items."""
+
+    BULLET = enum.auto()
+    NUMBER = enum.auto()
+    ALPHA_LOWER = enum.auto()
+    ALPHA_UPPER = enum.auto()
+    ROMAN_LOWER = enum.auto()
+    ROMAN_UPPER = enum.auto()
+
+
+# Ordered-marker label builders keyed by marker, given a zero-based index.
+_ORDERED_CORE: dict[Marker, Callable[[int], str]] = {
+    Marker.NUMBER: lambda index: str(index + 1),
+    Marker.ALPHA_LOWER: lambda index: _to_alpha(index, upper=False),
+    Marker.ALPHA_UPPER: lambda index: _to_alpha(index, upper=True),
+    Marker.ROMAN_LOWER: lambda index: _to_roman(index + 1, upper=False),
+    Marker.ROMAN_UPPER: lambda index: _to_roman(index + 1, upper=True),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class _ListItem:
+    """One list entry with an optional nested sub-list."""
+
+    content: Text
+    children: List | None = field(default=None)
+
+
+class List(Renderable):
+    """A bulleted or ordered list with optional nesting."""
+
+    __slots__ = (
+        "_marker",
+        "_items",
+        "_marker_style",
+        "_bullet",
+        "_suffix",
+        "_indent",
+        "_item_gap",
+        "_margin",
+    )
+
+    def __init__(
+        self,
+        *,
+        marker: Marker = Marker.BULLET,
+        marker_style: Style | None = None,
+        bullet: str | None = None,
+        suffix: str = "",
+        indent: int = 0,
+        item_gap: int = 0,
+        margin: Edges | None = None,
+    ) -> None:
+        self._marker = marker
+        self._items: list[_ListItem] = []
+        self._marker_style = (
+            marker_style if marker_style is not None else theme().secondary
+        )
+        self._bullet = bullet
+        self._suffix = suffix
+        self._indent = indent
+        self._item_gap = item_gap
+        self._margin = margin if margin is not None else Edges()
+
+    @classmethod
+    def ordered(cls, marker: Marker) -> List:
+        """
+        Returns an empty ordered list using ``marker`` with a ``.`` suffix.
+
+        Parameters
+        ----------
+        marker : Marker
+            The ordered marker style. ``Marker.BULLET`` yields no suffix.
+
+        Returns
+        -------
+        List
+            The configured, empty list.
+        """
+        suffix = "" if marker is Marker.BULLET else "."
+        return cls(marker=marker, suffix=suffix)
+
+    def item(self, content: IntoText) -> List:
+        """Adds a leaf item and returns the list."""
+        self._items.append(_ListItem(content=into_text(content)))
+        return self
+
+    def item_with(self, content: IntoText, children: List) -> List:
+        """Adds an item carrying a nested sub-list and returns the list."""
+        self._items.append(
+            _ListItem(content=into_text(content), children=children)
+        )
+        return self
+
+    def bullet(self, glyph: str) -> List:
+        """Sets a custom bullet glyph (bullet marker only)."""
+        self._bullet = glyph
+        return self
+
+    def marker_style(self, style: Style) -> List:
+        """Sets the marker style and returns the list."""
+        self._marker_style = style
+        return self
+
+    def indent(self, indent: int) -> List:
+        """Sets the left indent in columns and returns the list."""
+        self._indent = indent
+        return self
+
+    def item_gap(self, gap: int) -> List:
+        """Sets the number of blank lines between items."""
+        self._item_gap = gap
+        return self
+
+    def margin(self, margin: Edges) -> List:
+        """Sets the outer margin and returns the list."""
+        self._margin = margin
+        return self
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the list; ``max_width`` is accepted but not constraining."""
+        del max_width
+        return self._apply_margin(Rendered(self._render_lines()))
+
+    def _apply_margin(self, block: Rendered) -> Rendered:
+        """Surrounds ``block`` with the outer margin, matching Rust ``pad``."""
+        edges = self._margin
+        content_width = block.width()
+        inner_width = content_width + edges.horizontal()
+        lines: list[Line] = []
+        for _ in range(edges.top):
+            lines.append(blank_line(inner_width))
+        for line in block.lines:
+            lines.append(_pad_content_line(line, edges, content_width))
+        for _ in range(edges.bottom):
+            lines.append(blank_line(inner_width))
+        return Rendered(lines)
+
+    def _marker_label(self, index: int) -> str:
+        """Returns the marker label for the item at ``index``."""
+        if self._marker is Marker.BULLET:
+            glyph = (
+                self._bullet if self._bullet is not None else theme().bullet()
+            )
+            return f"{glyph} "
+        core = _ORDERED_CORE[self._marker](index)
+        return f"{core}{self._suffix} "
+
+    def _render_lines(self) -> list[Line]:
+        """Renders the list into a flat list of lines, without the margin."""
+        lines: list[Line] = []
+        for index, item in enumerate(self._items):
+            if index > 0:
+                for _ in range(self._item_gap):
+                    lines.append(Line())
+            self._render_item(index, item, lines)
+        return lines
+
+    def _render_item(
+        self, index: int, item: _ListItem, lines: list[Line]
+    ) -> None:
+        """Renders one item and its children into ``lines``."""
+        label = self._marker_label(index)
+        label_width = visible_width(label)
+        indent = " " * self._indent
+        hang = " " * (self._indent + label_width)
+        for row, content_line in enumerate(item.content.lines):
+            spans: list[Span] = []
+            if row == 0:
+                spans.append(Span.raw(indent))
+                spans.append(Span.styled(label, self._marker_style))
+            else:
+                spans.append(Span.raw(hang))
+            spans.extend(content_line.spans)
+            lines.append(Line(spans))
+        self._render_children(item, label_width, lines)
+
+    def _render_children(
+        self, item: _ListItem, label_width: int, lines: list[Line]
+    ) -> None:
+        """Renders a nested sub-list indented under its parent item."""
+        if item.children is None:
+            return
+        hang = self._indent + label_width
+        for child_line in item.children._render_lines():
+            spans: list[Span] = [Span.raw(" " * hang)]
+            spans.extend(child_line.spans)
+            lines.append(Line(spans))
+
+
+def _pad_content_line(line: Line, edges: Edges, content_width: int) -> Line:
+    """Adds left/right space columns around one content line."""
+    spans: list[Span] = []
+    if edges.left > 0:
+        spans.append(space_span(edges.left))
+    if edges.right > 0:
+        padded = pad_line(line, content_width, Align.LEFT)
+        spans.extend(padded.spans)
+        spans.append(space_span(edges.right))
+    else:
+        spans.extend(line.spans)
+    return Line(spans)
+
+
+def _to_alpha(index: int, *, upper: bool) -> str:
+    """Converts a zero-based index to bijective base-26 letters."""
+    value = index + 1
+    chars: list[str] = []
+    base = ord("A") if upper else ord("a")
+    while value > 0:
+        rem = (value - 1) % _ALPHA_BASE
+        chars.append(chr(base + rem))
+        value = (value - 1) // _ALPHA_BASE
+    return "".join(reversed(chars))
+
+
+def _to_roman(value: int, *, upper: bool) -> str:
+    """Converts a positive integer to a roman numeral."""
+    out: list[str] = []
+    for amount, symbol in _NUMERALS:
+        while value >= amount:
+            out.append(symbol)
+            value -= amount
+    text = "".join(out)
+    return text.upper() if upper else text

sparcli/output/live.py

@@ -0,0 +1,129 @@
+"""
+sparcli.output.live
+==================
+
+Defines the in-place redraw engine :class:`InPlace` and the :class:`Live` view.
+
+:class:`InPlace` rewinds the cursor and rewrites a frame in place; it powers
+spinners, progress bars, multi-progress groups and every interactive prompt.
+Off a terminal it emits no control codes and prints only the final frame once,
+so piped and captured output stays clean. :class:`Live` is the public wrapper
+for updating an arbitrary renderable in place.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+
+from sparcli.core import cursor
+from sparcli.core.render import Renderable, Rendered, write_line, write_rendered
+from sparcli.core.terminal import color_support, is_output_tty
+
+
+class InPlace:
+    """Redraws successive frames in the same terminal region."""
+
+    __slots__ = ("_interactive", "_silent", "_last_height", "_last_frame")
+
+    def __init__(self, interactive: bool, silent: bool) -> None:
+        self._interactive = interactive
+        self._silent = silent
+        self._last_height = 0
+        self._last_frame: Rendered | None = None
+
+    @classmethod
+    def create(cls, always: bool = False) -> InPlace:
+        """Returns an engine that redraws on a TTY (or always when forced)."""
+        return cls(interactive=always or is_output_tty(), silent=False)
+
+    @classmethod
+    def silent(cls) -> InPlace:
+        """Returns an engine that never draws, for headless prompts and tests."""
+        return cls(interactive=False, silent=True)
+
+    def draw(self, rendered: Rendered) -> None:
+        """Rewinds and rewrites the frame, or records it when off a terminal."""
+        if self._silent:
+            return
+        if not self._interactive:
+            self._last_frame = rendered
+            return
+        cursor.hide()
+        buffer = io.StringIO()
+        self._rewind(buffer)
+        support = color_support()
+        for index, line in enumerate(rendered.lines):
+            if index:
+                buffer.write("\r\n")
+            write_line(buffer, line, support)
+        sys.stdout.write(buffer.getvalue())
+        sys.stdout.flush()
+        self._last_height = rendered.height()
+
+    def reset(self) -> None:
+        """Forgets the previous frame after an external program drew over it."""
+        self._last_height = 0
+
+    def finish(self) -> None:
+        """Leaves the final frame in place and ends the session."""
+        if self._silent:
+            return
+        if self._interactive:
+            sys.stdout.write("\r\n")
+            sys.stdout.flush()
+        elif self._last_frame is not None:
+            write_rendered(sys.stdout, self._last_frame, color_support())
+            sys.stdout.flush()
+        cursor.show()
+        self._last_height = 0
+        self._last_frame = None
+
+    def clear(self) -> None:
+        """Erases the current frame from the terminal."""
+        if self._silent or not self._interactive:
+            self._last_frame = None
+            return
+        buffer = io.StringIO()
+        self._rewind(buffer)
+        sys.stdout.write(buffer.getvalue())
+        sys.stdout.flush()
+        cursor.show()
+        self._last_height = 0
+
+    def _rewind(self, buffer: io.StringIO) -> None:
+        """Writes the escape codes that move the cursor back to the frame top."""
+        if not self._last_height:
+            return
+        buffer.write("\r")
+        if self._last_height > 1:
+            buffer.write(f"\x1b[{self._last_height - 1}A")
+        buffer.write("\x1b[J")
+
+
+class Live:
+    """Updates an arbitrary renderable in place on the terminal."""
+
+    __slots__ = ("_inplace",)
+
+    def __init__(self, inplace: InPlace | None = None) -> None:
+        self._inplace = inplace or InPlace.create(always=False)
+
+    @classmethod
+    def always(cls) -> Live:
+        """Returns a live view that redraws even when off a terminal."""
+        return cls(InPlace.create(always=True))
+
+    def update(self, widget: Renderable) -> None:
+        """Renders ``widget`` at the terminal width and draws it in place."""
+        from sparcli.core.terminal import term_width
+
+        self._inplace.draw(widget.render(term_width()))
+
+    def finish(self) -> None:
+        """Leaves the final frame and ends the live session."""
+        self._inplace.finish()
+
+    def clear(self) -> None:
+        """Erases the live frame from the terminal."""
+        self._inplace.clear()