py-sparcli 0.3.0__py3-none-any.whl

sparcli/input/__init__.py

@@ -0,0 +1,42 @@
+"""
+sparcli.input
+============
+
+Interactive single-input prompts driven by an :class:`EventSource`.
+
+Every prompt exposes ``run()`` (real terminal), ``run_with(source)`` (the
+dependency-injection seam used by tests) and ``frame()`` (a static preview).
+Prompts return an :class:`~sparcli.input.outcome.Outcome`. This package
+re-exports the prompt classes and the command :class:`History`; the grouped
+helpers stay reachable as the ``event``, ``validate`` and ``shortcut``
+submodules.
+"""
+
+from sparcli.input.confirm import Confirm
+from sparcli.input.datepicker import DatePicker
+from sparcli.input.editor import edit_file
+from sparcli.input.fuzzy import FuzzySelect
+from sparcli.input.history import History
+from sparcli.input.number import NumberInput
+from sparcli.input.outcome import Outcome, OutcomeKind
+from sparcli.input.password import PasswordInput
+from sparcli.input.select import Select
+from sparcli.input.shortcut import Shortcut
+from sparcli.input.text import TextInput
+from sparcli.input.textarea import Textarea
+
+__all__ = [
+    "Confirm",
+    "DatePicker",
+    "FuzzySelect",
+    "History",
+    "NumberInput",
+    "Outcome",
+    "OutcomeKind",
+    "PasswordInput",
+    "Select",
+    "Shortcut",
+    "TextInput",
+    "Textarea",
+    "edit_file",
+]

sparcli/input/calc.py

@@ -0,0 +1,214 @@
+"""
+sparcli.input.calc
+==================
+
+Defines the calculator-mode expression evaluator behind ``NumberInput``.
+
+:func:`evaluate` is a small recursive-descent parser for the four arithmetic
+operators, parentheses and unary minus, with the usual precedence.
+:func:`parse_number` reads a single number for the plain (non-calculator)
+submit path. Both accept ``,`` or ``.`` as the decimal separator and report
+failures through :class:`CalcError`, whose message becomes the prompt's error
+line. This module is an implementation detail, not part of the public API.
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class CalcErrorKind(enum.Enum):
+    """The reason a numeric expression could not be evaluated."""
+
+    NOT_A_NUMBER = "not a number"
+    INVALID_NUMBER = "invalid number"
+    DIVISION_BY_ZERO = "division by zero"
+    MISSING_PARENTHESIS = "missing closing parenthesis"
+    TRAILING_INPUT = "unexpected trailing input"
+
+
+class CalcError(Exception):
+    """
+    Raised when parsing or evaluating a numeric expression fails.
+
+    Attributes
+    ----------
+    kind : CalcErrorKind
+        Which failure occurred; its value is the human-readable message.
+    """
+
+    def __init__(self, kind: CalcErrorKind) -> None:
+        super().__init__(kind.value)
+        self.kind = kind
+
+
+def parse_number(text: str) -> float:
+    """
+    Parses a single number, accepting ``,`` or ``.`` as the separator.
+
+    Parameters
+    ----------
+    text : str
+        The raw field text; surrounding whitespace is ignored.
+
+    Returns
+    -------
+    float
+        The parsed value.
+
+    Raises
+    ------
+    CalcError
+        With :attr:`CalcErrorKind.NOT_A_NUMBER` if ``text`` is empty or not a
+        valid number.
+
+    Examples
+    --------
+    >>> parse_number("3,5")
+    3.5
+    """
+    normalized = text.strip().replace(",", ".")
+    if not normalized:
+        raise CalcError(CalcErrorKind.NOT_A_NUMBER)
+    try:
+        return float(normalized)
+    except ValueError:
+        raise CalcError(CalcErrorKind.NOT_A_NUMBER) from None
+
+
+def evaluate(expr: str) -> float:
+    """
+    Evaluates an arithmetic expression with ``+ - * / ( )``.
+
+    Accepts ``,`` or ``.`` as the decimal separator and honours the usual
+    operator precedence and unary minus.
+
+    Parameters
+    ----------
+    expr : str
+        The expression to evaluate.
+
+    Returns
+    -------
+    float
+        The value of the expression.
+
+    Raises
+    ------
+    CalcError
+        On malformed input or division by zero.
+
+    Examples
+    --------
+    >>> evaluate("2 + 3 * 4")
+    14.0
+    >>> evaluate("(2 + 3) * 4")
+    20.0
+    """
+    parser = _Parser(expr.replace(",", "."))
+    value = parser.expression()
+    parser.skip_spaces()
+    if not parser.at_end():
+        raise CalcError(CalcErrorKind.TRAILING_INPUT)
+    return value
+
+
+class _Parser:
+    """A minimal recursive-descent arithmetic parser over a character list."""
+
+    __slots__ = ("_chars", "_pos")
+
+    def __init__(self, text: str) -> None:
+        self._chars: list[str] = list(text)
+        self._pos: int = 0
+
+    def expression(self) -> float:
+        """Parses ``term (('+'|'-') term)*``."""
+        value = self.term()
+        while True:
+            self.skip_spaces()
+            operator = self._peek()
+            if operator == "+":
+                self._pos += 1
+                value += self.term()
+            elif operator == "-":
+                self._pos += 1
+                value -= self.term()
+            else:
+                return value
+
+    def term(self) -> float:
+        """Parses ``factor (('*'|'/') factor)*``."""
+        value = self.factor()
+        while True:
+            self.skip_spaces()
+            operator = self._peek()
+            if operator == "*":
+                self._pos += 1
+                value *= self.factor()
+            elif operator == "/":
+                self._pos += 1
+                value = self._divide(value)
+            else:
+                return value
+
+    def factor(self) -> float:
+        """Parses a number, a parenthesized expression or a unary minus."""
+        self.skip_spaces()
+        char = self._peek()
+        if char == "(":
+            return self._grouped()
+        if char == "-":
+            self._pos += 1
+            return -self.factor()
+        return self._number()
+
+    def skip_spaces(self) -> None:
+        """Advances past any run of spaces."""
+        while self._peek() == " ":
+            self._pos += 1
+
+    def at_end(self) -> bool:
+        """Returns whether the whole input has been consumed."""
+        return self._pos >= len(self._chars)
+
+    def _divide(self, value: float) -> float:
+        """Consumes the divisor factor and divides, guarding against zero."""
+        divisor = self.factor()
+        if divisor == 0.0:
+            raise CalcError(CalcErrorKind.DIVISION_BY_ZERO)
+        return value / divisor
+
+    def _grouped(self) -> float:
+        """Parses a parenthesized subexpression, requiring a closing ``)``."""
+        self._pos += 1
+        value = self.expression()
+        self.skip_spaces()
+        if self._peek() != ")":
+            raise CalcError(CalcErrorKind.MISSING_PARENTHESIS)
+        self._pos += 1
+        return value
+
+    def _number(self) -> float:
+        """Parses a decimal number literal (digits and a decimal point)."""
+        start = self._pos
+        while _is_number_char(self._peek()):
+            self._pos += 1
+        text = "".join(self._chars[start : self._pos])
+        try:
+            return float(text)
+        except ValueError:
+            raise CalcError(CalcErrorKind.INVALID_NUMBER) from None
+
+    def _peek(self) -> str | None:
+        """Returns the current character without consuming it."""
+        if self._pos >= len(self._chars):
+            return None
+        return self._chars[self._pos]
+
+
+def _is_number_char(char: str | None) -> bool:
+    """Returns whether ``char`` may appear inside a number literal."""
+    return char is not None and (
+        char.isascii() and char.isdigit() or char == "."
+    )

sparcli/input/confirm.py

@@ -0,0 +1,188 @@
+"""
+sparcli.input.confirm
+=====================
+
+Defines :class:`Confirm`, a yes/no confirmation prompt.
+
+The prompt shows two options; the selected one is highlighted and the other is
+dimmed. ``y``/``n`` answer directly, Enter accepts the current selection, and
+the arrows, Tab, ``h`` or ``l`` toggle it. Registered
+:class:`~sparcli.input.shortcut.Shortcut` keys end the prompt with a shortcut
+outcome and appear in a footer hint and the ``?`` help overlay.
+"""
+
+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
+
+# Keys that toggle the current selection.
+_TOGGLE_CODES = frozenset(
+    {
+        KeyCode.LEFT,
+        KeyCode.RIGHT,
+        KeyCode.TAB,
+        KeyCode.char("h"),
+        KeyCode.char("l"),
+    }
+)
+
+
+class _State:
+    """The mutable state of a running confirm prompt."""
+
+    __slots__ = ("yes", "help")
+
+    def __init__(self, yes: bool) -> None:
+        self.yes = yes
+        self.help = False
+
+
+class Confirm:
+    """A yes/no confirmation prompt with custom labels and shortcuts."""
+
+    __slots__ = (
+        "_question",
+        "_default_yes",
+        "_yes_label",
+        "_no_label",
+        "_shortcuts",
+    )
+
+    def __init__(
+        self,
+        question: str = "",
+        *,
+        default_yes: bool = False,
+        yes_label: str = "Yes",
+        no_label: str = "No",
+        shortcuts: Iterable[Shortcut] | None = None,
+    ) -> None:
+        self._question = question
+        self._default_yes = default_yes
+        self._yes_label = yes_label
+        self._no_label = no_label
+        self._shortcuts: list[Shortcut] = (
+            list(shortcuts) if shortcuts is not None else []
+        )
+
+    def shortcuts(self, shortcuts: Iterable[Shortcut]) -> Confirm:
+        """Registers footer/overlay shortcuts and returns ``self``."""
+        self._shortcuts = list(shortcuts)
+        return self
+
+    def default_yes(self) -> Confirm:
+        """Sets the initial selection to "Yes" and returns ``self``."""
+        self._default_yes = True
+        return self
+
+    def labels(self, yes: str, no: str) -> Confirm:
+        """Sets custom labels for the two options and returns ``self``."""
+        self._yes_label = yes
+        self._no_label = no
+        return self
+
+    def run(self) -> Outcome[bool]:
+        """
+        Runs the prompt on the real terminal.
+
+        Returns
+        -------
+        Outcome[bool]
+            The chosen answer, a cancellation or a fired shortcut.
+
+        Raises
+        ------
+        NoTerminalError
+            If 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[bool]:
+        """Runs the prompt against any event source (used for tests)."""
+        state = _State(self._default_yes)
+        return run_prompt(source, state, self._render, self._handle)
+
+    def frame(self) -> Rendered:
+        """Renders the prompt's static frame without running it."""
+        state = _State(self._default_yes)
+        return self._render(state, False)
+
+    def _render(self, state: _State, final: bool) -> Rendered:
+        """Builds the prompt frame for the current selection."""
+        active = theme()
+        if state.help:
+            return Rendered(help_overlay(self._shortcuts))
+        spans = [
+            Span.raw(f"{self._question} "),
+            _option_span(self._yes_label, state.yes, active),
+            Span.raw(" "),
+            _option_span(self._no_label, not state.yes, active),
+        ]
+        lines = [Line(spans)]
+        if self._shortcuts:
+            lines.append(hint_line(self._shortcuts))
+        return Rendered(lines)
+
+    def _handle(self, state: _State, event: InputEvent) -> Flow[bool]:
+        """Handles one input event."""
+        if event.kind is not EventKind.KEY or event.key is None:
+            return Flow[bool].cont()
+        return self._handle_key(state, event.key)
+
+    def _handle_key(self, state: _State, key: KeyPress) -> Flow[bool]:
+        """Handles a single key press."""
+        if state.help:
+            state.help = False
+            return Flow[bool].cont()
+        if key.is_ctrl("c"):
+            return Flow[bool].cancel()
+        if key.code == KeyCode.char("?") and self._shortcuts:
+            state.help = True
+            return Flow[bool].cont()
+        fired = find(key, self._shortcuts)
+        if fired is not None:
+            return Flow[bool].shortcut(fired)
+        return self._decide(state, key.code)
+
+    def _decide(self, state: _State, code: KeyCode) -> Flow[bool]:
+        """Applies a selection, submission or cancellation key."""
+        if code == KeyCode.ESC:
+            return Flow[bool].cancel()
+        if code == KeyCode.ENTER:
+            return Flow[bool].submit(state.yes)
+        if code in (KeyCode.char("y"), KeyCode.char("Y")):
+            return Flow[bool].submit(True)
+        if code in (KeyCode.char("n"), KeyCode.char("N")):
+            return Flow[bool].submit(False)
+        if code in _TOGGLE_CODES:
+            state.yes = not state.yes
+        return Flow[bool].cont()
+
+
+def _option_span(label: str, selected: bool, active: Theme) -> Span:
+    """Renders one option, highlighted when selected and dimmed otherwise."""
+    if selected:
+        return Span.styled(f"[{label}]", active.selection)
+    return Span.styled(f" {label} ", Style.new().dim())