backpack-backbone 0.2.0__py3-none-any.whl

backbone/output.py

@@ -0,0 +1,216 @@
+"""The one place the CLI decides what its output looks like.
+
+Two modes, one set of calls. A command says *what* it produced (a table, a
+record, an event, a failure) and never how to render it, so adding `--json`
+needed no second code path and a new command gets both modes for free.
+
+Human tables are laid out by `prompt.core._table_widths` / `_render_table_row`,
+the same engine every list in the app uses, so a CLI table and a browse list
+agree about widths, truncation and which column drops first on a narrow
+terminal. Colour comes from `ui.Colors`, switched off process-wide by
+`ui.set_colour` rather than checked here.
+
+**Piping.** A list command prints its table when stdout is a terminal and one
+path per line when it is not, which is what `ls` does and what makes
+`tool list | tool read` work without a flag. `--json`
+overrides both.
+
+Exit codes are the module's other half: a command returns one, `cli.main`
+passes it to the shell.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from backbone.prompt import core as pc
+from backbone import ui
+
+# Exit codes. 0/1 are the shell's own conventions; the rest name the failures a
+# script would want to branch on without parsing a message.
+OK = 0            # it worked
+FAIL = 1          # it didn't, for a reason with no more specific code
+USAGE = 2         # the arguments were wrong
+NOT_FOUND = 3     # the thing asked for isn't there
+EXISTS = 4        # the thing asked for is there already
+NO_TOOL = 5       # a required external tool (ffmpeg, VLC) is missing
+
+# Bumped when a field changes meaning or goes away, never for an addition, so a
+# consumer can add fields without a version bump breaking it.
+SCHEMA_VERSION = 1
+
+_json = False
+_quiet = False
+
+
+def configure(*, json_mode: bool = False, quiet: bool = False,
+              colour: bool | None = None) -> None:
+    """Fix the output mode for the run. Called once, by `cli.main`.
+
+    `colour` defaults to `ui.colour_enabled()` (a terminal with NO_COLOR
+    unset), and JSON never carries colour whatever the terminal is.
+    """
+    global _json, _quiet
+    _json, _quiet = json_mode, quiet
+    if colour is None:
+        colour = ui.colour_enabled() and not json_mode
+    ui.set_colour(bool(colour))
+
+
+def json_mode() -> bool:
+    """Whether this run is emitting JSON."""
+    return _json
+
+
+def is_tty() -> bool:
+    """Whether stdout is a terminal: the switch between a table and bare paths."""
+    try:
+        return bool(sys.stdout.isatty())
+    except (AttributeError, ValueError):
+        return False
+
+
+def _envelope(kind: str, body: dict) -> dict:
+    """Wrap a payload with the fields every JSON object carries."""
+    return {'schema': SCHEMA_VERSION, 'kind': kind, **body}
+
+
+def _write(text: str = "") -> None:
+    """One line to stdout, flushed so a long run streams rather than buffers."""
+    sys.stdout.write(text + "\n")
+    sys.stdout.flush()
+
+
+def record(kind: str, body: dict, *, human: str | None = None) -> None:
+    """One object: a JSON line, or `human` (falling back to aligned key/value).
+
+    Used for the single-subject commands: `library stat`, one track's tags.
+    """
+    if _json:
+        _write(json.dumps(_envelope(kind, body)))
+        return
+    if _quiet:
+        return
+    if human is not None:
+        _write(human)
+        return
+    width = max((len(str(k)) for k in body), default=0)
+    dim, reset = ui.Colors.DIM, ui.Colors.RESET
+    for key, value in body.items():
+        _write(f"  {dim}{str(key).ljust(width)}{reset}  {human_value(value)}")
+
+
+def human_value(value) -> str:
+    """One config or record value on one line, for a person rather than a parser."""
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    if isinstance(value, list):
+        return ', '.join(str(v) for v in value) or '(none)'
+    if isinstance(value, dict):
+        return f"({len(value)} entries)"
+    return str(value)
+
+
+def table(kind: str, rows: list, columns: list, *,
+          cells=None, pipe_key: str = 'path') -> None:
+    """A list: JSON array, an aligned table on a terminal, or bare `pipe_key`s.
+
+    `rows` are dicts. `columns` are `prompt.core.Column` specs, and `cells` maps
+    one row to the list of strings those columns render, keeping the JSON
+    (whole objects) and the table (chosen fields) from having to agree on shape.
+    """
+    if _json:
+        _write(json.dumps(_envelope(kind, {'count': len(rows), 'items': rows})))
+        return
+    if _quiet:
+        return
+    if not rows:
+        if is_tty():
+            _write(f"  {ui.Colors.DIM}(nothing to show){ui.Colors.RESET}")
+        return
+    if not is_tty():
+        # Piped: one path per line, so the next command can read it on stdin.
+        for row in rows:
+            _write(str(row.get(pipe_key, '')))
+        return
+    cells = cells or (lambda r: [str(v) for v in r.values()])
+    body = [cells(r) for r in rows]
+    eff = ui.get_terminal_width() - 2 * ui.MARGIN_H
+    widths = pc._table_widths(body, columns, eff, 0, 0)
+    for cell_row in body:
+        _write(pc._render_table_row(cell_row, columns, False, widths, eff, 0))
+
+
+def event(kind: str, **fields) -> None:
+    """One step of a long operation: an NDJSON line, or a human progress line.
+
+    Flushed per event, so `tool run --json | jq` reports each file
+    as it happens rather than everything at the end.
+    """
+    if _json:
+        _write(json.dumps(_envelope('event', {'event': kind, **fields})))
+        return
+    if _quiet:
+        return
+    detail = fields.get('detail') or fields.get('path') or ''
+    mark = {'written': '✔', 'error': '✘'}.get(kind, '·')
+    _write(f"  {mark} {detail}")
+
+
+def note(text: str) -> None:
+    """An aside for a human: a count, a "nothing to do". Never emitted as JSON.
+
+    Anything a script needs belongs in a `record` or an `event`; this is the
+    sentence a person reads and a pipeline correctly ignores.
+    """
+    if not _json and not _quiet:
+        _write(f"  {text}")
+
+
+def fail(code: int, message: str, **context) -> int:
+    """Report a failure on stderr and return the exit code, for `return fail(…)`.
+
+    Under `--json` the shape is `{"error": {"code", "message", "context"}}`, with
+    `code` the symbolic name rather than the number so a consumer reads
+    `not_found` instead of remembering that 3 means that.
+    """
+    if _json:
+        body = _envelope('error', {'error': {
+            'code': code_name(code), 'message': message, 'context': context}})
+        sys.stderr.write(json.dumps(body) + "\n")
+    else:
+        accent, reset = ui.Colors.ACCENT, ui.Colors.RESET
+        detail = ''.join(f"\n  {k}: {v}" for k, v in context.items())
+        sys.stderr.write(f"{accent}✘{reset} {message}{detail}\n")
+    sys.stderr.flush()
+    return code
+
+
+_CODE_NAMES = {OK: 'ok', FAIL: 'failed', USAGE: 'usage', NOT_FOUND: 'not_found',
+               EXISTS: 'exists', NO_TOOL: 'missing_tool'}
+
+
+def code_name(code: int) -> str:
+    """The symbolic name for an exit code ('not_found' for 3)."""
+    return _CODE_NAMES.get(code, 'failed')
+
+
+def read_stdin_paths() -> list[str]:
+    """Paths piped in on stdin, one per line, blank lines and comments dropped.
+
+    The other half of `table`'s piped output, so a list of tracks flows into a
+    command that takes tracks. Returns [] when stdin is a terminal, so a command
+    with no arguments prompts or errors rather than hanging on a read that will
+    never end.
+    """
+    try:
+        if sys.stdin.isatty():
+            return []
+    except (AttributeError, ValueError):
+        return []
+    out = []
+    for line in sys.stdin:
+        line = line.strip()
+        if line and not line.startswith('#'):
+            out.append(line)
+    return out

backbone/procs.py

@@ -0,0 +1,60 @@
+"""Background processes a tool starts, finds and stops: its daemons, however
+they were launched."""
+import os
+import signal
+import subprocess
+import sys
+from itertools import dropwhile
+from pathlib import Path
+
+
+def ps_listing() -> str:
+    """Every running process's full command line, one per line."""
+    try:
+        return subprocess.run(["ps", "-Awwo", "command"], capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def find_processes(*names: str, launcher: str | None = None) -> list:
+    """(pid, command) for every running process whose program is one of
+    `names`, however it was started: `name`, `name.py`, `python3 name.py`, or
+    through a `launcher` command or package (`launcher name`,
+    `python3 -m launcher.name`). The calling process is never included."""
+    try:
+        out = subprocess.run(["ps", "-Awwo", "pid=,command="], capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    found = []
+    for line in out.splitlines():
+        pid, _, command = line.strip().partition(" ")
+        if not pid.isdigit() or int(pid) == os.getpid():
+            continue
+        args = list(dropwhile(lambda a: a.startswith("-") or Path(a).name.lower().startswith("python"), command.split()))
+        if not args:
+            continue
+        prog = Path(args[0]).name.removesuffix(".py")
+        if launcher and prog.startswith(launcher + "."):
+            prog = prog[len(launcher) + 1:]
+        if prog in names or (launcher and prog == launcher and len(args) > 1 and args[1] in names):
+            found.append((int(pid), command))
+    return found
+
+
+def stop_processes(*names: str, launcher: str | None = None) -> int:
+    """SIGTERMs every running process find_processes finds; returns how many."""
+    stopped = 0
+    for pid, _ in find_processes(*names, launcher=launcher):
+        try:
+            os.kill(pid, signal.SIGTERM)
+            stopped += 1
+        except OSError:
+            pass
+    return stopped
+
+
+def spawn_module(module: str, out_path: Path) -> None:
+    """Run `python -m module` in the background with this interpreter, its
+    output (unbuffered, so it can be read while it runs) appended to `out_path`."""
+    with open(out_path, "ab") as out:     # the child keeps its own copy of the handle
+        subprocess.Popen([sys.executable, "-u", "-m", module], stdout=out, stderr=subprocess.STDOUT)

backbone/prompt/__init__.py

@@ -0,0 +1,20 @@
+"""The prompt widgets, one import: lists (select, live_select, confirm,
+ListPlace), text (text, path, system_editor_edit), list_edit, dates, values,
+audio, and the shared chrome."""
+from backbone.prompt.core import (  # noqa: F401
+    Choice, Column, separator, HINTS_CLICK, add_help_corner, add_hint_click_cells,
+    help_corner_text, help_toggle_width, hints_visible, is_hints_key, rounded_header, toggle_hints,
+)
+from backbone.prompt.chrome import (  # noqa: F401
+    CHROME_HANDLED, CHROME_REDRAW, MODE_TOGGLE, move_hint,
+    append_chrome, chrome_hint_lines, chrome_hint_pairs, consume_chrome,
+    disable_mouse, enable_mouse,
+    set_activity_opener, set_player_opener, set_transport_handler,
+)
+from backbone.prompt.text import path, system_editor_edit, text  # noqa: F401
+from backbone.prompt.lists import ListPlace, confirm, live_select, options_menu, select  # noqa: F401
+from backbone.prompt.list_edit import list_edit  # noqa: F401
+from backbone.prompt.dates import calendar_select, datetime_edit  # noqa: F401
+from backbone.prompt.values import fraction_edit, number_edit, rating_edit, time_edit  # noqa: F401
+from backbone.prompt.audio import equaliser_edit, rva2_edit  # noqa: F401
+from backbone.prompt.keymap import keys_editor  # noqa: F401