simplibs-cli 0.1.0__py3-none-any.whl

simplibs/cli/prompts/prompt_path.py

@@ -0,0 +1,153 @@
+from pathlib import Path
+from typing import Literal
+from simplibs.exception import AccessError, StateError
+from simplibs.path import PathLike, PathPredicate, ensure_dir, ensure_file, normalize_path
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import (
+    build_rejection_message,
+    format_default_hint,
+    print_problem,
+    read_answer,
+    unquote_answer,
+)
+from ._validations import raise_create_needs_kind_error
+
+
+@validate_call
+def prompt_path(
+    message: str,
+    *,
+    kind: Literal["file", "dir", "any"] = "any",
+    must_exist: bool = False,
+    create_if_missing: bool = False,
+    default: PathLike | None = None,
+    rule: PathPredicate | None = None,
+    invalid_message: str | None = None,
+) -> Path:
+    """Ask the user for a path, asking again until it is acceptable.
+
+    The answer is normalized (`~` expanded, made absolute) and surrounding
+    quotes, as pasted by a file manager, are removed.
+
+    Args:
+        message: The question to display.
+        kind: `"file"` or `"dir"` makes an existing path of the other kind
+            unacceptable. `"any"` accepts both.
+        must_exist: If True, a missing path is refused.
+        create_if_missing: If True, a missing path is created — as a file
+            for `kind="file"`, as a directory for `kind="dir"`. It takes
+            precedence over `must_exist`.
+        default: Used when the user presses Enter with no input. It goes
+            through every check like a typed answer.
+        rule: A `Rule` from `simplibs.path.rules` (or any `(Path) -> bool`
+            callable) that the final path must satisfy.
+        invalid_message: What to say when `rule` refuses a path. Without it,
+            `rule.describe()` is used when `rule` is a `Rule`.
+
+    Returns:
+        The normalized path.
+
+    Raises:
+        ParamError: If `create_if_missing` is combined with `kind="any"`.
+
+    Example:
+        source = prompt_path("Source file", kind="file", must_exist=True)
+        target = prompt_path("Output folder", kind="dir", create_if_missing=True)
+        notes = prompt_path("Notes", rule=HasSuffix(".md") & IsFile())
+    """
+
+    # 1. Creating needs to know what to create
+    if create_if_missing and kind == "any":
+        raise_create_needs_kind_error()
+
+    # 2. The hint shown after the message
+    hint = format_default_hint(default)
+
+    # 3. Ask until a path is acceptable
+    while True:
+
+        # 3.1 Read the answer; an empty one falls back to the default
+        answer = unquote_answer(read_answer(f"{message}{hint}: "))
+        if not answer:
+            if default is None:
+                print_problem("Please enter a path.")
+                continue
+            answer = str(default)
+
+        # 3.2 Normalize; the path does not have to exist
+        try:
+            path = normalize_path(answer)
+        except AccessError:
+            print_problem(f"'{answer}' cannot be used as a path.")
+            continue
+
+        # 3.3 An existing path must be of the requested kind
+        if path.exists():
+            if kind == "file" and not path.is_file():
+                print_problem(f"Not a file: {path}")
+                continue
+            if kind == "dir" and not path.is_dir():
+                print_problem(f"Not a directory: {path}")
+                continue
+
+        # 3.4 A missing path is created, refused, or let through
+        elif create_if_missing:
+            try:
+                path = ensure_file(path) if kind == "file" else ensure_dir(path)
+            except (StateError, AccessError):
+                print_problem(f"Cannot create '{path}'. Is the location writable?")
+                continue
+        elif must_exist:
+            print_problem(f"Path does not exist: {path}")
+            continue
+
+        # 3.5 The rule judges the final path
+        if rule is not None and not rule(path):
+            print_problem(build_rejection_message(rule, invalid_message))
+            continue
+
+        # 3.6 Accepted
+        return path
+
+
+_DESIGN_NOTES = """
+# prompt_path — A Path That Is Safe to Use
+
+## Purpose
+Asks for a path and returns one that has passed every check the caller named.
+
+## `kind` Is Checked on Existing Paths
+`kind` is `"file"`, `"dir"` or `"any"`. It decides what is created and it also
+judges a path that already exists, so a folder is never accepted where a file
+was asked for.
+
+## `rule` Covers the Rest
+`kind` and `must_exist` cover the common cases; everything else is a rule from
+`simplibs.path.rules` (`HasSuffix(".md") & IsPathWritable()`), the same objects
+that filter scans.
+
+## Failures Re-ask
+A path that cannot be resolved (`AccessError`) and a creation that fails
+(`StateError` or `AccessError` from `ensure_file` / `ensure_dir`) are reported
+in one line and the question is asked again. Nothing ends the program in the
+middle of a question.
+
+## Quotes Are Removed
+A path dragged into a Windows console arrives as
+`"C:\\My Files\\a.txt"`, quotes included, so one surrounding pair is removed
+before the path is normalized.
+
+## `create_if_missing` and `rule`
+The rule runs last, on the final path. A rule that refuses a path that was
+created a moment ago leaves it on the disk, so rules for a creating prompt
+should judge the text of the path (suffix, name, location), not its content.
+
+## `create_if_missing` Needs a Kind
+Creating has to know what to create, so `create_if_missing=True` with
+`kind="any"` is a `ParamError` before the first question.
+
+## A Default Is Not Special
+It is checked like an answer. A default the checks refuse repeats the question
+instead of raising.
+"""

simplibs/cli/prompts/prompt_secret.py

@@ -0,0 +1,71 @@
+import getpass
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import print_problem
+from ._validations import raise_no_answer_available_error
+
+
+@validate_call
+def prompt_secret(
+    message: str,
+    *,
+    allow_empty: bool = False,
+) -> str:
+    """Ask the user for a secret (a password, a token) without showing it.
+
+    Args:
+        message: The question to display.
+        allow_empty: If True, an empty answer is accepted and returned as `""`.
+
+    Returns:
+        The answer exactly as typed. Surrounding whitespace is kept, because
+        it can be part of a secret.
+
+    Raises:
+        StateError: If the input ended before an answer was given.
+
+    Example:
+        token = prompt_secret("API token")
+    """
+
+    # 1. Ask until an answer is acceptable
+    while True:
+
+        # 1.1 Read without echo; a dead input becomes a card
+        try:
+            answer = getpass.getpass(f"{message}: ")
+        except EOFError as caught_exc:
+            raise_no_answer_available_error(message, caught_exc)
+
+        # 1.2 Empty — allowed, or asked again
+        if not answer and not allow_empty:
+            print_problem("Please enter a value.")
+            continue
+
+        # 1.3 Accepted
+        return answer
+
+
+_DESIGN_NOTES = """
+# prompt_secret — Typing That Is Not Shown
+
+## Purpose
+A token typed with `prompt_text` stays on the screen and in the scrollback.
+`getpass` hides it, and this prompt adds the repeat-until-given loop the other
+prompts have.
+
+## Its Own Read
+The only prompt that does not read through `read_answer`: that helper strips
+whitespace and uses `input`, which echoes. The end-of-input card is shared.
+
+## No Default, No Rule, No Hint
+A default would have to be printed to be useful, which defeats the purpose.
+A secret is checked by whatever uses it, and a rule that said "too short"
+would also tell a bystander something about it.
+
+## Not on a Terminal
+`getpass` reads from the terminal device when it can and falls back to
+standard input with a warning when it cannot. Piped answers therefore work,
+only unhidden. A program that must never read a secret from a pipe checks
+`is_interactive()` first.
+"""

simplibs/cli/prompts/prompt_text.py

@@ -0,0 +1,90 @@
+from typing import Callable
+from simplibs.validate import validate_call
+# Inners
+from ._helpers import (
+    build_rejection_message,
+    format_default_hint,
+    print_problem,
+    read_answer,
+)
+
+
+@validate_call
+def prompt_text(
+    message: str,
+    *,
+    default: str | None = None,
+    allow_empty: bool = False,
+    rule: Callable[[str], bool] | None = None,
+    invalid_message: str | None = None,
+) -> str:
+    """Ask the user for a line of text, 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 `rule` like any other answer. None means "no default".
+        allow_empty: If True, an empty answer (with no default) is accepted
+            and returned as `""`. It is not passed to `rule`.
+        rule: A `Rule` or any `(str) -> bool` callable that an answer must
+            satisfy.
+        invalid_message: What to say when `rule` refuses an answer. Without
+            it, the text of `rule.describe()` is used when `rule` is a `Rule`.
+
+    Returns:
+        The answer, stripped of surrounding whitespace.
+
+    Example:
+        name = prompt_text("Project name", rule=IsValidFilename())
+        tag = prompt_text("Tag", default="latest")
+    """
+
+    # 1. The hint shown after the message
+    hint = format_default_hint(default)
+
+    # 2. Ask until an answer is acceptable
+    while True:
+
+        # 2.1 Read the answer; an empty one falls back to the default
+        answer = read_answer(f"{message}{hint}: ")
+        if not answer and default is not None:
+            answer = default
+
+        # 2.2 Still empty — allowed, or asked again
+        if not answer:
+            if allow_empty:
+                return ""
+            print_problem("Please enter a value.")
+            continue
+
+        # 2.3 The rule judges the answer
+        if rule is not None and not rule(answer):
+            print_problem(build_rejection_message(rule, invalid_message))
+            continue
+
+        # 2.4 Accepted
+        return answer
+
+
+_DESIGN_NOTES = """
+# prompt_text — The Plain Question
+
+## Purpose
+The prompt for free text. A name, a tag or a comment is asked here, so
+`prompt_path` and every program that asks for a name need no loop of their own.
+
+## The Default Goes Through the Rule
+An answer and a default are one value as far as the rule is concerned, so what
+the function returns always satisfies `rule`. A default the rule refuses is a
+programmer's mistake that shows up as a repeated question, not as a card; the
+alternative, checking the default up front, would run the rule once more on
+every call.
+
+## `allow_empty`
+For optional answers ("Comment (optional)"). It applies only when there is no
+default: a default always wins over emptiness.
+
+## Rules Are Not Cleaned Up
+A `Rule` or a callable is called as it is, and anything it raises goes up.
+String rules from `simplibs-rules` answer True or False.
+"""

simplibs/cli/prompts/resolve_or_prompt.py

@@ -0,0 +1,74 @@
+from typing import Callable, TypeVar
+# Inners
+from ._helpers import print_problem
+
+
+T = TypeVar("T")
+
+
+def resolve_or_prompt(
+    value: T | None,
+    *,
+    is_valid: Callable[[T], bool],
+    prompt: Callable[[], T],
+    invalid_message: str | None = None,
+) -> T:
+    """Use a value from the command line if it is good, otherwise ask for it.
+
+    Args:
+        value: The candidate, typically from parsed arguments. None means
+            "not given" and is never reported.
+        is_valid: Decides whether `value` can be used as it is. A `Rule`
+            fits.
+        prompt: A zero-argument callable that asks the user, called only when
+            `value` is missing or refused.
+        invalid_message: A line printed before asking when `value` was given
+            but refused. Not printed for a missing value.
+
+    Returns:
+        `value` unchanged if it passed, otherwise what `prompt()` returns.
+
+    Example:
+        folder = resolve_or_prompt(
+            args.folder,
+            is_valid=IsDir(),
+            prompt=lambda: prompt_path("Folder", kind="dir", must_exist=True),
+            invalid_message=f"'{args.folder}' is not a folder.",
+        )
+    """
+
+    # 1. A given value that passes is used as it is
+    if value is not None and is_valid(value):
+        return value
+
+    # 2. A given value that does not pass is mentioned before asking
+    if value is not None and invalid_message:
+        print_problem(invalid_message)
+
+    # 3. Ask
+    return prompt()
+
+
+_DESIGN_NOTES = """
+# resolve_or_prompt — The Command Line First, the Question Second
+
+## Purpose
+The usual shape of an optional option: given and good, use it; given and bad,
+say so and ask; not given, ask. The program reads the same either way.
+
+## Not Validated by `validate_call`
+The result has the type of the value and of the prompt (`T`), which the
+decorator cannot express. The two callables fail loudly enough on their own:
+passing the result of a call instead of the callable ends in a `TypeError`
+naming it.
+
+## No Terminal
+The function does not check that anybody can answer. A script that must never
+wait calls `require_interactive("...")` before it, or passes `prompt` that
+raises.
+
+## Typed
+`value: T | None` and `prompt: Callable[[], T]` tie the three parts together
+for a type checker: what goes in and what the prompt returns are the same `T`,
+so what comes out is a `T` as well.
+"""

simplibs/cli/py.typed

@@ -0,0 +1 @@
+

simplibs/cli/reporting/__init__.py

@@ -0,0 +1,18 @@
+from .print_choices import print_choices
+from .report_failures import report_failures
+
+
+_DESIGN_NOTES = """
+# CLI Reporting Sub-Package
+
+## Purpose
+Output that is not a question: a list of options and the summary of a batch
+that partly failed.
+
+## Internal Components Registry
+
+| Component         | Type     | Description                                                           |
+| :---------------- | :------- | :-------------------------------------------------------------------- |
+| `print_choices`   | Function | Prints an aligned `key - description` list, optionally with a title.  |
+| `report_failures` | Function | Prints the failed items of a batch and returns whether all succeeded. |
+"""

simplibs/cli/reporting/print_choices.py

@@ -0,0 +1,58 @@
+from simplibs.style import BOLD, CYAN
+from simplibs.validate import validate_call
+
+
+@validate_call
+def print_choices(
+    options: dict[str, str],
+    *,
+    title: str | None = None,
+) -> None:
+    """Print an aligned list of `key - description` pairs.
+
+    Args:
+        options: A mapping of key -> human-readable description.
+        title: A heading printed above the list. None prints no heading.
+
+    Example:
+        print_choices({"json": "Machine-readable", "text": "For people"}, title="Formats:")
+        # Formats:
+        #   json - Machine-readable
+        #   text - For people
+    """
+
+    # 1. Heading, when there is one
+    if title is not None:
+        print(BOLD(title))
+
+    # 2. Width of the longest key, so the dashes line up
+    width = max((len(key) for key in options), default=0)
+
+    # 3. One line per option — padded first, styled after (codes have no width)
+    for key, description in options.items():
+        print(f"  {CYAN(key.ljust(width))} - {description}")
+
+    # 4. Blank line after the list
+    print()
+
+
+_DESIGN_NOTES = """
+# print_choices — A List the Eye Can Scan
+
+## Purpose
+The one place that formats options. `prompt_choice` and `prompt_multi_choice`
+call it before they ask, so a list looks the same in a prompt and on its own.
+
+## Width From the Data
+The column is as wide as the longest key, so the dashes always line up,
+whatever the keys are.
+
+## Padded Before Styled
+An escape code has no width on screen but counts as characters in
+`ljust`. The key is padded first and colored after; the other order would
+shorten the column by the length of the code.
+
+## Title Is Optional
+The prompts print the list without a heading, and a stand-alone list may have
+one. `title=None` prints no heading at all.
+"""

simplibs/cli/reporting/report_failures.py

@@ -0,0 +1,64 @@
+from typing import Any, Callable
+from simplibs.style import ERROR
+from simplibs.validate import validate_call
+
+
+@validate_call
+def report_failures(
+    results: list[tuple[Any, bool]],
+    *,
+    describe: Callable[[Any], str],
+    title: str = "The following items failed:",
+) -> bool:
+    """Print the failed items of a batch and say whether everything succeeded.
+
+    Args:
+        results: `(item, succeeded)` pairs from a batch operation.
+        describe: Turns one failed item into a line of the report.
+        title: Heading printed above the list of failures.
+
+    Returns:
+        True if every item succeeded (nothing is printed), False if at
+        least one failed.
+
+    Example:
+        ok = report_failures(results, describe=lambda path: f"{path.name}")
+        raise SystemExit(0 if ok else 1)
+    """
+
+    # 1. Collect the failed items
+    failed = [item for item, succeeded in results if not succeeded]
+    if not failed:
+        return True
+
+    # 2. Heading, then one line per failure
+    print(f"\n{ERROR(title)}")
+    for item in failed:
+        print(f"  {describe(item)}")
+
+    # 3. At least one item failed
+    return False
+
+
+_DESIGN_NOTES = """
+# report_failures — The Summary of a Partly Failed Batch
+
+## Purpose
+A batch keeps going after an error and reports at the end. The return value
+is the program's exit decision, so the call sits next to `SystemExit`.
+
+## Failures Only
+The function prints the failed items and prints nothing when everything
+succeeded. The name says "failures" for that reason, and the heading is the
+`title` keyword.
+
+## Standard Output
+The report goes to the same stream as the prompts. `simplibs-style` decides
+about colors by standard output, so a message on another stream could carry
+escape codes into a redirected file.
+
+## Items Stay Opaque
+The function never looks inside an item: `describe` is the only code that
+knows what an item is, which is why the pairs may hold paths, names or
+objects alike.
+"""

simplibs/cli/verbosity/__init__.py

@@ -0,0 +1,16 @@
+from .resolve_verbosity import resolve_verbosity
+
+
+_DESIGN_NOTES = """
+# CLI Verbosity Sub-Package
+
+## Purpose
+Turns the flags of a command line into a decision that the rest of the
+program can use.
+
+## Internal Components Registry
+
+| Component           | Type     | Description                                                   |
+| :------------------ | :------- | :------------------------------------------------------------ |
+| `resolve_verbosity` | Function | Resolves `--quiet` and `-v` / `-vv` into one logging level.   |
+"""

simplibs/cli/verbosity/resolve_verbosity.py

@@ -0,0 +1,76 @@
+import logging
+# Outers
+from simplibs.validate import validate_call
+
+
+@validate_call
+def resolve_verbosity(
+    *,
+    quiet: bool = False,
+    verbose: int = 0,
+    default_level: int = logging.WARNING,
+) -> int:
+    """Resolve `--quiet` and `-v` / `-vv` into one logging level.
+
+    `quiet` wins over `verbose` when both are given — a documented rule,
+    not an accident of the order of the checks.
+
+    Args:
+        quiet: If True, the result is `logging.ERROR` (only errors shown).
+        verbose: How many times the verbose flag was given. `0` changes
+            nothing, `1` shows `INFO`, `2` or more shows `DEBUG`. A bool
+            works as `0` or `1`; a negative number counts as `0`.
+        default_level: The level returned when no flag is set. A single
+            `-v` never makes the output quieter than this.
+
+    Returns:
+        The resolved `logging` level.
+
+    Example:
+        parser.add_argument("-v", "--verbose", action="count", default=0)
+        level = resolve_verbosity(quiet=args.quiet, verbose=args.verbose)
+        logging.basicConfig(level=level)
+    """
+
+    # 1. Quiet wins over verbose
+    if quiet:
+        return logging.ERROR
+
+    # 2. Two or more steps show everything
+    if verbose >= 2:
+        return logging.DEBUG
+
+    # 3. One step shows progress, but never less than the default already did
+    if verbose == 1:
+        return min(default_level, logging.INFO)
+
+    # 4. No flag — the caller's default
+    return default_level
+
+
+_DESIGN_NOTES = """
+# resolve_verbosity — Flags to a Level
+
+## Purpose
+`--quiet` and `-v` are values in the parsed arguments and a number in the
+logging module. This is the one place where the rule between them lives.
+
+## `verbose` Is a Count
+It has the shape that `argparse` (`action="count"`) and `click`
+(`count=True`) produce: `-v` is `1`, `-vv` is `2`. One step shows `INFO`, two
+or more show `DEBUG`. A bool also works, as `0` or `1`, so `verbose=True` means
+`INFO`; a program that wants `DEBUG` from a plain switch passes `verbose=2`.
+
+## Quiet Wins
+Both flags together is a contradiction. Refusing it would turn a harmless
+shell alias (`alias tool="tool --verbose"`) plus a `-q` into an error, so the
+quieter wish is honored.
+
+## One Step Never Mutes
+`min(default_level, INFO)`: with a default of `DEBUG` a single `-v` keeps
+`DEBUG`. A flag that asks for more detail must not take detail away.
+
+## It Only Decides
+The function returns a level and configures nothing. Setting up logging is
+the job of whatever logging the program uses.
+"""