wien-oepnv

Eigene Provider-Plugins anbinden

Die Feed-Pipeline kann über zusätzliche Provider erweitert werden, ohne den Kerncode anzupassen. Dieses Dokument zeigt, wie ein Plugin erstellt, geladen und getestet wird.

1. Plugin-Skelett erzeugen

Verwende den neuen Scaffold-Befehl, um ein startfertiges Modul zu erzeugen:

python scripts/scaffold_provider_plugin.py plugins/custom_provider.py

Die Datei enthält eine register_providers-Funktion, die einen Loader registriert. Der Loader muss eine Liste von Ereignisdictionaries liefern, die dem Eventschema entsprechen.

2. Provider implementieren

Ersetze den Platzhalter durch deine Datenquelle. Beispiel mit einem einfachen Cache-Leser:

from pathlib import Path
import json


def register_providers(register_provider):
    def load_custom_events():
        cache_path = Path("data/custom/events.json")
        if not cache_path.exists():
            return []
        return json.loads(cache_path.read_text(encoding="utf-8"))

    register_provider("CUSTOM_PROVIDER_ENABLE", load_custom_events, cache_key="custom")

Alternative: deklarative PROVIDERS-Konstante

Statt einer register_providers-Funktion kann das Plugin auch eine PROVIDERS-Konstante exportieren — die Loader-Engine (src/feed/providers.py:_register_plugin_providers) akzeptiert beide Stile. Jeder Eintrag ist ein Tupel (env_var, loader) bzw. (env_var, loader, cache_key). Wird cache_key weggelassen, leitet das Framework ihn aus der Env-Variable ab.

PROVIDERS = [
    ("CUSTOM_PROVIDER_ENABLE", load_custom_events, "custom"),
]

Sind beide vorhanden, wird zuerst register_providers aufgerufen und zusätzlich die Konstante ausgewertet. Falls keiner der beiden Hooks existiert, protokolliert das Framework eine Warnung und das Plugin wird übersprungen.

3. Plugin laden

Aktiviere das Plugin über die Umgebungsvariable WIEN_OEPNV_PROVIDER_PLUGINS. Mehrere Module werden kommasepariert angegeben:

export WIEN_OEPNV_PROVIDER_PLUGINS=plugins.custom_provider
export CUSTOM_PROVIDER_ENABLE=1
python -m src.cli feed build

Während des Builds erscheinen der Providerstatus und mögliche Warnungen im Feed-Health-Report. Dieser wird lokal nach jedem Lauf unter docs/feed-health.md (Markdown) und docs/feed-health.json (JSON) abgelegt; beide Dateien sind nicht im Repository versioniert.

4. Tests

Erstelle eine kleine Testdatei, die den Loader direkt aufruft oder den Feed-Build mit aktivem Plugin über python -m pytest ausführt. Die neuen End-to-End-Tests unter tests/test_provider_plugins.py zeigen, wie Plugins isoliert getestet werden können.