hyprmuse 0.3.2__py3-none-any.whl

hyprmuse/__init__.py

@@ -0,0 +1 @@
+"""hyprmuse - random quotes from musicians, authors and poets for hyprlock."""

hyprmuse/__main__.py

@@ -0,0 +1,10 @@
+"""Run the hyprmuse command: `python -m hyprmuse`, and the release binary's entry point.
+
+The import is absolute because packaging/build-binary.sh hands this file to PyInstaller
+as a plain script, outside the package, where a relative import has no parent.
+"""
+
+from hyprmuse.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyprmuse/cli.py

@@ -0,0 +1,232 @@
+"""Command line interface for hyprmuse."""
+
+import argparse
+import sys
+
+from . import config, library, lockscreen
+from .sources import AUTO_ORDER, REGISTRY, SourceError, get_source
+from .sources.base import Candidate
+
+
+def _err(msg: str) -> int:
+    print(f"hyprmuse: {msg}", file=sys.stderr)
+    return 1
+
+
+def _progress(msg: str) -> None:
+    print(f"  {msg}", file=sys.stderr)
+
+
+def _gather(query: str, source: str, lang: str) -> list[Candidate]:
+    """Candidates from one named source, or from every source in auto order."""
+    names = [source] if source else AUTO_ORDER
+    found: list[Candidate] = []
+    for name in names:
+        try:
+            hits = get_source(name).search(query, lang)
+        except SourceError as exc:
+            if source:
+                raise
+            print(f"  ({name} unavailable: {exc})", file=sys.stderr)
+            continue
+        found.extend(hits)
+        if source:
+            break
+    return found
+
+
+def _choose(cands: list[Candidate], assume_yes: bool) -> Candidate | None:
+    if not cands:
+        return None
+    if assume_yes or len(cands) == 1 or not sys.stdin.isatty():
+        return cands[0]
+    print("\nMatches:", file=sys.stderr)
+    for i, c in enumerate(cands, 1):
+        hint = f"  ({c.hint})" if c.hint else ""
+        print(f"  {i:2}. [{c.source}/{c.domain}] {c.name}{hint}", file=sys.stderr)
+    try:
+        raw = input("\nPick a number (blank to cancel): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        return None
+    if not raw.isdigit() or not 1 <= int(raw) <= len(cands):
+        return None
+    return cands[int(raw) - 1]
+
+
+def cmd_search(args) -> int:
+    cands = _gather(args.query, args.source, args.lang)
+    if not cands:
+        return _err(f"no matches for {args.query!r}")
+    for c in cands:
+        hint = f"  ({c.hint})" if c.hint else ""
+        print(f"[{c.source}/{c.domain}] {c.name}{hint}\n    {c.source}:{c.source_id}")
+    return 0
+
+
+def cmd_add(args) -> int:
+    try:
+        cands = _gather(args.query, args.source, args.lang)
+    except SourceError as exc:
+        return _err(str(exc))
+    cand = _choose(cands, args.yes)
+    if cand is None:
+        return _err(f"no match chosen for {args.query!r}")
+    print(f"Harvesting {cand.name} from {cand.source}…", file=sys.stderr)
+    try:
+        subject = get_source(cand.source).fetch(cand.source_id, _progress)
+    except SourceError as exc:
+        return _err(str(exc))
+    path = library.save(subject)
+    print(f"Saved {len(subject.items)} items for {subject.name} -> {path}")
+    return 0
+
+
+def cmd_list(args) -> int:
+    subjects = library.load_all()
+    if not subjects:
+        print("No subjects yet. Try: hyprmuse add \"Franz Kafka\"")
+        return 0
+    width = max(len(s.name) for s in subjects)
+    total = 0
+    for s in subjects:
+        total += len(s.items)
+        kind = "atomic" if s.items and s.items[0].atomic else "sliceable"
+        print(f"{s.name:{width}}  {len(s.items):5} items  {s.domain:11} "
+              f"{s.lang:3} {kind:10} {library.subject_key(s.source, s.source_id)}")
+    print(f"\n{len(subjects)} subjects, {total} items total")
+    return 0
+
+
+def cmd_remove(args) -> int:
+    matches = library.find(args.token)
+    if not matches:
+        return _err(f"no subject matching {args.token!r}")
+    if len(matches) > 1:
+        names = ", ".join(library.subject_key(m.source, m.source_id) for m in matches)
+        return _err(f"{args.token!r} is ambiguous: {names}")
+    subject = matches[0]
+    library.remove(subject)
+    print(f"Removed {subject.name}")
+    return 0
+
+
+def cmd_update(args) -> int:
+    targets = library.load_all() if args.all else library.find(args.token or "")
+    if not targets:
+        return _err("nothing to update")
+    failed = 0
+    for subj in targets:
+        print(f"Updating {subj.name} ({subj.source})…", file=sys.stderr)
+        try:
+            fresh = get_source(subj.source).fetch(subj.source_id, _progress)
+        except SourceError as exc:
+            print(f"  failed: {exc}", file=sys.stderr)
+            failed += 1
+            continue
+        library.save(fresh)
+        print(f"  {len(fresh.items)} items")
+    return 1 if failed and failed == len(targets) else 0
+
+
+def cmd_sources(args) -> int:
+    for name in AUTO_ORDER:
+        src = REGISTRY[name]
+        kind = "atomic" if src.produces_atomic else "sliceable"
+        print(f"{name:11} {src.domain:11} {kind}")
+    return 0
+
+
+def cmd_quote(args) -> int:
+    cfg = config.load_config()
+    for key, flag in (("lines", args.lines), ("width", args.width),
+                      ("max_lines", args.max_lines), ("max_chars", args.max_chars)):
+        if flag is not None:
+            cfg[key] = flag
+    text = lockscreen.quote(cfg, subject=args.subject, domain=args.domain,
+                            source=args.source, seed=args.seed,
+                            show_note=args.note)
+    if text is None:
+        print("No quotes stored yet — run: hyprmuse add \"Franz Kafka\"")
+        return 0
+    print(text)
+    return 0
+
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="hyprmuse",
+        description="Random quotes from musicians, authors and poets, for hyprlock.")
+    sub = p.add_subparsers(dest="cmd")
+
+    def add_search_flags(sp):
+        sp.add_argument("--source", default="", choices=sorted(REGISTRY) + [""],
+                        help="restrict to one source (default: try all)")
+        sp.add_argument("--lang", default="en",
+                        help="language edition, for wikiquote (e.g. de)")
+
+    sp = sub.add_parser("add", help="harvest a new subject")
+    sp.add_argument("query")
+    add_search_flags(sp)
+    sp.add_argument("--yes", "-y", action="store_true",
+                    help="take the best match without prompting")
+    sp.set_defaults(func=cmd_add)
+
+    sp = sub.add_parser("search", help="look up subjects without harvesting")
+    sp.add_argument("query")
+    add_search_flags(sp)
+    sp.set_defaults(func=cmd_search)
+
+    sp = sub.add_parser("list", help="show stored subjects")
+    sp.set_defaults(func=cmd_list)
+
+    sp = sub.add_parser("remove", help="delete a stored subject")
+    sp.add_argument("token", help="source:id or part of the name")
+    sp.set_defaults(func=cmd_remove)
+
+    sp = sub.add_parser("update", help="re-harvest stored subjects")
+    sp.add_argument("token", nargs="?", default="")
+    sp.add_argument("--all", action="store_true")
+    sp.set_defaults(func=cmd_update)
+
+    sp = sub.add_parser("sources", help="list available sources")
+    sp.set_defaults(func=cmd_sources)
+
+
+    sp = sub.add_parser("quote", help="print a random quote (default command)")
+    sp.add_argument("--lines", type=int, default=None,
+                    help="lines to take from sliceable items")
+    sp.add_argument("--width", type=int, default=None, help="wrap width, 0 disables")
+    sp.add_argument("--max-lines", type=int, default=None,
+                    help="most lines after wrapping; shorter picks are preferred")
+    sp.add_argument("--max-chars", type=int, default=None,
+                    help="most characters after wrapping, 0 disables")
+    sp.add_argument("--subject", default="", help="restrict to one subject")
+    sp.add_argument("--domain", default="", help="restrict to a domain")
+    sp.add_argument("--source", default="", help="restrict to a source")
+    sp.add_argument("--note", action="store_true", help="include the citation note")
+    sp.add_argument("--seed", type=int, default=None, help="deterministic pick")
+    sp.set_defaults(func=cmd_quote)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Bare `hyprmuse` prints a quote, so hyprlock can call it with no arguments.
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help")):
+        argv.insert(0, "quote")
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        return 130
+    except SourceError as exc:
+        return _err(str(exc))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyprmuse/config.py

@@ -0,0 +1,46 @@
+"""XDG paths and user configuration."""
+
+import os
+import tomllib
+from pathlib import Path
+
+APP = "hyprmuse"
+
+
+def _xdg(env: str, fallback: str) -> Path:
+    root = os.environ.get(env)
+    return (Path(root) if root else Path.home() / fallback) / APP
+
+
+DATA_DIR = _xdg("XDG_DATA_HOME", ".local/share")
+CONFIG_DIR = _xdg("XDG_CONFIG_HOME", ".config")
+SUBJECTS_DIR = DATA_DIR / "subjects"
+RECENT_FILE = DATA_DIR / "recent.json"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+DEFAULTS = {
+    "lines": 3,
+    "width": 60,
+    "max_lines": 6,
+    "max_chars": 0,  # total characters after wrapping, 0 = unlimited
+    "weighting": "subject",  # "subject" or "quote"
+    "avoid_repeats": 20,
+    "min_line_chars": 2,  # lines shorter than this ("-", "I") are skipped when slicing
+}
+
+
+def load_config() -> dict:
+    """Merge config.toml over DEFAULTS. Missing or broken file falls back cleanly."""
+    cfg = dict(DEFAULTS)
+    cfg["subjects"] = {}
+    if not CONFIG_FILE.exists():
+        return cfg
+    try:
+        raw = tomllib.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return cfg
+    for key in DEFAULTS:
+        if key in raw.get("quote", {}):
+            cfg[key] = raw["quote"][key]
+    cfg["subjects"] = raw.get("subjects", {})
+    return cfg

hyprmuse/library.py

@@ -0,0 +1,111 @@
+"""On-disk store: one JSON file per subject under the XDG data directory."""
+
+import json
+import os
+import re
+import tempfile
+import unicodedata
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import config
+from .sources.base import Item, Subject
+
+SCHEMA = 1
+
+
+def slugify(text: str) -> str:
+    norm = unicodedata.normalize("NFKD", text)
+    norm = "".join(c for c in norm if not unicodedata.combining(c))
+    norm = re.sub(r"[^a-zA-Z0-9]+", "-", norm).strip("-").lower()
+    return norm or "unnamed"
+
+
+def subject_key(source: str, source_id: str) -> str:
+    return f"{source}:{source_id}"
+
+
+def subject_path(source: str, source_id: str) -> Path:
+    return config.SUBJECTS_DIR / f"{source}--{slugify(source_id)}.json"
+
+
+def save(subject: Subject) -> Path:
+    """Write a subject atomically so a crash can never truncate the store."""
+    config.SUBJECTS_DIR.mkdir(parents=True, exist_ok=True)
+    path = subject_path(subject.source, subject.source_id)
+    payload = {
+        "schema": SCHEMA,
+        "source": subject.source,
+        "source_id": subject.source_id,
+        "name": subject.name,
+        "domain": subject.domain,
+        "lang": subject.lang,
+        "url": subject.url,
+        "fetched_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "attribution": subject.attribution,
+        "items": [
+            {"work": i.work, "url": i.url, "atomic": i.atomic,
+             "note": i.note, "lines": i.lines}
+            for i in subject.items
+        ],
+    }
+    fd, tmp = tempfile.mkstemp(dir=config.SUBJECTS_DIR, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, ensure_ascii=False, indent=2)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+    return path
+
+
+def _to_subject(data: dict) -> Subject:
+    return Subject(
+        source=data["source"],
+        source_id=data["source_id"],
+        name=data["name"],
+        domain=data.get("domain", "unknown"),
+        lang=data.get("lang", "en"),
+        url=data.get("url", ""),
+        attribution=data.get("attribution", {}),
+        items=[
+            Item(lines=i["lines"], work=i.get("work", ""), url=i.get("url", ""),
+                 atomic=i.get("atomic", False), note=i.get("note", ""))
+            for i in data.get("items", [])
+        ],
+    )
+
+
+def load_all() -> list[Subject]:
+    """Every stored subject. Unreadable files are skipped, not fatal."""
+    if not config.SUBJECTS_DIR.is_dir():
+        return []
+    out = []
+    for path in sorted(config.SUBJECTS_DIR.glob("*.json")):
+        try:
+            out.append(_to_subject(json.loads(path.read_text(encoding="utf-8"))))
+        except (OSError, ValueError, KeyError):
+            continue
+    return out
+
+
+def find(token: str) -> list[Subject]:
+    """Resolve 'source:id', or a case-insensitive substring of the name."""
+    subjects = load_all()
+    if ":" in token:
+        src, _, sid = token.partition(":")
+        exact = [s for s in subjects
+                 if s.source == src and s.source_id == sid]
+        if exact:
+            return exact
+    low = token.lower()
+    return [s for s in subjects if low in s.name.lower()]
+
+
+def remove(subject: Subject) -> bool:
+    path = subject_path(subject.source, subject.source_id)
+    if path.exists():
+        path.unlink()
+        return True
+    return False

hyprmuse/lockscreen.py

@@ -0,0 +1,224 @@
+"""The quote hyprlock shows: drawn from the library, fitted to a box, attributed.
+
+Everything about the box (wrapping, line and character caps, what happens when
+nothing fits) and about repeat avoidance lives here, behind ``quote``.
+"""
+
+import hashlib
+import json
+import random
+import textwrap
+from dataclasses import dataclass
+
+from . import config, library
+from .sources.base import Item, Subject
+from .text import stanzas, wrap
+
+DASH = "—"
+
+
+def quote(cfg: dict, *, subject: str = "", domain: str = "", source: str = "",
+          seed: int | None = None, show_note: bool = False) -> str | None:
+    """A random quote from the library, rendered as text for the lockscreen.
+
+    ``cfg`` is a config dict shaped like ``config.load_config()``'s: the keys
+    of ``config.DEFAULTS`` (each documented there) plus ``"subjects"``, the
+    per-subject ``enabled``/``weight`` table. A caller overriding a setting
+    replaces its key before the call.
+
+    ``subject`` (a name substring or a ``source:id`` key), ``domain`` and
+    ``source`` restrict which stored subjects are drawn from; empty means any.
+    ``seed`` makes the draw deterministic and leaves the repeat history alone.
+    ``show_note`` appends the item's citation note, when it has one.
+
+    The result is the quote body, a blank line, then "— Name" or "— Name: Work",
+    then the note if shown. The body fits the box ``cfg`` describes; when no
+    stored quote fits, the best effort is trimmed to it, and only then can a
+    line end in "…". Returns None when no stored subject passes the filters,
+    or none of their items has a line longer than ``cfg["min_line_chars"]``.
+
+    Unless ``seed`` is set, records the quote in ``config.RECENT_FILE`` so the
+    next ``cfg["avoid_repeats"]`` draws avoid it; a failure to write that file
+    is ignored, since a read-only home must not break the lockscreen.
+    """
+    pool = _candidates(cfg, subject=subject, domain=domain, source=source)
+    if not pool:
+        return None
+    rng = random.Random(seed)
+    recent = _load_recent()
+    keep = int(cfg.get("avoid_repeats", 20))
+    weights = [_weight(s, cfg) for s in pool]
+    if sum(weights) <= 0:
+        weights = [1.0] * len(pool)
+    fit = _Fit(width=int(cfg["width"]), max_lines=int(cfg["max_lines"]),
+               max_chars=int(cfg["max_chars"]))
+
+    draw = dict(num_lines=int(cfg["lines"]),
+                min_chars=int(cfg.get("min_line_chars", 0)),
+                recent=recent if keep > 0 else [])
+    chosen = _draw(pool, weights, rng, fit=fit, **draw)
+    if chosen is None and fit != _UNCONSTRAINED:
+        # Nothing in the library fits the box; a trimmed quote beats a blank
+        # lockscreen, so draw without it and let _render trim the result.
+        chosen = _draw(pool, weights, rng, fit=_UNCONSTRAINED, **draw)
+    if chosen is None:
+        return None
+
+    if keep > 0 and seed is None:
+        _save_recent(recent + [chosen.fingerprint()], keep)
+    return _render(chosen, fit, show_note=show_note)
+
+
+@dataclass(frozen=True)
+class _Fit:
+    """The box a rendered quote has to fit in. Zero means unconstrained."""
+
+    width: int = 0
+    max_lines: int = 0
+    max_chars: int = 0  # summed over the wrapped lines, newlines not counted
+
+    def accepts(self, lines: list[str]) -> bool:
+        body = wrap(lines, self.width)
+        if self.max_lines > 0 and len(body) > self.max_lines:
+            return False
+        if self.max_chars > 0 and sum(len(ln) for ln in body) > self.max_chars:
+            return False
+        return True
+
+    def trim(self, lines: list[str]) -> list[str]:
+        """Wrap ``lines`` and cut them to the box, keeping at least one line.
+
+        Whole lines go from the end first; only a single line still over
+        max_chars is cut inside, at a word boundary, and marked with "…".
+        """
+        body = wrap(lines, self.width)
+        if self.max_lines > 0:
+            body = body[:self.max_lines]
+        if self.max_chars <= 0:
+            return body
+        while len(body) > 1 and sum(len(ln) for ln in body) > self.max_chars:
+            body = body[:-1]
+        if body and len(body[0]) > self.max_chars:
+            short = textwrap.shorten(body[0], width=self.max_chars, placeholder="…")
+            # shorten() yields the bare placeholder when the first word alone
+            # is too long; a hard cut keeps some text instead.
+            if short == "…":
+                short = body[0][:self.max_chars - 1] + "…"
+            body = [short]
+        return body
+
+
+_UNCONSTRAINED = _Fit()
+
+
+@dataclass
+class _Pick:
+    """One drawn quote: the lines taken from ``item``, before wrapping."""
+
+    subject: Subject
+    item: Item
+    lines: list[str]
+
+    def fingerprint(self) -> str:
+        """Identifies the quote in the repeat history; equal text, equal print."""
+        seed = f"{self.subject.source}:{self.subject.source_id}:" + "|".join(self.lines)
+        return hashlib.sha1(seed.encode("utf-8")).hexdigest()[:16]
+
+
+def _render(pick: _Pick, fit: _Fit, *, show_note: bool) -> str:
+    who = pick.subject.name
+    work = pick.item.work.strip()
+    parts = ["\n".join(fit.trim(pick.lines)), "",
+             f"{DASH} {who}: {work}" if work else f"{DASH} {who}"]
+    if show_note and pick.item.note:
+        parts.extend(wrap([pick.item.note], fit.width))
+    return "\n".join(parts)
+
+
+def _load_recent() -> list[str]:
+    try:
+        return json.loads(config.RECENT_FILE.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+
+
+def _save_recent(seen: list[str], keep: int) -> None:
+    try:
+        config.DATA_DIR.mkdir(parents=True, exist_ok=True)
+        config.RECENT_FILE.write_text(json.dumps(seen[-keep:]), encoding="utf-8")
+    except OSError:
+        pass  # a read-only home must not break the lockscreen
+
+
+def _candidates(cfg: dict, *, subject: str, domain: str,
+                source: str) -> list[Subject]:
+    """Stored subjects with items, minus those disabled in config or filtered out."""
+    out = []
+    for subj in library.load_all():
+        settings = cfg.get("subjects", {}).get(
+            library.subject_key(subj.source, subj.source_id), {})
+        if settings.get("enabled") is False:
+            continue
+        if domain and subj.domain != domain:
+            continue
+        if source and subj.source != source:
+            continue
+        if subject and subject.lower() not in subj.name.lower() \
+                and subject != library.subject_key(subj.source, subj.source_id):
+            continue
+        if subj.items:
+            out.append(subj)
+    return out
+
+
+def _weight(subj: Subject, cfg: dict) -> float:
+    settings = cfg.get("subjects", {}).get(
+        library.subject_key(subj.source, subj.source_id), {})
+    base = float(settings.get("weight", 1.0))
+    # "quote" weighting makes every stored quote equally likely, so prolific
+    # subjects dominate; "subject" (the default) gives each subject equal say.
+    return base * len(subj.items) if cfg.get("weighting") == "quote" else base
+
+
+def _extract(item: Item, num_lines: int, rng: random.Random, *,
+             min_chars: int, fit: _Fit) -> list[str]:
+    """Lines to quote from one item, or [] if nothing from it fits.
+
+    Sliceable items are cut within a single stanza (blank-line delimited), so
+    a window never straddles a verse and its chorus. If the window overflows
+    the fit it is shortened from the end, a line at a time, before giving up.
+    """
+    groups = stanzas(item.lines, min_chars)
+    if not groups:
+        return []
+    if item.atomic:
+        whole = [ln for g in groups for ln in g]
+        return whole if fit.accepts(whole) else []
+    # A one-line stanza is usually a stray refrain tag or an orphaned line;
+    # prefer real stanzas whenever the item has any.
+    usable = [g for g in groups if len(g) >= 2] or groups
+    stanza = rng.choice(usable)
+    take = min(num_lines, len(stanza))
+    start = rng.randint(0, len(stanza) - take)
+    for n in range(take, 0, -1):
+        window = stanza[start:start + n]
+        if fit.accepts(window):
+            return window
+    return []
+
+
+def _draw(pool: list[Subject], weights: list[float], rng: random.Random, *,
+          num_lines: int, min_chars: int, fit: _Fit, recent: list[str],
+          tries: int = 40) -> _Pick | None:
+    """Weighted random pick, retrying briefly to avoid a recently shown one."""
+    chosen = None
+    for _ in range(tries):
+        subj = rng.choices(pool, weights=weights, k=1)[0]
+        item = rng.choice(subj.items)
+        lines = _extract(item, num_lines, rng, min_chars=min_chars, fit=fit)
+        if not lines:
+            continue
+        chosen = _Pick(subj, item, lines)
+        if chosen.fingerprint() not in recent:
+            break
+    return chosen

hyprmuse/sources/__init__.py

@@ -0,0 +1,25 @@
+"""Registry of quote sources."""
+
+from . import genius, gutenberg, poetrydb, wikiquote
+from .base import Candidate, Item, Source, SourceError, Subject
+
+REGISTRY: dict[str, Source] = {
+    s.SOURCE.name: s.SOURCE for s in (genius, wikiquote, poetrydb, gutenberg)
+}
+
+# Order tried when the user does not name a source explicitly. Wikiquote first:
+# it has the broadest subject coverage across every domain.
+AUTO_ORDER = ["wikiquote", "genius", "poetrydb", "gutenberg"]
+
+
+def get_source(name: str) -> Source:
+    try:
+        return REGISTRY[name]
+    except KeyError:
+        raise SourceError(
+            f"unknown source '{name}' (have: {', '.join(sorted(REGISTRY))})"
+        ) from None
+
+
+__all__ = ["REGISTRY", "AUTO_ORDER", "get_source", "Candidate", "Item",
+           "Source", "SourceError", "Subject"]