py-sparcli 0.3.0__py3-none-any.whl

sparcli/input/password.py

@@ -0,0 +1,233 @@
+"""
+sparcli.input.password
+======================
+
+Defines :class:`PasswordInput`, a masked single-line secret prompt.
+
+The prompt edits one line through the shared :class:`~sparcli.input.line_edit.
+LineEditor` but never shows the typed characters: each is drawn as a mask glyph
+(``*`` by default), or the length is hidden entirely when the mask is empty. It
+validates and filters input like :class:`~sparcli.input.text.TextInput` but
+omits history, suggestions and selection, and returns an
+:class:`~sparcli.input.outcome.Outcome` carrying the submitted secret.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from sparcli.core.render import Rendered
+from sparcli.core.style import Style
+from sparcli.core.terminal import is_input_tty
+from sparcli.core.theme import theme
+from sparcli.errors import NoTerminalError
+from sparcli.input.event import (
+    EventKind,
+    EventSource,
+    InputEvent,
+    KeyCode,
+    KeyKind,
+    KeyPress,
+    TerminalSource,
+)
+from sparcli.input.field import error_line, field_line, value_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
+from sparcli.input.validate import CharFilter, Validator
+
+# Default mask glyph shown for each typed character.
+_DEFAULT_MASK = "*"
+
+
+@dataclass(slots=True)
+class _State:
+    """Mutable state of a running password prompt."""
+
+    editor: LineEditor
+    error: str | None
+
+
+# Ctrl-letter editing actions dispatched on the shared line editor.
+_CTRL_ACTIONS: dict[str, Callable[[LineEditor], None]] = {
+    "u": LineEditor.kill_to_line_start,
+    "w": LineEditor.delete_word_back,
+}
+
+
+class PasswordInput:
+    """
+    A masked password input prompt.
+
+    Configure a prompt either through the keyword-only constructor options or
+    the matching fluent setters (each mutates and returns ``self``, so calls
+    chain), then run it with :meth:`run`. The typed value is displayed as
+    repeated mask glyphs; an empty :meth:`mask` hides the length entirely.
+    """
+
+    __slots__ = (
+        "_prompt",
+        "_initial",
+        "_mask",
+        "_max_chars",
+        "_validator",
+        "_char_filter",
+    )
+
+    def __init__(
+        self,
+        prompt: str,
+        *,
+        initial: str = "",
+        mask: str = _DEFAULT_MASK,
+        max_chars: int = 0,
+        validator: Validator | None = None,
+        char_filter: CharFilter | None = None,
+    ) -> None:
+        self._prompt: str = prompt
+        self._initial: str = initial
+        self._mask: str = mask
+        self._max_chars: int = max_chars
+        self._validator: Validator | None = validator
+        self._char_filter: CharFilter | None = char_filter
+
+    def initial(self, value: str) -> PasswordInput:
+        """Sets an initial value (mainly useful for previews)."""
+        self._initial = value
+        return self
+
+    def mask(self, mask: str) -> PasswordInput:
+        """Sets the mask glyph. An empty mask hides the length entirely."""
+        self._mask = mask
+        return self
+
+    def max_chars(self, maximum: int) -> PasswordInput:
+        """Limits the number of characters (0 = unlimited)."""
+        self._max_chars = maximum
+        return self
+
+    def validate(self, validator: Validator) -> PasswordInput:
+        """Sets a full-value validator and returns ``self``."""
+        self._validator = validator
+        return self
+
+    def char_filter(self, char_filter: CharFilter) -> PasswordInput:
+        """Sets a per-character filter and returns ``self``."""
+        self._char_filter = char_filter
+        return self
+
+    def run(self) -> Outcome[str]:
+        """
+        Runs the prompt on the real terminal.
+
+        Returns
+        -------
+        Outcome[str]
+            The submitted secret or a cancellation.
+
+        Raises
+        ------
+        NoTerminalError
+            When there is no 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 (the test seam)."""
+        state = _State(editor=LineEditor(self._initial), error=None)
+        return run_prompt(source, state, self._render, self._handle)
+
+    def frame(self) -> Rendered:
+        """Renders the static initial frame without running (for previews)."""
+        state = _State(editor=LineEditor(self._initial), error=None)
+        return self._render(state, False)
+
+    def _render(self, state: _State, final: bool) -> Rendered:
+        """Builds the prompt frame with the masked value."""
+        active_theme = theme()
+        display, cursor = self._masked(state)
+        if final:
+            line = value_line(self._prompt, display, Style.new(), active_theme)
+            return Rendered([line])
+        lines = [
+            field_line(self._prompt, display, cursor, Style.new(), active_theme)
+        ]
+        if state.error is not None:
+            lines.append(error_line(state.error, active_theme))
+        return Rendered(lines)
+
+    def _masked(self, state: _State) -> tuple[str, int]:
+        """Returns the masked display string and cursor index."""
+        if not self._mask:
+            return ("", 0)
+        glyph = self._mask[0]
+        return (glyph * len(state.editor), state.editor.cursor)
+
+    def _handle(self, state: _State, event: InputEvent) -> Flow[str]:
+        """Handles one input event."""
+        if event.kind is EventKind.PASTE and event.text is not None:
+            for ch in event.text:
+                self._type_char(state, ch)
+            return Flow[str].cont()
+        if event.kind is EventKind.KEY and event.key is not None:
+            return self._handle_key(state, event.key)
+        return Flow[str].cont()
+
+    def _handle_key(self, state: _State, key: KeyPress) -> Flow[str]:
+        """Handles a single key press."""
+        if key.ctrl:
+            self._handle_ctrl(state, key)
+            return Flow[str].cont()
+        code = key.code
+        if code == KeyCode.ESC:
+            return Flow[str].cancel()
+        if code == KeyCode.ENTER:
+            return self._submit(state)
+        self._edit_key(state, code)
+        return Flow[str].cont()
+
+    def _edit_key(self, state: _State, code: KeyCode) -> None:
+        """Applies a non-terminal editing or navigation key."""
+        if code == KeyCode.LEFT:
+            state.editor.move_left(select=False)
+        elif code == KeyCode.RIGHT:
+            state.editor.move_right(select=False)
+        elif code == KeyCode.BACKSPACE:
+            state.editor.backspace()
+        elif code == KeyCode.DELETE:
+            state.editor.delete()
+        elif code.kind is KeyKind.CHAR and code.ch is not None:
+            self._type_char(state, code.ch)
+
+    def _handle_ctrl(self, state: _State, key: KeyPress) -> None:
+        """Handles Ctrl-modified editing keys."""
+        code = key.code
+        if code.kind is not KeyKind.CHAR or code.ch is None:
+            return
+        action = _CTRL_ACTIONS.get(code.ch)
+        if action is not None:
+            action(state.editor)
+
+    def _submit(self, state: _State) -> Flow[str]:
+        """Validates and submits the current value."""
+        value = state.editor.value()
+        if self._validator is not None:
+            message = self._validator(value)
+            if message is not None:
+                state.error = message
+                return Flow[str].cont()
+        return Flow[str].submit(value)
+
+    def _type_char(self, state: _State, ch: str) -> None:
+        """Types one character if it passes the filter and length limit."""
+        if self._char_filter is not None and not self._char_filter(ch):
+            return
+        if self._max_chars > 0 and len(state.editor) >= self._max_chars:
+            return
+        state.editor.insert_char(ch)
+        state.error = None

sparcli/input/prompt.py

@@ -0,0 +1,134 @@
+"""
+sparcli.input.prompt
+===================
+
+Defines the shared prompt driver: render a frame, read an event, repeat.
+
+:func:`run_prompt` centralizes the event loop so each prompt supplies only a
+render callback and an event handler. The handler returns a :class:`Flow`
+telling the loop what to do next: keep going, submit a value, cancel, fire a
+shortcut, or refresh after an external program drew over the screen. Drawing
+goes through :class:`~sparcli.output.live.InPlace`, so the loop is a no-op for
+non-interactive sources.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import cast
+
+from sparcli.core.render import Rendered
+from sparcli.input.event import EventSource, InputEvent
+from sparcli.input.outcome import Outcome
+from sparcli.output.live import InPlace
+
+
+class FlowKind(enum.Enum):
+    """What a prompt's event handler decides after each event."""
+
+    CONTINUE = enum.auto()
+    SUBMIT = enum.auto()
+    CANCEL = enum.auto()
+    SHORTCUT = enum.auto()
+    REFRESH = enum.auto()
+
+
+@dataclass(frozen=True, slots=True, match_args=False)
+class Flow[T]:
+    """
+    The next step a prompt loop takes after handling an event.
+
+    Attributes
+    ----------
+    kind : FlowKind
+        Which control-flow decision this represents.
+    """
+
+    kind: FlowKind
+    _value: object = None
+    _id: int | None = None
+
+    __match_args__ = ("kind",)
+
+    @classmethod
+    def cont(cls) -> Flow[T]:
+        """Returns a flow that keeps the prompt open and redraws."""
+        return cls(FlowKind.CONTINUE)
+
+    @classmethod
+    def submit(cls, value: T) -> Flow[T]:
+        """Returns a flow that finishes with a submitted value."""
+        return cls(FlowKind.SUBMIT, value)
+
+    @classmethod
+    def cancel(cls) -> Flow[T]:
+        """Returns a flow that finishes as cancelled."""
+        return cls(FlowKind.CANCEL)
+
+    @classmethod
+    def shortcut(cls, shortcut_id: int) -> Flow[T]:
+        """Returns a flow that finishes because a shortcut fired."""
+        return cls(FlowKind.SHORTCUT, None, shortcut_id)
+
+    @classmethod
+    def refresh(cls) -> Flow[T]:
+        """Returns a flow that keeps open but redraws from scratch."""
+        return cls(FlowKind.REFRESH)
+
+    @property
+    def value(self) -> T:
+        """Returns the submitted value; only valid for a submit flow."""
+        return cast("T", self._value)
+
+    @property
+    def shortcut_id(self) -> int | None:
+        """Returns the fired shortcut id, or ``None`` for non-shortcut flows."""
+        return self._id
+
+
+def run_prompt[S, T](
+    source: EventSource,
+    state: S,
+    render: Callable[[S, bool], Rendered],
+    handle: Callable[[S, InputEvent], Flow[T]],
+) -> Outcome[T]:
+    """
+    Runs a prompt loop over ``source``, driving ``render`` and ``handle``.
+
+    Parameters
+    ----------
+    source : EventSource
+        Where events come from; its interactivity selects the draw engine.
+    state : S
+        The prompt state, mutated in place by ``handle``.
+    render : Callable[[S, bool], Rendered]
+        Builds the current frame. Its ``bool`` argument is ``True`` only for
+        the final frame drawn after submission.
+    handle : Callable[[S, InputEvent], Flow[T]]
+        Consumes one event and returns the next :class:`Flow`.
+
+    Returns
+    -------
+    Outcome[T]
+        The submitted value, a cancellation, or a fired shortcut.
+    """
+    inplace = InPlace.create() if source.is_interactive() else InPlace.silent()
+    while True:
+        inplace.draw(render(state, False))
+        flow = handle(state, source.next_event())
+        if flow.kind is FlowKind.CONTINUE:
+            continue
+        if flow.kind is FlowKind.REFRESH:
+            inplace.reset()
+            continue
+        if flow.kind is FlowKind.SUBMIT:
+            inplace.draw(render(state, True))
+            inplace.finish()
+            return Outcome.submitted(flow.value)
+        if flow.kind is FlowKind.SHORTCUT:
+            inplace.finish()
+            return Outcome.shortcut(flow.shortcut_id or 0)
+        inplace.finish()
+        return Outcome.cancelled()

sparcli/input/select.py

@@ -0,0 +1,336 @@
+"""
+sparcli.input.select
+=====================
+
+Defines :class:`Select`, the single- and multi-selection list prompt.
+
+A :class:`Select` shows a scrollable list of options and lets the user move a
+cursor, optionally toggle checkboxes (multi-select) and submit. It follows the
+shared prompt pattern: a kwargs constructor plus fluent builders, a
+:meth:`Select.run` guarded on an interactive terminal, and a
+:meth:`Select.run_with` that drives any :class:`~sparcli.input.event.EventSource`
+for headless tests. Navigation cycles by default and the visible window scrolls
+to keep the cursor on screen.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+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, Span
+from sparcli.core.theme import Theme, theme
+from sparcli.errors import NoTerminalError
+from sparcli.input.event import (
+    EventKind,
+    EventSource,
+    InputEvent,
+    KeyCode,
+    KeyPress,
+    TerminalSource,
+)
+from sparcli.input.guard import TerminalGuard
+from sparcli.input.outcome import Outcome
+from sparcli.input.prompt import Flow, run_prompt
+from sparcli.input.shortcut import Shortcut, find, help_overlay, hint_line
+
+# Default number of visible rows.
+DEFAULT_VISIBLE = 10
+
+# The prompt collects indices, so every flow it produces carries this type.
+_Flow = Flow[list[int]]
+
+# Character keys handled specially by the prompt.
+_VIM_UP = KeyCode.char("k")
+_VIM_DOWN = KeyCode.char("j")
+_SPACE = KeyCode.char(" ")
+_HELP = KeyCode.char("?")
+
+
+class _State:
+    """The mutable state of a running select prompt."""
+
+    __slots__ = ("cursor", "checked", "offset", "show_help")
+
+    def __init__(self, cursor: int, checked: list[bool], offset: int) -> None:
+        self.cursor = cursor
+        self.checked = checked
+        self.offset = offset
+        self.show_help = False
+
+
+class Select:
+    """
+    A scrollable selection list, single- or multi-select.
+
+    Attributes
+    ----------
+    prompt : str
+        The label shown above the list.
+    options : Iterable[str]
+        The selectable rows.
+    multi : bool
+        Whether checkboxes and multi-selection are enabled.
+    max_visible : int
+        The maximum number of rows shown at once.
+    cycle : bool
+        Whether cursor navigation wraps around at the ends.
+    shortcuts : Iterable[Shortcut]
+        Custom shortcuts shown in the footer and the ``?`` help overlay.
+    initial_cursor : int
+        The row highlighted when the prompt opens.
+    initial_checked : Iterable[int]
+        The rows checked when a multi-select prompt opens.
+    """
+
+    __slots__ = (
+        "_prompt",
+        "_options",
+        "_multi",
+        "_max_visible",
+        "_cycle",
+        "_shortcuts",
+        "_initial_cursor",
+        "_initial_checked",
+    )
+
+    def __init__(
+        self,
+        prompt: str,
+        *,
+        options: Iterable[str] = (),
+        multi: bool = False,
+        max_visible: int = DEFAULT_VISIBLE,
+        cycle: bool = True,
+        shortcuts: Iterable[Shortcut] = (),
+        initial_cursor: int = 0,
+        initial_checked: Iterable[int] = (),
+    ) -> None:
+        self._prompt = prompt
+        self._options = list(options)
+        self._multi = multi
+        self._max_visible = max(max_visible, 1)
+        self._cycle = cycle
+        self._shortcuts = list(shortcuts)
+        self._initial_cursor = initial_cursor
+        self._initial_checked = list(initial_checked)
+
+    def options(self, options: Iterable[str]) -> Select:
+        """Sets the selectable rows and returns ``self``."""
+        self._options = list(options)
+        return self
+
+    def multi(self) -> Select:
+        """Enables multi-selection with checkboxes and returns ``self``."""
+        self._multi = True
+        return self
+
+    def max_visible(self, rows: int) -> Select:
+        """Sets the maximum number of visible rows and returns ``self``."""
+        self._max_visible = max(rows, 1)
+        return self
+
+    def no_cycle(self) -> Select:
+        """Disables wrap-around navigation and returns ``self``."""
+        self._cycle = False
+        return self
+
+    def cursor(self, index: int) -> Select:
+        """Sets the initially highlighted row and returns ``self``."""
+        self._initial_cursor = index
+        return self
+
+    def checked(self, indices: Iterable[int]) -> Select:
+        """Sets the initially checked rows and returns ``self``."""
+        self._initial_checked = list(indices)
+        return self
+
+    def shortcuts(self, shortcuts: Iterable[Shortcut]) -> Select:
+        """Registers custom shortcuts and returns ``self``."""
+        self._shortcuts = list(shortcuts)
+        return self
+
+    def run(self) -> Outcome[int]:
+        """
+        Runs a single-select prompt and returns the chosen index.
+
+        Returns
+        -------
+        Outcome[int]
+            The submitted index, a cancellation, or a fired shortcut.
+
+        Raises
+        ------
+        NoTerminalError
+            If standard input or output is not an interactive terminal.
+        """
+        return _first_index(self._run_collect())
+
+    def run_multi(self) -> Outcome[list[int]]:
+        """
+        Runs a multi-select prompt and returns all checked indices.
+
+        Returns
+        -------
+        Outcome[list[int]]
+            The submitted indices, a cancellation, or a fired shortcut.
+
+        Raises
+        ------
+        NoTerminalError
+            If standard input or output is not an interactive terminal.
+        """
+        return self._run_collect()
+
+    def run_with(self, source: EventSource) -> Outcome[list[int]]:
+        """
+        Runs the prompt against ``source`` and returns the checked indices.
+
+        Parameters
+        ----------
+        source : EventSource
+            The event source driving the prompt (a fake in tests).
+
+        Returns
+        -------
+        Outcome[list[int]]
+            The submitted indices, a cancellation, or a fired shortcut.
+        """
+        if not self._options:
+            empty: list[int] = []
+            return Outcome.submitted(empty)
+        state = self._initial_state()
+        return run_prompt(source, state, self._render, self._handle)
+
+    def frame(self) -> Rendered:
+        """Renders the opening frame without running the prompt."""
+        return self._render(self._initial_state(), False)
+
+    def _run_collect(self) -> Outcome[list[int]]:
+        """Sets up the terminal and runs the prompt loop."""
+        if not is_input_tty():
+            raise NoTerminalError
+        with TerminalGuard():
+            return self.run_with(TerminalSource())
+
+    def _initial_state(self) -> _State:
+        """Builds the starting state from the initial cursor and checks."""
+        length = len(self._options)
+        cursor = min(self._initial_cursor, max(length - 1, 0))
+        checked = [False] * length
+        for index in self._initial_checked:
+            if 0 <= index < length:
+                checked[index] = True
+        offset = max(cursor - (self._max_visible - 1), 0)
+        return _State(cursor=cursor, checked=checked, offset=offset)
+
+    def _render(self, state: _State, _final: bool) -> Rendered:
+        """Builds the frame with the visible window of options."""
+        active = theme()
+        if state.show_help:
+            return Rendered(help_overlay(self._shortcuts))
+        lines = [Line.styled(self._prompt, active.title)]
+        end = min(state.offset + self._max_visible, len(self._options))
+        for index in range(state.offset, end):
+            lines.append(self._option_line(state, index, active))
+        if self._shortcuts:
+            lines.append(hint_line(self._shortcuts))
+        return Rendered(lines)
+
+    def _option_line(self, state: _State, index: int, active: Theme) -> Line:
+        """Renders one option row."""
+        is_cursor = index == state.cursor
+        marker = active.cursor_marker() if is_cursor else active.marker()
+        spans = [Span.styled(marker, active.selection)]
+        if self._multi:
+            checkbox = (
+                active.checkbox_on()
+                if state.checked[index]
+                else active.checkbox_off()
+            )
+            spans.append(Span.raw(checkbox))
+        style = active.selection if is_cursor else Style.new()
+        spans.append(Span.styled(self._options[index], style))
+        return Line(spans)
+
+    def _handle(self, state: _State, event: InputEvent) -> _Flow:
+        """Handles one input event."""
+        if event.kind is not EventKind.KEY or event.key is None:
+            return _Flow.cont()
+        return self._handle_key(state, event.key)
+
+    def _handle_key(self, state: _State, key: KeyPress) -> _Flow:
+        """Handles a single key press."""
+        if state.show_help:
+            state.show_help = False
+            return _Flow.cont()
+        if key.code == _HELP and self._shortcuts:
+            state.show_help = True
+            return _Flow.cont()
+        shortcut_id = find(key, self._shortcuts)
+        if shortcut_id is not None:
+            return _Flow.shortcut(shortcut_id)
+        if key.code == KeyCode.ESC:
+            return _Flow.cancel()
+        if key.code == KeyCode.ENTER:
+            return _Flow.submit(self._collect(state))
+        self._navigate(state, key.code)
+        return _Flow.cont()
+
+    def _navigate(self, state: _State, code: KeyCode) -> None:
+        """Applies a navigation or toggle key to the state."""
+        if code in (KeyCode.UP, _VIM_UP):
+            self._move_cursor(state, -1)
+        elif code in (KeyCode.DOWN, _VIM_DOWN):
+            self._move_cursor(state, 1)
+        elif code == KeyCode.HOME:
+            self._set_cursor(state, 0)
+        elif code == KeyCode.END:
+            self._set_cursor(state, len(self._options) - 1)
+        elif code == KeyCode.PAGE_UP:
+            self._move_cursor(state, -self._max_visible)
+        elif code == KeyCode.PAGE_DOWN:
+            self._move_cursor(state, self._max_visible)
+        elif code == _SPACE and self._multi:
+            state.checked[state.cursor] = not state.checked[state.cursor]
+
+    def _collect(self, state: _State) -> list[int]:
+        """Returns the result indices for the current state."""
+        if self._multi:
+            return [
+                index
+                for index in range(len(self._options))
+                if state.checked[index]
+            ]
+        return [state.cursor]
+
+    def _move_cursor(self, state: _State, delta: int) -> None:
+        """Moves the cursor by ``delta``, cycling or clamping per config."""
+        length = len(self._options)
+        if length == 0:
+            return
+        target = state.cursor + delta
+        if self._cycle:
+            target %= length
+        else:
+            target = max(0, min(target, length - 1))
+        self._set_cursor(state, target)
+
+    def _set_cursor(self, state: _State, index: int) -> None:
+        """Sets the cursor and scrolls so it stays visible."""
+        state.cursor = index
+        if index < state.offset:
+            state.offset = index
+        elif index >= state.offset + self._max_visible:
+            state.offset = index + 1 - self._max_visible
+
+
+def _first_index(outcome: Outcome[list[int]]) -> Outcome[int]:
+    """Reduces a collected outcome to its first index (single-select)."""
+    if outcome.is_shortcut:
+        return Outcome.shortcut(outcome.shortcut_id or 0)
+    if outcome.is_submitted and outcome.value:
+        return Outcome.submitted(outcome.value[0])
+    return Outcome.cancelled()