simplibs-cli 0.1.0__py3-none-any.whl

simplibs/cli/prompts/_validations/raise_create_needs_kind_error.py

@@ -0,0 +1,31 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_create_needs_kind_error() -> NoReturn:
+    """Raise ParamError when creation is requested without a kind."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="CLI_CREATE_NEEDS_KIND",
+        label="create_if_missing",
+        value=True,
+        problem="A missing path cannot be created without knowing whether it is a file or a directory.",
+        expected="kind='file' or kind='dir' together with create_if_missing=True.",
+        how_to_fix=(
+            "Pass kind='file' or kind='dir'.",
+            "Drop create_if_missing and accept any path.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_create_needs_kind_error — Create What?
+
+## Purpose
+`kind="any"` accepts both a file and a directory, which is exactly what
+creation cannot do. Guessing one of them (silently, for everybody who forgot
+the argument) would create the wrong thing, so the choice is the caller's and
+the missing one is a `ParamError`.
+"""

simplibs/cli/prompts/_validations/raise_default_not_in_options_error.py

@@ -0,0 +1,38 @@
+from typing import Any, NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_default_not_in_options_error(
+    default: Any,
+    options: dict[str, str],
+) -> NoReturn:
+    """Raise ParamError when a default is not one of the options.
+
+    Args:
+        default: The rejected default (a key, or a tuple of keys).
+        options: The options it was supposed to belong to.
+    """
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="CLI_DEFAULT_NOT_IN_OPTIONS",
+        label="default",
+        value=default,
+        problem="The default is not one of the options.",
+        expected=f"Only keys from the options: {', '.join(options)}.",
+        how_to_fix=(
+            "Use a key that exists in the options as the default.",
+            "Add the default to the options.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_default_not_in_options_error — A Default Nobody Could Type
+
+## Purpose
+Enter would return a key that the prompt itself would refuse. The promise of
+`prompt_choice` is that the result is always an option, so the contradiction
+is reported to the programmer instead of passed to the user.
+"""

simplibs/cli/prompts/_validations/raise_no_answer_available_error.py

@@ -0,0 +1,41 @@
+from typing import NoReturn
+from simplibs.exception import StateError
+
+
+def raise_no_answer_available_error(
+    prompt: str,
+    caught_exc: EOFError,
+) -> NoReturn:
+    """Raise StateError when the input ended before the user answered.
+
+    Args:
+        prompt: The question that could not be asked.
+        caught_exc: The `EOFError` raised by `input`.
+    """
+
+    # 1. Raise structured StateError wrapping the caught EOFError instance
+    raise StateError(
+        error_name="CLI_NO_ANSWER_AVAILABLE",
+        label="prompt",
+        value=prompt.strip(),
+        problem=(
+            "The input ended before an answer was given.",
+            "Nobody is there to answer — the program probably runs without a terminal.",
+        ),
+        expected="An interactive terminal, or the answer given in advance.",
+        how_to_fix=(
+            "Pass the value as a command-line option.",
+            "Run the program in a terminal.",
+            "Check with require_interactive() before asking.",
+        ),
+        exception=caught_exc,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_no_answer_available_error — The Input Is Gone
+
+## Purpose
+`input()` raises a bare `EOFError` with the message "EOF when reading a line",
+which says neither what was being asked nor what to do. The card says both.
+"""

simplibs/cli/prompts/_validations/raise_options_empty_error.py

@@ -0,0 +1,28 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_options_empty_error() -> NoReturn:
+    """Raise ParamError when a choice prompt has no options."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="CLI_OPTIONS_EMPTY",
+        label="options",
+        problem="There is nothing to choose from.",
+        expected="A mapping with at least one key -> description pair.",
+        how_to_fix=(
+            "Pass at least one option.",
+            "Skip the question when no option is available.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_options_empty_error — A Question With No Answer
+
+## Purpose
+With no options no key can ever match, so the prompt would ask forever.
+Raised before the first question.
+"""

simplibs/cli/prompts/_validations/raise_range_empty_error.py

@@ -0,0 +1,41 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_range_empty_error(
+    minimum: int,
+    maximum: int,
+) -> NoReturn:
+    """Raise ParamError when no number can satisfy both limits.
+
+    Args:
+        minimum: The lower limit.
+        maximum: The upper limit, smaller than `minimum`.
+    """
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="CLI_RANGE_EMPTY",
+        label="minimum",
+        value=minimum,
+        problem=(
+            f"The minimum {minimum} is greater than the maximum {maximum}.",
+            "No number can satisfy both limits.",
+        ),
+        expected="A minimum that is less than or equal to the maximum.",
+        how_to_fix=(
+            "Swap the two limits if they were mixed up.",
+            "Drop one of the limits if it is not needed.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_range_empty_error — Limits That Exclude Everything
+
+## Purpose
+With `minimum > maximum` every answer would be refused and the question
+repeated forever. Raised before the first question, like the other wrong
+calls.
+"""

simplibs/cli/prompts/prompt_choice.py

@@ -0,0 +1,87 @@
+from simplibs.validate import validate_call
+# Outers
+from ..reporting import print_choices
+# Inners
+from ._helpers import format_default_hint, print_problem, read_answer
+from ._validations import raise_default_not_in_options_error, raise_options_empty_error
+
+
+@validate_call
+def prompt_choice(
+    message: str,
+    options: dict[str, str],
+    *,
+    default: str | None = None,
+) -> str:
+    """Ask the user to pick one key from described options.
+
+    Args:
+        message: The question to display.
+        options: A mapping of key -> human-readable description, printed as
+            an aligned list before the question.
+        default: The key returned when the user presses Enter with no input.
+            It must be one of `options`. None means an explicit answer is
+            required.
+
+    Returns:
+        The chosen key — always a member of `options`.
+
+    Raises:
+        ParamError: If `options` is empty or `default` is not one of its keys.
+
+    Example:
+        fmt = prompt_choice("Format", {"json": "Machine-readable", "text": "For people"}, default="text")
+    """
+
+    # 1. A wrong call fails before the first question
+    if not options:
+        raise_options_empty_error()
+    if default is not None and default not in options:
+        raise_default_not_in_options_error(default, options)
+
+    # 2. Show every option once
+    print_choices(options)
+
+    # 3. The hint shown after the message
+    hint = format_default_hint(default)
+
+    # 4. Ask until a key is recognized
+    while True:
+
+        # 4.1 Read the answer
+        answer = read_answer(f"{message}{hint}: ")
+
+        # 4.2 Empty — the default, or asked again
+        if not answer:
+            if default is not None:
+                return default
+            print_problem("Please enter one of the options above.")
+            continue
+
+        # 4.3 A known key
+        if answer in options:
+            return answer
+
+        # 4.4 An unknown key
+        print_problem(f"'{answer}' is not a valid option. Please try again.")
+
+
+_DESIGN_NOTES = """
+# prompt_choice — One Key From a List
+
+## Purpose
+Asks, lists and returns a key that is certain to exist in `options`.
+
+## The Promise Is Kept
+The result is always a member of `options`. An empty `options` (nothing could
+ever match) and a `default` that is not one of the keys (Enter would return a
+key the prompt itself refuses) are wrong calls, refused with a `ParamError`
+before the first question.
+
+## Keys Are Matched Exactly
+No case folding and no numbers: a key is what the program defined, and
+guessing would let two keys such as `a` and `A` collide.
+
+## Return Type
+`str`, never `None`; a missing answer is asked again.
+"""

simplibs/cli/prompts/prompt_confirm.py

@@ -0,0 +1,73 @@
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import print_problem, read_answer
+
+
+@validate_call
+def prompt_confirm(
+    message: str,
+    *,
+    default: bool | None = None,
+) -> bool:
+    """Ask a yes/no question, asking again until the answer is understood.
+
+    Args:
+        message: The question to display. A `[y/n]` hint is appended, with
+            the default in upper case.
+        default: Returned when the user presses Enter with no input. None
+            means that an explicit answer is required.
+
+    Returns:
+        True for `y` or `yes`, False for `n` or `no` (any letter case).
+
+    Example:
+        if prompt_confirm("Overwrite the file?", default=False):
+            ...
+    """
+
+    # 1. The hint reflects the default
+    if default is True:
+        hint = "[Y/n]"
+    elif default is False:
+        hint = "[y/N]"
+    else:
+        hint = "[y/n]"
+
+    # 2. Ask until the answer is understood
+    while True:
+
+        # 2.1 Read the answer in lower case
+        answer = read_answer(f"{message} {hint}: ").lower()
+
+        # 2.2 Empty — the default, or asked again
+        if not answer:
+            if default is not None:
+                return default
+            print_problem("Please answer 'y' or 'n'.")
+            continue
+
+        # 2.3 Understood
+        if answer in ("y", "yes"):
+            return True
+        if answer in ("n", "no"):
+            return False
+
+        # 2.4 Not understood
+        print_problem("Please answer 'y' or 'n'.")
+
+
+_DESIGN_NOTES = """
+# prompt_confirm — Yes or No
+
+## Purpose
+The most common prompt. A destructive action should pass `default=False`, so
+that a hurried Enter means "no".
+
+## Return Type
+`bool`, never `None`, which is what a type checker needs for
+`if prompt_confirm(...)`. A missing answer is asked again, not returned.
+
+## Only `y`, `yes`, `n`, `no`
+English words, because the library's messages are English. Other languages
+are not guessed at: a program that needs them can ask with `prompt_choice`.
+"""

simplibs/cli/prompts/prompt_int.py

@@ -0,0 +1,99 @@
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import describe_range, format_default_hint, print_problem, read_answer
+from ._validations import raise_range_empty_error
+
+
+@validate_call
+def prompt_int(
+    message: str,
+    *,
+    default: int | None = None,
+    minimum: int | None = None,
+    maximum: int | None = None,
+) -> int:
+    """Ask the user for a whole number, asking again until it is acceptable.
+
+    Args:
+        message: The question to display.
+        default: Returned when the user presses Enter with no input. It goes
+            through the range check like a typed answer.
+        minimum: The smallest accepted number. None means no lower limit.
+        maximum: The largest accepted number. None means no upper limit.
+
+    Returns:
+        The number, within `minimum` and `maximum` when they are given.
+
+    Raises:
+        ParamError: If `minimum` is greater than `maximum`.
+
+    Example:
+        workers = prompt_int("Workers", default=4, minimum=1, maximum=64)
+    """
+
+    # 1. A range nobody can satisfy fails before the first question
+    if minimum is not None and maximum is not None and minimum > maximum:
+        raise_range_empty_error(minimum, maximum)
+
+    # 2. What is asked for, said once and reused for every refusal
+    range_text = describe_range(minimum, maximum)
+    expectation = f"Please enter a whole number {range_text}." if range_text else "Please enter a whole number."
+
+    # 3. The hint shown after the message
+    hint = format_default_hint(default)
+
+    # 4. Ask until a number is acceptable
+    while True:
+
+        # 4.1 Read the answer; an empty one falls back to the default
+        answer = read_answer(f"{message}{hint}: ")
+        if not answer:
+            if default is None:
+                print_problem(expectation)
+                continue
+            answer = str(default)
+
+        # 4.2 It must be a whole number
+        try:
+            number = int(answer)
+        except ValueError:
+            print_problem(expectation)
+            continue
+
+        # 4.3 It must lie within the limits
+        if minimum is not None and number < minimum:
+            print_problem(expectation)
+            continue
+        if maximum is not None and number > maximum:
+            print_problem(expectation)
+            continue
+
+        # 4.4 Accepted
+        return number
+
+
+_DESIGN_NOTES = """
+# prompt_int — A Whole Number Within Limits
+
+## Purpose
+Counts, ports, sizes: the answers that `prompt_text` would return as a string
+and the caller would then have to parse and range-check, usually forgetting
+one of the two.
+
+## Whole Numbers Only
+`3.5` and `1e3` are refused. A program that needs decimals can use
+`prompt_text` with a rule of its own, which keeps this function's promise
+("an `int` within the limits") simple.
+
+## Python's Own Reading of Numbers
+`int()` also accepts `+5`, `-5`, ` 5 ` and `1_000`. They are numbers, so they
+are accepted instead of being second-guessed by a stricter parser.
+
+## The Default Goes Through the Check
+Like in `prompt_text`: a default outside the limits repeats the question
+instead of raising, and what the function returns is always in range.
+
+## The Same Sentence for Every Refusal
+Not a number, too small, too large: the user needs one thing, the sentence
+that says what is accepted ("from 1 to 64").
+"""

simplibs/cli/prompts/prompt_multi_choice.py

@@ -0,0 +1,107 @@
+from simplibs.validate import validate_call
+# Outers
+from ..reporting import print_choices
+# Inners
+from ._helpers import format_default_hint, parse_keys, print_problem, read_answer
+from ._validations import raise_default_not_in_options_error, raise_options_empty_error
+
+
+@validate_call
+def prompt_multi_choice(
+    message: str,
+    options: dict[str, str],
+    *,
+    default: tuple[str, ...] = (),
+    allow_empty: bool = False,
+) -> tuple[str, ...]:
+    """Ask the user to pick one or more comma-separated keys from described options.
+
+    Args:
+        message: The question to display.
+        options: A mapping of key -> human-readable description.
+        default: The keys returned when the user presses Enter with no input.
+            Each must be one of `options`.
+        allow_empty: If True, an empty answer with no default is accepted
+            and returns `()`. Meant for "pick any extras" questions.
+
+    Returns:
+        The chosen keys in the order given, without repeats, each a
+        member of `options`.
+
+    Raises:
+        ParamError: If `options` is empty or a key of `default` is not in it.
+
+    Example:
+        extras = prompt_multi_choice("Extras", {"tests": "Test folder", "docs": "Docs folder"}, allow_empty=True)
+    """
+
+    # 1. A wrong call fails before the first question
+    if not options:
+        raise_options_empty_error()
+    if any(key not in options for key in default):
+        raise_default_not_in_options_error(default, options)
+
+    # 2. Show every option once
+    print_choices(options)
+
+    # 3. The hint shown after the message
+    hint = format_default_hint(",".join(default))
+
+    # 4. Ask until every key is recognized
+    while True:
+
+        # 4.1 Read the answer
+        answer = read_answer(f"{message}{hint}: ")
+
+        # 4.2 Empty — the default, nothing, or asked again
+        if not answer:
+            if default:
+                return default
+            if allow_empty:
+                return ()
+            print_problem("Please enter at least one option.")
+            continue
+
+        # 4.3 Split into keys; an answer like "," holds none
+        keys = parse_keys(answer)
+        if not keys:
+            print_problem("Please enter at least one option.")
+            continue
+
+        # 4.4 Every key must exist
+        unknown = [key for key in keys if key not in options]
+        if unknown:
+            print_problem(f"Unknown option(s): {', '.join(unknown)}. Please try again.")
+            continue
+
+        # 4.5 Accepted
+        return keys
+
+
+_DESIGN_NOTES = """
+# prompt_multi_choice — Several Keys From a List
+
+## Purpose
+The plural of `prompt_choice`: `tests,docs` answers "which of these".
+
+## The Default Is Checked Up Front
+Like in `prompt_choice`, every key of `default` must be one of `options`. A
+wrong call fails with a `ParamError` before the first question, and a valid
+default is returned as it is, not typed back through the parser.
+
+## Repeats Collapse
+`a,a` returns `("a",)`: a key counted twice is a typo, not a wish.
+
+## `allow_empty`
+Makes "none of them" a valid answer for questions that have no sensible
+default ("pick any extras"). It applies only when there is no default: a
+default always wins over emptiness.
+
+## Always a Tuple
+The return type is `tuple[str, ...]` and never `None`; "nothing chosen" is the
+empty tuple.
+
+## Order Is Kept
+The keys come back in the order typed, so a caller may treat the order as the
+user's priority.
+"""