trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/async_io.py

@@ -0,0 +1,299 @@
+"""Async I/O helpers — Qt-native replacements for `threading.Thread` +
+`requests` patterns scattered through the codebase.
+
+Two facilities live here:
+
+- ``get_qnam()`` — an app-wide ``QNetworkAccessManager``. QNAM is the
+  Qt-idiomatic way to do HTTP from a GUI app: it runs on the calling
+  thread's event loop, never blocks, fires ``finished`` per reply, and
+  internally pools connections + caps parallelism per host. The image
+  loader in ``ui_helpers`` uses it.
+
+- ``run_async(fn, *args, on_result=…, on_error=…)`` — runs a blocking
+  callable on a shared ``QThreadPool`` and dispatches the result onto
+  the GUI thread via Qt signals. Used for the still-sync ``requests``
+  paths in ``jellyfin_api`` (lyrics, library shuffle, favorite toggle).
+  Preferred over raw ``threading.Thread`` because workers are bounded
+  (no thread explosion on bursts) and lifetimes are managed by Qt.
+
+Both helpers lazy-construct on first use so tests can import the module
+without a live ``QApplication``.
+"""
+
+import logging
+import threading
+from typing import Any, Callable, Optional
+
+from PySide6.QtCore import QCoreApplication, QObject, QRunnable, QThread, QThreadPool, Signal
+from PySide6.QtNetwork import QNetworkAccessManager
+
+logger = logging.getLogger(__name__)
+
+# ── cold-import serialization ───────────────────────────────────────────────
+# CPython 3.14's import system raises `_DeadlockError` ("deadlock detected by
+# _ModuleLock(...)") when two threads cold-import overlapping module graphs at
+# once. A fork that fans several heavy *lazy* imports onto this module's shared
+# QThreadPool at startup can hit exactly that: distinct gateways whose first
+# import pulls in overlapping transitive deps race each other. Hold this one
+# lock around each lazy gateway's *cold* import (double-checked against that
+# gateway's own "already imported" flag) so first imports run one at a time;
+# once cached the lock is uncontended. Inert in bare trackerkeeper — no gateway here
+# takes it — it's a shared primitive for forks that need the serialization.
+cold_import_lock = threading.Lock()
+
+# ── QNetworkAccessManager singleton ─────────────────────────────────────────
+
+_qnam: Optional[QNetworkAccessManager] = None
+_qnam_lock = threading.Lock()
+
+
+def get_qnam() -> QNetworkAccessManager:
+    """Return the app-wide QNetworkAccessManager.
+
+    QNAM must be created and used from a single thread (the GUI thread
+    in our case). It pools connections, supports HTTP/2 transparently,
+    and caps concurrent requests per host at 6 — the 5-parallel-GET
+    figure cited in some Qt docs is for the legacy synchronous path.
+
+    Lazy: first call constructs it. Subsequent calls return the same
+    instance. Module import remains side-effect-free.
+    """
+    global _qnam
+    if _qnam is None:
+        with _qnam_lock:
+            if _qnam is None:
+                app = QCoreApplication.instance()
+                if app is not None and QThread.currentThread() is not app.thread():
+                    # Nothing enforces the GUI-thread-only contract above —
+                    # a worker-thread first call would give QNAM worker
+                    # affinity and every later GUI-thread use becomes a
+                    # cross-thread hazard. Loud trace, not a crash.
+                    logger.warning(
+                        "get_qnam() first called OFF the GUI thread — QNAM "
+                        "affinity will be wrong (see docstring)"
+                    )
+                _qnam = QNetworkAccessManager()
+    return _qnam
+
+
+# ── Shared thread pool for blocking work ────────────────────────────────────
+
+_pool: Optional[QThreadPool] = None
+_pool_lock = threading.Lock()
+
+
+def get_thread_pool() -> QThreadPool:
+    """Return the app-wide QThreadPool.
+
+    Bounded at 8 workers so a click-storm (e.g. mashing the shuffle
+    button) can't spawn one thread per click. Anything that doesn't
+    fit queues, which is exactly what we want.
+
+    Pool size sits at 8 (not 4) to keep the bulk-download path from
+    starving: ``library_sync`` runs *on* this pool while phase 2 fires
+    one ``_plan`` job per album onto the same pool. With 4 slots a
+    long-running ``sync_library`` plus 3 plannings could shut out the
+    first ``_download_track`` job (also pool-scheduled) for minutes.
+    Eight slots leaves comfortable headroom for ``_MAX_CONCURRENT=2``
+    downloads + several plannings + ``sync_library`` itself, and the
+    ``_planning_in_flight`` cap in ``offline.manager`` keeps phase 2
+    from flooding the queue past that.
+    """
+    global _pool
+    if _pool is None:
+        with _pool_lock:
+            if _pool is None:
+                pool = QThreadPool()
+                pool.setMaxThreadCount(8)
+                _pool = pool
+    return _pool
+
+
+# ── run_async: blocking callable → GUI-thread callback ──────────────────────
+
+
+class _Signaler(QObject):
+    """Signal carrier for cross-thread completion.
+
+    User callbacks are invoked through the QObject methods
+    ``_dispatch_result`` / ``_dispatch_error`` rather than connecting
+    them directly to the signals. The reason is subtle: PySide6 wraps
+    a plain Python slot in a temporary QObject that lives on the
+    thread of the ``.connect()`` call. With the auto-connection rule
+    that routes signals to the **slot's** owning thread, a plain
+    Python slot connected from a pool worker would route the
+    completion event back onto that worker's event loop — and pool
+    workers don't have event loops, so the callback would never fire.
+    Empirically observed 2026-05-18 as the "phase 2 stuck at 12
+    planning_in_flight" library-walk bug. Routing through methods of
+    the signaler itself (a QObject we pin to the GUI thread before
+    connecting) lets Qt route correctly to the GUI event loop.
+    """
+
+    completed = Signal(object)
+    failed = Signal(object)
+
+    def __init__(self, on_result=None, on_error=None):
+        super().__init__()
+        self._on_result = on_result
+        self._on_error = on_error
+
+    def _dispatch_result(self, result):  # GUI-thread slot
+        if self._on_result is not None:
+            try:
+                self._on_result(result)
+            except Exception:  # noqa: BLE001
+                # Keep swallowing — the dispatcher must stay robust — but
+                # surface the traceback so a bug in a user on_result
+                # callback isn't completely invisible.
+                logger.exception("async on_result callback failed")
+
+    def _dispatch_error(self, exc):  # GUI-thread slot
+        if self._on_error is not None:
+            try:
+                self._on_error(exc)
+            except Exception:  # noqa: BLE001
+                logger.exception("async on_error callback failed")
+
+
+# Pin live signalers across the cross-thread emit. Without this, PySide6
+# garbage-collects the QObject between `signal.emit()` (worker thread)
+# and the GUI-thread slot dispatch — slot never runs. Same pattern as
+# the `_pending_loaders` set the old image loader needed; centralising
+# it here lets us delete that one.
+_pending_signalers: set = set()
+
+
+class _AsyncTask(QRunnable):
+    def __init__(self, fn, args, kwargs, signaler: _Signaler):
+        super().__init__()
+        self._fn = fn
+        self._args = args
+        self._kwargs = kwargs
+        self._signaler = signaler
+        self.setAutoDelete(True)
+
+    def run(self):  # noqa: D401  (Qt override)
+        try:
+            result = self._fn(*self._args, **self._kwargs)
+        except Exception as exc:  # noqa: BLE001
+            self._emit(self._signaler.failed, exc)
+            return
+        self._emit(self._signaler.completed, result)
+
+    @staticmethod
+    def _emit(signal, payload) -> None:
+        # The signaler's C++ object can be gone by the time a pool worker
+        # finishes: at app/interpreter shutdown the QApplication is torn
+        # down while this daemon thread is still running its fn, so the
+        # emit hits a deleted QObject. Swallow that — the result has
+        # nowhere to go and there's nothing to recover. Without this, a
+        # job in flight at shutdown spews "RuntimeError: Signal source has
+        # been deleted" to stderr (harmless but noisy, and it surfaces a
+        # lot under random test order).
+        try:
+            signal.emit(payload)
+        except RuntimeError:
+            pass
+
+
+def run_async(
+    fn: Callable[..., Any],
+    *args,
+    on_result: Optional[Callable[[Any], None]] = None,
+    on_error: Optional[Callable[[Exception], None]] = None,
+    **kwargs,
+) -> None:
+    """Run ``fn(*args, **kwargs)`` on the shared pool; dispatch result
+    or exception back to the GUI thread.
+
+    Either callback may be omitted. Exceptions raised by ``fn`` are
+    routed to ``on_error`` if given, otherwise swallowed silently —
+    the caller is responsible for surfacing failures they care about.
+
+    **Caller-thread independence:** the signaler is pinned to the GUI
+    thread regardless of which thread called ``run_async``. Without
+    this, a call site running on a pool worker (e.g.
+    ``library_sync.sync_library`` invoking ``offline.download`` for each
+    album) would create the signaler with worker-thread affinity. Qt
+    ``AutoConnection`` would then queue the completion event onto that
+    worker's event loop — which doesn't exist — and the callback would
+    never fire. Symptom: plannings ran but their ``_planned`` callback
+    silently dropped, so no track ever dispatched. Pinning the signaler
+    to the GUI thread guarantees the callback lands on the GUI event
+    loop where the listeners live.
+    """
+    sig = _Signaler(on_result=on_result, on_error=on_error)
+    # Pin signaler to GUI thread before connecting so the QObject-method
+    # slots (``_dispatch_result`` / ``_dispatch_error``) route correctly
+    # via QueuedConnection back to the GUI event loop, even when the
+    # caller is itself on a pool worker (e.g. library_sync phase 2
+    # firing per-album ``offline.download`` calls).
+    try:
+        from PySide6.QtCore import QCoreApplication
+        app = QCoreApplication.instance()
+        if app is not None and sig.thread() is not app.thread():
+            sig.moveToThread(app.thread())
+    except Exception:
+        pass
+    _pending_signalers.add(sig)
+
+    def _drop(_=None):
+        _pending_signalers.discard(sig)
+
+    sig.completed.connect(sig._dispatch_result)
+    sig.failed.connect(sig._dispatch_error)
+    sig.completed.connect(_drop)
+    sig.failed.connect(_drop)
+
+    get_thread_pool().start(_AsyncTask(fn, args, kwargs, sig))
+
+
+# ── call_on_gui: run a callback on the GUI thread from any thread ────────────
+
+
+class _GuiInvoker(QObject):
+    """One-shot trampoline that runs a zero-arg callable on the GUI
+    thread. Pinned to the GUI thread (same mechanism as ``_Signaler``)
+    so a ``fire`` emit from a worker / asyncio-loop thread is delivered
+    via QueuedConnection onto the GUI event loop, never inline on the
+    caller's thread."""
+
+    fire = Signal(object)
+
+    def _run(self, fn):  # GUI-thread slot
+        _pending_signalers.discard(self)
+        try:
+            fn()
+        except Exception:  # noqa: BLE001
+            logger.exception("call_on_gui callback failed")
+
+
+def call_on_gui(fn: Callable[[], Any]) -> None:
+    """Invoke ``fn()`` on the GUI thread, callable from any thread.
+
+    Use when a callback fires on a non-GUI thread (e.g. a background
+    thread's completion callback via
+    ``concurrent.futures.Future.add_done_callback``) but needs to touch
+    widgets — which must only happen on the GUI thread. With no
+    QApplication (headless unit tests) there is no GUI event loop to
+    marshal onto, so ``fn`` runs inline on the caller.
+    """
+    try:
+        from PySide6.QtCore import QCoreApplication
+
+        app = QCoreApplication.instance()
+    except Exception:  # noqa: BLE001
+        app = None
+    if app is None:
+        try:
+            fn()
+        except Exception:  # noqa: BLE001
+            logger.exception("call_on_gui callback failed (headless)")
+        return
+    inv = _GuiInvoker()
+    if inv.thread() is not app.thread():
+        inv.moveToThread(app.thread())
+    _pending_signalers.add(inv)
+    inv.fire.connect(inv._run)
+    inv.fire.emit(fn)

trackerkeeper/autostart/__init__.py

@@ -0,0 +1,52 @@
+"""Launch-on-login control. Public API is platform-agnostic; the actual
+implementation lives in a per-OS backend module.
+
+Public API:
+    is_supported() -> bool   # backend can fulfil enable/disable
+    is_enabled() -> bool     # currently set to launch on login
+    enable() -> bool         # turn on; True iff the change took effect
+    disable() -> bool        # turn off; True iff a previous entry was removed
+
+Linux: writes/reads the XDG autostart entry in ~/.config/autostart.
+Windows (MSIX package): the AppxManifest ``startupTask``, toggled through
+the ``Windows.ApplicationModel.StartupTask`` WinRT API — packages can't use
+the Run key.
+Windows (Inno .exe / pip / source): a value under the per-user Run
+registry key.
+macOS: a LaunchAgent .plist in ~/Library/LaunchAgents with RunAtLoad for the
+Dev-ID/.dmg/pip/source builds; an SMAppService login item for the sandboxed
+Mac App Store build.
+Everything else: the unsupported backend returns False from every call so
+call sites can no-op cleanly.
+"""
+
+from __future__ import annotations
+
+from trackerkeeper.platform_compat import IS_LINUX, IS_MACOS, IS_WINDOWS, is_msix_packaged
+
+if IS_LINUX:
+    from trackerkeeper.autostart import _linux as _backend
+elif IS_WINDOWS and is_msix_packaged():
+    from trackerkeeper.autostart import _msix as _backend
+elif IS_WINDOWS:
+    from trackerkeeper.autostart import _windows as _backend
+elif IS_MACOS:
+    from trackerkeeper.autostart import _macos as _backend
+else:
+    from trackerkeeper.autostart import _unsupported as _backend
+
+
+def is_supported() -> bool:
+    return _backend.is_supported()
+
+
+def is_enabled() -> bool:
+    return _backend.is_enabled()
+
+
+def enable() -> bool:
+    return _backend.enable()
+
+
+def disable() -> bool:
+    return _backend.disable()

trackerkeeper/autostart/_linux.py

@@ -0,0 +1,129 @@
+"""XDG autostart backend. Manages ~/.config/autostart/<app-id>.desktop —
+the standard cross-DE mechanism for "launch on login" on Linux. KDE,
+GNOME, XFCE, Cinnamon, MATE, and LXQt all read this directory.
+
+Strategy:
+- Enable: copy the installed ~/.local/share/applications/<app-id>.desktop
+  into the autostart dir if it exists; otherwise synthesize a minimal
+  entry pointing at the current interpreter and package.
+- Disable: delete the autostart file.
+- is_enabled: file exists and isn't marked Hidden=true (some DEs flip
+  this flag instead of removing the file).
+
+The desktop-id (``identity.desktop_id()`` = the reverse-DNS app-id) names
+both files, so the copy branch matches the file the installers actually
+drop. We never touch the source desktop file in ~/.local/share/applications.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from trackerkeeper import identity
+
+_AUTOSTART_DIR = Path.home() / ".config" / "autostart"
+_AUTOSTART_FILE = _AUTOSTART_DIR / f"{identity.desktop_id()}.desktop"
+_SOURCE_DESKTOP = (
+    Path.home()
+    / ".local"
+    / "share"
+    / "applications"
+    / f"{identity.desktop_id()}.desktop"
+)
+
+
+def is_supported() -> bool:
+    return True
+
+
+def is_enabled() -> bool:
+    if not _AUTOSTART_FILE.exists():
+        return False
+    try:
+        for line in _AUTOSTART_FILE.read_text().splitlines():
+            line = line.strip()
+            # Either Hidden=true or X-GNOME-Autostart-enabled=false
+            # disables the entry without removing the file.
+            if line.lower() == "hidden=true":
+                return False
+            if line.lower() == "x-gnome-autostart-enabled=false":
+                return False
+    except Exception:
+        return False
+    return True
+
+
+def enable() -> bool:
+    """Drop a .desktop entry into ~/.config/autostart. Returns True on
+    success, False on filesystem errors (e.g. read-only home)."""
+    try:
+        _AUTOSTART_DIR.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        return False
+
+    if _SOURCE_DESKTOP.exists():
+        try:
+            content = _SOURCE_DESKTOP.read_text()
+        except Exception:
+            content = _synth_desktop_entry()
+        else:
+            content = _strip_hidden_flags(content)
+    else:
+        content = _synth_desktop_entry()
+
+    try:
+        _AUTOSTART_FILE.write_text(content)
+        # 0644 — autostart files don't need to be executable.
+        _AUTOSTART_FILE.chmod(0o644)
+        return True
+    except Exception:
+        return False
+
+
+def disable() -> bool:
+    """Remove the autostart entry. Returns True if a file was removed,
+    False if there was nothing to do (or removal failed)."""
+    if not _AUTOSTART_FILE.exists():
+        return False
+    try:
+        _AUTOSTART_FILE.unlink()
+        return True
+    except Exception:
+        return False
+
+
+def _strip_hidden_flags(content: str) -> str:
+    """Remove Hidden / X-GNOME-Autostart-enabled disable flags so a
+    previously-disabled entry becomes active when re-enabled."""
+    out_lines = []
+    for line in content.splitlines():
+        s = line.strip().lower()
+        if s.startswith("hidden=") or s.startswith("x-gnome-autostart-enabled="):
+            continue
+        out_lines.append(line)
+    return "\n".join(out_lines) + "\n"
+
+
+def _synth_desktop_entry() -> str:
+    """Fallback: build a minimal entry from the current interpreter and
+    the installed package (`python -m <app>`). Used when the canonical
+    entry under ~/.local/share/applications is missing."""
+    # parent.parent = the package dir; its parent is whatever holds the
+    # package (repo root or site-packages) — Path= there so a repo checkout
+    # launches from the repo.
+    pkg_dir = Path(__file__).resolve().parent.parent
+    interpreter = sys.executable or "python3"
+    return (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        f"Name={identity.display_name()}\n"
+        f"Comment={identity.display_name()}\n"
+        f"Exec={interpreter} -m {identity.app()}\n"
+        f"Path={pkg_dir.parent}\n"
+        f"Icon={identity.desktop_id()}\n"
+        "Terminal=false\n"
+        "Categories=Utility;\n"
+        "StartupNotify=true\n"
+        "X-GNOME-Autostart-enabled=true\n"
+    )

trackerkeeper/autostart/_macos.py

@@ -0,0 +1,163 @@
+"""macOS launch-on-login backend — two mechanisms, picked by build variant.
+
+- **Mac App Store (sandboxed)**: an ``SMAppService`` login item (macOS 13+). A
+  sandboxed app CANNOT write ``~/Library/LaunchAgents``, so the LaunchAgent path
+  below is illegal there — register the main app as a login item through the
+  ServiceManagement framework instead.
+- **Developer-ID .dmg / source / pip**: a per-user LaunchAgent in
+  ``~/Library/LaunchAgents``. launchd reads it at session login and ``RunAtLoad``
+  starts the app once. The standard sandbox-free mechanism for a GUI app.
+
+The public API (``is_supported`` / ``is_enabled`` / ``enable`` / ``disable``)
+branches on :func:`trackerkeeper.platform_compat.is_macos_sandboxed`. The LaunchAgent
+plist generation stays pure stdlib (plistlib + pathlib), so it's import-safe +
+unit-testable off a Mac; the SMAppService calls are runtime-only (pyobjc,
+macOS 13+, the bundled .app) and never run on the test machine because
+``is_macos_sandboxed()`` is False there.
+"""
+
+from __future__ import annotations
+
+import plistlib
+import sys
+from pathlib import Path
+
+from trackerkeeper import identity
+from trackerkeeper.platform_compat import is_macos_sandboxed
+
+_AGENTS_DIR = Path.home() / "Library" / "LaunchAgents"
+
+
+def _label() -> str:
+    """Reverse-DNS LaunchAgent label, matching the macOS bundle identifier
+    (``com.{org}.{app}``) — routed through identity, never a literal."""
+    return identity.cf_bundle_id()
+
+
+def _plist_path() -> Path:
+    return _AGENTS_DIR / f"{_label()}.plist"
+
+
+# --- Mac App Store: SMAppService login item (sandbox-legal, macOS 13+) -------
+
+def _sm_service():
+    """The SMAppService that represents THIS app as a login item."""
+    from ServiceManagement import SMAppService
+
+    return SMAppService.mainAppService()
+
+
+def _sm_supported() -> bool:
+    try:
+        from ServiceManagement import SMAppService  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _sm_is_enabled() -> bool:
+    try:
+        try:
+            from ServiceManagement import SMAppServiceStatusEnabled as _EN
+
+            enabled = int(_EN)
+        except Exception:
+            enabled = 1  # SMAppServiceStatus.enabled
+        return int(_sm_service().status()) == enabled
+    except Exception:
+        return False
+
+
+def _sm_enable() -> bool:
+    try:
+        ok, _err = _sm_service().registerAndReturnError_(None)
+        return bool(ok)
+    except Exception:
+        return False
+
+
+def _sm_disable() -> bool:
+    try:
+        ok, _err = _sm_service().unregisterAndReturnError_(None)
+        return bool(ok)
+    except Exception:
+        return False
+
+
+# --- Developer-ID / source: per-user LaunchAgent -----------------------------
+
+def _program_arguments() -> list[str]:
+    """The launchd ProgramArguments for however this process was started."""
+    if getattr(sys, "frozen", False):
+        # Inside <app>.app/Contents/MacOS/<app> — launch the binary directly.
+        return [sys.executable]
+    interpreter = sys.executable or "python3"
+    return [interpreter, "-m", identity.app()]
+
+
+def _plist_bytes() -> bytes:
+    """Serialize the LaunchAgent plist. Pure — unit-tested off a Mac."""
+    return plistlib.dumps(
+        {
+            "Label": _label(),
+            "ProgramArguments": _program_arguments(),
+            "RunAtLoad": True,
+            # Foreground app, not a daemon — gives it normal UI scheduling.
+            "ProcessType": "Interactive",
+        }
+    )
+
+
+def _la_is_enabled() -> bool:
+    return _plist_path().exists()
+
+
+def _la_enable() -> bool:
+    """Write the LaunchAgent. Returns True on success, False on filesystem
+    errors (e.g. read-only home)."""
+    try:
+        _AGENTS_DIR.mkdir(parents=True, exist_ok=True)
+        _plist_path().write_bytes(_plist_bytes())
+        return True
+    except Exception:
+        return False
+
+
+def _la_disable() -> bool:
+    """Remove the LaunchAgent. Returns True if a file was removed, False if
+    there was nothing to do (or removal failed)."""
+    plist = _plist_path()
+    if not plist.exists():
+        return False
+    try:
+        plist.unlink()
+        return True
+    except Exception:
+        return False
+
+
+# --- public API: pick the mechanism by build variant -------------------------
+
+def is_supported() -> bool:
+    if is_macos_sandboxed():
+        return _sm_supported()
+    return True
+
+
+def is_enabled() -> bool:
+    if is_macos_sandboxed():
+        return _sm_is_enabled()
+    return _la_is_enabled()
+
+
+def enable() -> bool:
+    if is_macos_sandboxed():
+        return _sm_enable()
+    return _la_enable()
+
+
+def disable() -> bool:
+    if is_macos_sandboxed():
+        return _sm_disable()
+    return _la_disable()