simplibs-cli 0.1.0__py3-none-any.whl

simplibs/cli/__init__.py

@@ -0,0 +1,87 @@
+from .interaction import is_interactive, require_interactive
+from .prompts import (
+    prompt_choice,
+    prompt_confirm,
+    prompt_int,
+    prompt_multi_choice,
+    prompt_path,
+    prompt_secret,
+    prompt_text,
+    resolve_or_prompt,
+)
+from .reporting import print_choices, report_failures
+from .verbosity import resolve_verbosity
+
+__all__ = [
+    # prompts — ask a person
+    "prompt_text",
+    "prompt_int",
+    "prompt_secret",
+    "prompt_confirm",
+    "prompt_choice",
+    "prompt_multi_choice",
+    "prompt_path",
+    "resolve_or_prompt",
+    # interaction — is there a person to ask
+    "is_interactive",
+    "require_interactive",
+    # reporting — say something that is not a question
+    "print_choices",
+    "report_failures",
+    # verbosity — flags to a level
+    "resolve_verbosity",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs-cli — Package Root
+
+## Purpose
+The small, repeatable parts of a command-line program that talks to a person:
+questions that ask again until the answer is usable, the check whether anyone
+can answer, a clear list of options, a summary of what failed, and the
+translation of `--quiet` / `-v` into a logging level.
+
+    from simplibs.cli import prompt_confirm, prompt_path, resolve_or_prompt
+
+## What the Root Exports
+Every function, from one import line. The package has no classes, rules or
+actions: a prompt is an interaction, not a step of a data pipeline, so there
+would be nothing for an `Action` to do.
+
+## What It Does Not Do
+* **Parse arguments.** `argparse`, `click` and `typer` do it well; this
+  library starts where they hand over the values (`resolve_or_prompt`).
+* **Configure logging.** `resolve_verbosity` returns a level, and the logging
+  library applies it.
+
+## Layers
+`interaction`, `reporting` and `verbosity` stand alone; `prompts` uses
+`reporting`. Every layer imports only from those before it.
+
+## Dependencies
+`simplibs-exception` (cards), `simplibs-validate` (`validate_call`),
+`simplibs-path` (`prompt_path`), `simplibs-style` (colors that disappear
+outside a terminal) and `simplibs-rules` (the message of a refusing `Rule`).
+
+## `__all__`
+Defined here only; the sub-packages export by plain imports.
+
+## Internal Components Registry (Root Exports)
+
+| Component             | Type     | Description                                                          |
+| :-------------------- | :------- | :------------------------------------------------------------------- |
+| `prompt_text`         | Function | A line of text, optionally checked by a rule.                        |
+| `prompt_int`          | Function | A whole number, optionally within limits.                            |
+| `prompt_secret`       | Function | A line typed without being shown.                                    |
+| `prompt_confirm`      | Function | A yes/no question.                                                   |
+| `prompt_choice`       | Function | One key from a described set of options.                             |
+| `prompt_multi_choice` | Function | One or more comma-separated keys from a described set.               |
+| `prompt_path`         | Function | A normalized path of a given kind, existing or created.              |
+| `resolve_or_prompt`   | Function | Uses a command-line value, asks only when it is missing or refused.  |
+| `is_interactive`      | Function | True when both input and output are a terminal.                      |
+| `require_interactive` | Function | Raises when there is nobody to ask.                                  |
+| `print_choices`       | Function | Prints an aligned `key - description` list.                          |
+| `report_failures`     | Function | Prints the failed items of a batch, returns whether all succeeded.   |
+| `resolve_verbosity`   | Function | Resolves `--quiet` / `-v` / `-vv` into a logging level.              |
+"""

simplibs/cli/interaction/__init__.py

@@ -0,0 +1,21 @@
+from .is_interactive import is_interactive
+from .require_interactive import require_interactive
+
+
+_DESIGN_NOTES = """
+# CLI Interaction Sub-Package
+
+## Purpose
+Answers one question before a program asks anything: is there somebody to
+ask? A prompt on a redirected input waits forever or fails far from its cause,
+so the check is a function of its own that the caller can use first.
+
+## Internal Components Registry
+
+| Component             | Type     | Description                                                         |
+| :-------------------- | :------- | :------------------------------------------------------------------ |
+| `is_interactive`      | Function | True when both input and output are a terminal.                     |
+| `require_interactive` | Function | Raises `StateError` when `is_interactive()` is False.               |
+| `_helpers`            | Package  | `is_terminal` — one stream asked whether it is a terminal.          |
+| `_validations`        | Package  | `raise_not_interactive_error`.                                      |
+"""

simplibs/cli/interaction/_helpers/__init__.py

@@ -0,0 +1,15 @@
+from .is_terminal import is_terminal
+
+
+_DESIGN_NOTES = """
+# CLI Interaction Internal Helpers Sub-Package
+
+## Purpose
+Building blocks private to `interaction/`.
+
+## Internal Components Registry
+
+| Component     | Type     | Description                                        |
+| :------------ | :------- | :------------------------------------------------- |
+| `is_terminal` | Function | Asks one stream whether it is a terminal, safely.  |
+"""

simplibs/cli/interaction/_helpers/is_terminal.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+
+def is_terminal(
+    stream: Any,
+) -> bool:
+    """Return whether a stream is a terminal, without ever raising.
+
+    Args:
+        stream: A file-like object, or `None`.
+
+    Returns:
+        True only for a stream that answers `isatty()` with True.
+    """
+
+    # 1. No stream at all (a windowed interpreter has no stdin)
+    if stream is None:
+        return False
+
+    # 2. Ask the stream; a closed file or a stub without `isatty` is no terminal
+    try:
+        return bool(stream.isatty())
+    except (AttributeError, ValueError):
+        return False
+
+
+_DESIGN_NOTES = """
+# is_terminal — One Stream, One Safe Answer
+
+## Purpose
+`sys.stdin` can be `None` (a program started without a console), closed, or
+replaced by an object that has no `isatty`. All three mean "not a terminal",
+and none of them should surface as an exception from a yes/no question.
+"""

simplibs/cli/interaction/_validations/__init__.py

@@ -0,0 +1,15 @@
+from .raise_not_interactive_error import raise_not_interactive_error
+
+
+_DESIGN_NOTES = """
+# CLI Interaction Validations Sub-Package
+
+## Purpose
+Diagnostic raisers for the interaction check.
+
+## Internal Components Registry
+
+| Component                     | Type     | Description                                                  |
+| :---------------------------- | :------- | :----------------------------------------------------------- |
+| `raise_not_interactive_error` | Function | Raises `StateError` when there is no terminal to ask in.     |
+"""

simplibs/cli/interaction/_validations/raise_not_interactive_error.py

@@ -0,0 +1,42 @@
+from typing import NoReturn
+from simplibs.exception import StateError
+
+
+def raise_not_interactive_error(
+    reason: str | None,
+) -> NoReturn:
+    """Raise StateError when an answer is needed but there is no terminal.
+
+    Args:
+        reason: What was missing, or None.
+    """
+
+    # 1. The reason, when there is one, becomes the last line of the problem
+    problem = (
+        "An answer is needed, but there is no terminal to ask in.",
+        "Input or output is redirected (a pipe, a file, a scheduler or CI).",
+    )
+    if reason:
+        problem = problem + (reason,)
+
+    # 2. Raise structured StateError wrapping a RuntimeError
+    raise StateError(
+        error_name="CLI_NOT_INTERACTIVE",
+        label="terminal",
+        problem=problem,
+        expected="Input and output connected to a terminal, or every value given in advance.",
+        how_to_fix=(
+            "Pass the missing value as a command-line option.",
+            "Run the program in a terminal.",
+        ),
+        exception=RuntimeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_not_interactive_error — Nobody to Ask
+
+## Purpose
+Raised by `require_interactive`. It is a `StateError` and not a `ParamError`:
+the arguments are fine, the environment the program runs in is not.
+"""

simplibs/cli/interaction/is_interactive.py

@@ -0,0 +1,41 @@
+import sys
+# Inners
+from ._helpers import is_terminal
+
+
+def is_interactive() -> bool:
+    """Return whether the program can talk to a person.
+
+    Returns:
+        True when both standard input and standard output are terminals.
+        False in a pipe, behind a redirect, in a scheduler or in CI.
+
+    Example:
+        if not is_interactive():
+            print("Pass --name, there is nobody to ask.")
+    """
+
+    # 1. A person needs a way to answer and a way to read the question
+    return is_terminal(sys.stdin) and is_terminal(sys.stdout)
+
+
+_DESIGN_NOTES = """
+# is_interactive — Is There Somebody to Ask?
+
+## Purpose
+`resolve_or_prompt` falls back to a question when an option is missing. In a
+script that fallback must not happen, and this is the check for it.
+
+## Both Streams
+Input alone is not enough: with output redirected, the question would be
+written into a file where nobody reads it. Both must be terminals.
+
+## The Streams Are Read on Every Call
+`sys.stdin` and `sys.stdout` are looked up when the function runs, not at
+import, so a program (or a test) that replaces them is noticed.
+
+## Not Checked Inside the Prompts
+The prompts do not call this. Piped answers (`echo y | tool`) are a legitimate
+way to drive a program, and tests feed answers the same way. Whether a missing
+answer is an error is the caller's decision: `require_interactive()`.
+"""

simplibs/cli/interaction/require_interactive.py

@@ -0,0 +1,41 @@
+from simplibs.validate import validate_call
+# Inners
+from .is_interactive import is_interactive
+from ._validations import raise_not_interactive_error
+
+
+@validate_call
+def require_interactive(
+    reason: str | None = None,
+) -> None:
+    """Raise when the program cannot ask a person anything.
+
+    Args:
+        reason: What the program wanted to ask, added to the error so the
+            user sees why an answer was needed (e.g. `"--output is missing"`).
+
+    Raises:
+        StateError: If input or output is not a terminal.
+
+    Example:
+        if args.output is None:
+            require_interactive("--output is missing")
+            args.output = prompt_path("Output folder")
+    """
+
+    # 1. Fail with a readable card instead of waiting on a dead input
+    if not is_interactive():
+        raise_not_interactive_error(reason)
+
+
+_DESIGN_NOTES = """
+# require_interactive — Fail Early, Say Why
+
+## Purpose
+The assertion form of `is_interactive`: one line in front of a prompt that
+turns "the program hangs in CI" into a card naming the missing option.
+
+## The Reason
+Without it the card could only say "no terminal". With the reason the user
+reads what the program was missing and passes it as an option instead.
+"""

simplibs/cli/prompts/__init__.py

@@ -0,0 +1,43 @@
+from .prompt_choice import prompt_choice
+from .prompt_confirm import prompt_confirm
+from .prompt_multi_choice import prompt_multi_choice
+from .prompt_path import prompt_path
+from .prompt_text import prompt_text
+from .resolve_or_prompt import resolve_or_prompt
+from .prompt_int import prompt_int
+from .prompt_secret import prompt_secret
+
+
+_DESIGN_NOTES = """
+# CLI Prompts Sub-Package
+
+## Purpose
+Questions to a person at a terminal. Every prompt asks again until the answer
+is acceptable, so what it returns needs no second check.
+
+## Shared Behavior
+* **An empty answer** returns the default when there is one. Without a
+  default it is refused and asked again (`prompt_multi_choice`, `prompt_text`
+  and `prompt_secret` can allow it).
+* **A refused answer** is explained in one warning line, then the question
+  is repeated. Nothing is raised for a typo.
+* **A wrong call** (an empty option list, a default that is not an option,
+  limits that exclude everything) is the programmer's mistake and raises a
+  `ParamError` at once, before the first question.
+* **No input at all** (the stream ended) raises `StateError`.
+
+## Internal Components Registry
+
+| Component            | Type     | Description                                                           |
+| :------------------- | :------- | :-------------------------------------------------------------------- |
+| `prompt_text`        | Function | A line of text, optionally checked by a rule.                         |
+| `prompt_int`         | Function | A whole number, optionally within limits.                             |
+| `prompt_secret`      | Function | A line typed without being shown.                                     |
+| `prompt_confirm`     | Function | A yes/no question.                                                    |
+| `prompt_choice`      | Function | One key from a described set of options.                              |
+| `prompt_multi_choice`| Function | One or more comma-separated keys from a described set.                |
+| `prompt_path`        | Function | A normalized path, optionally of a given kind, existing or created.   |
+| `resolve_or_prompt`  | Function | Uses a value from the command line, asks only when it is missing.     |
+| `_helpers`           | Package  | Reading answers, warning lines, hints and parsing.                    |
+| `_validations`       | Package  | Diagnostic raisers for wrong calls and a dead input.                  |
+"""

simplibs/cli/prompts/_helpers/__init__.py

@@ -0,0 +1,27 @@
+from .build_rejection_message import build_rejection_message
+from .format_default_hint import format_default_hint
+from .parse_keys import parse_keys
+from .print_problem import print_problem
+from .unquote_answer import unquote_answer
+from .describe_range import describe_range
+from .read_answer import read_answer
+
+
+_DESIGN_NOTES = """
+# CLI Prompts Internal Helpers Sub-Package
+
+## Purpose
+Building blocks shared by the prompts and private to them.
+
+## Internal Components Registry
+
+| Component                 | Type     | Description                                                      |
+| :------------------------ | :------- | :--------------------------------------------------------------- |
+| `read_answer`             | Function | The one place that reads a visible line from the user.           |
+| `print_problem`           | Function | Prints a refusal as a warning line.                              |
+| `format_default_hint`     | Function | Builds the ` [default]` text shown after a question.             |
+| `build_rejection_message` | Function | The line shown when a rule refuses an answer.                    |
+| `describe_range`          | Function | Words for the limits of a number: `from 1 to 64`.                |
+| `parse_keys`              | Function | Splits comma-separated keys, dropping empties and repeats.       |
+| `unquote_answer`          | Function | Removes one pair of surrounding quotes from an answer.           |
+"""

simplibs/cli/prompts/_helpers/build_rejection_message.py

@@ -0,0 +1,43 @@
+from typing import Any
+from simplibs.rules import Rule
+
+
+def build_rejection_message(
+    rule: Any,
+    invalid_message: str | None,
+) -> str:
+    """Choose the line shown when a rule refuses an answer.
+
+    Args:
+        rule: The rule or callable that refused.
+        invalid_message: The caller's own message, or None.
+
+    Returns:
+        `invalid_message` when given; otherwise a line built from
+        `rule.describe()` for a `Rule`, or a plain one for any other callable.
+    """
+
+    # 1. The caller knows best
+    if invalid_message is not None:
+        return invalid_message
+
+    # 2. A Rule can say what it expects
+    if isinstance(rule, Rule):
+        return f"The value is not valid. Expected: {rule.describe()}."
+
+    # 3. A plain callable cannot
+    return "The value is not valid."
+
+
+_DESIGN_NOTES = """
+# build_rejection_message — Saying Why a Rule Said No
+
+## Purpose
+`prompt_text` and `prompt_path` both take a rule and both need the same
+sentence when it refuses.
+
+## `describe()` as the Source
+A `Rule` carries a short noun phrase for what it requires, written for exactly
+this kind of message. A lambda carries nothing, which is why `invalid_message`
+exists.
+"""

simplibs/cli/prompts/_helpers/describe_range.py

@@ -0,0 +1,36 @@
+def describe_range(
+    minimum: int | None,
+    maximum: int | None,
+) -> str:
+    """Describe the accepted numbers in a few words.
+
+    Args:
+        minimum: The lower limit, or None.
+        maximum: The upper limit, or None.
+
+    Returns:
+        `"from 1 to 64"`, `"1 or more"`, `"64 or less"`, or an empty
+        string when there are no limits.
+    """
+
+    # 1. Both limits
+    if minimum is not None and maximum is not None:
+        return f"from {minimum} to {maximum}"
+
+    # 2. One limit
+    if minimum is not None:
+        return f"{minimum} or more"
+    if maximum is not None:
+        return f"{maximum} or less"
+
+    # 3. No limits
+    return ""
+
+
+_DESIGN_NOTES = """
+# describe_range — The Limits in Words
+
+## Purpose
+The part of the refusal sentence of `prompt_int` that changes with the limits,
+kept out of the prompt so that the loop reads as questions and decisions only.
+"""

simplibs/cli/prompts/_helpers/format_default_hint.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+
+def format_default_hint(
+    default: Any,
+) -> str:
+    """Build the ` [default]` text shown after a question.
+
+    Args:
+        default: The default value, or None.
+
+    Returns:
+        `" [value]"`, or an empty string when there is no default or it
+        is empty.
+    """
+
+    # 1. Text of the default; None and "" show nothing
+    text = "" if default is None else str(default)
+
+    # 2. Leading space included, so it joins the message directly
+    return f" [{text}]" if text else ""
+
+
+_DESIGN_NOTES = """
+# format_default_hint — What Enter Will Do
+
+## Purpose
+The same bracket after every question, built once.
+
+## An Empty Default Shows Nothing
+`[]` tells the user nothing. A default of `""` (accepted by `prompt_text`)
+looks the same as no default, which is also how it behaves.
+"""

simplibs/cli/prompts/_helpers/parse_keys.py

@@ -0,0 +1,30 @@
+def parse_keys(
+    raw: str,
+) -> tuple[str, ...]:
+    """Split a comma-separated answer into keys.
+
+    Args:
+        raw: The answer, e.g. `"a, b,,a"`.
+
+    Returns:
+        The keys in the order given, stripped, without empty items and
+        without repeats: `("a", "b")`.
+    """
+
+    # 1. Split, strip, and drop empty items
+    keys = [part.strip() for part in raw.split(",") if part.strip()]
+
+    # 2. Drop repeats, keeping the first occurrence of each
+    return tuple(dict.fromkeys(keys))
+
+
+_DESIGN_NOTES = """
+# parse_keys — The Answer as a List
+
+## Purpose
+The parsing step of `prompt_multi_choice`, apart from the validation, so the
+loop reads as questions and decisions only.
+
+## Repeats
+`dict.fromkeys` removes them and keeps the order, which a `set` would not.
+"""

simplibs/cli/prompts/_helpers/print_problem.py

@@ -0,0 +1,23 @@
+from simplibs.style import WARNING
+
+
+def print_problem(
+    message: str,
+) -> None:
+    """Print a refusal of an answer as a warning line.
+
+    Args:
+        message: What was wrong with the answer.
+    """
+
+    # 1. One styled line; plain text when styles are off
+    print(WARNING(message))
+
+
+_DESIGN_NOTES = """
+# print_problem — How a Prompt Complains
+
+## Purpose
+Every "please try again" has the same look, and the look can be changed here.
+Plain text when the output is not a terminal, because `simplibs-style` decides.
+"""

simplibs/cli/prompts/_helpers/read_answer.py

@@ -0,0 +1,44 @@
+# Outers
+from .._validations import raise_no_answer_available_error
+
+
+def read_answer(
+    prompt: str,
+) -> str:
+    """Read one visible line from the user and strip surrounding whitespace.
+
+    Args:
+        prompt: The text shown before the cursor.
+
+    Returns:
+        The answer, possibly empty.
+
+    Raises:
+        StateError: If the input ended before an answer was given.
+    """
+
+    # 1. Ask; a dead input becomes a card instead of a bare EOFError
+    try:
+        return input(prompt).strip()
+    except EOFError as caught_exc:
+        raise_no_answer_available_error(prompt, caught_exc)
+
+
+_DESIGN_NOTES = """
+# read_answer — The One Place That Reads
+
+## Purpose
+Every prompt that shows what is typed reads through this function, so there is
+exactly one `input` call for them. A test that feeds answers patches
+`builtins.input` once, and the end-of-input behavior is the same everywhere.
+(`prompt_secret` reads through `getpass` and shares only the card.)
+
+## End of Input
+A program started with a closed or exhausted input (`tool < /dev/null`, a CI
+job) gets `EOFError` from `input`. It is turned into a `StateError` that says
+nobody is there to answer.
+
+## Ctrl+C Is Left Alone
+`KeyboardInterrupt` is the user saying "stop", and a prompt that swallowed it
+would be a trap. It goes up unchanged.
+"""

simplibs/cli/prompts/_helpers/unquote_answer.py

@@ -0,0 +1,32 @@
+def unquote_answer(
+    answer: str,
+) -> str:
+    """Remove one pair of matching quotes around an answer.
+
+    Args:
+        answer: The answer, already stripped.
+
+    Returns:
+        The answer without the outer `"` or `'` pair, stripped again.
+        An answer without such a pair is returned unchanged.
+    """
+
+    # 1. Only a matching pair around the whole answer is a quote
+    if len(answer) >= 2 and answer[0] == answer[-1] and answer[0] in "\"'":
+        return answer[1:-1].strip()
+
+    # 2. Anything else is part of the answer
+    return answer
+
+
+_DESIGN_NOTES = """
+# unquote_answer — Paths Dragged Into a Console
+
+## Purpose
+A file manager pastes a path with spaces in quotes. `normalize_path` would
+read the quotes as part of the name and report a path that does not exist.
+
+## Only a Matching Pair
+`"a` or `a"` or `it's` are left alone; the answer is changed only when the
+same quote starts and ends it.
+"""

simplibs/cli/prompts/_validations/__init__.py

@@ -0,0 +1,23 @@
+from .raise_create_needs_kind_error import raise_create_needs_kind_error
+from .raise_default_not_in_options_error import raise_default_not_in_options_error
+from .raise_no_answer_available_error import raise_no_answer_available_error
+from .raise_options_empty_error import raise_options_empty_error
+from .raise_range_empty_error import raise_range_empty_error
+
+
+_DESIGN_NOTES = """
+# CLI Prompts Validations Sub-Package
+
+## Purpose
+Diagnostic raisers for wrong calls of the prompts and for a dead input.
+
+## Internal Components Registry
+
+| Component                              | Type     | Description                                                            |
+| :------------------------------------- | :------- | :--------------------------------------------------------------------- |
+| `raise_create_needs_kind_error`        | Function | Raises `ParamError` for `create_if_missing` with `kind="any"`.         |
+| `raise_default_not_in_options_error`   | Function | Raises `ParamError` when a default is not one of the options.          |
+| `raise_no_answer_available_error`      | Function | Raises `StateError` when the input ended before an answer.             |
+| `raise_options_empty_error`            | Function | Raises `ParamError` when there is nothing to choose from.              |
+| `raise_range_empty_error`              | Function | Raises `ParamError` when `minimum` is greater than `maximum`.          |
+"""