backpack-backbone 0.2.0__tar.gz → 0.3.0__tar.gz

{backpack_backbone-0.2.0/backpack_backbone.egg-info → backpack_backbone-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backpack-backbone
-Version: 0.2.0
+Version: 0.3.0
 Summary: Shared code for the back* tools: terminal UI, prompt widgets, live views, logging, dates, settings plumbing and small file helpers, implemented once.
 License: MIT
 Project-URL: Homepage, https://github.com/RedEraRrow/backbone

backpack_backbone-0.3.0/backbone/nav.py

@@ -0,0 +1,198 @@
+"""nav.py - app-wide navigation breadcrumb and the quit-to-terminal signal,
+shared by every back* tool that uses backbone's prompt widgets.
+"""
+NAV_STACK = ["Home"]
+
+
+class QuitToTerminal(BaseException):
+    """Raised to unwind the entire menu stack and exit straight to the
+    terminal. Derives from BaseException (not Exception) so it bypasses
+    ``except Exception`` handlers in editors/widgets and propagates cleanly
+    up to the app's main(), where the alt-screen is restored in a finally.
+
+    `q` quits an app from anywhere by raising this on the spot - there is
+    deliberately no "leave this widget and quit later" flag: `q` is never a
+    way out of a widget; Esc (or <-/b where a widget has no other use for
+    them) is what backs out.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Tabs. Each tab's screen loop runs in its own thread, but only one at a time:
+# switching hands the turn to the other tab's thread and parks this one where it
+# is, so every tab comes back exactly as it was left, however deep its menus go.
+import queue as _queue
+import sys as _sys
+import threading as _threading
+from contextlib import contextmanager as _contextmanager
+
+TABS: list = []                 # (name, run) pairs while an app runs as tabs
+_active = [0]                   # the tab on screen
+_turns: dict = {}               # tab index → Event set while it's that tab's turn
+_visits: list = []              # tabs most recently shown last, for going back
+_stacks: dict = {}              # each tab's breadcrumb, kept while another shows
+_ended: _queue.Queue = _queue.Queue()
+_mine = _threading.local()      # .tab: the tab this thread runs
+_modal = [0]                    # screens inside nav.modal(): no switching
+_base_tty = [None]              # the terminal as run_tabs found it: each tab starts so
+_fresh: set = set()             # tabs to start again from the top when next shown
+
+
+class _StartAfresh(BaseException):
+    """Unwinds a parked tab back to its start (go_to_tab's `fresh`)."""
+
+
+def _tty():
+    """The terminal's attributes, or None (Windows, or not a terminal)."""
+    try:
+        import termios
+        return termios.tcgetattr(_sys.stdin.fileno())
+    except Exception:
+        return None
+
+
+def _set_tty(attrs) -> None:
+    if attrs is not None:
+        import termios
+        termios.tcsetattr(_sys.stdin.fileno(), termios.TCSADRAIN, attrs)
+
+
+def run_tabs(tabs: list, home: int = 0) -> None:
+    """Run an app as tabs, `tabs` being (name, run) pairs, starting on `home`,
+    until a tab raises (QuitToTerminal to quit, or a crash), which is raised here.
+
+    A tab whose run() returns (backed out of its top level) goes back to the tab
+    shown before it, or, with none, `home` starts again."""
+    _base_tty[0] = _tty()
+    crumb = NAV_STACK[:]
+    TABS[:] = tabs
+    try:
+        _show(home)
+        while True:
+            try:   # a timeout, so signals (a resize) still reach this, the main thread
+                i, exc = _ended.get(timeout=0.2)
+            except _queue.Empty:
+                continue
+            _turns.pop(i, None)
+            _stacks.pop(i, None)
+            if i in _visits:
+                _visits.remove(i)
+            if exc is not None:
+                raise exc
+            _show(_visits[-1] if _visits else home)
+    finally:
+        # Tabs still parked stay parked: their threads die with the app.
+        TABS.clear()
+        _turns.clear(); _visits.clear(); _stacks.clear(); _fresh.clear()
+        _active[0] = 0
+        NAV_STACK[:] = crumb
+        _set_tty(_base_tty[0])  # parked tabs never get to restore it themselves
+
+
+def _show(i: int) -> None:
+    """Make tab `i` the one on screen and give it the turn, starting its thread
+    on its first visit."""
+    if _active[0] in _turns:            # still running: keep its breadcrumb
+        _stacks[_active[0]] = NAV_STACK[:]
+    _active[0] = i
+    NAV_STACK[:] = _stacks.get(i) or [TABS[i][0]]
+    if i in _visits:
+        _visits.remove(i)
+    _visits.append(i)
+    if i not in _turns:
+        _turns[i] = _threading.Event()
+        _threading.Thread(target=_tab_thread, args=(i,), daemon=True,
+                          name=f"tab-{TABS[i][0]}").start()
+    _turns[i].set()
+
+
+def _tab_thread(i: int) -> None:
+    _mine.tab = i
+    _turns[i].wait()
+    _set_tty(_base_tty[0])
+    _fresh.discard(i)
+    exc = None
+    while True:
+        try:
+            TABS[i][1]()
+        except _StartAfresh:
+            NAV_STACK[:] = [TABS[i][0]]
+            continue
+        except BaseException as e:      # handed to run_tabs, which raises it
+            exc = e
+        break
+    _ended.put((i, exc))
+
+
+@_contextmanager
+def modal():
+    """For a screen that mustn't be left for another tab (one playing its own
+    audio): inside it, tab keys and clicks do nothing and the bar is dimmed."""
+    _modal[0] += 1
+    try:
+        yield
+    finally:
+        _modal[0] -= 1
+
+
+def is_modal() -> bool:
+    return _modal[0] > 0
+
+
+def active_tab() -> int:
+    """The tab on screen."""
+    return _active[0]
+
+
+def current_tab() -> int | None:
+    """The tab this thread runs, or None outside tabs."""
+    return getattr(_mine, 'tab', None) if TABS else None
+
+
+def switch_to(j: int) -> None:
+    """From a tab's thread, show tab `j`; returns once this tab is shown again,
+    with the terminal as it was."""
+    i = current_tab()
+    if i is None or j == i:
+        return
+    attrs = _tty()
+    _turns[i].clear()
+    _show(j)
+    _turns[i].wait()
+    _set_tty(attrs)
+    if i in _fresh:
+        _fresh.discard(i)
+        raise _StartAfresh()
+
+
+def go_to_tab(name: str, fresh: bool = False) -> bool:
+    """Show the tab called `name` from another tab, returning (True) once that
+    one is left. False, doing nothing, outside tabs or already on it.
+    `fresh`: that tab starts again from the top rather than where it was left
+    (for a tab told where to open)."""
+    names = [n for n, _run in TABS]
+    if current_tab() is None or name not in names or names.index(name) == current_tab():
+        return False
+    if fresh:
+        _fresh.add(names.index(name))
+    switch_to(names.index(name))
+    return True
+
+
+def tab_for(key: str, use_keys: bool = True) -> int | None:
+    """The tab a key or click asks for: a click on the tab bar, F1, F2… (keys
+    nothing types, so they work on any screen), and with `use_keys` Tab /
+    Shift-Tab. None when it isn't one, or is the tab already showing."""
+    if current_tab() is None or is_modal() or not isinstance(key, str):
+        return None
+    n, i, j = len(TABS), _active[0], None
+    if key.startswith('MOUSE_CLICK:'):
+        parts = key.split(':')
+        from backbone import ui
+        if len(parts) > 3 and parts[2].isdigit() and int(parts[2]) <= ui.tab_rows():
+            j = ui.tab_at(int(parts[3]))
+    elif use_keys and key in ('TAB', 'BACKTAB'):
+        j = (i + (1 if key == 'TAB' else -1)) % n
+    elif key[:1] == 'F' and key[1:].isdigit() and 1 <= int(key[1:]) <= n:
+        j = int(key[1:]) - 1
+    return j if j != i else None

backpack_backbone-0.3.0/backbone/prompt/__init__.py

@@ -0,0 +1,21 @@
+"""The prompt widgets, one import: lists (select, live_select, confirm,
+ListPlace), text (text, path, multiline, system_editor_edit), list_edit, dates, values,
+audio, and the shared chrome."""
+from backbone.prompt.core import (  # noqa: F401
+    Choice, Column, JumpTo, Pane, PanelTitle, Preview, Trail, box_fits, box_lines, separator, HINTS_CLICK, add_help_corner, add_hint_click_cells,
+    help_corner_text, path_box, help_toggle_shown, help_toggle_width, hints_visible, is_hints_key, place_help_toggle, rounded_header,
+    set_help_toggle_shown, toggle_hints, columns_shown, set_columns_shown,
+)
+from backbone.prompt.chrome import (  # noqa: F401
+    CHROME_HANDLED, CHROME_REDRAW, MODE_TOGGLE, move_hint,
+    append_chrome, boxed_chrome, chrome_hint_lines, chrome_hint_pairs, consume_chrome, inner_rule,
+    disable_mouse, enable_mouse,
+    open_command_line, set_activity_opener, set_command_line, set_player_opener, set_transport_handler,
+)
+from backbone.prompt.text import multiline, overlay_checklist, overlay_text, path, system_editor_edit, text, token_completions  # 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

{backpack_backbone-0.2.0 → backpack_backbone-0.3.0}/backbone/prompt/audio.py

@@ -8,8 +8,9 @@ from backbone.prompt.core import (
 from backbone import keys, ui
 from backbone.nav import QuitToTerminal
 from backbone.prompt.chrome import (
-    append_chrome, CHROME_HANDLED, chrome_hint_lines, CHROME_REDRAW, consume_chrome, disable_mouse, enable_mouse,
+    boxed_chrome, CHROME_HANDLED, chrome_hint_lines, CHROME_REDRAW, consume_chrome, disable_mouse, enable_mouse,
 )
+from backbone.prompt.core import box_fits
 from backbone.prompt.text import text
 from backbone.prompt.core import C
 
@@ -89,11 +90,9 @@ def _eq_fmt_freq(freq: float) -> str:
 def _eq_render_lines(bands: list, cursor: int, message: str, status: str,
                      cols: int, rows: int, show_curve: bool = True) -> list[str]:
     """Render the graphic-EQ plot: vertical bands from a 0 dB baseline, a dim
-    response curve through the band tops, dB axis and frequency labels."""
-    out = [
-        f"  {C.DIM}{message}{C.RESET}",
-        f"{C.DIM}{'─' * ui.get_terminal_width()}{C.RESET}",
-    ]
+    response curve through the band tops, dB axis and frequency labels. Two
+    rows of `rows` are left for the box's borders (boxed_chrome titles it)."""
+    out = []
     n = len(bands)
     plot_w = max(10, cols - 5)              # 4 cols for the dB label + 1 gap
     avail = rows - 9
@@ -208,11 +207,9 @@ def _rva2_render_lines(gain: float, message: str, avail: int | None = None) -> l
       Cut rows  (db < 0): bar fills downward; ▀ lights first (top half, at gain ≤ db+0.5),
                            then █ when gain ≤ db.
     Every 0.5 dB step changes a visible half-block, so no increment is invisible.
+    The box around it (boxed_chrome) carries `message`.
     """
-    out = [
-        f"  {C.DIM}{message}{C.RESET}",
-        f"{C.DIM}{'─' * 20}{C.RESET}",
-    ]
+    out = []
 
     # One row per dB is the ideal, but the meter must still fit above the hint
     # bar and the now-playing box: on a short terminal it would otherwise run off the
@@ -280,7 +277,7 @@ def rva2_edit(message: str = "Volume adjustment:", gain: float = 0.0) -> float |
         _avail = _hint_pin_target() - 4 - len(chrome_hint_lines(_pairs))
         lines = _rva2_render_lines(gain, message, avail=_avail)
         lines.append(f"  {C.ACCENT}▸{C.RESET} {C.BOLD}{gain:+.1f} dB{C.RESET}")
-        append_chrome(lines, _pairs, _hint_cells)
+        lines, _dx = boxed_chrome(lines, message, _pairs, _hint_cells)
         w.render(lines)
 
     result = None
@@ -362,6 +359,11 @@ def equaliser_edit(message: str = "Equalisation:", adjustments: list | None = No
     old = _get_term_attrs(fd)
     w = _Widget(fd)
     _hint_cells: dict = {}   # clickable hint keys, filled by append_chrome
+    _dx = [0]                # how far right the box moved the plot (boxed_chrome)
+
+    def _plot_cols() -> int:
+        """The width the plot is laid out in: inside the box, when there is one."""
+        return _cols() - (4 if box_fits() else 0)
 
     def _clamp(g: float) -> float:
         return max(-_EQ_GAIN_MAX, min(_EQ_GAIN_MAX, g))
@@ -388,9 +390,9 @@ def equaliser_edit(message: str = "Equalisation:", adjustments: list | None = No
                   (L("levels.delete", most=1), "delete"), (L("levels.zero"), "zero"), (L("levels.flat"), "flat"),
                   (L("levels.preset"), "preset"), (L("levels.save"), "save"), (L("levels.back"), "back"),
                   (L("list.quit"), "quit app")]
-        lines = _eq_render_lines(bands, cursor, message, status, _cols(),
+        lines = _eq_render_lines(bands, cursor, message, status, _plot_cols(),
                                  _hint_pin_target() - len(chrome_hint_lines(_pairs)))
-        append_chrome(lines, _pairs, _hint_cells, help_key=True)
+        lines, _dx[0] = boxed_chrome(lines, message, _pairs, _hint_cells, help_key=True)
         w.render(lines)
 
     result = None
@@ -458,7 +460,7 @@ def equaliser_edit(message: str = "Equalisation:", adjustments: list | None = No
             elif act == 'levels.add':
                 _restore_term_attrs(fd, old)
                 disable_mouse()
-                freq_str = text("Add band frequency (Hz):")
+                freq_str = text("Band frequency in Hz:")
                 _set_raw(fd)
                 enable_mouse()
                 screen_takeover_next()   # paint over the previous screen, no flash
@@ -481,8 +483,8 @@ def equaliser_edit(message: str = "Equalisation:", adjustments: list | None = No
             elif key.startswith('MOUSE_CLICK:') and n:
                 parts = key.split(':')
                 col = int(parts[3]) if len(parts) > 3 else 1
-                plot_w = max(10, _cols() - 5)
-                x = col - 5  # the 3-col dB label + a space; the plot starts at col 5
+                plot_w = max(10, _plot_cols() - 5)
+                x = col - 5 - _dx[0]  # the 3-col dB label + a space; the plot starts at col 5, then the box's shift
                 if 0 <= x < plot_w:
                     bx = _eq_band_x(n, plot_w)
                     cursor = min(range(n), key=lambda i: abs(bx[i] - x))

{backpack_backbone-0.2.0 → backpack_backbone-0.3.0}/backbone/prompt/chrome.py

@@ -3,10 +3,11 @@ player and transport keys, mouse reporting, and the per-edit raw-text toggle."""
 from __future__ import annotations
 import sys
 from backbone.prompt.core import (
-    _IS_WINDOWS, _hint, add_hint_click_cells, footer_click_action, _hint_pin_target,
+    box_fits, boxed_frame, render_status_bar, C,
+    _IS_WINDOWS, FOOTER_ACTIONS, _hint, add_hint_click_cells, footer_click_action, _hint_pin_target,
     screen_invalidate, HINTS_CLICK, is_hints_key, toggle_hints, place_help_toggle,
 )
-from backbone import keys, ui
+from backbone import keys, nav, ui
 
 
 # Live on every screen: the background-audio transport (routed through
@@ -74,6 +75,26 @@ def set_player_opener(fn) -> None:
     _player_opener = fn
 
 
+_command_line = None
+
+
+def set_command_line(fn) -> None:
+    """Register a ``callable()`` that `:` opens, where a screen leaves it free.
+    It returns whether it opened a screen of its own (the screen under it then
+    needs drawing again)."""
+    global _command_line
+    _command_line = fn
+
+
+def open_command_line() -> bool | None:
+    """Run the registered command line: whether it opened a screen of its own;
+    None when there is none to run here (none registered, or a screen that
+    keeps you in it, nav.modal())."""
+    if _command_line is None or nav.is_modal():
+        return None
+    return bool(_command_line())
+
+
 # --- shared widget chrome -------------------------------------------------
 # Every screen owes the user the same four things: a hint bar pinned above the
 # now-playing box and status bar so its keys never move, those keys clickable, the
@@ -135,15 +156,43 @@ def append_chrome(out: list, pairs, cells: dict, *, extra: str = "",
     if hint_lines:
         start = len(out) - len(hint_lines)
         for k in range(len(hint_lines)):
-            # `_Widget.render` lays line j at terminal row anchor(1) + MARGIN_V + j.
+            # `_Widget.render` lays line j at terminal row anchor(1) + top_margin() + j.
             add_hint_click_cells(cells, out[start + k],
-                                 1 + ui.MARGIN_V + (start + k), items)
-    place_help_toggle(out, 1 + ui.MARGIN_V, cells, help_key)
+                                 1 + ui.top_margin() + (start + k), items)
+    place_help_toggle(out, 1 + ui.top_margin(), cells, help_key)
     return out
 
 
-def consume_chrome(key: str, cells: dict):
-    """Handle a transport key, a now-playing box click, or a click on a hint key.
+def inner_rule() -> str:
+    """A divider across the inside of a widget's box (boxed_chrome)."""
+    return f"  {C.DIM}{'─' * max(1, ui.get_terminal_width() - 2 * ui.MARGIN_H - 4)}{C.RESET}"
+
+
+def boxed_chrome(body: list, title: str, pairs, cells: dict, *, extra: str = "",
+                 help_key: bool = False, header: list | None = None) -> tuple[list, int]:
+    """A widget's whole frame: any `header` lines, then `body` (lines with the
+    usual left margin) in a box titled `title` that reaches down to the hint
+    bar, then the bar (append_chrome). In a window too small for a box, `title`
+    is a line above the body instead. Either way the body starts one line under
+    the header; returns the lines and how many columns right the body moved (2
+    inside the box, for "│ " where the margin was), for a widget that maps
+    clicks on its body."""
+    title, header = title.strip().rstrip(":"), list(header or [])
+    if not box_fits():
+        out = header + [f"  {C.DIM}{title}{C.RESET}"] + list(body)
+        append_chrome(out, pairs, cells, extra=extra, help_key=help_key)
+        return out, 0
+    box_h = max(3, _hint_pin_target() - len(header) - len(chrome_hint_lines(pairs, extra=extra)))
+    out = boxed_frame(header, list(body), title, box_h, help_key and not header)
+    append_chrome(out, pairs, cells, extra=extra, help_key=help_key)
+    return out, 2
+
+
+def consume_chrome(key: str, cells: dict, free_keys: bool = False):
+    """Handle a transport key, a now-playing box click, a click on a hint key,
+    or a click on the tab bar. With `free_keys` (a screen that has no other use
+    for them), also Tab / Shift-Tab and the digits for the tabs, and `:` for
+    the command line.
 
     Returns :data:`CHROME_HANDLED` when the key is fully dealt with,
     :data:`CHROME_REDRAW` when the caller should also repaint, the synthesised
@@ -155,6 +204,21 @@ def consume_chrome(key: str, cells: dict):
         # background track change went by), so repaint everything.
         screen_invalidate()
         return CHROME_REDRAW
+    if free_keys and key == ':' and (opened := open_command_line()) is not None:
+        if not opened:                       # just the overlay, put back: only the toast is new
+            render_status_bar()
+            return CHROME_HANDLED
+        screen_invalidate()
+        if not _IS_WINDOWS:
+            sys.stdout.write("\033[?1000h\033[?1006h")
+        return CHROME_REDRAW
+    tab = nav.tab_for(key, free_keys)
+    if tab is not None:
+        nav.switch_to(tab)              # back here once this tab shows again
+        screen_invalidate()
+        if not _IS_WINDOWS:
+            sys.stdout.write("\033[?1000h\033[?1006h")   # the other tab may have had the mouse off
+        return CHROME_REDRAW
     if is_hints_key(key, bool(cells.get('__help_key__'))):
         toggle_hints()
         return CHROME_REDRAW            # the bar appeared or went: re-lay the screen
@@ -183,7 +247,7 @@ def consume_chrome(key: str, cells: dict):
                 sys.stdout.write("\033[?1000h\033[?1006h")
             sys.stdout.flush()
             return CHROME_REDRAW
-        if act in ('playpause', 'next', 'prev') and _transport_handler is not None:
+        if act in FOOTER_ACTIONS and _transport_handler is not None:
             _transport_handler(act)
             return CHROME_HANDLED
         hit = cells.get((row, col))
@@ -210,8 +274,9 @@ def disable_mouse() -> None:
 
 
 def set_transport_handler(fn) -> None:
-    """Register ``callable(action)`` for the global transport hotkeys, where
-    action is 'playpause', 'next', or 'prev'. Kept as a registered callback so
+    """Register ``callable(action)`` for the global transport hotkeys and clicks
+    on the now-playing box, where action is one of FOOTER_ACTIONS ('time': its
+    clock was clicked). Kept as a registered callback so
     prompt need not import the playback layer (mirrors set_player_opener)."""
     global _transport_handler
     _transport_handler = fn