README.md

metadata

title: Rheinpegel Python WebApp
emoji: 📚
colorFrom: purple
colorTo: green
sdk: docker
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

<<<<<<< HEAD # rheinpegel-python-app

Rheinpegel App

Eine moderne FastAPI-Anwendung, die den aktuellen Rheinpegel (Köln) abruft, zwischenspeichert und visuell aufbereitet. Die Anwendung kombiniert serverseitiges Polling mit einem reaktiven Frontend (AJAX, Countdown, Sparkline) und liefert zusätzlich Status- sowie Prometheus-Kennzahlen.

Hauptfunktionen

• Asynchrones Polling der offiziellen Quelle via httpx mit Timeout (8 s) und exponentiellem Backoff (4 Versuche).
• Automatische Format-Erkennung für JSON oder XML und robuste Feldzuordnung.
• Trend-Berechnung aus Rohdaten oder anhand der letzten Messwerte (Δ > 2 cm ⇒ ↑, Δ < −2 ⇒ ↓).
• Mehrstufiges Caching: In-Memory-Ringpuffer (48 Werte) + JSON-Persistenz unter data/cache.json.
• Demo-Modus bei Netzwerkfehlern oder via ?demo=1 mit synthetischen, plausiblen Messwerten.
• FastAPI + Jinja2 Dashboard mit responsive Karte, Warnstufen, Sparkline (Inline-SVG) sowie Auto-Refresh-Toggle und Countdown.
• Prometheus-Metriken: letzte Latenz, Erfolgs-/Fehlerzähler, Datenalter und Health-Endpoint.

Voraussetzungen

• Python 3.11+
• Optional: uv für schnelle virtuelle Umgebungen

Installation & Setup

Variante A: uv

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .
cp .env.example .env

Variante B: pip / venv

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e .
copy .env.example .env  # Windows

Hinweis: Die Umgebungsvariablen (.env) steuern u.a. den Polling-Intervall (REFRESH_SECONDS), die Quelle (SOURCE_URL) und die Zeitzone (TZ).

Starten der Anwendung

uvicorn app.main:app --reload
# oder
python -m app.main

Die Oberfläche ist anschließend unter http://127.0.0.1:8000 erreichbar.

Wichtige Endpunkte

Route	Beschreibung
/	Dashboard mit Live-Karte, Trend, Sparkline
/api/latest	Neueste Messung (JSON) + komplette Historie
/api/history	Maximal 48 Messpunkte aus dem Ringpuffer
/healthz	200 OK, wenn der Hintergrund-Task aktiv ist
/metrics	Prometheus-kompatible Kennzahlen

Demo-Modus

Alle Endpunkte akzeptieren ?demo=1, um synthetische Daten zu liefern und das UI als „Demo“ zu markieren.

Tests

pytest

Die Tests decken das Parsing (JSON/XML) sowie zentrale FastAPI-Endpunkte ab.

Docker

docker build -t rheinpegel-app .
docker run -p 8000:8000 --env-file .env rheinpegel-app

Oder via Compose:

docker-compose up --build

Der Container läuft als Non-Root-User, besitzt einen Healthcheck (/healthz) und bindet ./data für persistente Caches ein.

Beispiel systemd Unit (optional)

[Unit]
Description=Rheinpegel App
After=network.target

[Service]
User=www-data
WorkingDirectory=/opt/rheinpegel-app
EnvironmentFile=/opt/rheinpegel-app/.env
ExecStart=/opt/rheinpegel-app/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

Weiterentwicklung

• UI-Optimierungen, z. B. zusätzliche Karten oder historische Auswertungen
• Export in weitere Formate (CSV/ICS)
• Alarm-Benachrichtigungen (E-Mail, Webhooks) basierend auf Warnstufen

Viel Spaß beim Ausprobieren der Rheinpegel-App!