pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cli/primitive.py

@@ -0,0 +1,308 @@
+"""How one command-line string becomes a value (Effect's ``Primitive``).
+
+A ``Primitive[A]`` has a ``tag`` (``"Boolean"``, ``"Int"``, ...) used for
+help and completions, and ``parse``: the effect turning the text into an
+``A`` or failing with a message for the user. Flags and arguments are
+built on them; most programs never touch one directly::
+
+    yield from primitive.integer.parse("42")  # 42
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Generic, Literal, Never, TypeVar
+
+from pyfect import _js_date as js_date
+from pyfect import redacted as redacted_
+from pyfect import schema as S
+from pyfect._json_text import parse as parse_json
+from pyfect._json_text import stringify
+from pyfect.cli._environment import Environment
+from pyfect.effect import Effect, fail, gen, succeed
+from pyfect.encoding import ini, toml, yaml
+from pyfect.file_system import FileSystem
+from pyfect.path import Path
+from pyfect.redacted import Redacted
+from pyfect.schema import Codec
+from pyfect.schema.issue import Issue
+
+A_co = TypeVar("A_co", covariant=True)
+
+type PathType = Literal["file", "directory", "either"]
+type FileFormat = Literal["ini", "json", "toml", "yaml"]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class Primitive(Generic[A_co]):
+    """Parses one string into an ``A``; failures are messages for the user.
+    ``choice_keys`` and ``path_type`` describe choices and paths to help
+    and completions."""
+
+    tag: str
+    parse: Callable[[str], Effect[A_co, str, Environment]]
+    choice_keys: tuple[str, ...] | None = None
+    path_type: PathType | None = None
+
+
+def _schema_primitive[A](tag: str, schema: Codec[A, object, Never, object]) -> Primitive[A]:
+    decode = S.decode_unknown_effect(S.to_codec_string_tree(schema))
+    return Primitive(tag, lambda value: decode(value).map_error(lambda error: error.message))
+
+
+_TRUE_LITERALS = ("true", "yes", "on", "1", "y")
+_FALSE_LITERALS = ("false", "no", "off", "0", "n")
+_BOOLEAN_EXPECTED = "Expected " + " | ".join(
+    stringify(v) for v in (*_TRUE_LITERALS, *_FALSE_LITERALS)
+)
+
+
+def is_true_literal(value: str) -> bool:
+    return value in _TRUE_LITERALS
+
+
+def is_false_literal(value: str) -> bool:
+    return value in _FALSE_LITERALS
+
+
+def _parse_boolean(value: str) -> Effect[bool, str]:
+    if value in _TRUE_LITERALS:
+        return succeed(True)
+    if value in _FALSE_LITERALS:
+        return succeed(False)
+    return fail(_BOOLEAN_EXPECTED)
+
+
+boolean: Primitive[bool] = Primitive("Boolean", _parse_boolean)
+"""``true`` / ``yes`` / ``on`` / ``1`` / ``y`` and ``false`` / ``no`` /
+``off`` / ``0`` / ``n``."""
+
+finite: Primitive[float] = _schema_primitive("Finite", S.Finite)
+"""A finite number, as JavaScript reads one (``1e3``, ``-42.5``)."""
+
+integer: Primitive[int] = _schema_primitive("Int", S.Int)
+"""An integer (``1e3`` is 1000; ``3.14`` is not one)."""
+
+
+def _parse_date(value: str) -> Effect[datetime, str]:
+    parsed = js_date.parse(value)
+    return fail("Expected a valid Date") if parsed is None else succeed(parsed)
+
+
+date_: Primitive[datetime] = Primitive("Date", _parse_date)
+"""An ECMAScript (ISO 8601) date or date-time, as an aware ``datetime``: a
+date alone is midnight UTC and a date-time without an offset is local
+time, as JavaScript's ``Date`` reads them."""
+
+string: Primitive[str] = Primitive("String", succeed)
+
+
+def choice[A](choices: Sequence[tuple[str, A]]) -> Primitive[A]:
+    """One of the keys, giving its value; otherwise fails with the keys."""
+    mapping = dict(choices)
+    valid = " | ".join(stringify(key) for key, _ in choices)
+
+    def parse(value: str) -> Effect[A, str]:
+        if value in mapping:
+            return succeed(mapping[value])
+        return fail(valid)
+
+    return Primitive("Choice", parse, choice_keys=tuple(key for key, _ in choices))
+
+
+def _absolute(path: str):
+    paths = yield from Path()
+    return path if paths.is_absolute(path) else paths.resolve(path)
+
+
+def path(path_type: PathType, must_exist: bool = False) -> Primitive[str]:
+    """A path, resolved to an absolute one. With ``must_exist`` it must
+    exist; an existing path must be of ``path_type``."""
+
+    def parse(value: str) -> Effect[str, str, Environment]:
+        def body():
+            fs = yield from FileSystem()
+            absolute = yield from _absolute(value)
+            exists = yield from fs.exists(absolute).map_error(
+                lambda e: f"Failed to check path existence: {e.message}"
+            )
+            if must_exist and not exists:
+                return (yield from fail(f"Path does not exist: {absolute}"))
+            if exists and path_type != "either":
+                info = yield from fs.stat(absolute).map_error(
+                    lambda e: f"Failed to stat path: {e.message}"
+                )
+                if path_type == "file" and info.type != "File":
+                    return (yield from fail(f"Path is not a file: {absolute}"))
+                if path_type == "directory" and info.type != "Directory":
+                    return (yield from fail(f"Path is not a directory: {absolute}"))
+            return absolute
+
+        return gen(body)
+
+    return Primitive("Path", parse, path_type=path_type)
+
+
+redacted: Primitive[Redacted[str]] = Primitive(
+    "Redacted", lambda value: succeed(redacted_.make(value))
+)
+"""The text, wrapped so it never shows in logs or output."""
+
+
+def _read_file_text(file_path: str) -> Effect[str, str, Environment]:
+    def body():
+        fs = yield from FileSystem()
+        absolute = yield from _absolute(file_path)
+        exists = yield from fs.exists(absolute).map_error(
+            lambda e: f"Failed to check file existence: {e.message}"
+        )
+        if not exists:
+            return (yield from fail(f"File does not exist: {absolute}"))
+        info = yield from fs.stat(absolute).map_error(lambda e: f"Failed to stat file: {e.message}")
+        if info.type != "File":
+            return (yield from fail(f"Path is not a file: {absolute}"))
+        return (
+            yield from fs.read_file_string(absolute).map_error(
+                lambda e: f"Failed to read file: {e.message}"
+            )
+        )
+
+    return gen(body)
+
+
+file_text: Primitive[str] = Primitive("FileText", _read_file_text)
+"""The contents of the file at the path."""
+
+
+def _js_error_text(error: Exception) -> str:
+    """JavaScript's ``${error}``: what the parsers raise as ``ValueError``,
+    Effect's throw as ``SyntaxError``."""
+    name = "SyntaxError" if type(error) is ValueError else type(error).__name__
+    return f"{name}: {error}"
+
+
+_FILE_PARSERS: dict[str, Callable[[str], object]] = {
+    "ini": ini.parse,
+    "json": parse_json,
+    "toml": toml.parse,
+    "yml": yaml.parse,
+    "yaml": yaml.parse,
+}
+
+
+def file_parse(format: FileFormat | None = None) -> Primitive[object]:
+    """The parsed contents of the file at the path: INI, JSON, TOML or YAML,
+    by ``format`` or else the file's extension (``.yml`` is YAML too)."""
+
+    def parse(file_path: str) -> Effect[object, str, Environment]:
+        def body():
+            file_format = format or file_path.rsplit(".", 1)[-1]
+            parser = _FILE_PARSERS.get(file_format)
+            if parser is None:
+                return (yield from fail(f"Unsupported file format: {file_format}"))
+            content = yield from _read_file_text(file_path)
+            try:
+                return parser(content)
+            except Exception as error:
+                return (
+                    yield from fail(
+                        f"Failed to parse '.{file_format}' file content: {_js_error_text(error)}"
+                    )
+                )
+
+        return gen(body)
+
+    return Primitive("FileParse", parse)
+
+
+def file_schema[A](
+    schema: Codec[A, object, Environment, object],
+    *,
+    format: FileFormat | None = None,
+    error_formatter: Callable[[Issue], str] | None = None,
+) -> Primitive[A]:
+    """The file's parsed contents (as ``file_parse``) decoded by ``schema``;
+    a decoding failure is ``error_formatter(issue)`` or the schema error's
+    message."""
+    decode = S.decode_unknown_effect(schema)
+    parse_file = file_parse(format).parse
+
+    def parse(file_path: str) -> Effect[A, str, Environment]:
+        def body():
+            content = yield from parse_file(file_path)
+            return (
+                yield from decode(content).map_error(
+                    lambda error: error_formatter(error.issue) if error_formatter else error.message
+                )
+            )
+
+        return gen(body)
+
+    return Primitive("FileSchema", parse)
+
+
+def _parse_key_value(value: str) -> Effect[dict[str, str], str]:
+    key, separator, val = value.partition("=")
+    if not separator:
+        return fail(f"Invalid key=value format. Expected format: key=value, got: {value}")
+    if not key or not val:
+        return fail(f"Invalid key=value format. Both key and value must be non-empty. Got: {value}")
+    return succeed({key: val})
+
+
+key_value_pair: Primitive[dict[str, str]] = Primitive("KeyValuePair", _parse_key_value)
+"""``key=value`` (the value may hold more ``=``), as a one-entry dict."""
+
+never: Primitive[Never] = Primitive("Never", lambda _: fail("This option does not accept values"))
+"""Accepts nothing."""
+
+_TYPE_NAMES = {
+    "Boolean": "boolean",
+    "String": "string",
+    "Int": "integer",
+    "Finite": "number",
+    "Date": "date",
+    "Path": "path",
+    "Choice": "choice",
+    "Redacted": "string",
+    "FileText": "file",
+    "FileParse": "file",
+    "FileSchema": "file",
+    "KeyValuePair": "key=value",
+    "Never": "none",
+}
+
+
+def type_name(primitive: Primitive[Any]) -> str:
+    """The name help shows for the primitive's values."""
+    return _TYPE_NAMES.get(primitive.tag, "value")
+
+
+def is_boolean(primitive: Primitive[Any]) -> bool:
+    return primitive.tag == "Boolean"
+
+
+__all__ = [
+    "FileFormat",
+    "PathType",
+    "Primitive",
+    "boolean",
+    "choice",
+    "date_",
+    "file_parse",
+    "file_schema",
+    "file_text",
+    "finite",
+    "integer",
+    "is_boolean",
+    "is_false_literal",
+    "is_true_literal",
+    "key_value_pair",
+    "never",
+    "path",
+    "redacted",
+    "string",
+    "type_name",
+]

pyfect/cli/prompt/__init__.py

@@ -0,0 +1,75 @@
+"""Interactive prompts on the ``Terminal`` service (Effect's ``Prompt``).
+
+A prompt is an effect: ``yield from prompt`` (or ``run(prompt)``) asks it.
+Prompts combine with ``map``, ``flat_map`` and ``all``; ``custom`` builds
+new ones from render / process / clear handlers. Styling comes from the
+``PromptTheme`` reference, overridable per prompt with ``theme=``.
+"""
+
+from pyfect.cli.prompt._auto_complete import auto_complete
+from pyfect.cli.prompt._choices import Choice
+from pyfect.cli.prompt._confirm import confirm, toggle
+from pyfect.cli.prompt._core import (
+    Action,
+    Beep,
+    Event,
+    Handlers,
+    Input,
+    NextFrame,
+    ProcessInput,
+    Prompt,
+    PromptEnvironment,
+    PromptTheme,
+    Submit,
+    Theme,
+    ThemeOptions,
+    all,
+    custom,
+    make_theme,
+    run,
+)
+from pyfect.cli.prompt._core import prompt_succeed as succeed
+from pyfect.cli.prompt._date import date
+from pyfect.cli.prompt._date_parts import Locales
+from pyfect.cli.prompt._file import FileType, file
+from pyfect.cli.prompt._multi_select import multi_select
+from pyfect.cli.prompt._number import integer, number
+from pyfect.cli.prompt._select import select
+from pyfect.cli.prompt._text import hidden, list_, password, string
+
+__all__ = [
+    "Action",
+    "Beep",
+    "Choice",
+    "Event",
+    "FileType",
+    "Handlers",
+    "Input",
+    "Locales",
+    "NextFrame",
+    "ProcessInput",
+    "Prompt",
+    "PromptEnvironment",
+    "PromptTheme",
+    "Submit",
+    "Theme",
+    "ThemeOptions",
+    "all",
+    "auto_complete",
+    "confirm",
+    "custom",
+    "date",
+    "file",
+    "hidden",
+    "integer",
+    "list_",
+    "make_theme",
+    "multi_select",
+    "number",
+    "password",
+    "run",
+    "select",
+    "string",
+    "succeed",
+    "toggle",
+]

pyfect/cli/prompt/_auto_complete.py

@@ -0,0 +1,205 @@
+"""``auto_complete``: ``select`` with a filter typed above the list."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+
+from pyfect.cli import _ansi as ansi
+from pyfect.cli.prompt._choices import Choice, initial_index, paging, render_row, render_submitted
+from pyfect.cli.prompt._core import (
+    Action,
+    Beep,
+    Handlers,
+    NextFrame,
+    Prompt,
+    Submit,
+    Theme,
+    ThemeOptions,
+    active_symbols,
+    custom,
+    entries_to_display,
+    erase_text,
+    get_theme,
+    render_prompt,
+    reset_current_line,
+    submitted_symbols,
+    terminal_columns,
+)
+from pyfect.effect import Effect, gen, succeed
+from pyfect.terminal import UserInput
+
+
+@dataclass(frozen=True, slots=True)
+class _State:
+    query: str
+    index: int
+    filtered: tuple[int, ...]
+
+    @property
+    def cursor(self) -> int:
+        return self.filtered.index(self.index) if self.index in self.filtered else 0
+
+
+def _filter(choices: Sequence[Choice[Any]], query: str) -> tuple[int, ...]:
+    needle = query.lower()
+    return tuple(i for i, choice in enumerate(choices) if needle in choice.title.lower())
+
+
+@dataclass(frozen=True, slots=True)
+class _AutoComplete[A]:
+    message: str
+    choices: tuple[Choice[A], ...]
+    max_per_page: int
+    filter_label: str
+    filter_placeholder: str
+    empty_message: str
+    theme: ThemeOptions | None
+
+    def initial(self) -> _State:
+        start = initial_index(self.choices)
+        filtered = _filter(self.choices, "")
+        index = 0 if not filtered else start if start in filtered else filtered[0]
+        return _State("", index, filtered)
+
+    def _update(self, state: _State, query: str) -> _State:
+        matches = _filter(self.choices, query)
+        if not matches:
+            return _State(query, 0, matches)
+        index = state.index if state.index in matches else matches[0]
+        return _State(query, index, matches)
+
+    def _filter_text(self, state: _State, figures: Theme, plain: bool) -> str:
+        if not state.query:
+            placeholder = self.filter_placeholder
+            value = (
+                placeholder
+                if plain
+                else ansi.annotate(figures.colors, placeholder, figures.muted_color)
+            )
+        elif plain:
+            value = state.query
+        else:
+            value = ansi.annotate(
+                figures.colors, state.query, ansi.underlined, figures.primary_color
+            )
+        return f"[{self.filter_label}: {value}]"
+
+    def _output(
+        self, state: _State, leading: str, trailing: str, figures: Theme, plain: bool
+    ) -> str:
+        text = self._filter_text(state, figures, plain)
+        return render_prompt(text, self.message, leading, trailing, figures, plain=plain)
+
+    def _rows(self, state: _State, figures: Theme, plain: bool) -> str:
+        if not state.filtered:
+            empty = self.empty_message
+            return empty if plain else ansi.annotate(figures.colors, empty, figures.muted_color)
+        total = len(state.filtered)
+        window = entries_to_display(state.cursor, total, self.max_per_page)
+        rows: list[str] = []
+        for position in range(window.start, window.end):
+            index = state.filtered[position]
+            prefix = paging(figures, window, position, total)
+            rows.append(
+                render_row(figures, self.choices[index], state.index == index, prefix, plain)
+            )
+        return "\n".join(rows)
+
+    def render(self, state: _State, action: Action[_State, A]) -> Effect[str]:
+        def body():
+            figures = yield from get_theme(self.theme)
+            match action:
+                case Beep():
+                    return ansi.beep
+                case NextFrame():
+                    next_state = action.state
+                    output = self._output(next_state, *active_symbols(figures), figures, False)
+                    return ansi.cursor_hide + output + "\n" + self._rows(next_state, figures, False)
+                case Submit():
+                    output = self._output(state, *submitted_symbols(figures), figures, False)
+                    return render_submitted(figures, output, self.choices[state.index].title)
+
+        return gen(body)
+
+    def _move(self, state: _State, step: int) -> Effect[Action[_State, A]]:
+        if not state.filtered:
+            return succeed(Beep())
+        position = (state.cursor + step) % len(state.filtered)
+        return succeed(NextFrame(replace(state, index=state.filtered[position])))
+
+    def _submit(self, state: _State) -> Effect[Action[_State, A]]:
+        if not state.filtered:
+            return succeed(Beep())
+        chosen = self.choices[state.index]
+        return succeed(Beep() if chosen.disabled else Submit(chosen.value))
+
+    def _ctrl(self, input: UserInput, state: _State) -> Effect[Action[_State, A]]:
+        match input.key.name:
+            case "u":
+                return succeed(NextFrame(self._update(state, "")))
+            case "p" | "k":
+                return self._move(state, -1)
+            case "n":
+                return self._move(state, 1)
+            case _:
+                return succeed(Beep())
+
+    def process(  # noqa: PLR0911 - one return per key
+        self, input: UserInput, state: _State
+    ) -> Effect[Action[_State, A]]:
+        if input.key.ctrl:
+            return self._ctrl(input, state)
+        match input.key.name:
+            case "up":
+                return self._move(state, -1)
+            case "down" | "tab":
+                return self._move(state, 1)
+            case "backspace":
+                if not state.query:
+                    return succeed(Beep())
+                return succeed(NextFrame(self._update(state, state.query[:-1])))
+            case "enter" | "return":
+                return self._submit(state)
+            case _:
+                text = input.input or ""
+                if not text:
+                    return succeed(Beep())
+                return succeed(NextFrame(self._update(state, state.query + text)))
+
+    def clear(self, state: _State, action: Action[_State, A]):
+        def body():
+            columns = yield from terminal_columns()
+            figures = yield from get_theme(self.theme)
+            output = self._output(state, figures.prefix, figures.pointer_small, figures, True)
+            text = f"{output}\n{self._rows(state, figures, True)}"
+            return erase_text(text, columns) + reset_current_line()
+
+        return gen(body)
+
+
+def auto_complete[A](
+    message: str,
+    choices: Sequence[Choice[A]],
+    *,
+    max_per_page: int = 10,
+    filter_label: str = "filter",
+    filter_placeholder: str = "type to filter",
+    empty_message: str = "No matches",
+    theme: ThemeOptions | None = None,
+) -> Prompt[A]:
+    """``select`` with a filter: typing narrows the list to titles
+    containing the text (case-insensitively); Ctrl+N / Ctrl+P / Ctrl+K and
+    the arrows move, Ctrl+U clears the filter."""
+    handlers = _AutoComplete(
+        message,
+        tuple(choices),
+        max_per_page,
+        filter_label,
+        filter_placeholder,
+        empty_message,
+        theme,
+    )
+    initial = handlers.initial()
+    return custom(initial, Handlers(handlers.render, handlers.process, handlers.clear))

pyfect/cli/prompt/_choices.py

@@ -0,0 +1,104 @@
+"""What ``select``, ``auto_complete`` and ``multi_select`` share: the
+``Choice`` type and how a row of the list is drawn."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from pyfect.cli import _ansi as ansi
+from pyfect.cli.prompt._core import (
+    Theme,
+    Window,
+    annotate_symbol,
+    render_paging_prefix,
+    render_prompt,
+    submitted_symbols,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Choice[A]:
+    """One option: its ``title``, the ``value`` it gives, an optional
+    ``description`` shown while it is highlighted, whether it is
+    ``disabled``, and whether it starts ``selected``."""
+
+    title: str
+    value: A
+    description: str | None = None
+    disabled: bool = False
+    selected: bool = False
+
+
+def initial_index(choices: Sequence[Choice[Any]]) -> int:
+    """The choice marked ``selected`` (the first without one); at most one
+    may be marked."""
+    selected = [i for i, choice in enumerate(choices) if choice.selected]
+    if len(selected) > 1:
+        raise ValueError(
+            "InvalidArgumentException: only a single choice can be selected by default "
+            "for Prompt.Select"
+        )
+    return selected[0] if selected else 0
+
+
+def render_header(
+    leading: str, trailing: str, message: str | None, theme: Theme, *, plain: bool = False
+) -> str | None:
+    if message is None:
+        return None
+    return render_prompt("", message, leading, trailing, theme, plain=plain)
+
+
+def with_header(header: str | None, body: str) -> str:
+    return body if header is None else header + "\n" + body
+
+
+def render_description(choice: Choice[Any], active: bool, theme: Theme, plain: bool) -> str:
+    if not choice.disabled and choice.description and active:
+        text = theme.description_separator + choice.description
+        return text if plain else ansi.annotate(theme.colors, text, theme.muted_color)
+    return ""
+
+
+def render_title(choice: Choice[Any], active: bool, theme: Theme, plain: bool) -> str:
+    if plain:
+        return choice.title
+    if active:
+        color = theme.muted_color if choice.disabled else theme.primary_color
+        return ansi.annotate(theme.colors, choice.title, ansi.underlined, color)
+    if choice.disabled:
+        return ansi.annotate(theme.colors, choice.title, ansi.strikethrough, theme.muted_color)
+    return choice.title
+
+
+def render_pointer(theme: Theme, active: bool, disabled: bool, prefix: str, plain: bool) -> str:
+    if not active:
+        return prefix + " " * len(theme.pointer)
+    if plain:
+        return theme.pointer + prefix
+    if disabled:
+        return annotate_symbol(theme, theme.pointer, ansi.bold, theme.muted_color) + prefix
+    return annotate_symbol(theme, theme.pointer, theme.primary_color) + prefix
+
+
+def paging(theme: Theme, window: Window, index: int, total: int) -> str:
+    return render_paging_prefix(
+        theme,
+        index == window.start and window.start > 0,
+        index == window.end - 1 and window.end < total,
+    )
+
+
+def render_row(theme: Theme, choice: Choice[Any], active: bool, prefix: str, plain: bool) -> str:
+    pointer = render_pointer(theme, active, choice.disabled, prefix, plain)
+    title = render_title(choice, active, theme, plain)
+    return pointer + title + " " + render_description(choice, active, theme, plain)
+
+
+def render_submitted(theme: Theme, header: str | None, text: str) -> str:
+    """The answered prompt: the header (or the tick alone) and ``text``."""
+    leading, _ = submitted_symbols(theme)
+    shown = ansi.annotate(theme.colors, text, theme.submitted_color)
+    return (leading if header is None else header) + " " + shown + "\n"