yrtria/MediaShelf
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implement MediaShelf v1

Browse source 
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
This commit is contained in:
Jess Hallsworth 2026-09-07 14:59:03 +00:00
parent 58c2883492
commit 6a557bcdd9
No known key found for this signature in database
37 changed files with 6486 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

68
mediashelf/providers/__init__.py Normal file
View file

@ -0,0 +1,68 @@
"""Provider construction and history-source selection."""
from __future__ import annotations
import logging
from .base import ( # noqa: F401
Account,
AuthError,
Coverage,
HistoryProvider,
Item,
Library,
MediaProvider,
Part,
ProviderError,
ServerInfo,
WatchEvent,
)
from .plex import PlexClient, PlexHistoryProvider, PlexProvider
from .tautulli import TautulliClient, TautulliHistoryProvider
log = logging.getLogger(__name__)
def build_media_provider(cfg) -> PlexProvider:
client = PlexClient(
cfg.plex_base_url, cfg.plex_token,
timeout=cfg.plex_timeout_s,
verify_ssl=cfg.plex_verify_ssl,
page_size=cfg.plex_page_size,
request_delay_ms=cfg.plex_request_delay_ms,
)
return PlexProvider(client)
def build_history_provider(cfg, media: PlexProvider):
"""Pick a history source per HISTORY_SOURCE (§4.11).
'auto' prefers Tautulli and falls back to Plex, reporting the reason rather
than degrading silently — a silently degraded score is one that gets trusted
when it shouldn't be. Returns (provider, degraded_reason_or_None).
"""
mode = (cfg.history_source or "auto").lower()
if mode == "plex":
return PlexHistoryProvider(media.client), None
if mode in ("auto", "tautulli"):
if not cfg.tautulli_configured:
if mode == "tautulli":
raise ProviderError("HISTORY_SOURCE=tautulli but Tautulli is not configured")
return PlexHistoryProvider(media.client), "Tautulli is not configured"
client = TautulliClient(
cfg.tautulli_base_url, cfg.tautulli_api_key,
timeout=cfg.tautulli_timeout_s, page_size=cfg.tautulli_page_size,
)
provider = TautulliHistoryProvider(client)
try:
provider.server_info()
return provider, None
except ProviderError as e:
if mode == "tautulli":
raise
log.warning("Tautulli unreachable, falling back to Plex history: %s", e)
return PlexHistoryProvider(media.client), "Tautulli unreachable: %s" % e
raise ProviderError("unknown HISTORY_SOURCE %r" % cfg.history_source)

139
mediashelf/providers/base.py Normal file
View file

@ -0,0 +1,139 @@
"""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: ...

294
mediashelf/providers/plex.py Normal file
View file

@ -0,0 +1,294 @@
"""Plex Media Server provider.
Talks directly to the server on the LAN with a server token — no plex.tv round
trip, so it works whether or not Plex's cloud is up. JSON throughout via the
Accept header, which avoids XML parsing entirely (§4.1).
"""
from __future__ import annotations
import logging
import time
from typing import Iterator
import requests
from .base import (
Account,
AuthError,
Coverage,
Item,
Library,
Part,
ProviderError,
ServerInfo,
WatchEvent,
)
log = logging.getLogger(__name__)
LIBTYPE_MOVIE = 1
LIBTYPE_SHOW = 2
LIBTYPE_SEASON = 3
LIBTYPE_EPISODE = 4
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 PlexClient:
def __init__(self, base_url: str, token: str, *, timeout: int = 30,
verify_ssl: bool = True, page_size: int = 500,
request_delay_ms: int = 0, client_id: str = "mediashelf"):
if not base_url or not token:
raise ProviderError("Plex is not configured (PLEX_BASE_URL / PLEX_TOKEN)")
self.base_url = base_url.rstrip("/")
self.timeout = timeout
self.verify_ssl = verify_ssl
self.page_size = page_size
self.delay = request_delay_ms / 1000.0
self.session = requests.Session()
self.session.headers.update({
"X-Plex-Token": token,
"Accept": "application/json",
"X-Plex-Product": "MediaShelf",
"X-Plex-Client-Identifier": client_id,
})
def get(self, path: str, params: dict | None = None, *, headers: dict | None = None) -> dict:
url = self.base_url + path
last: Exception | None = None
for attempt in range(3):
try:
if self.delay:
time.sleep(self.delay)
r = self.session.get(url, params=params, headers=headers,
timeout=self.timeout, verify=self.verify_ssl)
if r.status_code in (401, 403):
raise AuthError("Plex rejected the token (HTTP %s)" % r.status_code)
r.raise_for_status()
return r.json().get("MediaContainer", {}) or {}
except AuthError:
raise # never retried: a retry loop will not fix a bad token
except Exception as e: # noqa: BLE001
last = e
if attempt < 2:
time.sleep(2 ** attempt)
raise ProviderError("Plex request failed: %s (%s)" % (path, last))
def paged(self, path: str, params: dict | None = None) -> Iterator[dict]:
"""Yield Metadata rows, paging with X-Plex-Container-* headers."""
start = 0
while True:
headers = {
"X-Plex-Container-Start": str(start),
"X-Plex-Container-Size": str(self.page_size),
}
mc = self.get(path, params, headers=headers)
batch = mc.get("Metadata") or []
if not batch:
return
for row in batch:
yield row
start += len(batch)
total = _int(mc.get("totalSize") or mc.get("size") or 0)
if start >= total:
return
class PlexProvider:
"""MediaProvider implementation."""
kind = "plex"
def __init__(self, client: PlexClient):
self.client = client
# ── identity ─────────────────────────────────────────────────────────
def server_info(self) -> ServerInfo:
mc = self.client.get("/identity")
return ServerInfo(
kind="plex",
name=mc.get("friendlyName") or "Plex",
version=mc.get("version") or "",
server_id=mc.get("machineIdentifier") or "",
base_url=self.client.base_url,
)
# ── libraries ────────────────────────────────────────────────────────
def libraries(self) -> list[Library]:
mc = self.client.get("/library/sections")
out = []
for d in mc.get("Directory") or []:
kind = d.get("type")
if kind not in ("movie", "show"):
continue # music/photo/other are out of scope (§1.2)
out.append(Library(
provider_key=str(d.get("key")),
title=(d.get("title") or "").strip(),
kind=kind,
locations=[loc.get("path") for loc in (d.get("Location") or [])
if loc.get("path")],
))
return out
# ── items ────────────────────────────────────────────────────────────
def items(self, library: Library) -> Iterator[Item]:
libtype = LIBTYPE_MOVIE if library.kind == "movie" else LIBTYPE_EPISODE
path = "/library/sections/%s/all" % library.provider_key
for row in self.client.paged(path, {"type": libtype}):
item = self._to_item(row, library)
if item is not None:
yield item
def show_guids(self, library: Library) -> dict[str, str]:
"""Map show ratingKey -> show guid.
Episodes carry grandparentRatingKey but not the show's guid, and keep
marks for seasons are keyed on the SHOW's guid (§6.6), so this mapping
has to be fetched separately — one cheap request per show library.
"""
out: dict[str, str] = {}
path = "/library/sections/%s/all" % library.provider_key
for row in self.client.paged(path, {"type": LIBTYPE_SHOW}):
rk = row.get("ratingKey")
if rk is not None:
out[str(rk)] = row.get("guid") or ""
return out
@staticmethod
def _to_item(row: dict, library: Library) -> Item | None:
rk = row.get("ratingKey")
if rk is None:
return None
parts: list[Part] = []
resolution = video_codec = None
for media in row.get("Media") or []:
if resolution is None:
resolution = media.get("videoResolution")
video_codec = media.get("videoCodec")
for p in media.get("Part") or []:
if not p.get("file"):
continue
parts.append(Part(
file_path=p["file"],
size_bytes=_int(p.get("size")),
provider_part_id=str(p.get("id")) if p.get("id") is not None else None,
container=p.get("container") or media.get("container"),
resolution=media.get("videoResolution"),
video_codec=media.get("videoCodec"),
audio_codec=media.get("audioCodec"),
bitrate=_opt_int(media.get("bitrate")),
))
kind = "movie" if library.kind == "movie" else "episode"
return Item(
provider_item_id=str(rk),
kind=kind,
title=row.get("title") or "(untitled)",
library_key=library.provider_key,
guid=row.get("guid"),
sort_title=row.get("titleSort"),
year=_opt_int(row.get("year")),
added_at=_opt_int(row.get("addedAt")),
updated_at=_opt_int(row.get("updatedAt")),
duration_ms=_int(row.get("duration")),
view_count=_int(row.get("viewCount")),
last_viewed_at=_opt_int(row.get("lastViewedAt")),
resolution=resolution,
video_codec=video_codec,
parts=parts,
show_id=str(row["grandparentRatingKey"]) if row.get("grandparentRatingKey") is not None else None,
show_title=row.get("grandparentTitle"),
season_id=str(row["parentRatingKey"]) if row.get("parentRatingKey") is not None else None,
season_number=_opt_int(row.get("parentIndex")),
episode_number=_opt_int(row.get("index")),
)
def refresh_library(self, library: Library) -> None:
raise NotImplementedError("v1 never writes to Plex (§1.2)")
class PlexHistoryProvider:
"""Fallback HistoryProvider using /status/sessions/history/all.
Server-wide across accounts, which solves the token-scoping problem — but it
records only that a play happened, never how far it got. Everything it
returns is therefore treated as a completed view and the 'rejection' score
component drops out of the weighting (§4.11).
"""
name = "plex"
def __init__(self, client: PlexClient):
self.client = client
@property
def has_completion_data(self) -> bool:
return False
def server_info(self) -> ServerInfo:
mc = self.client.get("/identity")
return ServerInfo(
kind="plex",
name=mc.get("friendlyName") or "Plex",
version=mc.get("version") or "",
server_id=mc.get("machineIdentifier") or "",
base_url=self.client.base_url,
)
def accounts(self) -> list[Account]:
try:
mc = self.client.get("/accounts")
except ProviderError:
return []
out = []
for a in mc.get("Account") or []:
if a.get("id") is None:
continue
out.append(Account(account_id=str(a["id"]), name=a.get("name")))
return out
def watch_events(self, since: int | None = None) -> Iterator[WatchEvent]:
params: dict = {"sort": "viewedAt:desc"}
for row in self.client.paged("/status/sessions/history/all", params):
viewed = _opt_int(row.get("viewedAt"))
rk = row.get("ratingKey")
if viewed is None or rk is None:
continue
if since is not None and viewed <= since:
return # sorted desc: the watermark ends the walk
yield WatchEvent(
source="plex",
source_row_id=str(row.get("historyKey") or f"{rk}:{viewed}"),
provider_item_id=str(rk),
viewed_at=viewed,
account_id=str(row["accountID"]) if row.get("accountID") is not None else None,
media_type=row.get("type"),
)
def coverage(self) -> Coverage:
earliest = latest = None
count = 0
for ev in self.watch_events():
count += 1
if latest is None or ev.viewed_at > latest:
latest = ev.viewed_at
if earliest is None or ev.viewed_at < earliest:
earliest = ev.viewed_at
return Coverage(earliest, latest, count)

220
mediashelf/providers/tautulli.py Normal file
View file

@ -0,0 +1,220 @@
"""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