tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/images.py

@@ -0,0 +1,133 @@
+"""The covers of the albums, the radio stations and the entries of Spotify: images in one folder, the images folder.
+
+A cover is kept here under a generated name that begins with :data:`ALBUM_PREFIX`, :data:`STATION_PREFIX` or
+:data:`SPOTIFY_PREFIX`; the entry names it. Only these images count: any other file in the folder is ignored. An album
+without such a cover shows an image of its folder or of its tracks (:func:`tinyjukebox.metadata.find_cover`).
+"""
+
+import os
+import re
+import secrets
+from collections.abc import Callable
+
+from tinyjukebox.errors import BadRequest, NotFound, PayloadTooLarge
+
+__all__ = [
+    "ALBUM_PREFIX",
+    "IMAGE_TYPES",
+    "MAX_IMAGE_SIZE",
+    "SPOTIFY_PREFIX",
+    "STATION_PREFIX",
+    "Images",
+    "image_extension",
+    "is_cover",
+    "take_over",
+]
+
+IMAGE_TYPES = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp"}
+MAX_IMAGE_SIZE = 10 * 2**20
+STATION_PREFIX = "station-"
+SPOTIFY_PREFIX = "spotify-"
+ALBUM_PREFIX = "album-"
+# the generated name of the cover of an album. Not every "album-…": until 0.28 the folder held the card images of
+# tags, and the images that tinyjukebox-import-covers reads are named "album-<id>"
+_ALBUM_COVER = re.compile(r"album-[0-9a-f]{8}")
+
+
+def image_extension(data: bytes) -> str | None:
+    """File extension for the image type detected from the content - ``None`` for unsupported data."""
+    if data.startswith(b"\xff\xd8\xff"):
+        return ".jpg"
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return ".png"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return ".webp"
+    return None
+
+
+def is_cover(name: str) -> bool:
+    """Whether ``name`` is the name of a cover: the prefix of a station or an entry of Spotify, or the generated name
+    of the cover of an album, and the extension of an image."""
+    base, extension = os.path.splitext(name)
+    if extension.lower() not in IMAGE_TYPES:
+        return False
+    return name.startswith((STATION_PREFIX, SPOTIFY_PREFIX)) or _ALBUM_COVER.fullmatch(base) is not None
+
+
+def take_over(old_folder: str, folder: str) -> int:
+    """Until 0.28 the covers of the stations were in the folder ``cards``, among the card images of tags. Move them
+    from ``old_folder`` to ``folder``; whatever else is in the old folder stays there and is not used any more.
+    Returns the number of covers moved."""
+    try:
+        names = [name for name in os.listdir(old_folder) if is_cover(name)]
+    except (FileNotFoundError, NotADirectoryError):
+        return 0
+    os.makedirs(folder, exist_ok=True)
+    moved = 0
+    for name in names:
+        if not os.path.exists(os.path.join(folder, name)):
+            os.replace(os.path.join(old_folder, name), os.path.join(folder, name))
+            moved += 1
+    return moved
+
+
+class Images:
+    """The covers of the albums, stations and entries of Spotify in ``folder``. Only files listed in the folder are
+    ever opened - names from requests are never used as paths directly."""
+
+    def __init__(self, folder: str) -> None:
+        self.folder = folder
+        self._listener: Callable[[], None] | None = None
+
+    def listen(self, listener: Callable[[], None]) -> None:
+        """``listener()`` is called whenever an image was added or removed - for the synchronization
+        (:mod:`tinyjukebox.sync`)."""
+        self._listener = listener
+
+    def _tell(self) -> None:
+        if self._listener is not None:
+            self._listener()
+
+    def names(self) -> list[str]:
+        try:
+            names = os.listdir(self.folder)
+        except FileNotFoundError:
+            return []
+        return sorted(name for name in names if is_cover(name))
+
+    def has(self, name: str) -> bool:
+        """Whether the image ``name`` is in the folder."""
+        return name in self.names()
+
+    def _check_name(self, name: str) -> str:
+        if name not in self.names():
+            raise NotFound(f"unknown image '{name}'.")
+        return name
+
+    def image(self, name: str) -> tuple[bytes, str]:
+        """(content, mime type) of an image."""
+        name = self._check_name(name)
+        with open(os.path.join(self.folder, name), "rb") as f:
+            return f.read(), IMAGE_TYPES[os.path.splitext(name)[1].lower()]
+
+    def add(self, data: bytes, prefix: str = STATION_PREFIX) -> str:
+        """Store a new cover (jpeg, png or webp) of a station or, with :data:`ALBUM_PREFIX` or :data:`SPOTIFY_PREFIX`,
+        of an album or an entry of Spotify - returns its generated name."""
+        if len(data) > MAX_IMAGE_SIZE:
+            raise PayloadTooLarge("image is too large.", code="image.too_large")
+        extension = image_extension(data)
+        if extension is None:
+            raise BadRequest("only jpeg, png and webp images are supported.", code="image.type")
+        os.makedirs(self.folder, exist_ok=True)
+        name = f"{prefix}{secrets.token_hex(4)}{extension}"
+        temp = os.path.join(self.folder, f".{name}.tmp")  # hidden: no cover while it is written
+        with open(temp, "wb") as f:
+            f.write(data)
+        os.replace(temp, os.path.join(self.folder, name))
+        self._tell()
+        return name
+
+    def delete(self, name: str) -> None:
+        self._check_name(name)
+        os.remove(os.path.join(self.folder, name))
+        self._tell()

tinyjukebox/latency.py

@@ -0,0 +1,43 @@
+"""Latency of the reaction chains of the box (tag read → playback, button pressed → volume set)."""
+
+import logging
+import threading
+import time
+
+from tinyjukebox.core.logging import get_child
+
+__all__ = ["ReactionTimer"]
+
+
+class ReactionTimer:
+    """Measures one reaction chain and logs one info line per step with the time since its trigger.
+
+    :meth:`begin` starts a measurement (a pending one is dropped), :meth:`step` logs an intermediate step and
+    :meth:`end` logs the last step and finishes the measurement. Steps without a pending measurement are ignored -
+    e.g. the start of the next track is no reaction to a tag.
+    """
+
+    def __init__(self, name: str, logger: logging.Logger) -> None:
+        self._name = name
+        self._logger = get_child(logger, "latency")
+        self._lock = threading.Lock()
+        self._started: float | None = None
+
+    def begin(self, started: float | None = None) -> None:
+        """Start a measurement at ``started`` (``time.monotonic()``; default: now)."""
+        with self._lock:
+            self._started = time.monotonic() if started is None else started
+
+    def step(self, what: str) -> None:
+        self._log(what, finish=False)
+
+    def end(self, what: str) -> None:
+        self._log(what, finish=True)
+
+    def _log(self, what: str, finish: bool) -> None:
+        with self._lock:
+            started = self._started
+            if finish:
+                self._started = None
+        if started is not None:
+            self._logger.info("%s: %s after %.0f ms", self._name, what, (time.monotonic() - started) * 1000)

tinyjukebox/library/__init__.py

@@ -0,0 +1,2 @@
+"""The library of Tiny Jukebox: the catalog and the albums for all boxes, and the versions of the box software
+(docs/developer/library.md). Console script: ``tinyjukebox-library``."""

tinyjukebox/library/diagnostics.py

@@ -0,0 +1,183 @@
+"""What the library keeps of the logs of the boxes (docs/developer/library.md, section 4.22): the records a box
+delivers, and the last startup failure of a box that cannot start.
+
+SQLite of its own, apart from the journal: a listening record and a technical log are different things, and this one
+is thrown away by age and by number. A record is taken once - a box that sends a batch again after a lost answer
+changes nothing.
+"""
+
+import datetime
+import json
+import sqlite3
+import threading
+from typing import Any
+
+from tinyjukebox.sync.util import timestamp
+
+__all__ = ["DAYS", "PER_BOX", "Diagnostics"]
+
+DAYS = 30
+PER_BOX = 20000
+LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+COLUMNS = ("box", "boot", "seq", "received", "time", "uptime", "level", "component", "code", "message", "version")
+INSERT = "INSERT OR IGNORE INTO records VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+FILTERS = ("box", "level", "component", "version", "code", "since", "until", "text")
+
+
+class Diagnostics:
+    def __init__(self, filename: str, days: int = DAYS, per_box: int = PER_BOX) -> None:
+        self._days = days
+        self._per_box = per_box
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(filename, check_same_thread=False)
+        with self._lock, self._db:
+            self._db.execute(
+                "CREATE TABLE IF NOT EXISTS records (box TEXT, boot INTEGER, seq INTEGER, received TEXT, time TEXT, "
+                "uptime REAL, level TEXT, component TEXT, code TEXT, message TEXT, version TEXT, data TEXT, "
+                "PRIMARY KEY (box, boot, seq))"
+            )
+            self._db.execute("CREATE INDEX IF NOT EXISTS records_time ON records (box, time)")
+            self._db.execute("CREATE TABLE IF NOT EXISTS startup (box TEXT PRIMARY KEY, received TEXT, report TEXT)")
+        self._added = 0
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+    # --- what a box delivers -----------------------------------------------------------------------------------------
+
+    def add(self, box: str, envelope: dict[str, Any]) -> int:
+        """Records of one start of a box; returns how many were new."""
+        boot, version = int(envelope.get("boot") or 0), str(envelope.get("version") or "")
+        records = envelope.get("records") or []
+        if not isinstance(records, list):
+            raise TypeError("'records' must be a list")
+        received, new = timestamp(), 0
+        rows = []
+        for record in records:
+            if not isinstance(record, dict) or not isinstance(record.get("seq"), int):
+                continue
+            extra = {key: value for key, value in record.items() if key not in COLUMNS}
+            rows.append((
+                box, boot, record["seq"], received, str(record.get("time") or received),
+                float(record.get("uptime") or 0), str(record.get("level") or "INFO"),
+                str(record.get("component") or ""), str(record.get("code") or "")[:200],
+                str(record.get("message") or "")[:4000], version, json.dumps(extra),
+            ))  # fmt: skip
+        dropped = {str(level): int(count) for level, count in (envelope.get("dropped") or {}).items() if count}
+        if dropped:  # the box had to throw records away: the library says how many
+            rows.append((
+                box, boot, _own_number(), received, received, 0.0,
+                "WARNING", "diagnostics", "diagnostics.dropped",
+                "the box dropped records it could not deliver: "
+                + ", ".join(f"{count} {level}" for level, count in sorted(dropped.items())),
+                version, json.dumps({"params": dropped}),
+            ))  # fmt: skip
+        with self._lock, self._db:
+            for row in rows:
+                new += self._db.execute(INSERT, row).rowcount
+            self._added += new
+            if self._added > 500:  # now and then, not with every batch
+                self._added = 0
+                self._prune()
+        return new
+
+    def _prune(self) -> None:
+        """Called with the lock held: the records older than the days, and per box beyond the number."""
+        limit = datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=self._days)
+        self._db.execute("DELETE FROM records WHERE time < ?", (limit.strftime("%Y-%m-%dT%H:%M:%SZ"),))
+        for (box,) in self._db.execute("SELECT DISTINCT box FROM records").fetchall():
+            self._db.execute(
+                "DELETE FROM records WHERE box = ? AND rowid NOT IN "
+                "(SELECT rowid FROM records WHERE box = ? ORDER BY time DESC, seq DESC LIMIT ?)",
+                (box, box, self._per_box),
+            )
+
+    def prune(self) -> None:
+        with self._lock, self._db:
+            self._prune()
+
+    # --- a box that cannot start -------------------------------------------------------------------------------------
+
+    def startup(self, box: str, report: dict[str, Any]) -> None:
+        """The last startup failure of a box replaces the one before: a restart loop does not fill the library."""
+        clean: dict[str, Any] = {
+            key: str(report[key])[:limit]
+            for key, limit in (("version", 50), ("slot", 20), ("since", 40), ("error", 8000), ("recovery", 2000))
+            if report.get(key) not in (None, "")
+        }
+        clean["failures"] = int(report.get("failures") or 0)
+        with self._lock, self._db:
+            self._db.execute("INSERT OR REPLACE INTO startup VALUES (?, ?, ?)", (box, timestamp(), json.dumps(clean)))
+
+    def started(self, box: str) -> None:
+        """The application of the box runs again: its last startup failure becomes a record of its history."""
+        with self._lock, self._db:
+            row = self._db.execute("SELECT received, report FROM startup WHERE box = ?", (box,)).fetchone()
+            if row is None:
+                return
+            received, report = row[0], json.loads(row[1])
+            self._db.execute("DELETE FROM startup WHERE box = ?", (box,))
+            message = (
+                f"the box could not start ({report.get('failures', 0)} failed starts since {report.get('since', '?')})"
+                + (f": {report['error'].strip().splitlines()[-1]}" if report.get("error", "").strip() else "")
+            )
+            self._db.execute(
+                INSERT,
+                (box, 0, _own_number(), received, received, 0.0, "ERROR", "start", "startup.failed", message[:4000],
+                 report.get("version", ""), json.dumps({"traceback": report.get("error", ""), "params": report})),
+            )  # fmt: skip
+
+    def startups(self) -> dict[str, dict[str, Any]]:
+        """The boxes that cannot start, with their last report."""
+        with self._lock:
+            rows = self._db.execute("SELECT box, received, report FROM startup").fetchall()
+        return {box: {**json.loads(report), "received": received} for box, received, report in rows}
+
+    # --- for the page ------------------------------------------------------------------------------------------------
+
+    def query(self, limit: int = 1000, **filters: str) -> list[dict[str, Any]]:
+        """The newest records that match, oldest first. ``level``: at least this level; ``text``: in the message, the
+        code or the component; ``since``/``until``: times as the records carry them."""
+        where, values = ["1"], []
+        for key in ("box", "component", "version", "code"):
+            if filters.get(key):
+                where.append(f"{key} = ?")
+                values.append(filters[key])
+        if filters.get("level") in LEVELS:
+            levels = LEVELS[LEVELS.index(filters["level"]) :]
+            where.append(f"level IN ({', '.join('?' * len(levels))})")
+            values.extend(levels)
+        if filters.get("since"):
+            where.append("time >= ?")
+            values.append(filters["since"])
+        if filters.get("until"):
+            where.append("time <= ?")
+            values.append(filters["until"])
+        if filters.get("text"):
+            where.append("(message LIKE ? OR code LIKE ? OR component LIKE ?)")
+            values.extend([f"%{filters['text']}%"] * 3)
+        with self._lock:
+            rows = self._db.execute(
+                f"SELECT {', '.join(COLUMNS)}, data FROM records WHERE {' AND '.join(where)} "  # noqa: S608 - fixed names
+                "ORDER BY time DESC, boot DESC, seq DESC LIMIT ?",
+                (*values, limit),
+            ).fetchall()
+        return [{**dict(zip(COLUMNS, row[:-1], strict=True)), **json.loads(row[-1])} for row in reversed(rows)]
+
+    def choices(self, box: str | None = None) -> dict[str, list[str]]:
+        """What the filters of the page offer: the components, versions and codes there are."""
+        result = {}
+        with self._lock:
+            for key in ("component", "version", "code"):
+                rows = self._db.execute(
+                    f"SELECT DISTINCT {key} FROM records WHERE (? IS NULL OR box = ?) ORDER BY {key}",  # noqa: S608
+                    (box, box),
+                ).fetchall()
+                result[key] = [row[0] for row in rows if row[0]]
+        return result
+
+
+def _own_number() -> int:
+    """The number of a record the library writes itself: negative, so that it never meets one of a box."""
+    return -int(datetime.datetime.now(datetime.UTC).timestamp() * 1_000_000)

tinyjukebox/library/journal.py

@@ -0,0 +1,94 @@
+"""The journal of the library (docs/developer/library.md, section 7): what the boxes delivered, and what
+the library noted itself.
+
+SQLite, part of Python. A line of a box is taken exactly once and never changed; it can only be flagged as discarded.
+"""
+
+import json
+import os
+import sqlite3
+import tempfile
+import threading
+from typing import Any
+
+from tinyjukebox.sync.util import timestamp
+
+__all__ = ["Journal"]
+
+
+class Journal:
+    def __init__(self, filename: str) -> None:
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(filename, check_same_thread=False)
+        with self._lock, self._db:
+            self._db.execute(
+                "CREATE TABLE IF NOT EXISTS lines (box TEXT, n INTEGER, received TEXT, version TEXT, line TEXT, "
+                "discarded INTEGER DEFAULT 0, PRIMARY KEY (box, n))"
+            )
+            self._db.execute(
+                "CREATE TABLE IF NOT EXISTS records (id INTEGER PRIMARY KEY, time TEXT, kind TEXT, box TEXT, data TEXT)"
+            )
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+    def add(self, box: str, confirmed: int, lines: list[dict[str, Any]]) -> int:
+        """Take the lines that follow the number ``confirmed`` without a gap; return the number confirmed now."""
+        with self._lock, self._db:
+            for line in sorted(lines, key=lambda line: int(line["n"])):
+                if line["n"] <= confirmed:
+                    continue  # delivered before: the confirmation got lost
+                if line["n"] != confirmed + 1:
+                    break
+                self._db.execute(
+                    "INSERT OR IGNORE INTO lines (box, n, received, version, line) VALUES (?, ?, ?, ?, ?)",
+                    (box, line["n"], timestamp(), line.get("version"), json.dumps(line)),
+                )
+                confirmed = line["n"]
+        return confirmed
+
+    def snapshot(self) -> bytes:
+        """The database as a file of its own, for a backup: a copy made by SQLite, never the file that is written."""
+        with self._lock, tempfile.TemporaryDirectory() as folder:
+            filename = os.path.join(folder, "journal.sqlite")
+            copy = sqlite3.connect(filename)
+            try:
+                self._db.backup(copy)
+            finally:
+                copy.close()
+            with open(filename, "rb") as infile:
+                return infile.read()
+
+    def discard(self, box: str, version: str) -> int:
+        with self._lock, self._db:
+            return self._db.execute(
+                "UPDATE lines SET discarded = 1 WHERE box = ? AND version = ?", (box, version)
+            ).rowcount
+
+    def lines(self, box: str | None = None) -> list[dict[str, Any]]:
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT box, discarded, line FROM lines WHERE (? IS NULL OR box = ?) ORDER BY box, n", (box, box)
+            ).fetchall()
+        return [{**json.loads(line), "box": row_box, "discarded": bool(discarded)} for row_box, discarded, line in rows]
+
+    def record(self, kind: str, box: str | None, data: dict[str, Any]) -> None:
+        """Something the library notes itself: a conflict, a rejected change, a switch of version of a box."""
+        with self._lock, self._db:
+            self._db.execute(
+                "INSERT INTO records (time, kind, box, data) VALUES (?, ?, ?, ?)",
+                (timestamp(), kind, box, json.dumps(data)),
+            )
+
+    def records(self, kind: str | None = None, box: str | None = None) -> list[dict[str, Any]]:
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT time, kind, box, data FROM records WHERE (? IS NULL OR kind = ?) AND (? IS NULL OR box = ?) "
+                "ORDER BY id",
+                (kind, kind, box, box),
+            ).fetchall()
+        return [
+            {"time": time, "kind": row_kind, "box": row_box, **json.loads(data)}
+            for time, row_kind, row_box, data in rows
+        ]