backpack-backbone 0.2.0__py3-none-any.whl

backbone/__init__.py

@@ -0,0 +1,30 @@
+"""backbone - shared terminal UI: colours, meters, prompt widgets, live views."""
+from .ui import (
+    Colors,
+    MARGIN_H,
+    MARGIN_V,
+    SPIN,
+    PARTS,
+    SPARK,
+    spinner,
+    content_width,
+    rule,
+    bar,
+    header_box,
+    wrap_margins,
+)
+
+__all__ = [
+    "Colors",
+    "MARGIN_H",
+    "MARGIN_V",
+    "SPIN",
+    "PARTS",
+    "SPARK",
+    "spinner",
+    "content_width",
+    "rule",
+    "bar",
+    "header_box",
+    "wrap_margins",
+]

backbone/app.py

@@ -0,0 +1,26 @@
+"""Which program is running, so shared code can find its files: a name and a
+config folder, set once at startup by the host program (its config module)."""
+import os
+from pathlib import Path
+
+
+def _default_dir(name: str) -> Path:
+    """The platform's usual config folder for `name`."""
+    if os.name == "nt":
+        base = os.getenv("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / name.capitalize()
+    xdg = os.getenv("XDG_CONFIG_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".config") / name
+
+
+name = "backbone"
+config_dir = _default_dir(name)
+
+
+def configure(app_name: str, app_config_dir=None) -> None:
+    """Name the running program and its config folder (the platform default for
+    that name when not given). The diagnostics log and the saved hints switch
+    live there."""
+    global name, config_dir
+    name = app_name
+    config_dir = Path(app_config_dir) if app_config_dir else _default_dir(app_name)

backbone/datetime_parse.py

@@ -0,0 +1,224 @@
+"""One parser for every hand-typed date: the calendar, the date/time editor,
+the schedule table, filename values.
+
+Everything goes through :func:`parse_datetime`.  It accepts what a person
+plausibly types, keeps whatever precision was given, and says *why* when it can't
+read something so the caller can show that rather than a bare failure.
+
+Accepted, all with ``-``, ``/`` or ``.`` between the parts and zero-padding
+optional::
+
+    2008              2008-07           2008-07-02        2008-7-2
+    2008/07/02        2008.7.2          20080702
+    2008-07-02 18:30  2008-07-02T18:30  2008-07-02 18:30:45
+
+A time may follow the date after a ``T`` (either case) or a space, as ``HH:MM``
+or ``HH:MM:SS``.  A trailing timezone (``Z`` or ``±HH:MM``) is stripped: the
+tags Backtrack writes are local wall-clock timestamps.
+
+Day-first vs month-first (``02/07/2008``) is ambiguous and is resolved
+only when the caller says how, via ``dayfirst``.  Left unset, an ambiguous date
+is refused rather than guessed, because guessing wrong writes a plausible-looking
+wrong date that nobody notices.
+"""
+from __future__ import annotations
+
+import datetime
+import re
+from typing import NamedTuple, Optional
+
+__all__ = ['ParsedDateTime', 'parse_datetime', 'parse_date', 'parse_time',
+           'format_datetime', 'PRECISIONS']
+
+# Coarse → fine.  A caller can compare precisions with `PRECISIONS.index(...)`
+# to demand at least a given granularity.
+PRECISIONS = ('year', 'month', 'day', 'minute', 'second')
+
+# Year-first, any of - / . between parts, zero-padding optional.
+_YEAR_FIRST_RE = re.compile(r'^(\d{4})(?:[-/.\s](\d{1,2})(?:[-/.\s](\d{1,2}))?)?$')
+# ISO basic form, 20080702.
+_COMPACT_RE = re.compile(r'^(\d{4})(\d{2})(\d{2})$')
+# Day- or month-first, e.g. 02/07/2008, order decided by `dayfirst`.
+_YEAR_LAST_RE = re.compile(r'^(\d{1,2})[-/.\s](\d{1,2})[-/.\s](\d{4})$')
+# A trailing timezone we drop rather than try to honour.
+_TZ_RE = re.compile(r'(Z|[+-]\d{2}:?\d{2})$', re.IGNORECASE)
+
+
+class ParsedDateTime(NamedTuple):
+    """The result of reading a date/time a user typed.
+
+    ``date`` is always a real ``datetime.date`` on success (a year- or
+    month-only input is completed to the 1st so callers that just need *a* date
+    have one), and ``precision`` records how much was actually given, so a caller
+    that needs a real day (a schedule counting in days, say) can insist on it
+    instead of silently scheduling from an invented 1 January.
+
+    ``time`` is ``'HH:MM:SS'`` or None.  ``error`` is '' on success and otherwise
+    a short phrase naming what was wrong, fit to show the user directly.
+    """
+    date: Optional[datetime.date]
+    time: Optional[str]
+    precision: str
+    error: str
+
+    @property
+    def ok(self) -> bool:
+        """True if the input parsed."""
+        return not self.error
+
+
+def parse_time(raw) -> Optional[str]:
+    """Normalise ``HH``/``HH:MM``/``HH:MM:SS`` to ``'HH:MM:SS'``; None if unreadable.
+
+    Rejects out-of-range parts (``25:00``, ``18:75``) rather than rolling them
+    over, so a typo surfaces instead of quietly becoming a different time.
+    """
+    if raw is None:
+        return None
+    s = str(raw).strip()
+    if not s:
+        return None
+    parts = s.split(':')
+    if len(parts) > 3 or not all(p.strip().isdigit() for p in parts if p.strip() != ''):
+        return None
+    try:
+        h = int(parts[0])
+        m = int(parts[1]) if len(parts) > 1 and parts[1].strip() else 0
+        sec = int(parts[2]) if len(parts) > 2 and parts[2].strip() else 0
+    except (ValueError, IndexError):
+        return None
+    if 0 <= h < 24 and 0 <= m < 60 and 0 <= sec < 60:
+        return f"{h:02d}:{m:02d}:{sec:02d}"
+    return None
+
+
+def _split_date_time(s: str) -> tuple:
+    """Split a stamp into its date and time halves.
+
+    A ``T`` always separates them.  A space only does when what follows it looks
+    like a clock time (it carries a ``:``) because a space is *also* a legal
+    separator inside the date itself: ``2008 07 02`` is a date, while
+    ``2008-07-02 18:30`` is a date and a time.
+    """
+    upper = s.upper()
+    if 'T' in upper:
+        cut = upper.index('T')
+        return s[:cut].strip(), s[cut + 1:].strip()
+    if ' ' in s:
+        head, _, tail = s.rpartition(' ')
+        if ':' in tail:
+            return head.strip(), tail.strip()
+    return s.strip(), ''
+
+
+def split_stamp(raw) -> tuple:
+    """The date and time halves of a typed stamp, any trailing timezone dropped."""
+    return _split_date_time(_TZ_RE.sub('', str(raw or '').strip()).strip())
+
+
+def _read_date(part: str, dayfirst: Optional[bool]) -> tuple:
+    """Parse the date half → ``(date, precision, error)``."""
+    m = _COMPACT_RE.match(part)
+    if m:
+        y, mo, d = (int(g) for g in m.groups())
+        return _build(y, mo, d, 'day')
+
+    m = _YEAR_FIRST_RE.match(part)
+    if m:
+        year, month, day = m.groups()
+        if month is None:
+            return _build(int(year), 1, 1, 'year')
+        if day is None:
+            return _build(int(year), int(month), 1, 'month')
+        return _build(int(year), int(month), int(day), 'day')
+
+    m = _YEAR_LAST_RE.match(part)
+    if m:
+        a, b, year = (int(g) for g in m.groups())
+        # Only one ordering can be right when a part exceeds 12 (13/07/2008 has
+        # to be day-first), so try both and see how many survive.
+        day_first_ok = 1 <= b <= 12
+        month_first_ok = 1 <= a <= 12
+        if day_first_ok and month_first_ok:
+            # Genuinely ambiguous: 02/07/2008 is 2 July or 2 February depending
+            # on where you live. Honour an explicit choice, else refuse rather
+            # than pick one and be silently wrong.
+            if dayfirst is None:
+                return None, '', (f"{part!r} could be day-first or month-first: "
+                                  "write it year-first (2008-07-02)")
+            day, month = (a, b) if dayfirst else (b, a)
+        elif day_first_ok:
+            day, month = a, b
+        elif month_first_ok:
+            month, day = a, b
+        else:
+            return None, '', f"{part!r} has no valid month"
+        return _build(year, month, day, 'day')
+
+    return None, '', f"{part!r} is not a date"
+
+
+def _build(year: int, month: int, day: int, precision: str) -> tuple:
+    """Validate y/m/d into a real date, or report why it isn't one."""
+    if not 1 <= month <= 12:
+        return None, '', f"there is no month {month}"
+    try:
+        return datetime.date(year, month, day), precision, ''
+    except ValueError:
+        return None, '', (f"{year:04d}-{month:02d}-{day:02d} is not a real date")
+
+
+def parse_datetime(raw, *, dayfirst: Optional[bool] = None) -> ParsedDateTime:
+    """Read a date, optionally with a time, from something a user typed.
+
+    ``dayfirst`` resolves ``02/07/2008``: True reads it day-first, False
+    month-first, and the default (None) refuses it and says to write the date
+    year-first.  Year-first input is never ambiguous and never consults it.
+    """
+    if raw is None:
+        return ParsedDateTime(None, None, '', 'no date given')
+    date_part, time_part = split_stamp(raw)
+    if not date_part:
+        return ParsedDateTime(None, None, '', 'no date given')
+
+    date, precision, err = _read_date(date_part, dayfirst)
+    if err:
+        return ParsedDateTime(None, None, '', err)
+
+    if not time_part:
+        return ParsedDateTime(date, None, precision, '')
+
+    tod = parse_time(time_part)
+    if tod is None:
+        return ParsedDateTime(None, None, '', f"{time_part!r} is not a valid 24-hour time")
+    # A time implies a full date; without one we would be timing an invented day.
+    if precision != 'day':
+        return ParsedDateTime(None, None, '', f"{date_part!r} needs a full year-month-day "
+                                              "to carry a time")
+    return ParsedDateTime(date, tod, 'second' if tod[-2:] != '00' else 'minute', '')
+
+
+def parse_date(raw, *, dayfirst: Optional[bool] = None) -> Optional[datetime.date]:
+    """Just the date, or None if it won't parse. Any time given is ignored."""
+    return parse_datetime(raw, dayfirst=dayfirst).date
+
+
+def format_datetime(parsed: ParsedDateTime) -> str:
+    """Render a parse back out at the precision it was given."""
+    if parsed.date is None:
+        return ''
+    if parsed.precision == 'year':
+        return f"{parsed.date.year:04d}"
+    if parsed.precision == 'month':
+        return f"{parsed.date.year:04d}-{parsed.date.month:02d}"
+    if parsed.time:
+        return f"{parsed.date.isoformat()} {parsed.time}"
+    return parsed.date.isoformat()
+
+
+def parse_date_parts(raw, *, dayfirst: Optional[bool] = None) -> Optional[tuple]:
+    """``(year, month, day)`` for a typed date, or None: the shape the calendar
+    and date/time widgets work in.  A year- or month-only input completes to the
+    1st, as those widgets have always done."""
+    d = parse_datetime(raw, dayfirst=dayfirst).date
+    return (d.year, d.month, d.day) if d else None

backbone/deps.py

@@ -0,0 +1,98 @@
+"""What a tool needs besides Python, checked in one place: at startup for what
+it can't run without (`require`), and as a report for everything (each tool's
+`doctor` command), each with how to install it on the platform it's on.
+
+    VLC = Dep("VLC", probe=..., needed_for="playback", required=True,
+              hints={"macos": "brew install vlc", "debian": "sudo apt install vlc"})
+    deps.require([VLC])        # prints the hint and exits when VLC is missing
+"""
+from __future__ import annotations
+import os
+import shutil
+import sys
+from dataclasses import dataclass, field
+from typing import Callable
+
+from backbone.log import log
+
+
+@dataclass(frozen=True)
+class Dep:
+    name: str
+    probe: Callable[[], str | None]   # what was found (a path, a version), or None
+    needed_for: str
+    required: bool = False
+    # Install hint per platform (see platform_key); "other" when none fits.
+    hints: dict = field(default_factory=dict)
+
+
+def which(*commands: str) -> Callable[[], str | None]:
+    """A probe for the first of `commands` on the PATH."""
+    return lambda: next((p for c in commands if (p := shutil.which(c))), None)
+
+
+def platform_key() -> str:
+    """macos, windows, debian (Ubuntu too), fedora, arch, or linux."""
+    if sys.platform == "darwin":
+        return "macos"
+    if os.name == "nt":
+        return "windows"
+    ids = ""
+    try:
+        with open("/etc/os-release", encoding="utf-8") as f:
+            for line in f:
+                if line.startswith(("ID=", "ID_LIKE=")):
+                    ids += " " + line.split("=", 1)[1].strip().strip('"').lower()
+    except OSError:
+        pass
+    for key, names in (("debian", ("debian", "ubuntu")), ("fedora", ("fedora", "rhel")),
+                       ("arch", ("arch",))):
+        if any(n in ids.split() for n in names):
+            return key
+    return "linux"
+
+
+def hint(dep: Dep) -> str:
+    """How to install `dep` here."""
+    key = platform_key()
+    return (dep.hints.get(key) or (dep.hints.get("linux") if key in ("debian", "fedora", "arch") else None)
+            or dep.hints.get("other", ""))
+
+
+def check(deps: list[Dep]) -> list[tuple[Dep, str | None]]:
+    """Each dependency with what was found, or None when it's missing. A probe
+    that fails counts as missing (and is logged)."""
+    out = []
+    for dep in deps:
+        try:
+            found = dep.probe() or None
+        except Exception as exc:
+            log.info("dependency %s: probe failed: %s", dep.name, exc)
+            found = None
+        out.append((dep, found))
+    return out
+
+
+def report_lines(deps: list[Dep]) -> list[str]:
+    """One line per dependency, for a plain-text doctor."""
+    lines = []
+    for dep, found in check(deps):
+        if found:
+            lines.append(f"  ok       {dep.name}: {found}")
+        else:
+            need = "MISSING " if dep.required else "missing "
+            lines.append(f"  {need} {dep.name} (for {dep.needed_for}): {hint(dep)}")
+    return lines
+
+
+def require(deps: list[Dep], tool: str) -> None:
+    """Exit with what to install when a required dependency is missing, before
+    the tool starts rather than as a traceback once it's running."""
+    missing = [d for d, found in check(deps) if d.required and not found]
+    if not missing:
+        return
+    print(f"{tool} can't start: something it needs isn't installed.", file=sys.stderr)
+    for d in missing:
+        print(f"  {d.name} (for {d.needed_for}): {hint(d)}", file=sys.stderr)
+    print(f"`{tool} doctor` lists everything it uses.", file=sys.stderr)
+    raise SystemExit(1)

backbone/files.py

@@ -0,0 +1,61 @@
+"""Files: atomic writes and backups, a daemon's timestamped log, free space and folder counts."""
+import os
+import shutil
+import tempfile
+
+
+def write_text_atomic(path, text: str) -> None:
+    """Write `text` to `path` via a temporary file in the same directory that
+    then replaces it: the file is either the old version or the new one, never
+    half of the new one."""
+    path = os.fspath(path)
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path) or ".", prefix=".tmp_",
+                               suffix=os.path.splitext(path)[1])
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def backup_copy(path) -> str | None:
+    """Copy `path` to `path.bak` (replacing an older one) before it's
+    overwritten; returns the backup's path, or None if there was nothing to copy."""
+    path = os.fspath(path)
+    if not os.path.isfile(path):
+        return None
+    dest = path + ".bak"
+    shutil.copy2(path, dest)
+    return dest
+
+
+def log_line(path, message: str) -> None:
+    """Print `message` with a timestamp and append the same line to the log at
+    `path`: a daemon's running record, readable on screen and afterwards."""
+    from datetime import datetime
+    line = f"{datetime.now():%Y-%m-%d %H:%M:%S}  {message}"
+    print(line)
+    with open(path, "a") as f:
+        f.write(line + "\n")
+
+
+def disk_free(path) -> str:
+    """Free space on `path`'s volume as `df -h` shows it, or "?"."""
+    import subprocess
+    try:
+        lines = subprocess.run(["df", "-h", os.fspath(path)], capture_output=True, text=True, timeout=10).stdout.splitlines()
+    except (OSError, subprocess.TimeoutExpired):
+        return "?"
+    return lines[-1].split()[3] if len(lines) > 1 else "?"
+
+
+def count_entries(d) -> int:
+    """How many entries the folder `d` holds, 0 if it doesn't exist."""
+    return len(os.listdir(d)) if os.path.isdir(d) else 0

backbone/keyboard.py

@@ -0,0 +1,148 @@
+"""Which keyboard the typist is using, only as far as search needs it.
+
+`search._lev` scores a spelling mistake by whether the wrong letter sits next to
+the right one, so the only thing that matters here is where the *letters* are.
+That collapses the world's keyboards into a handful of families: British, US,
+Canadian, Irish, Australian and ABC differ solely in punctuation and dead keys,
+and are all one QWERTY as far as a typo is concerned.
+
+Detection is best-effort by design. Every branch is wrapped, and anything
+unreadable, unrecognised or unknown falls back to QWERTY. `BACKTRACK_KEYBOARD` overrides it
+outright, which is the only thing that can be right over SSH: the layout lives
+on the machine in front of the typist, not the one running the process.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+# Row-by-row key positions. Punctuation is kept in place even though nothing
+# looks it up: it holds the columns open, so dropping the leading "'," from
+# Dvorak's top row would slide every letter on it one key to the left.
+LAYOUTS: dict[str, tuple[str, ...]] = {
+    'qwerty':  ("1234567890-=", "qwertyuiop[]", "asdfghjkl;'", "zxcvbnm,./"),
+    'qwertz':  ("1234567890ß'", "qwertzuiopü+", "asdfghjklöä", "yxcvbnm,.-"),
+    'azerty':  ("1234567890°+", "azertyuiop^$", "qsdfghjklmù", "wxcvbn,;:!"),
+    'dvorak':  ("1234567890[]", "',.pyfgcrl/=", "aoeuidhtns-", ";qjkxbmwvz"),
+    'colemak': ("1234567890-=", "qwfpgjluy;[]", "arstdhneio'", "zxcvbkm,./"),
+}
+
+DEFAULT = 'qwerty'
+
+# Layout names (macOS), XKB codes (Linux) and language ids (Windows) that move
+# letters around. Matched as substrings against a lowercased name, so "Swiss
+# German" and "German - Standard" both land on QWERTZ.
+_NAME_FAMILIES: tuple[tuple[str, str], ...] = (
+    ('dvorak', 'dvorak'), ('colemak', 'colemak'),
+    ('azerty', 'azerty'), ('french', 'azerty'), ('belgian', 'azerty'),
+    ('qwertz', 'qwertz'), ('german', 'qwertz'), ('swiss', 'qwertz'),
+    ('austrian', 'qwertz'), ('czech', 'qwertz'), ('slovak', 'qwertz'),
+    ('hungarian', 'qwertz'), ('croatian', 'qwertz'), ('serbian', 'qwertz'),
+    ('slovenian', 'qwertz'), ('bosnian', 'qwertz'),
+)
+
+_XKB_FAMILIES: dict[str, str] = {
+    'fr': 'azerty', 'be': 'azerty',
+    'de': 'qwertz', 'ch': 'qwertz', 'at': 'qwertz', 'cz': 'qwertz',
+    'sk': 'qwertz', 'hu': 'qwertz', 'hr': 'qwertz', 'rs': 'qwertz',
+    'si': 'qwertz', 'ba': 'qwertz',
+}
+
+# Windows primary language ids (the low byte of the low word of the HKL).
+_WIN_FAMILIES: dict[int, str] = {
+    0x0c: 'azerty',                                     # French (incl. Belgian)
+    0x13: 'azerty',                                     # Dutch; Belgian is AZERTY
+    0x07: 'qwertz', 0x05: 'qwertz', 0x0e: 'qwertz',     # German, Czech, Hungarian
+    0x1b: 'qwertz', 0x24: 'qwertz', 0x1a: 'qwertz',     # Slovak, Slovenian, Croatian
+}
+
+
+def _family_from_name(name: str) -> str | None:
+    """Map a human layout name ("ABC - AZERTY", "Swiss German") to a family."""
+    low = name.lower()
+    for needle, family in _NAME_FAMILIES:
+        if needle in low:
+            return family
+    return None
+
+
+def _detect_macos() -> str | None:
+    """The selected input source, straight out of the HIToolbox preferences.
+
+    Read with plistlib rather than shelling out to `defaults`: no subprocess on
+    startup, and no dependency on pyobjc for the Carbon TIS API.
+    """
+    import plistlib
+    path = os.path.expanduser("~/Library/Preferences/com.apple.HIToolbox.plist")
+    with open(path, 'rb') as fh:
+        prefs = plistlib.load(fh)
+    for source in prefs.get('AppleSelectedInputSources', []):
+        if source.get('InputSourceKind') != 'Keyboard Layout':
+            continue
+        # A selected source can be one with no letter arrangement of its own:
+        # "Unicode Hex Input" is US letters with hex entry bolted on. Unnamed
+        # families fall through to QWERTY rather than guessing from whatever
+        # else the user happens to have enabled.
+        return _family_from_name(str(source.get('KeyboardLayout Name', '')))
+    return None
+
+
+def _detect_linux() -> str | None:
+    """XKB layout: the X server first, then systemd, then the Debian default."""
+    import subprocess
+
+    for cmd, key in ((['setxkbmap', '-query'], 'layout:'),
+                     (['localectl', 'status'], 'x11 layout:')):
+        try:
+            out = subprocess.run(cmd, capture_output=True, text=True, timeout=2).stdout
+        except (OSError, subprocess.SubprocessError):
+            continue
+        for line in out.splitlines():
+            low = line.strip().lower()
+            if low.startswith(key):
+                # "layout: gb,fr": the first is the active one.
+                code = low[len(key):].strip().split(',')[0].strip()
+                if code:
+                    return _XKB_FAMILIES.get(code, DEFAULT)
+
+    try:
+        with open('/etc/default/keyboard') as fh:
+            for line in fh:
+                if line.startswith('XKBLAYOUT='):
+                    code = line.split('=', 1)[1].strip().strip('"\'').split(',')[0]
+                    if code:
+                        return _XKB_FAMILIES.get(code, DEFAULT)
+    except OSError:
+        pass
+    return None
+
+
+def _detect_windows() -> str | None:
+    """Active keyboard layout of the foreground thread, via user32.
+
+    The HKL's low word is a language id, which is as far as this gets: it names
+    French but cannot tell US Dvorak from US QWERTY (that lives in the registry,
+    keyed by device). Dvorak and Colemak users on Windows want the env var.
+    """
+    import ctypes
+    hkl = ctypes.windll.user32.GetKeyboardLayout(0)          # type: ignore[attr-defined]
+    return _WIN_FAMILIES.get(hkl & 0xff, DEFAULT)
+
+
+def detect() -> str:
+    """Name the keyboard family in front of the user. Never raises."""
+    override = (os.environ.get('BACKTRACK_KEYBOARD') or '').strip().lower()
+    if override in LAYOUTS:
+        return override
+
+    detector = ({'darwin': _detect_macos, 'win32': _detect_windows}
+                .get(sys.platform, _detect_linux))
+    try:
+        return detector() or DEFAULT
+    except Exception:
+        return DEFAULT
+
+
+def rows(name: str | None = None) -> tuple[str, ...]:
+    """Key rows for a layout family, or for the detected one."""
+    return LAYOUTS.get(name or detect(), LAYOUTS[DEFAULT])