CineInfo Quellen DE

CineInfo-Quellen

CineInfo-Quellen sind der Erweiterungspunkt, über den ein Drittanbieter-Modul eigene CineInfo-Daten (Bewertungen, Provider, eigene Felder, ...) zusätzlich zur eingebauten TMDB-Abfrage liefern kann — ohne Änderung am Core. Während ein Provider-Pill nur ein kleines Verfügbarkeits-Badge zeigt, speist eine Quelle echte Felder in die CineInfo-Abfragen selbst ein.

Der Core bleibt maßgeblich: Quellen werden über das TMDB-Ergebnis gelegt, und ohne registrierte Quelle ist der gesamte Mechanismus ein kostenneutraler Durchlauf.

Die zwei Batch-Formen

Jede Quelle deklariert ein einziges Fähigkeits-Flag; der Orchestrator wählt die Abfrageform automatisch — dafür gibt es keine Nutzer-Einstellung:

supports_bulk	Orchestrator ruft	Bedeutung	Wofür
False	fetch_one(item, ctx) je Item	„einzeln nach und nach" — eine Anfrage pro Item, geschleift mit begrenzter Parallelität	Upstreams mit einer Abfrage pro Anfrage (z. B. TMDB)
True	fetch_many(items, ctx) je Chunk	„alles in einer Anfrage" — eine Anfrage für bis zu max_bulk Items	Upstreams mit echtem Bulk-Endpoint

Beide Formen laufen durch dieselbe Cache-, Rate-Limit- und Dedup-Schicht — eine Quelle implementiert Batching, Caching oder Drosselung also nie selbst.

Eine Quelle schreiben

from ...cineinfo.source import CineInfoSource, QueryContext
from ...db import get_setting

class MySource(CineInfoSource):
    id = "myprovider"            # stabil; zugleich Cache-Namespace + Limiter-Bucket
    label = "My Provider"
    supports_bulk = False        # ← die gesamte Batch-Form-Entscheidung
    rate = 5.0                   # max. Upstream-Anfragen/Sekunde
    cache_ttl = 86400.0          # Provider-Cache-TTL in Sekunden (0 = kein Cache)

    def is_enabled(self) -> bool:
        # Dem eigenen Toggle folgen: ein deaktiviertes/deinstalliertes Modul
        # trägt sofort nichts mehr bei, ohne Registry-Aufräumen.
        return get_setting("myprovider_enabled", "0") == "1"

    def fetch_one(self, item: dict, ctx: QueryContext) -> dict:
        # item trägt einen stabilen "key" plus Lookup-Felder
        # (title / imdb_id / tmdb_id). ctx.country und ctx.ui_lang sind gesetzt.
        # Nur die Felder zurückgeben, die man tatsächlich kennt.
        ...
        return {"vote_average": 8.1, "myprovider_url": "https://..."}

Eine Bulk-Quelle implementiert stattdessen fetch_many(items, ctx) und gibt {item["key"]: payload} für den ganzen Chunk in einer Anfrage zurück.

Registrieren

Aus dem register(app) des Moduls:

from ...cineinfo.registry import register_cineinfo_source
register_cineinfo_source(MySource())

Pro Quelle eine Instanz registrieren. Es dürfen mehrere sein (z. B. eine je Batch-Form).

Wie die Daten ankommen

Die Core-CineInfo-Endpoints (/api/tmdb/info, /api/tmdb/batch) rufen cineinfo.enrich(...) auf, das jede aktivierte Quelle ausführt und deren Payload feldweise auf die TMDB-Basis legt:

• Die eingebauten TMDB-Daten gewinnen. Eine Quelle füllt nur Felder, die TMDB fehlen oder leer sind — plus eigene Zusatzfelder.
• Quellen werden in stabiler id-Reihenfolge angewandt (deterministisch).
• 0 / False sind gültige Werte und bleiben erhalten (nicht „leer").

Was du geschenkt bekommst

Cache-first (nur Cache-Misses gehen ins Netz, über die geteilte provider_cache-Tabelle), ein Token-Bucket-Rate-Limiter pro Quelle, In-Flight- Deduplizierung gleichzeitiger identischer Abfragen, begrenzte Parallelität, Timeouts pro Abfrage und Fehler-Isolation — ein fehlerhaftes Item oder eine fehlerhafte Quelle legt CineInfo nie lahm.

Referenz-Implementierung

Siehe .examples/thirdparties/example_cineinfo_source/ für ein vollständiges, offline-taugliches Modul, das je eine Quelle beider Batch-Formen unter dem CineInfo-Einstellungs-Tab registriert. Das Plug-in-System selbst ist in .examples/thirdparties/README.md dokumentiert.