jumble-cli 0.1.0__py3-none-any.whl

jumble/__init__.py

@@ -0,0 +1,6 @@
+"""Random string generator, with a command line and a Textual TUI."""
+
+from jumble.cli import main
+from jumble.generate import CHARSETS, JumbleError, Settings, generate, strength, validate
+
+__all__ = ["CHARSETS", "JumbleError", "Settings", "generate", "main", "strength", "validate"]

jumble/__main__.py

@@ -0,0 +1,3 @@
+from jumble.cli import main
+
+raise SystemExit(main())

jumble/cli.py

@@ -0,0 +1,271 @@
+"""The `jumble` command (docs/spec.md §4)."""
+
+import argparse
+import importlib.metadata
+import json
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from jumble.config import config_path, file_settings, load
+from jumble.generate import (
+    CHARSETS,
+    LOOK_ALIKES,
+    JumbleError,
+    Settings,
+    Strength,
+    check_names,
+    generate,
+    settings_dict,
+    strength,
+    strength_line,
+)
+
+DEFAULTS = Settings()
+
+# The PyPI distribution; `jumble` there is someone else's (DEC-24).
+DISTRIBUTION = "jumble-cli"
+
+# The settings a command-line flag can only turn on (§5.2, DEC-9).
+BOOLEANS = ("no_ambiguous", "each", "no_repeat", "unique")
+
+
+def installed_version() -> str:
+    """The installed package's version, as `--version` and the TUI header show it (§4, §7.1)."""
+    return importlib.metadata.version(DISTRIBUTION)
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="jumble",
+        # Bare jumble's two routes (§4, DEC-21).
+        description="Generate random strings. jumble alone, typed in a terminal, opens the "
+        "interactive generator, as jumble tui does; piped, in a script, or with any option, "
+        "it prints.",
+    )
+    # -n, -c, and --custom default to None, so an option given at its default
+    # value still overrides the settings file (§5.2).
+    p.add_argument(
+        "-n",
+        "--length",
+        type=int,
+        metavar="N",
+        help=f"characters per string (default {DEFAULTS.length})",
+    )
+    p.add_argument(
+        "-c",
+        "--count",
+        type=int,
+        metavar="N",
+        help=f"how many strings (default {DEFAULTS.count})",
+    )
+    # No argparse choices: validation reports unknown and empty names (§2.2, §6).
+    p.add_argument(
+        "-s",
+        "--charset",
+        action="append",
+        default=[],
+        metavar="NAME[,NAME...]",
+        help="character sets to draw from; repeat or separate with commas. "
+        f"Sets: {', '.join(CHARSETS)} "
+        f"(default: {', '.join(DEFAULTS.charsets)}, when neither --custom nor the "
+        "settings file chooses characters)",
+    )
+    p.add_argument(
+        "--custom",
+        metavar="CHARS",
+        help="also draw from these characters, as one more set",
+    )
+    p.add_argument(
+        "-a",
+        "--no-ambiguous",
+        action="store_true",
+        help=f"leave out look-alike characters: {' '.join(LOOK_ALIKES)}",
+    )
+    p.add_argument(
+        "-e", "--each", action="store_true", help="at least one character from every chosen set"
+    )
+    p.add_argument(
+        "-r", "--no-repeat", action="store_true", help="no character twice within a string"
+    )
+    p.add_argument("-u", "--unique", action="store_true", help="no string twice in the output")
+    # Default None, so `-o -` can be told apart from no -o (§4).
+    p.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="write to FILE, created or overwritten, instead of stdout; - means stdout",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="write one JSON object with the strings, their strength, and the settings used",
+    )
+    p.add_argument(
+        "--strength",
+        action="store_true",
+        help="also print the alphabet size and bits per string to stderr",
+    )
+    p.add_argument(
+        "--no-config",
+        action="store_true",
+        help=f"ignore the settings file ({config_path()})",
+    )
+    # argparse prints and exits as it reaches it, before any file is read (§4).
+    p.add_argument(
+        "--version",
+        action="version",
+        version=f"jumble {installed_version()}",
+        help="print the version and exit",
+    )
+    sub = p.add_subparsers(dest="command")
+    sub.add_parser(
+        "tui",
+        # It starts from the effective settings, the file's included (§7.5).
+        help="open the interactive generator, starting from the settings file and the "
+        "options before tui (not with --output, --json, or --strength)",
+        description="Open the interactive generator. It starts from the settings file, "
+        "and options given before tui override it, for example: jumble -n 32 -s digits tui",
+    )
+    return p
+
+
+def settings_from(args: argparse.Namespace, file: Mapping[str, Any]) -> Settings:
+    """One `Settings` from parsed arguments over the settings file's keys (§5.2, DEC-9).
+
+    Built-in defaults, then `file` (what `config.load` returned, or `{}`), then
+    the command line. `length`, `count`, and the booleans go key by key; an
+    option counts when it is given, even at its default value, and a flag
+    only turns its option on. The characters go as a whole: `-s` or
+    `--custom` (even `--custom ''`) replaces both of the file's `charsets` and
+    `custom`. The default sets apply only when no level chose any. The
+    command line is laid over the file's keys and merged by
+    `config.file_settings`, so there is one merge.
+    """
+    values = dict(file)
+    for key in ("length", "count"):
+        if getattr(args, key) is not None:
+            values[key] = getattr(args, key)
+    for key in BOOLEANS:
+        if getattr(args, key):
+            values[key] = True
+    names = tuple(name for value in args.charset for name in value.split(","))
+    if names or args.custom is not None:
+        values["charsets"], values["custom"] = names, args.custom or ""
+    return file_settings(values)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    p = parser()
+    if argv is None:
+        argv = sys.argv[1:]
+    # Bare jumble at a prompt is jumble tui; piped or scripted, it prints (§4, DEC-21).
+    # The TUI needs both streams, so a terminal on stdout alone isn't enough.
+    if not argv and is_terminal(sys.stdin) and is_terminal(sys.stdout):
+        argv = ["tui"]
+    args = p.parse_args(argv)
+    if args.command == "tui":
+        # Before the TUI starts or any file is touched; -o - counts as given (§4, §6).
+        misused = (
+            ("--output", args.output is not None),
+            ("--json", args.json),
+            ("--strength", args.strength),
+        )
+        for option, given in misused:
+            if given:
+                p.error(f"{option} can't be used with tui")
+        file_error = None
+        try:
+            file = {} if args.no_config else load(config_path())
+        except JumbleError as e:
+            # The TUI starts as if --no-config were given and toasts the
+            # message, so the file can be repaired from there (§7.4, DEC-17).
+            file, file_error = {}, str(e)
+        settings = settings_from(args, file)
+        try:
+            # Only a name no checkbox can hold stops the TUI; any other bad
+            # value starts it with the banner shown (§7.5, DEC-16).
+            check_names(settings.charsets)
+        except JumbleError as e:
+            print(f"jumble: error: {e}", file=sys.stderr)
+            return 2
+        from jumble.tui import JumbleApp
+
+        JumbleApp(settings, file_error=file_error).run()
+        return 0
+    # Generate everything before opening any output, so a failed run writes
+    # nothing and leaves an existing -o file as it was (§4.1, DEC-8).
+    try:
+        # A broken file stops the run even where the command line overrides
+        # the bad key (§5.1, DEC-17); --no-config doesn't read it at all.
+        file = {} if args.no_config else load(config_path())
+        settings = settings_from(args, file)
+        strings = generate(settings)
+    except JumbleError as e:
+        # The message is the whole output, with no usage line (§6).
+        print(f"jumble: error: {e}", file=sys.stderr)
+        return 2
+    # After generate, so a failed run's error is generate's.
+    st = strength(settings)
+    text = json_output(strings, settings, st) if args.json else "".join(f"{s}\n" for s in strings)
+    data = text.encode()
+    to_stdout = args.output is None or args.output == "-"
+    try:
+        write_output(args.output, data)
+    except OSError as e:
+        if not to_stdout:
+            print(f"jumble: error: can't write {args.output}: {e.strerror}", file=sys.stderr)
+        elif isinstance(e, BrokenPipeError):
+            # The reader closed the pipe and got what it asked for: exit quietly (§6, DEC-14).
+            quiet_stdout()
+        else:
+            print(f"jumble: error: can't write stdout: {e.strerror}", file=sys.stderr)
+        return 1
+    if args.strength:
+        # After the output, and only for a run that succeeded (§4.3).
+        print(strength_line(st), file=sys.stderr)
+    return 0
+
+
+def is_terminal(stream: Any) -> bool:
+    """Whether `stream` is a terminal; a closed standard stream (`None`) is not."""
+    return stream is not None and stream.isatty()
+
+
+def json_output(strings: list[str], settings: Settings, st: Strength) -> str:
+    """The §4.2 object for `strings`, drawn from `settings` of strength `st`, and a newline."""
+    obj = {
+        "strings": strings,
+        "alphabet_size": st.alphabet_size,
+        "strength_bits": round(st.bits, 1),
+        "strength_is_bound": st.is_bound,
+        "settings": settings_dict(settings),
+    }
+    return json.dumps(obj, indent=2, ensure_ascii=False) + "\n"
+
+
+def write_output(path: str | None, data: bytes) -> None:
+    """Write `data` to stdout when `path` is None or `-`, else to the file `path` (§4.1).
+
+    Stdout gets the bytes through its binary buffer, so output is UTF-8 whatever
+    the locale's encoding.
+    """
+    if path is None or path == "-":
+        sys.stdout.flush()
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+        return
+    with open(path, "wb") as f:
+        f.write(data)
+
+
+def quiet_stdout() -> None:
+    """Point fd 1 at the null device after a closed pipe (DEC-14).
+
+    Stdout's buffer may still hold bytes; the flush at interpreter exit then
+    has somewhere to go instead of printing `Exception ignored … BrokenPipeError`.
+    This is the recipe in the Python `signal` docs' note on SIGPIPE.
+    """
+    devnull = os.open(os.devnull, os.O_WRONLY)
+    os.dup2(devnull, sys.stdout.fileno())

jumble/config.py

@@ -0,0 +1,182 @@
+"""The settings file (docs/spec.md §5): reading it, and saving over it.
+
+Section numbers below refer to the spec.
+"""
+
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import fields, replace
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from tomlkit.exceptions import TOMLKitError
+
+from jumble.generate import JumbleError, Settings, check_value, settings_dict
+
+# §1's setting names, in §1's order.
+NAMES: tuple[str, ...] = tuple(f.name for f in fields(Settings))
+
+
+def config_path() -> Path:
+    """Where the settings file is (§5.1, DEC-10).
+
+    `$JUMBLE_CONFIG` if set and not empty, as given; else
+    `$XDG_CONFIG_HOME/jumble/config.toml` if that is an absolute path; else
+    `~/.config/jumble/config.toml`, on macOS too.
+    """
+    if given := os.environ.get("JUMBLE_CONFIG"):
+        return Path(given)
+    xdg = Path(os.environ.get("XDG_CONFIG_HOME", ""))
+    if xdg.is_absolute():
+        return xdg / "jumble" / "config.toml"
+    return Path.home() / ".config" / "jumble" / "config.toml"
+
+
+def _type_word(name: str, value: object) -> str | None:
+    """The §6 type word when `value` hasn't setting `name`'s type (§5.1), else None."""
+    if name in ("length", "count"):
+        # A TOML boolean is a Python bool, which is an int too: rule it out.
+        ok = isinstance(value, int) and not isinstance(value, bool)
+        return None if ok else "an integer"
+    if name == "charsets":
+        ok = isinstance(value, list) and all(isinstance(v, str) for v in value)
+        return None if ok else "a list of set names"
+    if name == "custom":
+        return None if isinstance(value, str) else "a string"
+    return None if isinstance(value, bool) else "a boolean"
+
+
+def load(path: Path) -> dict[str, object]:
+    """The settings file at `path`, as its keys and values in the file's order.
+
+    A missing file is `{}`. Anything else wrong raises `JumbleError` with the
+    §6 settings-file message for the first error, checked in §5.1's order:
+    reading, then UTF-8 and TOML, then each key's name, type, and own rule.
+    Rules that relate settings to each other are left to `validate` (DEC-17).
+    """
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return {}
+    except OSError as e:
+        raise JumbleError(f"can't read {path}: {e.strerror}") from e
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise JumbleError(f"{path}: invalid TOML: not UTF-8") from e
+    try:
+        table = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise JumbleError(f"{path}: invalid TOML: {e}") from e
+
+    for key, value in table.items():
+        if key not in NAMES:
+            raise JumbleError(f"{path}: {key}: unknown setting")
+        if word := _type_word(key, value):
+            raise JumbleError(f"{path}: {key}: must be {word}")
+        try:
+            check_value(key, value)
+        except JumbleError as e:
+            raise JumbleError(f"{path}: {key}: {e}") from e
+    return table
+
+
+def file_settings(file: Mapping[str, Any]) -> Settings:
+    """The built-in defaults, then `file`'s keys, merged as §5.2 merges them (DEC-9).
+
+    `file` is what `load` returned, or `{}`. `length`, `count`, and the four
+    options go key by key. The characters go as a whole: a file that sets
+    `charsets` or `custom` chooses with both, so `custom = "abc"` alone
+    chooses no named set; the default sets apply only when neither chooses
+    any. `cli.settings_from` lays the command line over the file and merges
+    through here, and the settings screen fills its form from this (§7.4).
+    """
+    defaults = Settings()
+    values = {key: file[key] for key in NAMES if key in file}
+    charsets = tuple(values.pop("charsets", ()))
+    custom = values.pop("custom", "")
+    if not charsets and not custom:
+        # Nothing chose any characters, so the default sets apply (§1, DEC-9).
+        charsets = defaults.charsets
+    return replace(defaults, **values, charsets=charsets, custom=custom)
+
+
+# A new file starts from this, with the saved values in place of these
+# defaults (§5.3); a test holds it to the spec's copy.
+TEMPLATE = """\
+# jumble settings. Every key is optional; options given on the command
+# line override them. See `jumble --help` for the character sets.
+
+# Characters per string, at least 1.
+length = 16
+# How many strings, at least 1.
+count = 1
+# The named sets to draw from.
+charsets = ["lower", "upper", "digits"]
+# Extra characters, drawn as one more set.
+custom = ""
+# Leave out look-alike characters such as 0 O l 1 I.
+no_ambiguous = false
+# At least one character from every chosen set.
+each = false
+# No character twice within a string.
+no_repeat = false
+# No string twice in the output.
+unique = false
+"""
+
+
+def _document(path: Path) -> tomlkit.TOMLDocument:
+    """The file at `path` to save over, or the template in its place (§5.3 step 1).
+
+    A missing file, or one that is not UTF-8 or not valid TOML, is replaced
+    by the template; a file that exists but can't be read raises `JumbleError`.
+    """
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return tomlkit.parse(TEMPLATE)
+    except OSError as e:
+        raise JumbleError(f"can't save {path}: {e.strerror}") from e
+    try:
+        text = data.decode("utf-8")
+        # Valid TOML is what `load` reads: tomlkit also parses TOML 1.1, which
+        # tomllib rejects, and a line kept from such a file would still break
+        # the command line (DEC-19).
+        tomllib.loads(text)
+        return tomlkit.parse(text)
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError, TOMLKitError):
+        return tomlkit.parse(TEMPLATE)
+
+
+def save(path: Path, settings: Settings) -> None:
+    """Write `settings` to the settings file at `path`, keeping what it can (§5.3, DEC-18).
+
+    Unknown keys are removed; a key whose value already equals the saved one,
+    in TOML type and value, is left as it is, comments and all; any other is
+    replaced on its own line, and a missing one is appended. The write is in
+    place, through a symlink, after creating missing parent directories. A
+    file that can't be read or written raises `JumbleError` with
+    `can't save PATH: REASON` (§7.4). Pass settings that have passed
+    `validate`.
+    """
+    doc = _document(path)
+    for key in [key for key in doc if key not in NAMES]:
+        del doc[key]
+    for key, value in settings_dict(settings).items():
+        if key in doc:
+            old = doc.item(key).unwrap()
+            # Same type, then same value: `True == 1` and `16.0 == 16` would
+            # otherwise leave `length = true` and `length = 16.0` in place.
+            if type(old) is type(value) and old == value:
+                continue
+        # Replaces the value in place, keeping the line's comment, or appends
+        # `KEY = VALUE` at the end.
+        doc[key] = value
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(tomlkit.dumps(doc).encode("utf-8"))
+    except OSError as e:
+        raise JumbleError(f"can't save {path}: {e.strerror}") from e