Dieses Repository bündelt sämtliche Komponenten, um einen konsolidierten Meldungs-Feed für den öffentlichen Verkehr in Wien und dem niederösterreichisch-burgenländischen Umland zu erzeugen. Der Feed kombiniert offizielle Informationen der Wiener Linien (WL), der ÖBB und der Verkehrsverbund Ost-Region GmbH (VOR) und stellt sie als aufbereitetes RSS-Dokument zur Verfügung. Zusätzlich sind Werkzeuge zur Pflege des Stationsverzeichnisses, zur Verwaltung der Provider-Caches sowie eine komplette Referenzdokumentation für die VOR/VAO-ReST-API enthalten.

• Zentrale Datenaufbereitung – Störungsmeldungen, Baustellen und Hinweise mehrerer Provider werden vereinheitlicht, dedupliziert und mit konsistenten Metadaten versehen.
• Reproduzierbarer Feed-Bau – Sämtliche Schritte (Cache-Aktualisierung, Feed-Generierung, Tests) lassen sich lokal oder in CI/CD-Workflows reproduzieren.
• Nachvollziehbare Datenbasis – Alle externen Datenquellen, Lizenzen und Skripte zur Pflege des Stationsverzeichnisses sind dokumentiert und versioniert.

Der Feed-Bau folgt einem klaren Ablauf:

1. Provider-Caches – Je Provider existiert ein Update-Skript (scripts/update_*_cache.py) sowie eine GitHub Action, die den Cache regelmäßig aktualisiert (cache/<provider>/events.json). Die Provider lassen sich über Umgebungsvariablen deaktivieren, ohne den restlichen Prozess zu beeinflussen.
2. Feed-Generator – src/build_feed.py liest die Cache-Dateien, normalisiert Texte, entfernt Duplikate und schreibt den RSS-Feed nach docs/feed.xml. Umfangreiche Guards gegen ungültige Umgebungsvariablen, Pfade oder Zeitzonen stellen stabile Builds sicher.
3. Stationsdaten – data/stations.json liefert vereinheitlichte Stations- und Haltestelleninformationen als Referenz für die Provider-Logik. Mehrere Skripte in scripts/ und automatisierte Workflows pflegen diese Datei fortlaufend.
4. Dokumentation & Audits – Der Ordner docs/ enthält Prüfberichte, API-Anleitungen und Audits, die das Verhalten des Systems transparent machen.

• About & Topics pflegen – Verwende eine kurze, keyword-starke Projektbeschreibung (z. B. „RSS-Feed für Störungs- und Baustellenmeldungen im Wiener ÖPNV“) und ergänze Topics wie vienna, public-transport, verkehrsmeldungen, rss-feed, python. So verbesserst du das Ranking innerhalb der GitHub-Suche.
• Feed prominent verlinken – Der RSS-Feed ist unter docs/feed.xml verfügbar. In GitHub Pages bindet der <link rel="alternate" type="application/rss+xml">-Eintrag den Feed direkt im HTML-Head ein, wodurch Google Discover & Co. ihn leichter finden.
• Sitemap & Robots nutzen – docs/sitemap.xml und docs/robots.txt sind bereits vorbereitet. Reiche die Sitemap in der Google Search Console ein, damit neue Meldungen schneller indexiert werden.
• Externe Signale aufbauen – Stelle das Projekt in Blogposts, Foren (z. B. Reddit, Mastodon, lokale ÖPNV-Gruppen) oder Newsletter vor. Backlinks von thematisch relevanten Seiten erhöhen die Sichtbarkeit in klassischen Suchmaschinen.
• Monitoring etablieren – Beobachte GitHub Insights (Stars, Forks, Traffic) sowie Feed-Validatoren wie https://validator.w3.org/feed/. Automatisierte Checks helfen, strukturelle Probleme früh zu erkennen.

1. Python-Version: Das Projekt ist auf Python 3.11 ausgelegt (pyproject.toml).

2. Abhängigkeiten installieren:

   python -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

3. Statische Analysen: Die CI führt ruff check und mypy aus; lokal spiegelst du das Verhalten mit

   python -m pip install -r requirements-dev.txt
   scripts/run_static_checks.py

4. Umgebungsvariablen: Sensible Daten (Tokens, Basis-URLs) werden ausschließlich über die Umgebung gesetzt. Lokale .env-Dateien können über WIEN_OEPNV_ENV_FILES eingebunden werden.

   Das Skript scripts/run_static_checks.py führt neben ruff und mypy auch einen Secret-Scan aus (scripts/scan_secrets.py), sodass versehentlich eingecheckte Tokens früh auffallen.

Für wiederkehrende Aufgaben steht eine gebündelte Kommandozeile zur Verfügung. Der Aufruf python -m src.cli bündelt die wichtigsten Skripte und sorgt für konsistente Exit-Codes – ideal für lokale Reproduzierbarkeit oder CI-Jobs.

# Alle Provider-Caches sequenziell aktualisieren (Standardverhalten).
python -m src.cli cache update

# Nur ausgewählte Provider aktualisieren.
python -m src.cli cache update wl oebb

# Feed generieren (äquivalent zu python -m src.build_feed).
python -m src.cli feed build

# Zugangsdaten prüfen und beim ersten Fehler abbrechen.
python -m src.cli tokens verify --stop-on-error

# Stationsverzeichnis prüfen und Bericht speichern.
python -m src.cli stations validate --output docs/stations_validation_report.md

# Ruff + mypy wie in der CI ausführen.
python -m src.cli checks --fix

# Interaktiven Konfigurationsassistenten starten (schreibt .env).
python -m src.cli config wizard

# Repository auf versehentlich eingecheckte Secrets prüfen.
python -m src.cli security scan

Die Unterbefehle akzeptieren standardmäßig alle bekannten Ziele (z. B. Provider wl, oebb, vor) und lassen sich bei Bedarf präzise einschränken. Über --python kann ein alternativer Interpreter für die Hilfsskripte gesetzt werden.

src/build_feed.py liest zahlreiche Umgebungsvariablen. Für den Einstieg empfiehlt sich der Assistent scripts/configure_feed.py, der eine bestehende .env einliest, die relevanten Schlüssel erklärt und wahlweise interaktiv oder per --accept-defaults eine neue Konfiguration schreibt. Die wichtigsten Parameter:

Alle Pfade werden durch _resolve_env_path auf docs/, data/ oder log/ beschränkt, um Path-Traversal zu verhindern.

Wird build_feed als Skript ausgeführt (python -m src.build_feed), richtet es seine Logging-Handler automatisch über configure_logging() ein. Beim Einbinden des Moduls in andere Anwendungen bleibt die globale Logging-Konfiguration ab Python-Import unverändert; rufe in diesem Fall src.build_feed.configure_logging() explizit auf, bevor du die Feed-Funktionen verwendest.

• Läuft der Feed-Build über src/build_feed.py, landen Fehler- und Traceback-Ausgaben automatisch in log/errors.log (rotierende Log-Datei, konfigurierbar über LOG_DIR, LOG_MAX_BYTES, LOG_BACKUP_COUNT). Ohne Fehler bleibt die Datei unberührt.
• Ausführliche Statusmeldungen (z. B. zum VOR-Abruf) werden zusätzlich in log/diagnostics.log gesammelt.
• Beim manuellen Aufruf der Hilfsskripte, z. B. scripts/update_vor_cache.py, erscheinen Warnungen und Fehler direkt auf stdout. Für nachträgliche Analysen kannst du den jeweiligen Lauf zusätzlich mit LOG_DIR auf ein separates Verzeichnis umleiten.
• Setzt du LOG_FORMAT=json, schreibt das Projekt strukturierte JSON-Logs mit Zeitstempeln im Format Europe/Vienna. Ohne Angabe bleibt das klassische Textformat aktiv.

Das Repository stellt die aufbereiteten Meldungen nicht nur als RSS-Feed bereit, sondern bietet auch stabile JSON-Datensätze und wiederverwendbare Python-Helfer für die Integration in andere Anwendungen.

1. Repository klonen und in ein virtuelles Environment wechseln (python -m venv .venv && source .venv/bin/activate).
2. Projektabhängigkeiten installieren (python -m pip install -r requirements.txt).
3. Die gewünschten Cache-Dateien unter cache/<provider>/events.json konsumieren oder die Python-Helfer aus src/ nutzen.

Die Cache-Dateien werden von den GitHub-Actions regelmäßig aktualisiert und enthalten ausschließlich strukturierte JSON-Listen. Sie sind damit ohne zusätzlichen Build-Schritt sofort für externe Automationen verwendbar.

Für Python-Anwendungen existieren zwei bequeme Zugriffspfade:

• Direkter Cache-Zugriff – src.utils.cache.read_cache() liest die zwischengespeicherten Provider-Events als Python-Liste von Dictionaries ein (Wrapper wie src.build_feed.read_cache_wl() sind bereits vorkonfiguriert für „wl“, „oebb“, „vor“ und „baustellen“).【F:src/utils/cache.py†L38-L90】【F:src/build_feed.py†L706-L724】
• Live-Abruf der Provider – Die Module src.providers.wl_fetch, src.providers.oebb und src.providers.vor stellen jeweils eine Funktion fetch_events() bereit, die die Rohdaten der Wiener Linien, ÖBB bzw. der VOR/VAO-API direkt normalisiert. Authentifizierung und Ratenlimits der VOR-API werden dabei automatisch behandelt.【F:src/providers/wl_fetch.py†L520-L618】【F:src/providers/oebb.py†L109-L168】【F:src/providers/vor.py†L520-L677】

Minimalbeispiel für den Cache-Zugriff:

from src.utils.cache import read_cache

wl_events = read_cache("wl")
for event in wl_events:
    print(event["title"], event["starts_at"])

Unabhängig vom Provider folgen alle Ereignisse derselben Struktur, die auch im Feed verwendet wird. Die wichtigsten Felder im JSON-Cache (Strings im ISO-8601-Format) bzw. bei direkter Python-Nutzung (Python-datetime-Objekte) sind:

Eine formale Beschreibung steht als JSON-Schema bereit und eignet sich für Validierungen in Drittprojekten. Alle Felder sind als Unicode-Strings hinterlegt, zusätzliche provider-spezifische Hilfsfelder werden vor dem JSON-Export entfernt, sodass die Datensätze stabil und schema-konform bleiben.【F:src/providers/wl_fetch.py†L568-L618】【F:src/providers/oebb.py†L143-L168】【F:src/providers/vor.py†L548-L677】

Der Meldungsfeed sammelt offizielle Störungs- und Hinweisinformationen der Wiener Linien (WL), der Verkehrsverbund Ost-Region GmbH (VOR), der ÖBB sowie ergänzende Baustelleninformationen der Stadt Wien.

• Quelle: Realtime-Störungs-Endpoint (WL_RSS_URL, Default: https://www.wienerlinien.at/ogd_realtime).
• Cache: cache/wl/events.json, aktualisiert durch scripts/update_wl_cache.py bzw. .github/workflows/update-wl-cache.yml.
• Spezifika: Aufbereitung und Zeitleistenlogik befinden sich in src/providers/wiener_linien.py und src/providers/wl_fetch.py.

• Quelle: Offizielle ÖBB-Störungsinformationen gemäß interner Whitelist.
• Cache: cache/oebb/events.json, gepflegt über scripts/update_oebb_cache.py sowie .github/workflows/update-oebb-cache.yml.
• Spezifika: Provider-Adapter src/providers/oebb.py normalisiert die vielfältigen Meldungsformate und setzt die WL/ÖBB Namenskonventionen um.

• Quelle: VOR/VAO-ReST-API, authentifiziert über einen Access Token (VOR_ACCESS_ID).
• Cache: cache/vor/events.json, gepflegt mittels scripts/update_vor_cache.py und .github/workflows/update-vor-cache.yml.
• Rate-Limit: Tageslimits werden automatisch überwacht (MAX_REQUESTS_PER_DAY in src/providers/vor.py). Wiederholte Cache-Aktualisierungen werden bei ausgeschöpftem Limit übersprungen.
• Unterstützung: Für lokale Experimente stehen Hilfsskripte wie scripts/check_vor_auth.py oder scripts/fetch_vor_haltestellen.py bereit.

• Quelle: Open-Government-Data-Baustellenfeed der Stadt Wien (BAUSTELLEN_DATA_URL, Default: offizieller WFS-Endpoint).
• Cache: cache/baustellen/events.json, gepflegt via scripts/update_baustellen_cache.py und eigener GitHub-Action (optional).
• Fallback: Schlägt der Remote-Abruf fehl (z. B. wegen Rate-Limits), nutzt das Skript data/samples/baustellen_sample.geojson als Grunddatensatz, damit der Feed konsistent bleibt.

Zusätzliche Datenquellen lassen sich ohne Änderungen am Kerncode anbinden. Das How-to eigene Provider-Plugins anbinden erläutert den Workflow und verweist auf das Skript scripts/scaffold_provider_plugin.py, das ein lauffähiges Modul-Skelett erzeugt. Aktivierte Plugins erscheinen automatisch im Feed-Health-Report und können über WIEN_OEPNV_PROVIDER_PLUGINS gesteuert werden.

• Kontext: Die Meldungen enthalten Metadaten zu Bezirk, Maßnahme, Zeitraum sowie geokodierte Adressen und ergänzen damit ÖPNV-Störungsmeldungen um bauzeitliche Einschränkungen.

Vor produktiven oder manuellen Abrufen empfiehlt sich ein schneller Vollständigkeitscheck der benötigten Secrets:

python scripts/verify_vor_access_id.py

Das Skript lädt automatisch .env, data/secrets.env und config/secrets.env und bricht mit Exit-Code 1 ab, wenn kein gültiger VOR_ACCESS_ID-Token gefunden wurde.

export WL_ENABLE=true
export OEBB_ENABLE=true
export VOR_ENABLE=true
# Provider-spezifische Secrets/Tokens setzen (z. B. VOR_ACCESS_ID, VOR_BASE_URL ...)
python -m src.build_feed

Der Feed liegt anschließend unter docs/feed.xml. Bei Bedarf lässt sich OUT_PATH auf ein alternatives Verzeichnis umbiegen.

data/stations.json vereint ÖBB-, Wiener-Linien- und VOR-Haltestellen mit den Feldern bst_id, bst_code, name, in_vienna, pendler, source sowie optionalen Aliasen. Die Datenbasis stammt aus folgenden Quellen:

• ÖBB-Verkehrsstationen (Verzeichnis der Verkehrsstationen.xlsx, Lizenz CC BY 3.0 AT).
• Wiener Linien OGD (wienerlinien-ogd-haltestellen.csv, wienerlinien-ogd-haltepunkte.csv, Lizenz CC BY 4.0).
• VOR: GTFS- oder CSV-Exporte unter CC BY 4.0.
• Google: Ergänzende Abgleiche via Google Maps Platform (Places API) zur Validierung von Geokoordinaten und Aliasen, Nutzung gemäß den Google Maps Platform Nutzungsbedingungen.

Die GitHub Action .github/workflows/update-stations.yml aktualisiert data/stations.json monatlich automatisch.

Nutze python -m src.cli stations validate, um einen Markdown-Bericht zum Stationsverzeichnis zu erzeugen. Der Standardlauf prüft Dubletten anhand der Geokoordinaten, meldet fehlende Alias-Einträge, erkennt Koordinaten-Anomalien (z. B. vertauschte Werte oder fehlende Angaben) und gleicht vor_id-Werte mit data/gtfs/stops.txt ab. Über --output docs/stations_validation_report.md wird der Bericht persistiert und kann in CI-Pipelines mit --fail-on-issues als Guardrail dienen.

data/pendler_bst_ids.json listet Stationen außerhalb der Stadtgrenze, die dennoch als Pendler:innen-Knoten im Verzeichnis verbleiben sollen. Änderungen an dieser Liste wirken sich beim nächsten Lauf von update_station_directory.py aus.

Weitere offene Datensätze (z. B. ÖBB-GTFS, Streckendaten, Wiener OGD, INSPIRE-Geodaten) können lokal in data/ abgelegt und mit Feed- oder Stationsdaten verknüpft werden. Hinweise zu Lizenzierung und Verknüpfung stehen in diesem Abschnitt, um eine saubere Nachnutzung zu gewährleisten.

Die wichtigsten GitHub Actions:

• update-wl-cache.yml, update-oebb-cache.yml, update-vor-cache.yml – füllen die Provider-Caches.
• update-stations.yml – pflegt monatlich data/stations.json.
• build-feed.yml – erzeugt docs/feed.xml auf Basis der aktuellen Caches.
• test.yml & test-vor-api.yml – führen die vollständige Test-Suite bzw. VOR-spezifische Integrationstests aus; test.yml läuft bei jedem Push sowie Pull Request und stellt die kontinuierliche Testabdeckung sicher.

Alle Feed-Builds warten auf die Cache-Jobs (needs-Abhängigkeit), damit stets konsistente Daten verwendet werden.

• Tests: python -m pytest führt sämtliche Unit- und Integrationstests aus (tests/).
• Kontinuierliche Tests: Die GitHub Action test.yml automatisiert die im Audit empfohlene regelmäßige Testausführung und bricht Builds bei fehlschlagender Test-Suite ab.
• Statische Analyse & Typprüfung: ruff check (Stil/Konsistenz) und mypy (vollständige Typabdeckung über das gesamte Paket src/) laufen identisch zur CI via python -m src.cli checks. Optional lassen sich über --fix Ruff-Autofixes aktivieren oder zusätzliche Argumente an Ruff durchreichen.
• Logging: Zur Laufzeit entsteht log/errors.log mit rotierenden Dateien; Größe und Anzahl sind konfigurierbar.

Die neue Kommandozeile (python -m src.cli) bündelt bisher verstreute Skripte. Wichtige Unterbefehle:

• python -m src.cli cache update <wl|oebb|vor> – aktualisiert den jeweiligen Provider-Cache.
• python -m src.cli stations update <all|directory|vor|wl> – führt die bestehenden Stations-Skripte mit optionalem --verbose aus.
• python -m src.cli feed build – startet den Feed-Build mit der aktuellen Umgebung.
• python -m src.cli feed lint – prüft die aggregierten Items auf fehlende GUIDs oder unerwartete Duplikate.
• python -m src.cli tokens verify <vor|google-places|vor-auth> – validiert Secrets und API-Zugänge.
• python -m src.cli checks [--fix] [--ruff-args …] – ruft die statischen Prüfungen konsistent zur CI auf.

python -m src.cli stations validate --output docs/stations_validation_report.md erstellt den Report docs/stations_validation_report.md. Die Ausgabe enthält zusammengefasste Kennzahlen und detaillierte Listen der gefundenen Probleme. Über --decimal-places lässt sich die Toleranz für Dubletten steuern.

Die CLI respektiert die vorhandene Logging-Konfiguration (log/errors.log, log/diagnostics.log). Für Ad-hoc-Audits lassen sich Berichte und Skriptausgaben über --output-Parameter in nachvollziehbaren Pfaden versionieren. Jeder Feed-Build erzeugt zusätzlich einen aktuellen Gesundheitsbericht unter docs/feed-health.md.

• Secrets (z. B. VOR_ACCESS_ID, VOR_BASE_URL) werden ausschließlich über Umgebungsvariablen bereitgestellt und niemals im Repository abgelegt.
• Beispielskripte und Tests nutzen Platzhalter oder export-Statements und schreiben keine Klartextwerte in Logs.
• Pfadangaben sind auf kontrollierte Verzeichnisse beschränkt; ungültige Eingaben lösen Warnungen oder Fallbacks aus.

Die detaillierte API-Referenz ist vollständig in docs/Handbuch_VAO_ReST_API_2025-08-11.pdf hinterlegt. Ergänzende Inhalte:

• docs/reference/ – Endpunktbeschreibungen und Beispielanfragen.
• docs/how-to/ – Schritt-für-Schritt-Anleitungen (z. B. Versionsabfragen).
• docs/examples/ – Shell-Snippets, etwa version-check.sh.
• docs/vor_api_review.md, docs/status_vor_api.md – Audit- und Statusberichte.

Der Abschnitt „VOR ergänzen“ im Stationskapitel erläutert, wie API-basierte Stationsdaten in das Verzeichnis aufgenommen werden.

• Leerer Feed: Prüfen, ob alle Provider aktiviert sind und ihre Cache-Dateien gültige JSON-Listen enthalten.
• Abgelaufene Meldungen: MAX_ITEM_AGE_DAYS und ABSOLUTE_MAX_AGE_DAYS anpassen; Logs geben Hinweise auf verworfene Items.
• API-Authentifizierung: Mit python scripts/check_vor_auth.py lässt sich die Gültigkeit des Tokens verifizieren.
• Timeouts: PROVIDER_TIMEOUT erhöhen oder einzelne Provider temporär deaktivieren, um Fehlerquellen einzugrenzen.

Für vertiefende Audits, technische Reviews und historische Entscheidungen liegen zahlreiche Berichte in docs/ (z. B. system_review.md, code_quality_review.md). Diese Dokumente erleichtern die Einordnung vergangener Änderungen und liefern Kontext für Weiterentwicklungen des Wien-ÖPNV-Feeds.