Jess Hallsworth
6a557bcdd9
The application the design describes: Flask + SQLite, Plex for library data, Tautulli for watch history, report-only. Structure follows the design's seams. providers/ splits MediaProvider from HistoryProvider, because on this network library data and watch data live on different machines and Jellyfin later will have no Tautulli equivalent. scoring.py implements the reclaim score twice - as a SQL expression for the live grid (weights change on every slider drag, so storing it would mean rewriting thousands of rows per drag) and in Python for CSV export and tests, with a property test over 500 generated rows asserting the two agree. rules.py compiles saved views to parameterized SQL through a field/operator whitelist; nothing user-supplied is ever interpolated. Three properties are enforced by test rather than asserted in prose: - Ingest is idempotent. Three consecutive full scans leave every count and every byte total unchanged. A scanner that double-counts produces a report that looks plausible and is wrong. - Keep marks survive Plex reassigning every rating key in the library. They are keyed on content GUID, scoped per library so the Movies and 4K Movies copies of the same film mark independently. - Every config variable the app reads is declared in docker-compose.yml, so a variable set in Portainer can never silently do nothing. Also found and fixed while verifying against a fake Plex+Tautulli pair: executescript() commits the pending transaction, so migrations needed their BEGIN/COMMIT inside the script; replaceChildren() renders null as the literal text "null"; a hash-only URL change does not reload the document, so deep links needed a hashchange listener; and SQLite ROUND rounds half away from zero where Python rounds half to even. 73 tests, no live server required. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GVbG48GAXfCZatcmX123Ra
139 lines
3.7 KiB
Python
139 lines
3.7 KiB
Python
"""Provider protocols and the normalized types everything above this layer speaks.
|
|
|
|
Two protocols, deliberately separate (§3.1): MediaProvider knows what exists,
|
|
HistoryProvider knows what was watched. On this network those are two different
|
|
machines — Plex on Loki, Tautulli on Isis — and Emby/Jellyfin later will have no
|
|
Tautulli equivalent at all.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from typing import Iterator, Protocol, runtime_checkable
|
|
|
|
|
|
class ProviderError(RuntimeError):
|
|
"""Any failure talking to a source. Carries a message safe to display."""
|
|
|
|
|
|
class AuthError(ProviderError):
|
|
"""Credentials rejected. Never retried — a retry loop won't fix a bad token."""
|
|
|
|
|
|
@dataclass
|
|
class ServerInfo:
|
|
kind: str
|
|
name: str
|
|
version: str = ""
|
|
server_id: str = "" # Plex machineIdentifier / Tautulli pms_identifier
|
|
base_url: str = ""
|
|
|
|
|
|
@dataclass
|
|
class Library:
|
|
provider_key: str
|
|
title: str
|
|
kind: str # 'movie' | 'show'
|
|
locations: list[str] = field(default_factory=list)
|
|
|
|
|
|
@dataclass
|
|
class Part:
|
|
file_path: str
|
|
size_bytes: int = 0
|
|
provider_part_id: str | None = None
|
|
container: str | None = None
|
|
resolution: str | None = None
|
|
video_codec: str | None = None
|
|
audio_codec: str | None = None
|
|
bitrate: int | None = None
|
|
|
|
|
|
@dataclass
|
|
class Item:
|
|
"""A movie or an episode as the source reports it.
|
|
|
|
Episodes carry their season and show identity so the ingest can roll them up
|
|
without a second pass over the API.
|
|
"""
|
|
|
|
provider_item_id: str
|
|
kind: str # 'movie' | 'episode'
|
|
title: str
|
|
library_key: str
|
|
guid: str | None = None
|
|
sort_title: str | None = None
|
|
year: int | None = None
|
|
added_at: int | None = None
|
|
updated_at: int | None = None
|
|
duration_ms: int = 0
|
|
view_count: int = 0
|
|
last_viewed_at: int | None = None
|
|
resolution: str | None = None
|
|
video_codec: str | None = None
|
|
parts: list[Part] = field(default_factory=list)
|
|
# episode-only
|
|
show_id: str | None = None
|
|
show_title: str | None = None
|
|
show_guid: str | None = None
|
|
season_id: str | None = None
|
|
season_number: int | None = None
|
|
episode_number: int | None = None
|
|
|
|
@property
|
|
def size_bytes(self) -> int:
|
|
return sum(p.size_bytes for p in self.parts)
|
|
|
|
|
|
@dataclass
|
|
class WatchEvent:
|
|
"""One playback event, normalized across sources."""
|
|
|
|
source: str # 'tautulli' | 'plex'
|
|
source_row_id: str
|
|
provider_item_id: str
|
|
viewed_at: int
|
|
account_id: str | None = None
|
|
reference_id: str | None = None
|
|
stopped_at: int | None = None
|
|
play_duration_s: int | None = None
|
|
paused_counter_s: int | None = None
|
|
percent_complete: int | None = None
|
|
watched_status: float | None = None
|
|
media_type: str | None = None
|
|
platform: str | None = None
|
|
|
|
|
|
@dataclass
|
|
class Account:
|
|
account_id: str
|
|
name: str | None = None
|
|
friendly_name: str | None = None
|
|
|
|
|
|
@dataclass
|
|
class Coverage:
|
|
earliest_event_at: int | None
|
|
latest_event_at: int | None
|
|
event_count: int
|
|
|
|
|
|
@runtime_checkable
|
|
class MediaProvider(Protocol):
|
|
def server_info(self) -> ServerInfo: ...
|
|
def libraries(self) -> list[Library]: ...
|
|
def items(self, library: Library) -> Iterator[Item]: ...
|
|
def refresh_library(self, library: Library) -> None: ... # v2 only
|
|
|
|
|
|
@runtime_checkable
|
|
class HistoryProvider(Protocol):
|
|
name: str
|
|
|
|
def server_info(self) -> ServerInfo: ...
|
|
def accounts(self) -> list[Account]: ...
|
|
def watch_events(self, since: int | None = None) -> Iterator[WatchEvent]: ...
|
|
def coverage(self) -> Coverage: ...
|
|
|
|
@property
|
|
def has_completion_data(self) -> bool: ...
|