MediaShelf/mediashelf/providers/tautulli.py

"""Tautulli history provider — the primary watch-data source (§4.8).

Tautulli's database is independent of Plex's: clearing or pruning Plex history
does not touch it, and unlike Plex it records how far into an item each play
actually got. That last fact is the whole reason this is the primary source.

Two things this module deliberately does NOT do:

  * It never calls get_library_media_info for a show section. Measured against
    the live server, that returns show-level rows with file_size 0 regardless of
    the section_type parameter, so it cannot supply TV sizes (§4.11). Plex is the
    only size authority.
  * It never trusts an HTTP 200 as success. Tautulli returns 200 with
    result:"error" in the body as its normal failure mode.
"""

from __future__ import annotations

import logging
import time
from typing import Iterator

import requests

from .base import (
    Account,
    AuthError,
    Coverage,
    ProviderError,
    ServerInfo,
    WatchEvent,
)

log = logging.getLogger(__name__)


def _int(v, default=0):
    try:
        return int(v)
    except (TypeError, ValueError):
        return default


def _opt_int(v):
    try:
        return int(v)
    except (TypeError, ValueError):
        return None


class TautulliClient:
    def __init__(self, base_url: str, api_key: str, *, timeout: int = 30,
                 page_size: int = 1000):
        if not base_url or not api_key:
            raise ProviderError("Tautulli is not configured")
        self.base_url = base_url.rstrip("/") + "/api/v2"
        self.api_key = api_key
        self.timeout = timeout
        self.page_size = page_size
        self.session = requests.Session()

    def cmd(self, command: str, **params):
        params["apikey"] = self.api_key
        params["cmd"] = command
        last: Exception | None = None
        for attempt in range(3):
            try:
                r = self.session.get(self.base_url, params=params, timeout=self.timeout)
                if r.status_code in (401, 403):
                    raise AuthError("Tautulli rejected the API key (HTTP %s)" % r.status_code)
                r.raise_for_status()
                body = r.json()
                resp = (body or {}).get("response") or {}
                result = resp.get("result")
                if result != "success":
                    msg = resp.get("message") or "unknown error"
                    # An invalid key surfaces here as a 200 with result:error.
                    if "apikey" in str(msg).lower() or "auth" in str(msg).lower():
                        raise AuthError("Tautulli: %s" % msg)
                    raise ProviderError("Tautulli cmd=%s failed: %s" % (command, msg))
                return resp.get("data")
            except (AuthError, ProviderError):
                raise
            except Exception as e:  # noqa: BLE001
                last = e
                if attempt < 2:
                    time.sleep(2 ** attempt)
        raise ProviderError("Tautulli request failed: cmd=%s (%s)" % (command, last))


class TautulliHistoryProvider:
    """HistoryProvider implementation."""

    name = "tautulli"

    def __init__(self, client: TautulliClient):
        self.client = client

    @property
    def has_completion_data(self) -> bool:
        return True

    def server_info(self) -> ServerInfo:
        d = self.client.cmd("get_server_info") or {}
        return ServerInfo(
            kind="tautulli",
            name=d.get("pms_name") or "Tautulli",
            version="",
            server_id=d.get("pms_identifier") or "",
            base_url=self.client.base_url,
        )

    def accounts(self) -> list[Account]:
        data = self.client.cmd("get_users") or []
        out = []
        for u in data:
            uid = u.get("user_id")
            if uid is None:
                continue
            out.append(Account(
                account_id=str(uid),
                name=u.get("username"),
                friendly_name=u.get("friendly_name") or u.get("username"),
            ))
        return out

    def _history_page(self, start: int, length: int, order_dir: str = "desc") -> tuple[list[dict], int]:
        d = self.client.cmd(
            "get_history",
            grouping=0,           # raw events; MediaShelf does its own merging (§4.9)
            order_column="date",
            order_dir=order_dir,
            start=start,
            length=length,
        ) or {}
        rows = d.get("data") or []
        total = _int(d.get("recordsFiltered") or d.get("recordsTotal") or 0)
        return rows, total

    def watch_events(self, since: int | None = None) -> Iterator[WatchEvent]:
        """Walk history newest-first, stopping at the watermark."""
        start = 0
        while True:
            rows, total = self._history_page(start, self.client.page_size)
            if not rows:
                return
            for row in rows:
                viewed = _opt_int(row.get("date"))
                rk = row.get("rating_key")
                if viewed is None or rk in (None, ""):
                    continue
                if since is not None and viewed <= since:
                    return
                yield self._to_event(row, viewed, rk)
            start += len(rows)
            if start >= total:
                return

    @staticmethod
    def _to_event(row: dict, viewed: int, rk) -> WatchEvent:
        row_id = row.get("row_id")
        return WatchEvent(
            source="tautulli",
            source_row_id=str(row_id if row_id is not None else f"{rk}:{viewed}"),
            provider_item_id=str(rk),
            viewed_at=viewed,
            account_id=str(row["user_id"]) if row.get("user_id") is not None else None,
            reference_id=str(row["reference_id"]) if row.get("reference_id") is not None else None,
            stopped_at=_opt_int(row.get("stopped")),
            play_duration_s=_opt_int(row.get("play_duration")),
            paused_counter_s=_opt_int(row.get("paused_counter")),
            percent_complete=_opt_int(row.get("percent_complete")),
            watched_status=_float_or_none(row.get("watched_status")),
            media_type=row.get("media_type"),
            platform=row.get("platform"),
        )

    def coverage(self) -> Coverage:
        """Cheap: one row from each end plus the reported total."""
        newest, total = self._history_page(0, 1, "desc")
        oldest, _ = self._history_page(0, 1, "asc")
        latest = _opt_int(newest[0].get("date")) if newest else None
        earliest = _opt_int(oldest[0].get("date")) if oldest else None
        return Coverage(earliest, latest, total)

    # ── movie-only cross-check (§4.11) ───────────────────────────────────

    def movie_media_info(self, section_id: str) -> list[dict]:
        """Per-item size/play data for a MOVIE section only.

        Never call this for a show section: it returns show-level rows with
        file_size 0 whatever section_type is passed.
        """
        out: list[dict] = []
        start = 0
        while True:
            d = self.client.cmd(
                "get_library_media_info",
                section_id=section_id,
                start=start,
                length=self.client.page_size,
                order_column="file_size",
                order_dir="desc",
            ) or {}
            rows = d.get("data") or []
            if not rows:
                break
            out.extend(rows)
            total = _int(d.get("recordsFiltered") or d.get("recordsTotal") or 0)
            start += len(rows)
            if start >= total:
                break
        return out


def _float_or_none(v):
    try:
        return float(v)
    except (TypeError, ValueError):
        return None