py-sparcli 0.3.0__py3-none-any.whl

sparcli/input/textarea.py

@@ -0,0 +1,242 @@
+"""
+sparcli.input.textarea
+======================
+
+Defines :class:`Textarea`, a multi-line text input prompt.
+
+The textarea drives a :class:`~sparcli.input.line_edit.LineEditor` in multi-line
+mode: Enter inserts a newline, Ctrl-D submits the whole buffer and Esc cancels.
+Arrows plus Home/End move the caret (Shift extends a selection), Up/Down move
+between rows preserving the column, and the usual Ctrl editing keys apply. With
+the editor enabled, Ctrl-G opens ``$EDITOR`` on a Markdown temp file and folds
+the result back in. Each buffer line is rendered under the prompt, with a block
+cursor on the caret's line that is dropped on the final frame.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from sparcli.core.render import Rendered
+from sparcli.core.style import Style
+from sparcli.core.terminal import is_input_tty
+from sparcli.core.text import Line
+from sparcli.core.theme import theme
+from sparcli.errors import NoTerminalError, SparcliError
+from sparcli.input.editor import edit_text, suspended_raw_mode
+from sparcli.input.event import (
+    EventKind,
+    EventSource,
+    InputEvent,
+    KeyCode,
+    KeyKind,
+    KeyPress,
+    TerminalSource,
+)
+from sparcli.input.field import field_line
+from sparcli.input.guard import TerminalGuard
+from sparcli.input.line_edit import LineEditor
+from sparcli.input.outcome import Outcome
+from sparcli.input.prompt import Flow, run_prompt
+
+logger = logging.getLogger(__name__)
+
+# Flow specialized for this prompt, so control constructors bind their type.
+_StrFlow = Flow[str]
+
+# Temp-file extension used when editing the buffer in an external editor.
+_EDITOR_SUFFIX = ".md"
+# Ctrl-letter that submits the buffer.
+_SUBMIT_KEY = "d"
+# Ctrl-letter that opens the external editor.
+_EDITOR_KEY = "g"
+
+# Ctrl-letter editing operations shared with the single-line text input.
+_CTRL_OPS: dict[str, Callable[[LineEditor], None]] = {
+    "a": LineEditor.select_all,
+    "w": LineEditor.delete_word_back,
+    "u": LineEditor.kill_to_line_start,
+    "k": LineEditor.kill_to_line_end,
+    "c": LineEditor.copy,
+    "x": LineEditor.cut,
+    "v": LineEditor.paste,
+}
+
+
+class Textarea:
+    """
+    A multi-line text input prompt.
+
+    Attributes
+    ----------
+    prompt : str
+        The label shown above the buffer.
+
+    Examples
+    --------
+    >>> area = Textarea("Notes").initial("hello")
+    >>> area.frame().height()
+    2
+    """
+
+    __slots__ = ("_prompt", "_initial", "_editor_enabled", "_editor_command")
+
+    def __init__(
+        self,
+        prompt: str,
+        *,
+        initial: str = "",
+        editor_enabled: bool = False,
+        editor_command: str | None = None,
+    ) -> None:
+        self._prompt = prompt
+        self._initial = initial
+        self._editor_enabled = editor_enabled or editor_command is not None
+        self._editor_command = editor_command
+
+    def initial(self, value: str) -> Textarea:
+        """Sets the initial multi-line value and returns ``self``."""
+        self._initial = value
+        return self
+
+    def editor(self) -> Textarea:
+        """Enables opening the buffer in ``$EDITOR`` with Ctrl-G."""
+        self._editor_enabled = True
+        return self
+
+    def editor_command(self, command: str) -> Textarea:
+        """Sets the editor command (implies :meth:`editor`)."""
+        self._editor_enabled = True
+        self._editor_command = command
+        return self
+
+    def run(self) -> Outcome[str]:
+        """
+        Runs the prompt on the real terminal.
+
+        Returns
+        -------
+        Outcome[str]
+            The submitted text or a cancellation.
+
+        Raises
+        ------
+        NoTerminalError
+            If standard input or output is not an interactive terminal.
+        """
+        if not is_input_tty():
+            raise NoTerminalError()
+        with TerminalGuard():
+            return self.run_with(TerminalSource())
+
+    def run_with(self, source: EventSource) -> Outcome[str]:
+        """
+        Runs the prompt against any event source (used for tests).
+
+        Parameters
+        ----------
+        source : EventSource
+            The source of input events driving the prompt.
+
+        Returns
+        -------
+        Outcome[str]
+            The prompt result.
+        """
+        editor = LineEditor(self._initial, multiline=True)
+        return run_prompt(source, editor, self._render, self._handle)
+
+    def frame(self) -> Rendered:
+        """Renders the prompt's static frame without running it."""
+        return self._render(LineEditor(self._initial, multiline=True), False)
+
+    def _render(self, editor: LineEditor, final_frame: bool) -> Rendered:
+        """Builds the frame, drawing the cursor on its line."""
+        active = theme()
+        cursor_line, cursor_col = editor.cursor_line_col()
+        lines = [Line.styled(self._prompt, active.title)]
+        for index, text in enumerate(editor.lines()):
+            if index == cursor_line and not final_frame:
+                lines.append(
+                    field_line("", text, cursor_col, Style.new(), active)
+                )
+            else:
+                lines.append(Line.raw(text))
+        return Rendered(lines)
+
+    def _handle(self, editor: LineEditor, event: InputEvent) -> Flow[str]:
+        """Handles one event for the textarea."""
+        if event.kind is EventKind.PASTE and event.text is not None:
+            editor.insert_str(event.text)
+            return _StrFlow.cont()
+        if event.kind is not EventKind.KEY or event.key is None:
+            return _StrFlow.cont()
+        return self._handle_key(editor, event.key)
+
+    def _handle_key(self, editor: LineEditor, key: KeyPress) -> Flow[str]:
+        """Handles a single key press (delegating Ctrl keys)."""
+        if key.ctrl:
+            return self._handle_ctrl(editor, key)
+        code = key.code
+        if code == KeyCode.ESC:
+            return _StrFlow.cancel()
+        _apply_edit(editor, key)
+        return _StrFlow.cont()
+
+    def _handle_ctrl(self, editor: LineEditor, key: KeyPress) -> Flow[str]:
+        """Handles Ctrl-modified keys (submit, editor and edit ops)."""
+        code = key.code
+        if code.kind is not KeyKind.CHAR or code.ch is None:
+            return _StrFlow.cont()
+        ch = code.ch
+        if ch == _SUBMIT_KEY:
+            return _StrFlow.submit(editor.value())
+        if ch == _EDITOR_KEY and self._editor_enabled:
+            return self._launch_editor(editor)
+        operation = _CTRL_OPS.get(ch)
+        if operation is not None:
+            operation(editor)
+        return _StrFlow.cont()
+
+    def _launch_editor(self, editor: LineEditor) -> Flow[str]:
+        """Opens the buffer in an external editor, then refreshes."""
+        text = _edit_externally(self._editor_command, editor.value())
+        if text is not None:
+            editor.set_value(text.rstrip("\n"))
+        return _StrFlow.refresh()
+
+
+def _apply_edit(editor: LineEditor, key: KeyPress) -> None:
+    """Applies a non-Ctrl editing or movement key to the editor."""
+    code = key.code
+    if code == KeyCode.ENTER:
+        editor.insert_newline()
+    elif code == KeyCode.LEFT:
+        editor.move_left(select=key.shift)
+    elif code == KeyCode.RIGHT:
+        editor.move_right(select=key.shift)
+    elif code == KeyCode.UP:
+        editor.move_up(select=key.shift)
+    elif code == KeyCode.DOWN:
+        editor.move_down(select=key.shift)
+    elif code == KeyCode.HOME:
+        editor.move_home(select=key.shift)
+    elif code == KeyCode.END:
+        editor.move_end(select=key.shift)
+    elif code == KeyCode.BACKSPACE:
+        editor.backspace()
+    elif code == KeyCode.DELETE:
+        editor.delete()
+    elif code.kind is KeyKind.CHAR and code.ch is not None:
+        editor.insert_char(code.ch)
+
+
+def _edit_externally(command: str | None, text: str) -> str | None:
+    """Edits ``text`` externally with raw mode suspended; ``None`` on error."""
+    try:
+        with suspended_raw_mode():
+            return edit_text(command, text, _EDITOR_SUFFIX)
+    except SparcliError as error:
+        logger.debug("external editor failed: %s", error)
+        return None

sparcli/input/validate.py

@@ -0,0 +1,67 @@
+"""
+sparcli.input.validate
+=====================
+
+Defines validation callbacks and character filters for text prompts.
+
+A :data:`Validator` inspects a whole input value and returns an error message
+(or ``None`` when the value is acceptable). A :data:`CharFilter` decides whether
+a single typed character is allowed. The builtins here cover the common cases:
+non-empty input, minimum length, and digit / decimal / alphabetic /
+alphanumeric / no-space character sets.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+# Returns an error message for a bad value, or ``None`` when it is acceptable.
+Validator = Callable[[str], str | None]
+
+# Decides whether a single typed character is accepted.
+CharFilter = Callable[[str], bool]
+
+
+def non_empty() -> Validator:
+    """Returns a validator that rejects empty (whitespace-only) input."""
+
+    def validate(value: str) -> str | None:
+        return None if value.strip() else "must not be empty"
+
+    return validate
+
+
+def min_len(minimum: int) -> Validator:
+    """Returns a validator requiring at least ``minimum`` characters."""
+
+    def validate(value: str) -> str | None:
+        if len(value) < minimum:
+            return f"must be at least {minimum} characters"
+        return None
+
+    return validate
+
+
+def digits() -> CharFilter:
+    """Returns a filter accepting only ASCII digits."""
+    return lambda ch: "0" <= ch <= "9"
+
+
+def decimal() -> CharFilter:
+    """Returns a filter accepting digits plus a sign and decimal point."""
+    return lambda ch: ("0" <= ch <= "9") or ch in {".", "-"}
+
+
+def alpha() -> CharFilter:
+    """Returns a filter accepting only alphabetic characters."""
+    return lambda ch: ch.isalpha()
+
+
+def alnum() -> CharFilter:
+    """Returns a filter accepting only alphanumeric characters."""
+    return lambda ch: ch.isalnum()
+
+
+def no_space() -> CharFilter:
+    """Returns a filter rejecting whitespace."""
+    return lambda ch: not ch.isspace()

sparcli/output/__init__.py

@@ -0,0 +1,56 @@
+"""
+sparcli.output
+=============
+
+Printable widgets that render styled blocks to the terminal.
+
+Every widget implements :class:`~sparcli.core.render.Renderable`. This package
+re-exports the full set for flat imports; the composition helpers
+:func:`align`, :func:`pad` and :func:`vstack` stack and place rendered blocks.
+"""
+
+from sparcli.output.alert import Alert, AlertKind
+from sparcli.output.badge import Badge
+from sparcli.output.columns import Columns
+from sparcli.output.compose import align, pad, vstack
+from sparcli.output.diff import Diff
+from sparcli.output.kv import KeyValue
+from sparcli.output.list import List, Marker
+from sparcli.output.live import Live
+from sparcli.output.multiprogress import MultiProgress
+from sparcli.output.pager import Pager
+from sparcli.output.panel import Panel
+from sparcli.output.progress import ProgressBar, ProgressStyle, Thresholds
+from sparcli.output.rule import Rule
+from sparcli.output.spinner import Spinner, SpinnerStyle
+from sparcli.output.table import Cell, Column, Table
+from sparcli.output.tree import Tree, TreeNode
+
+__all__ = [
+    "Alert",
+    "AlertKind",
+    "Badge",
+    "Cell",
+    "Column",
+    "Columns",
+    "Diff",
+    "KeyValue",
+    "List",
+    "Live",
+    "Marker",
+    "MultiProgress",
+    "Pager",
+    "Panel",
+    "ProgressBar",
+    "ProgressStyle",
+    "Rule",
+    "Spinner",
+    "SpinnerStyle",
+    "Table",
+    "Thresholds",
+    "Tree",
+    "TreeNode",
+    "align",
+    "pad",
+    "vstack",
+]

sparcli/output/alert.py

@@ -0,0 +1,107 @@
+"""
+sparcli.output.alert
+===================
+
+Defines :class:`Alert`, a bordered callout with a semantic icon and color.
+
+Each :class:`AlertKind` maps to a theme style (info, warning, error, ...) and a
+two-step icon (Unicode with an ASCII fallback). The border and icon share the
+kind's accent color. Convenience constructors cover the common kinds.
+"""
+
+from __future__ import annotations
+
+import enum
+
+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, theme
+from sparcli.output.box import BoxOpts, draw_box
+
+
+class AlertKind(enum.Enum):
+    """The semantic kind of an alert."""
+
+    INFO = enum.auto()
+    DEBUG = enum.auto()
+    WARNING = enum.auto()
+    ERROR = enum.auto()
+    SUCCESS = enum.auto()
+
+
+# Per-kind (unicode icon, ascii icon).
+_ICONS: dict[AlertKind, tuple[str, str]] = {
+    AlertKind.INFO: ("ℹ", "i"),
+    AlertKind.DEBUG: ("⚙", "*"),
+    AlertKind.WARNING: ("⚠", "!"),
+    AlertKind.ERROR: ("✖", "x"),
+    AlertKind.SUCCESS: ("✔", "+"),
+}
+
+
+def _kind_style(kind: AlertKind, active: Theme) -> Style:
+    """Returns the theme style for an alert kind."""
+    styles: dict[AlertKind, Style] = {
+        AlertKind.INFO: active.info,
+        AlertKind.DEBUG: active.debug,
+        AlertKind.WARNING: active.warning,
+        AlertKind.ERROR: active.error,
+        AlertKind.SUCCESS: active.success,
+    }
+    return styles[kind]
+
+
+class Alert(Renderable):
+    """A bordered callout carrying a semantic icon and color."""
+
+    __slots__ = ("_kind", "_content")
+
+    def __init__(self, kind: AlertKind, content: IntoText) -> None:
+        self._kind = kind
+        self._content = into_text(content)
+
+    @classmethod
+    def info(cls, content: IntoText) -> Alert:
+        """Returns an info alert."""
+        return cls(AlertKind.INFO, content)
+
+    @classmethod
+    def debug(cls, content: IntoText) -> Alert:
+        """Returns a debug alert."""
+        return cls(AlertKind.DEBUG, content)
+
+    @classmethod
+    def warning(cls, content: IntoText) -> Alert:
+        """Returns a warning alert."""
+        return cls(AlertKind.WARNING, content)
+
+    @classmethod
+    def error(cls, content: IntoText) -> Alert:
+        """Returns an error alert."""
+        return cls(AlertKind.ERROR, content)
+
+    @classmethod
+    def success(cls, content: IntoText) -> Alert:
+        """Returns a success alert."""
+        return cls(AlertKind.SUCCESS, content)
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the alert into at most ``max_width`` columns."""
+        active = theme()
+        style = _kind_style(self._kind, active)
+        icon = _ICONS[self._kind][0 if active.unicode else 1]
+        content = _prefix_icon(self._content, icon, style)
+        opts = BoxOpts(
+            border=active.border,
+            border_style=style,
+        )
+        return draw_box(Rendered.from_text(content), opts, max_width)
+
+
+def _prefix_icon(content: Text, icon: str, style: Style) -> Text:
+    """Prepends a styled icon to the first line of ``content``."""
+    lines = list(content.lines) or [Line()]
+    first = lines[0]
+    prefixed = Line([Span.styled(f"{icon} ", style), *first.spans])
+    return Text([prefixed, *lines[1:]])

sparcli/output/badge.py

@@ -0,0 +1,82 @@
+"""
+sparcli.output.badge
+====================
+
+Defines :class:`Badge`, a small inline token such as ``[TAG]`` or ``(v1.0)``.
+
+A badge wraps a short text in a pair of caps and paints it in a single style,
+defaulting to the accent color in bold. It renders to one line and also exposes
+:meth:`Badge.span`, so it can be embedded inline in other lines. Both a keyword
+constructor and fluent builder methods are provided, matching :class:`Panel`.
+"""
+
+from __future__ import annotations
+
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import Line, Span
+from sparcli.core.theme import theme
+
+_DEFAULT_LEFT_CAP = "["
+_DEFAULT_RIGHT_CAP = "]"
+
+
+class Badge(Renderable):
+    """A small inline token with configurable caps and style."""
+
+    __slots__ = ("_text", "_left_cap", "_right_cap", "_style", "_pad")
+
+    def __init__(
+        self,
+        text: str,
+        *,
+        left_cap: str = _DEFAULT_LEFT_CAP,
+        right_cap: str = _DEFAULT_RIGHT_CAP,
+        style: Style | None = None,
+        pad: int = 0,
+    ) -> None:
+        self._text = text
+        self._left_cap = left_cap
+        self._right_cap = right_cap
+        self._style = style if style is not None else _default_style()
+        self._pad = pad
+
+    def caps(self, left: str, right: str) -> Badge:
+        """Sets both caps at once and returns the badge."""
+        self._left_cap = left
+        self._right_cap = right
+        return self
+
+    def style(self, style: Style) -> Badge:
+        """Sets the badge text style and returns the badge."""
+        self._style = style
+        return self
+
+    def pad(self, pad: int) -> Badge:
+        """Sets the number of spaces inside the caps and returns the badge."""
+        self._pad = pad
+        return self
+
+    def span(self) -> Span:
+        """
+        Returns the badge as a single styled :class:`Span`.
+
+        Returns
+        -------
+        Span
+            The caps and padded text painted in the badge style.
+        """
+        spaces = " " * max(0, self._pad)
+        content = (
+            f"{self._left_cap}{spaces}{self._text}{spaces}{self._right_cap}"
+        )
+        return Span.styled(content, self._style)
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the badge as a single line, ignoring ``max_width``."""
+        return Rendered([Line([self.span()])])
+
+
+def _default_style() -> Style:
+    """Returns the default accent-bold badge style from the theme."""
+    return Style.new().with_fg(theme().accent).bold()