tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/core/ui/tools.py

@@ -0,0 +1,73 @@
+"""Console helpers for UI commands: paging, yes/no questions and argument parsing."""
+
+import shlex
+import sys
+
+__all__ = ["get_yes_no", "getch", "more", "parse"]
+
+PAGE_SIZE = 35
+_PAGER_TEXT = "   --- ENTER: next page / SPACE: next line / ESC: abort ---"
+_ESC, _SPACE, _ENTER = "\x1b", " ", ("\r", "\n")
+
+
+def getch() -> str:
+    """Read a single character from stdin without echo (falls back to line input if stdin is not a terminal)."""
+    if not sys.stdin.isatty():
+        line = sys.stdin.readline()
+        return line[0] if line else _ESC
+    if sys.platform == "win32":
+        import msvcrt  # noqa: PLC0415 - platform specific
+
+        return msvcrt.getwch()
+
+    import termios  # noqa: PLC0415 - platform specific
+    import tty  # noqa: PLC0415 - platform specific
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        return sys.stdin.read(1)
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def more(text: str, page_size: int = PAGE_SIZE) -> None:
+    """Print ``text`` page by page (only paged if stdout is a terminal)."""
+    lines = text.split("\n")
+    if not sys.stdout.isatty():
+        print(text)
+        return
+    remaining = page_size
+    for line in lines:
+        print(line)
+        remaining -= 1
+        if remaining == 0:
+            print(_PAGER_TEXT, end="\r", flush=True)
+            while True:
+                char = getch()
+                if char == _ESC:
+                    print(" " * len(_PAGER_TEXT), end="\r")
+                    return
+                if char == _SPACE:
+                    remaining = 1
+                    break
+                if char in _ENTER:
+                    remaining = page_size
+                    break
+            print(" " * len(_PAGER_TEXT), end="\r")
+
+
+def get_yes_no() -> str:
+    """Ask 'continue (y/n)' until the user answers; returns ``"y"`` or ``"n"``."""
+    while True:
+        print("continue (y/n):")
+        char = getch().lower()
+        if char in ("y", "n"):
+            return char
+        print(f"unexpected character '{char}'")
+
+
+def parse(arg: str) -> tuple[str, ...]:
+    """Split a command argument string like a shell does (quotes group words)."""
+    return tuple(shlex.split(arg))

tinyjukebox/core/unexpected.py

@@ -0,0 +1,46 @@
+"""The central place for exceptions that nobody expected.
+
+A broken album, a dead radio station or a library that cannot be reached are expected errors and are handled where
+they occur. What arrives here was caught at one of the places that keep the box alive whatever happens: a thread, a
+state machine, the dispatch of the messages, a request of the web page. It was logged there already; the health check
+of a new version (:mod:`tinyjukebox.slots`) listens here.
+"""
+
+import logging
+import threading
+from collections.abc import Callable
+
+__all__ = ["Listener", "report", "subscribe", "unsubscribe"]
+
+_logger = logging.getLogger(__name__)
+
+Listener = Callable[[BaseException, str], None]
+
+_lock = threading.Lock()
+_listeners: list[Listener] = []
+
+
+def subscribe(listener: Listener) -> None:
+    """``listener(error, where)`` is called for every unexpected exception from now on."""
+    with _lock:
+        _listeners.append(listener)
+
+
+def unsubscribe(listener: Listener) -> None:
+    with _lock:
+        if listener in _listeners:
+            _listeners.remove(listener)
+
+
+def report(error: BaseException, where: str) -> None:
+    """Tell the listeners. ``where``: the place that caught the exception, e.g. ``thread RestApi``.
+
+    A listener that fails is logged and ends nothing: the callers are the places that keep the box alive - the
+    dispatch of the messages, a state machine - and a listener writes files, which fails on a full or read-only card."""
+    with _lock:
+        listeners = list(_listeners)
+    for listener in listeners:
+        try:
+            listener(error, where)
+        except Exception:
+            _logger.exception("a listener of unexpected exceptions failed (%s)", where)

tinyjukebox/data/activities.py

@@ -0,0 +1,175 @@
+"""Activities of all tags (activities json file)."""
+
+import logging
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.data.activity import ActivityAlbum
+from tinyjukebox.data.common import Listener, Mirror, TargetType, UpdateJson, is_unmapped
+from tinyjukebox.data.jsondata import JsonData
+from tinyjukebox.data.tag import Tag
+from tinyjukebox.data.tags import Tags
+from tinyjukebox.schema.activities import schema
+
+__all__ = ["Activities", "create_activity_factory", "load_activity_factory"]
+
+
+def create_activity_factory(tag: Any, update_json: UpdateJson | None, logger: logging.Logger) -> ActivityAlbum:
+    """New activity for a linked tag. :raises ValueError: for missing, unlinked or unsupported tags."""
+    factory_logger = get_child(logger, "create_activity_factory")
+    if tag is None or not hasattr(tag, "target_id"):
+        factory_logger.error("tag not provided or not a tag: %s", tag)
+        raise ValueError("tag not provided or not a tag.")
+    if is_unmapped(tag.target_id):
+        factory_logger.error("target id of tag must be set.")
+        raise ValueError("target id of tag must be set.")
+    if tag.target_type not in (TargetType.album, TargetType.spotify):
+        factory_logger.error("unknown target type: %s.", tag.target_type)
+        raise ValueError(f"unknown target type: {tag.target_type}.")
+    return ActivityAlbum.create_activity(tag, update_json, logger)
+
+
+def load_activity_factory(
+    activity: dict[str, Any] | None, update_json: UpdateJson | None, logger: logging.Logger
+) -> ActivityAlbum:
+    """Activity from the json file. :raises ValueError: for invalid entries."""
+    factory_logger = get_child(logger, "load_activity_factory")
+    if activity is None or "target-type" not in activity:
+        factory_logger.error("expected dict with key 'target-type', got %s", activity)
+        raise ValueError("expected dict with key 'target-type'")
+    if activity["target-type"] not in (TargetType.album.name, TargetType.spotify.name):
+        factory_logger.error("unknown target type: %s.", activity["target-type"])
+        raise ValueError(f"unknown target type: {activity['target-type']}.")
+    return ActivityAlbum(activity, update_json, logger)
+
+
+class Activities:
+    """Activities by tag uid. The file is written on every change of an activity (see
+    :class:`~tinyjukebox.data.tags.Tags` for the locking rules).
+
+    A file that neither it nor its backup can be read is not fatal: the activities are rebuilt from the tags (all
+    albums start from the beginning).
+    """
+
+    def __init__(self, filename: str, tags: Tags, logger: logging.Logger) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._lock = threading.RLock()
+        self._tags = tags
+        self._filename = filename
+        self._mirror = Mirror()
+        self.activities: dict[str, ActivityAlbum] = {}
+        self._json = JsonData(filename, filename + "_", schema, self._logger, entries=True)
+        if self._json.started_empty:
+            self._logger.warning("__init__ - no usable activities file - rebuilding.")
+            self.rebuild_activities()
+            return
+        for key, activity in list(self._json.data.items()):
+            try:
+                self.activities[key] = load_activity_factory(activity, self._update_json, self._logger)
+            except ValueError as e:  # a position this version cannot use does not keep the box from starting
+                self._json.set_aside(key, activity, str(e))
+
+    def rebuild_activities(self) -> None:
+        """New activities (start of the album) for all tags linked to an album or an entry of Spotify - radio
+        stations have none."""
+        self._logger.info("rebuild_activities")
+        with self._lock:
+            self.activities = {
+                tag.tag_uid: create_activity_factory(tag, self._update_json, self._logger)
+                for tag in self._tags.all()
+                if tag.tag_uid is not None
+                and tag.target_type in (TargetType.album, TargetType.spotify)
+                and not is_unmapped(tag.target_id)
+            }
+            self._update_json()
+
+    def _to_dict(self) -> dict[str, Any]:
+        return {key: activity.to_dict() for key, activity in self.activities.items()}
+
+    def _update_json(self) -> None:
+        with self._lock:
+            data = self._to_dict()
+            self._json.store(data)
+            self._mirror.changed(data)
+
+    def listen(self, listener: Listener) -> None:
+        """``listener(tag_uid, entry)`` is called for every activity that changes from now on (``None``: deleted)."""
+        with self._lock:
+            self._mirror.listen(listener, self._to_dict())
+
+    def sync(self, get: Callable[[], dict[str, Any]]) -> bool:
+        """Make the activities what ``get()`` returns (the content of the activities json file), keeping the
+        activities that stay. The listener is not called. Returns whether something changed."""
+        with self._lock:
+            data, aside = self._json.split(get())
+            if data == self._to_dict() and aside == self._json.aside:
+                return False
+            for key in [key for key in self.activities if key not in data]:
+                del self.activities[key]
+            for key, entry in data.items():
+                try:
+                    if key in self.activities:
+                        self.activities[key].load(entry)
+                    else:
+                        self.activities[key] = load_activity_factory(entry, self._update_json, self._logger)
+                except ValueError as e:
+                    self._logger.warning("sync - activity '%s' set aside: %s", key, e)
+                    self.activities.pop(key, None)
+                    aside[key] = entry
+            data = self._to_dict()
+            self._json.store(data, aside)
+            self._mirror.replaced(data)
+            return True
+
+    def all(self) -> dict[str, ActivityAlbum]:
+        """Snapshot of all activities by tag uid."""
+        with self._lock:
+            return dict(self.activities)
+
+    def get_activity(self, tag_uid: str | None) -> ActivityAlbum:
+        """:raises ValueError: for unknown tag uids."""
+        activity = self.activities.get(tag_uid) if tag_uid is not None else None
+        if activity is None:
+            self._logger.warning("get_activity - unknown tag uid %s.", tag_uid)
+            raise ValueError(f"get_activity - unknown tag uid {tag_uid}.")
+        return activity
+
+    def add_activity(self, tag: Tag | None) -> ActivityAlbum:
+        """New activity for the tag. :raises ValueError: if the tag is missing, unlinked or has an activity."""
+        if tag is None or tag.tag_uid is None:
+            self._logger.warning("add_activity - tag is None.")
+            raise ValueError("add_activity - tag is None.")
+        with self._lock:
+            if tag.tag_uid in self.activities:
+                self._logger.warning("add_activity - tag uid %s already exists.", tag.tag_uid)
+                raise ValueError(f"add_activity - tag uid {tag.tag_uid} already exists.")
+            activity = create_activity_factory(tag, self._update_json, self._logger)
+            self.activities[tag.tag_uid] = activity
+            self._update_json()
+        return activity
+
+    def delete_activity(self, tag_uid: str | None) -> None:
+        if tag_uid is None:
+            self._logger.warning("delete_activity - tag is None.")
+            raise ValueError("delete_activity - tag is None.")
+        with self._lock:
+            if tag_uid not in self.activities:
+                self._logger.warning("delete_activity - unknown tag uid %s.", tag_uid)
+                raise ValueError(f"delete_activity - unknown tag uid {tag_uid}.")
+            del self.activities[tag_uid]
+            self._update_json()
+
+    def sanity_check(self) -> bool:
+        result = True
+        for key, activity in self.all().items():
+            if key != activity.tag_uid:
+                self._logger.warning("sanity_check - key '%s' != activity.tag_uid '%s'", key, activity.tag_uid)
+                result = False
+            if not activity.sanity_check():
+                result = False
+        return result
+
+    def to_text(self) -> str:
+        return "\n".join(f"key: {key}, activity: {activity.to_text()}" for key, activity in self.all().items())

tinyjukebox/data/activity.py

@@ -0,0 +1,138 @@
+"""Activities: the playback position of a tag's target (where to resume when the tag is placed again)."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.data.common import TargetType, UpdateJson, extra_fields, is_unmapped
+
+__all__ = ["AActivity", "ActivityAlbum"]
+
+_REQUIRED_ALBUM_KEYS = ("track-id", "track-time", "album-finished")
+_FIELDS = ("tag-uid", "target-id", "target-type", "track-uri", *_REQUIRED_ALBUM_KEYS)
+
+
+class AActivity(ABC):
+    """Base class of all activities."""
+
+    def __init__(
+        self,
+        tag_uid: str,
+        target_id: str | int,
+        target_type: TargetType,
+        update_json: UpdateJson | None,
+        logger: logging.Logger,
+    ) -> None:
+        self._logger = get_child(logger, f"{type(self).__name__}.{tag_uid}-{target_id}")
+        self.tag_uid = tag_uid
+        self.target_id = target_id
+        self.target_type = target_type
+        if target_id is None or not str(target_id):
+            self._logger.error("__init__ - target id must not be empty.")
+            raise ValueError("target id must not be empty.")
+        if update_json is None or not callable(update_json):
+            self._logger.error("__init__ - update_json method not provided")
+            raise ValueError("update_json method not provided.")
+        self._update_json = update_json
+
+    @abstractmethod
+    def to_dict(self) -> dict[str, Any]: ...
+
+    @abstractmethod
+    def to_text(self) -> str: ...
+
+    @abstractmethod
+    def sanity_check(self) -> bool: ...
+
+
+class ActivityAlbum(AActivity):
+    """Entry of the activities json file - the position in an album or an entry of Spotify::
+
+    {"tag-uid": "1:2:3:4", "target-id": "7", "track-id": 2, "track-time": 31.4, "album-finished": false,
+     "target-type": "album"}
+
+    An entry of Spotify has ``"target-type": "spotify"`` and also ``track-uri``, the address of its track.
+    """
+
+    def __init__(self, activity: dict[str, Any] | None, update_json: UpdateJson | None, logger: logging.Logger) -> None:
+        if not isinstance(activity, dict) or "tag-uid" not in activity or "target-id" not in activity:
+            logger.error("ActivityAlbum.__init__ - activity must be a dict with tag-uid and target-id: %s", activity)
+            raise ValueError("activity must be a dict with tag-uid and target-id.")
+        target_type = TargetType.spotify if activity.get("target-type") == TargetType.spotify.name else TargetType.album
+        super().__init__(activity["tag-uid"], activity["target-id"], target_type, update_json, logger)
+        self.load(activity)
+
+    def load(self, activity: dict[str, Any]) -> None:
+        """Take over target and position of ``activity`` (an entry of the activities json file) - nothing is
+        written."""
+        missing = [key for key in _REQUIRED_ALBUM_KEYS if key not in activity]
+        if missing:
+            self._logger.error("__init__ - activity misses %s (%s).", missing, activity)
+            raise ValueError(f"activity misses {missing}.")
+        self.target_id = activity["target-id"]
+        self.extra = extra_fields(activity, _FIELDS)  # fields of a newer version: kept and written back
+        self.track_id: int = activity["track-id"]
+        self.track_time: float = activity["track-time"]
+        self.finished: bool = activity["album-finished"]
+        self.track_uri: str | None = activity.get("track-uri")
+
+    def update(self, track_id: int, track_time: float, album_finished: bool, track_uri: str | None = None) -> None:
+        """Store the new position - the json file is written only if something changed."""
+        new = (track_id, track_time, album_finished, track_uri)
+        if new == (self.track_id, self.track_time, self.finished, self.track_uri):
+            self._logger.debug("update - unchanged")
+            return
+        self.track_id, self.track_time, self.finished, self.track_uri = new
+        self._update_json()
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "tag-uid": self.tag_uid,
+            "target-id": self.target_id,
+            "track-id": self.track_id,
+            "track-time": self.track_time,
+            "album-finished": self.finished,
+            "target-type": self.target_type.name,
+        }
+        if self.track_uri is not None:
+            result["track-uri"] = self.track_uri
+        return {**result, **self.extra}
+
+    def to_text(self) -> str:
+        return (
+            f"target id: {self.target_id}, track id: {self.track_id}, time: {self.track_time}, "
+            f"finished: {self.finished}"
+        )
+
+    def sanity_check(self) -> bool:
+        if self.track_time is not None and self.track_time < 0:
+            self._logger.warning("sanity_check - track time < 0 (%s)", self.track_time)
+            return False
+        if self.track_id is not None and self.track_id < 0:
+            self._logger.warning("sanity_check - track id < 0 (%s)", self.track_id)
+            return False
+        finished: object = self.finished  # may have been set to anything
+        if not isinstance(finished, bool):
+            self._logger.warning("sanity_check - finished is not a bool (%s).", type(self.finished))
+            return False
+        return True
+
+    @classmethod
+    def create_activity(cls, tag: Any, update_json: UpdateJson | None, logger: logging.Logger) -> "ActivityAlbum":
+        """New activity (start of the album) for a linked tag. :raises ValueError: for missing or unlinked tags."""
+        target_id = getattr(tag, "target_id", None)
+        if tag is None or is_unmapped(target_id) or not hasattr(tag, "tag_uid"):
+            logger.error("ActivityAlbum.create_activity - tag must be linked to a target: %s", tag)
+            raise ValueError("tag must be linked to a target.")
+        activity = {
+            "tag-uid": tag.tag_uid,
+            "target-id": target_id,
+            "track-id": 0,
+            "track-time": 0,
+            "album-finished": False,
+            "target-type": TargetType.spotify.name
+            if getattr(tag, "target_type", None) == TargetType.spotify
+            else TargetType.album.name,
+        }
+        return ActivityAlbum(activity, update_json, logger)

tinyjukebox/data/common.py

@@ -0,0 +1,91 @@
+"""Types and helpers shared by tags, targets and activities."""
+
+import datetime
+from collections.abc import Callable, Iterable, Mapping
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "NO_TARGET",
+    "TIMESTAMP_FORMAT",
+    "Listener",
+    "Mirror",
+    "TargetType",
+    "UpdateJson",
+    "extra_fields",
+    "is_unmapped",
+    "is_valid_timestamp",
+    "now",
+]
+
+TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
+NO_TARGET = -1
+"""target id of a tag that is not linked to a target yet (stored as -1 or "-1")."""
+
+UpdateJson = Callable[[], None]
+"""Callback of a collection: write the current state of all entries to the json file."""
+
+
+Listener = Callable[[str, Any], None]
+"""Called with key and new value of an entry of a collection that changed (``None``: the entry is gone)."""
+
+
+class Mirror:
+    """Tells a listener which entries of a collection changed - the synchronization with the library
+    (:mod:`tinyjukebox.sync`) records every change this way, whoever made it. Called under the lock of the
+    collection."""
+
+    def __init__(self) -> None:
+        self._listener: Listener | None = None
+        self._known: dict[str, Any] = {}
+
+    def listen(self, listener: Listener, known: dict[str, Any]) -> None:
+        """``known``: the entries as the listener knows them already."""
+        self._listener = listener
+        self._known = known
+
+    def changed(self, data: dict[str, Any]) -> None:
+        """``data``: all entries as they are now."""
+        if self._listener is None:
+            return
+        known, self._known = self._known, data
+        for key in [*known, *(key for key in data if key not in known)]:
+            if known.get(key) != data.get(key):
+                self._listener(key, data.get(key))
+
+    def replaced(self, data: dict[str, Any]) -> None:
+        """The entries were set by the one who listens: nothing to tell."""
+        self._known = data
+
+
+class TargetType(Enum):
+    album = "album"
+    radio = "radio"
+    spotify = "spotify"
+
+
+def now() -> str:
+    """Current UTC time in the timestamp format of the json files."""
+    return datetime.datetime.now(datetime.UTC).strftime(TIMESTAMP_FORMAT)
+
+
+def is_valid_timestamp(value: object) -> bool:
+    if not isinstance(value, str):
+        return False
+    try:
+        datetime.datetime.strptime(value, TIMESTAMP_FORMAT)
+    except ValueError:
+        return False
+    return True
+
+
+def is_unmapped(target_id: object) -> bool:
+    """True for the target id of a tag that is not linked (-1, "-1") and for missing ids."""
+    return target_id is None or str(target_id) == str(NO_TARGET)
+
+
+def extra_fields(entry: Mapping[str, Any], known: Iterable[str]) -> dict[str, Any]:
+    """The fields of an entry that this version does not know - a newer version wrote them. They are kept and written
+    back as they are, so that this version never deletes them (docs/developer/library.md, section 4.21)."""
+    known = set(known)
+    return {key: value for key, value in entry.items() if key not in known}

tinyjukebox/data/degraded.py

@@ -0,0 +1,39 @@
+"""What the box could not load and works without (docs/developer/library.md, section 4.21).
+
+A damaged or unknown entry of a json file, a damaged line of the journal, a file that cannot be read: the box leaves it
+out and goes on with the rest instead of not starting. Each such case is noted here with a message, so that the log, the
+page of the box and the library say that the box does not have everything. Noted per source (a file) and key (an
+entry): loading the source again replaces its notes.
+"""
+
+import threading
+
+__all__ = ["clear", "note", "notes", "replace"]
+
+_lock = threading.Lock()
+_notes: dict[str, dict[str, str]] = {}  # source -> key -> message
+
+
+def note(source: str, key: str, message: str) -> None:
+    with _lock:
+        _notes.setdefault(source, {})[key] = message
+
+
+def replace(source: str, messages: dict[str, str]) -> None:
+    """The notes of ``source`` are these now (none: it is complete)."""
+    with _lock:
+        if messages:
+            _notes[source] = dict(messages)
+        else:
+            _notes.pop(source, None)
+
+
+def notes() -> list[str]:
+    with _lock:
+        return [message for source in sorted(_notes) for message in _notes[source].values()]
+
+
+def clear() -> None:
+    """Forget everything - for the tests, which run many boxes in one process."""
+    with _lock:
+        _notes.clear()