backpack-backbone 0.2.0__py3-none-any.whl

backbone/keys.py

@@ -0,0 +1,271 @@
+"""Key bindings: every rebindable key, named by what it does.
+
+A screen defines its actions where it uses them, then asks which action a key
+is rather than comparing literal keys, and builds its hints from the same
+table, so a rebound key works and is shown everywhere at once:
+
+    keys.define("player", "Player", [
+        ("next", ("]",), "next track"),
+        ("prev", ("[",), "previous track"),
+    ])
+    if keys.action(key, "player") == "player.next": ...
+    hint pair: (keys.label("player.prev", "player.next"), "prev/next")
+
+Key names are what `prompt.core._read_key` returns ('UP', 'SPACE', 'ENTER',
+'\\x10' for Ctrl-P, 'b', ...). An action may have several keys (aliases such
+as b/B/Esc). The user's changes live in <config folder>/keys.json, apart from
+the host's own config for the reason the hints switch is: a screen holding a
+loaded config would save it back over a change made meanwhile.
+"""
+from __future__ import annotations
+import json
+import os
+import time
+from dataclasses import dataclass
+
+from backbone.log import log
+
+
+@dataclass(frozen=True)
+class Action:
+    id: str                  # "scope.name"
+    scope: str
+    label: str               # what it does, for the Key bindings page
+    default: tuple
+
+
+_titles: dict[str, str] = {}             # scope → its heading, in definition order
+_within: dict[str, tuple] = {}           # scope → the scopes active alongside it
+_actions: dict[str, Action] = {}         # id → Action, in definition order
+
+# Never rebindable: Ctrl-C always quits, and pointer/focus events aren't keys.
+_FIXED = ('CTRL_C',)
+_EVENT_PREFIXES = ('MOUSE_', 'SCROLL_', 'FOCUS_')
+
+
+def define(scope: str, title: str, actions: list, within: tuple = ("global",)) -> None:
+    """Register a scope's actions: (name, default keys, label) each. `within`:
+    the scopes also live on that screen (their keys are found after its own,
+    and a key can't mean two things across them)."""
+    _titles.setdefault(scope, title)
+    _within[scope] = tuple(s for s in within if s != scope)
+    for name, default, label in actions:
+        aid = f"{scope}.{name}"
+        _actions[aid] = Action(aid, scope, label, tuple(default))
+
+
+def actions(scope: str | None = None) -> list[Action]:
+    """Every action, or one scope's, in definition order."""
+    return [a for a in _actions.values() if scope is None or a.scope == scope]
+
+
+def scopes() -> list[tuple[str, str]]:
+    """(scope, title) for every scope that has actions, in definition order."""
+    return [(s, t) for s, t in _titles.items() if any(a.scope == s for a in _actions.values())]
+
+
+# --- the user's bindings: keys.json -------------------------------------------
+
+_saved: dict = {'map': None, 'mtime': None, 'checked': 0.0}
+_RECHECK_S = 1.0         # how often to look for a change made by another window
+
+
+def _path():
+    from backbone import app
+    return app.config_dir / "keys.json"
+
+
+def _overrides() -> dict[str, tuple]:
+    """The user's bindings, re-read when the file changes (another window may
+    have rebound a key). A broken file means the defaults, and a log line."""
+    now = time.monotonic()
+    if _saved['map'] is not None and now - _saved['checked'] < _RECHECK_S:
+        return _saved['map']
+    _saved['checked'] = now
+    try:
+        mtime = _path().stat().st_mtime
+    except OSError:
+        mtime = None
+    if _saved['map'] is not None and mtime == _saved['mtime']:
+        return _saved['map']
+    _saved['mtime'] = mtime
+    found: dict[str, tuple] = {}
+    if mtime is not None:
+        try:
+            raw = json.loads(_path().read_text(encoding="utf-8"))
+            if not isinstance(raw, dict):
+                raise ValueError("not a JSON object")
+        except (OSError, ValueError) as exc:
+            log.warning("keys.json unreadable, using the default keys: %s", exc)
+            raw = {}
+        for aid, ks in raw.items():
+            if isinstance(ks, list) and all(isinstance(k, str) and k for k in ks):
+                found[aid] = tuple(ks)
+            else:
+                log.warning("keys.json: ignoring %r (not a list of key names)", aid)
+    _saved['map'] = found
+    return found
+
+
+def _write(overrides: dict[str, tuple]) -> None:
+    """Save the bindings atomically. Entries for actions this build doesn't
+    define are kept: another tool or version may still use them."""
+    path = _path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps({k: list(v) for k, v in overrides.items()}, indent=1),
+                       encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError as exc:
+        log.warning("couldn't save keys.json: %s", exc)
+    _saved.update(map=dict(overrides), mtime=None, checked=0.0)
+
+
+def of(aid: str) -> tuple:
+    """The keys bound to an action: the user's, or else its default."""
+    return _overrides().get(aid, _actions[aid].default)
+
+
+def changed(aid: str) -> bool:
+    return of(aid) != _actions[aid].default
+
+
+def bind(aid: str, keys: tuple) -> None:
+    """Set an action's keys (an empty tuple leaves it unbound)."""
+    overrides = dict(_overrides())
+    if tuple(keys) == _actions[aid].default:
+        overrides.pop(aid, None)
+    else:
+        overrides[aid] = tuple(keys)
+        if not keys:
+            log.info("key binding %s left without a key", aid)
+    _write(overrides)
+
+
+def reset(aid: str | None = None) -> None:
+    """Back to the default keys: one action, or every one."""
+    if aid is None:
+        _write({k: v for k, v in _overrides().items() if k not in _actions})
+    else:
+        overrides = dict(_overrides())
+        overrides.pop(aid, None)
+        _write(overrides)
+
+
+def bindable(key: str) -> bool:
+    """Whether a key can be bound at all."""
+    return bool(key) and key not in _FIXED and not key.startswith(_EVENT_PREFIXES)
+
+
+# --- lookups -------------------------------------------------------------------
+
+def _chain(scope: str) -> tuple:
+    return (scope, *_within.get(scope, ()))
+
+
+def action(key: str, scope: str) -> str | None:
+    """Which action `key` is on a screen of `scope`: its own actions first,
+    then the scopes live alongside it. None when the key is unbound there."""
+    for s in _chain(scope):
+        for a in _actions.values():
+            if a.scope == s and key in of(a.id):
+                return a.id
+    return None
+
+
+def keys_for(spec: str) -> tuple:
+    """A widget parameter that takes a key may be given an action id instead:
+    its bound keys, or the plain key itself."""
+    if spec in _actions:
+        return of(spec)
+    if len(spec) > 2 and "." in spec[1:-1] and spec.replace(".", "").replace("_", "").isalnum():
+        log.warning("key spec %r looks like an action id but none is defined", spec)
+    return (spec,)
+
+
+def hint_for(spec: str) -> str:
+    """The hint text for such a parameter: the action's keys, or the key as given."""
+    return label(spec) if spec in _actions else spec
+
+
+def describe(spec: str) -> str:
+    """What an action does, for a menu ("" for a plain key)."""
+    a = _actions.get(spec)
+    return a.label if a else ""
+
+
+def expand(mapping: dict | None) -> dict:
+    """{key or action id: value} → {key: value}, every bound key of an action."""
+    return {k: v for spec, v in (mapping or {}).items() for k in keys_for(spec)}
+
+
+def pressed(key: str, aid: str) -> bool:
+    """Whether `key` is one of the action's keys."""
+    return key in of(aid)
+
+
+def conflicts(aid: str, key: str) -> list[str]:
+    """Other actions already using `key` somewhere this action is live: its own
+    scope, the scopes live alongside it, and the scopes it is live alongside."""
+    scope = _actions[aid].scope
+    related = set(_chain(scope)) | {s for s, w in _within.items() if scope in w}
+    return [a.id for a in _actions.values()
+            if a.id != aid and a.scope in related and key in of(a.id)]
+
+
+# --- how keys are shown ---------------------------------------------------------
+
+_GLYPHS = {
+    'UP': '↑', 'DOWN': '↓', 'LEFT': '←', 'RIGHT': '→', 'PGUP': '⇞', 'PGDN': '⇟',
+    'SPACE': 'space', 'ENTER': '↵', 'ESC': 'esc', 'TAB': 'tab', 'BACKTAB': '⇧tab',
+    'HOME': 'home', 'END': 'end', 'BACKSPACE': '⌫', 'DELETE': 'del', 'INSERT': 'ins',
+    '\x1f': '^/', '\x1b': 'esc',
+}
+_ARROWS = set('↑↓←→⇞⇟')
+
+
+def glyph(key: str) -> str:
+    """How one key is written in hints and on the Key bindings page."""
+    if key in _GLYPHS:
+        return _GLYPHS[key]
+    if len(key) == 1 and 1 <= ord(key) <= 26:
+        return '^' + chr(ord(key) + 96)              # '\x10' → '^p'
+    return key
+
+
+class HintKey(str):
+    """A hint's key text that also knows the real key behind each glyph, so a
+    click on it replays the bound key whatever it looks like ('/', '[', '^/')."""
+    tokens: list                                     # (offset, glyph length, key)
+
+
+def _display_keys(aids: tuple) -> list[str]:
+    """The keys to show for these actions: each once, and a letter's other
+    case left out when both are bound (b/B is one key to the reader)."""
+    shown: list[str] = []
+    for aid in aids:
+        for k in of(aid):
+            if k in shown or (len(k) == 1 and k.isalpha() and k.swapcase() in shown):
+                continue
+            shown.append(k)
+    return shown
+
+
+def label(*aids: str, first: bool = False, most: int | None = None) -> HintKey:
+    """The hint text for these actions' keys ("[/]", "↑↓", "space/p"), for a
+    hint short on room: `first` shows each action's first key only, `most`
+    caps how many keys are shown in all."""
+    shown = _display_keys(aids) if not first else [
+        ks[0] for ks in (_display_keys((a,)) for a in aids) if ks]
+    shown = shown[:most] if most else shown
+    text, tokens = "", []
+    for k in shown:
+        g = glyph(k)
+        if text and not (g in _ARROWS and text[-1] in _ARROWS):
+            text += "/"                              # arrows run together: ↑↓, ←→
+        tokens.append((len(text), len(g), k))
+        text += g
+    out = HintKey(text)
+    out.tokens = tokens
+    return out

backbone/log.py

@@ -0,0 +1,61 @@
+"""Diagnostics log: <config folder>/<program>.log (see backbone.app) while the
+host turns it on (backtrack's Settings → Diagnostics). Off, it costs a level
+check and nothing more.
+
+    from backbone.log import log
+    log.debug("redrew in %.0f ms", ms)
+"""
+import logging
+from logging.handlers import RotatingFileHandler
+
+log = logging.getLogger("backbone")
+log.addHandler(logging.NullHandler())
+log.propagate = False
+log.setLevel(logging.CRITICAL + 1)          # silent until configure(True)
+
+
+def log_path():
+    """Where the log is written."""
+    from backbone import app
+    return app.config_dir / f"{app.name}.log"
+
+
+def configure(enabled: bool) -> None:
+    """Start or stop writing the log (the `debug` setting)."""
+    for h in [h for h in log.handlers if isinstance(h, RotatingFileHandler)]:
+        log.removeHandler(h)
+        h.close()
+    if not enabled:
+        log.setLevel(logging.CRITICAL + 1)
+        return
+    path = log_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handler = RotatingFileHandler(path, maxBytes=1_000_000, backupCount=2, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s.%(msecs)03d %(levelname)-7s %(message)s",
+                                           "%H:%M:%S"))
+    log.addHandler(handler)
+    log.setLevel(logging.DEBUG)
+    log.info("diagnostics log started")
+
+
+def enabled() -> bool:
+    """Whether anything is being logged, for callers whose message is costly to build."""
+    return log.isEnabledFor(logging.DEBUG)
+
+
+class quietly:
+    """`with quietly():` carries on past a failure that mustn't stop anything
+    (best-effort cleanup, a cosmetic redraw), but notes it in the diagnostics
+    log, so a swallowed error still leaves a trace when Diagnostics is on."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, kind, exc, tb) -> bool:
+        if kind is None or not issubclass(kind, Exception):
+            return False
+        if log.isEnabledFor(logging.DEBUG):
+            import os
+            where = f"{os.path.basename(tb.tb_frame.f_code.co_filename)}:{tb.tb_lineno}"
+            log.debug("ignored at %s: %s: %s", where, kind.__name__, exc)
+        return True

backbone/nav.py

@@ -0,0 +1,17 @@
+"""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.
+    """

backbone/notify.py

@@ -0,0 +1,36 @@
+"""Telling someone something happened: a push to their phone through ntfy, or
+a chime at the machine."""
+import subprocess
+import threading
+import urllib.request
+
+
+def ntfy(server: str, topic: str, title: str, message: str, priority: str = "default", tags: str = "") -> None:
+    """Push `message` to an ntfy topic in the background. Nothing is sent
+    without a topic, and a failed send is dropped rather than raised: a missed
+    notification must never stop the work it reports on."""
+    if not topic:
+        return
+
+    def _send():
+        req = urllib.request.Request(
+            f"{server.rstrip('/')}/{topic}", data=message.encode(), method="POST",
+            headers={"Title": title, "Priority": priority, "Tags": tags},
+        )
+        try:
+            urllib.request.urlopen(req, timeout=10)
+        except Exception:
+            pass
+
+    threading.Thread(target=_send, daemon=True).start()
+
+
+def chime() -> None:
+    """The macOS done sound, or the terminal bell where there's no afplay."""
+    try:
+        if subprocess.run(["afplay", "/System/Library/Sounds/Glass.aiff"],
+                          capture_output=True, timeout=10).returncode == 0:
+            return
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    print("\a", end="", flush=True)

backbone/numbering.py

@@ -0,0 +1,182 @@
+"""Number rendering shared by the patterning tools: arabic, roman, or written out.
+
+One place owns the three styles so a file-name pattern (``%track:r%``), a bulk
+range template (``Act {r}``) and the playback panel's movement numeral all agree.
+"""
+from __future__ import annotations
+
+# Value → symbol, largest first: the standard subtractive-notation table.
+_ROMAN: tuple[tuple[int, str], ...] = (
+    (1000, 'M'), (900, 'CM'), (500, 'D'), (400, 'CD'),
+    (100, 'C'), (90, 'XC'), (50, 'L'), (40, 'XL'),
+    (10, 'X'), (9, 'IX'), (5, 'V'), (4, 'IV'), (1, 'I'),
+)
+
+_ONES = ('zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight',
+         'nine', 'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen',
+         'sixteen', 'seventeen', 'eighteen', 'nineteen')
+_TENS = ('', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy',
+         'eighty', 'ninety')
+
+# Recognised number styles, and the case modifiers each accepts.
+STYLES: dict[str, str] = {
+    'n': 'Arabic (3)',
+    'r': 'Roman (III)',
+    'en': 'Written out (Three)',
+}
+CASES: str = "l = lower, u = UPPER, t = Title Case"
+
+
+def roman(num: int) -> str:
+    """Integer → Roman numeral ('' for anything below 1, which has no numeral)."""
+    try:
+        n = int(num)
+    except (TypeError, ValueError):
+        return ''
+    if n < 1:
+        return ''
+    out: list[str] = []
+    for value, symbol in _ROMAN:
+        count, n = divmod(n, value)
+        out.append(symbol * count)
+    return ''.join(out)
+
+
+def in_words(num: int) -> str:
+    """Integer → English words, lower case ('twenty-one', 'one hundred and five').
+
+    Covers 0-999,999; anything outside that falls back to the digits, since a
+    pattern is better off showing a number than nothing.
+    """
+    try:
+        n = int(num)
+    except (TypeError, ValueError):
+        return str(num)
+    if n < 0:
+        return f"minus {in_words(-n)}"
+    if n >= 1_000_000:
+        return str(n)
+
+    if n < 20:
+        return _ONES[n]
+    if n < 100:
+        tens, ones = divmod(n, 10)
+        return _TENS[tens] + (f"-{_ONES[ones]}" if ones else "")
+    if n < 1000:
+        hundreds, rest = divmod(n, 100)
+        out = f"{_ONES[hundreds]} hundred"
+        return f"{out} and {in_words(rest)}" if rest else out
+    thousands, rest = divmod(n, 1000)
+    out = f"{in_words(thousands)} thousand"
+    if not rest:
+        return out
+    # "two thousand and five", but "two thousand one hundred and five".
+    joiner = " and " if rest < 100 else " "
+    return out + joiner + in_words(rest)
+
+
+# --- reading numbers back ------------------------------------------------
+
+_ROMAN_VALUES = {'I': 1, 'V': 5, 'X': 10, 'L': 50, 'C': 100, 'D': 500, 'M': 1000}
+
+_WORD_VALUES: dict[str, int] = {w: i for i, w in enumerate(_ONES)}
+_WORD_VALUES.update({w: i * 10 for i, w in enumerate(_TENS) if w})
+_WORD_SCALES = {'hundred': 100, 'thousand': 1000}
+
+# Regex fragments for matching a number written in each style, for pattern
+# templates that parse names ("Act III - Title", "Series Three, Episode Four").
+# Case-insensitive in-place so they can drop into a larger pattern unchanged.
+ROMAN_FRAGMENT = r'(?i:[mdclxvi]+)'
+WORD_FRAGMENT = (r'(?i:(?:' + '|'.join(
+    sorted(list(_ONES) + [t for t in _TENS if t] + list(_WORD_SCALES) + ['and'],
+           key=len, reverse=True)) + r')(?:[- ](?:' + '|'.join(
+    sorted(list(_ONES) + [t for t in _TENS if t] + list(_WORD_SCALES) + ['and'],
+           key=len, reverse=True)) + r'))*)')
+
+
+def from_roman(text: str) -> int | None:
+    """Roman numeral → int, or None if `text` isn't one ('XIV' → 14)."""
+    t = str(text).strip().upper()
+    if not t or any(c not in _ROMAN_VALUES for c in t):
+        return None
+    total = 0
+    for i, c in enumerate(t):
+        v = _ROMAN_VALUES[c]
+        # A smaller symbol before a larger one is subtractive (IV, IX, XL…).
+        total += -v if (i + 1 < len(t) and v < _ROMAN_VALUES[t[i + 1]]) else v
+    if total < 1 or roman(total) != t:
+        return None            # not canonical ('IIII', 'VX'): treat as text
+    return total
+
+
+def from_words(text: str) -> int | None:
+    """English words → int, or None if unparseable ('twenty-one' → 21)."""
+    tokens = [w for w in str(text).lower().replace('-', ' ').split() if w != 'and']
+    if not tokens:
+        return None
+    total = current = 0
+    for w in tokens:
+        if w in _WORD_SCALES:
+            scale = _WORD_SCALES[w]
+            # "two hundred" scales what's pending; "thousand" banks it.
+            current = max(current, 1) * scale
+            if scale >= 1000:
+                total += current
+                current = 0
+        elif w in _WORD_VALUES:
+            current += _WORD_VALUES[w]
+        else:
+            return None
+    return (total + current) or (0 if 'zero' in tokens else None)
+
+
+def parse(text) -> int | None:
+    """Read a number written in any of the three styles: '4', 'IV' or 'four'."""
+    t = str(text).strip()
+    if not t:
+        return None
+    if t.lstrip('-').isdigit():
+        return int(t)
+    return from_roman(t) if from_roman(t) is not None else from_words(t)
+
+
+def apply_case(text: str, case: str) -> str:
+    """Apply a case modifier: 'l' lower, 'u' upper, 't' Title Case.
+
+    Anything else (including an empty modifier) capitalises the first letter
+    only: 'Twenty-one' rather than 'Twenty-One', which reads better mid-title.
+    """
+    if not text:
+        return text
+    if case == 'l':
+        return text.lower()
+    if case == 'u':
+        return text.upper()
+    if case == 't':
+        return '-'.join(w.capitalize() for w in text.split('-')) if '-' in text \
+            else ' '.join(w.capitalize() for w in text.split(' '))
+    return text[0].upper() + text[1:]
+
+
+def render(value, style: str = 'n', spec: str = '') -> str:
+    """Render `value` in one of the three number styles.
+
+    ``style`` is 'n' (arabic), 'r' (roman) or 'en' (written out); ``spec`` is a
+    case modifier for 'r'/'en', or a `format()` spec for 'n' (so ``{n:02d}``
+    padding still works). A value that isn't a number comes back unchanged, and
+    a number with no Roman form (0 or less) falls back to its digits rather than
+    vanishing from the pattern.
+    """
+    try:
+        n = int(str(value).strip())
+    except (TypeError, ValueError):
+        return str(value)
+
+    if style == 'r':
+        return apply_case(roman(n), spec) or str(n)
+    if style == 'en':
+        return apply_case(in_words(n), spec or 'c')
+    try:
+        return format(n, spec) if spec else str(n)
+    except (ValueError, TypeError):
+        return str(n)