# Python-Werkzeuge für die Wegwichtel-REST-API

Die Skripte und die automatisierte Python-Coverage-Erzeugung benötigen nur Python 3 und die Standardbibliothek. Node.js, `curl`, `pip` und zusätzliche Python-Pakete sind auf dem aufrufenden Rechner nicht erforderlich.

## Authentifizierung

Jeder Request wird zunächst ohne vorauseilenden Authorization-Header ausgeführt. Antwortet ein vorgeschalteter Webserver mit `401 Unauthorized`, verwendet die gemeinsame Request-Schicht zuerst die Umgebungsvariablen `API_USER` und `API_PASSWORD`. Sind beide gesetzt, wird derselbe Request genau mit diesen Basic-Auth-Credentials wiederholt. Fehlen sie, fragt das Werkzeug Benutzername und Passwort interaktiv ab. Das Passwort wird mit `getpass` ohne Bildschirmausgabe eingelesen. Führende und nachgestellte Whitespaces werden aus beiden Umgebungsvariablen entfernt; reine Whitespace-Werte gelten als nicht gesetzt.

Für unbeaufsichtigte Aufrufe und CI-Pipelines:

```bash
export API_USER='florian'
export API_PASSWORD='geheimes-passwort'
```

Die API-Basisadresse ist standardmäßig `https://wegwichtel.de`. Alle Skripte unterstützen außerdem `--base-url` für abweichende Zielsysteme und `--username` für eine interaktive Anmeldung. Fehlende fachliche Parameter werden interaktiv abgefragt.

## Routen

### Lokale Moderation auf dem Server

`moderate_routes.py` greift direkt auf die bestehende SQLite-Datenbank zu und
benötigt keine API-Verbindung. Ohne Parameter zeigt es alle Strecken mit ID,
Name, Status und Freigabezeitpunkt an. Darunter stehen die Stationen tabellarisch
mit ID, Platz, Beschreibung, Erstelldatum und dauerhaften Links zu Bildern und Tonaufnahmen.
Die Anzeige öffnet die Datenbank ausschließlich lesend. Einrichtung und
passwortgeschützter Webzugang sind in
[MODERATION-MEDIEN.md](../../MODERATION-MEDIEN.md) beschrieben; die spätere
Ersteller-Zuordnung ist in [TODO-MODERATION.md](../../TODO-MODERATION.md) vorgemerkt:

```bash
python3 tools/python/moderate_routes.py
python3 tools/python/moderate_routes.py --enable 12
python3 tools/python/moderate_routes.py --disable 12
```

Alternativ aus dem Projektverzeichnis über npm:

```bash
npm run moderate
npm run moderate -- -e 12
npm run moderate -- -d 12
```

Das `--` trennt die npm-Optionen von den Parametern des Moderationsskripts.

Kurzformen: `-e 12` und `-d 12`. `--enanble` wird als Alias für `--enable`
unterstützt. Freigeben setzt `activated_at` auf den aktuellen UTC-Zeitstempel;
Zurückziehen setzt es auf `NULL`. Gelöschte Strecken werden nicht freigegeben.

Das Skript liest `.env` im Projektverzeichnis, unabhängig vom Arbeitsverzeichnis.
`DATA_DIR` bestimmt das Datenverzeichnis, standardmäßig `data`; darin liegt
`wegwichtel.sqlite`. Bereits gesetzte Umgebungsvariablen haben Vorrang wie beim
App-Start. Die `.env` unterstützt einzeilige Werte, Anführungszeichen, Kommentare
und `export`; sie wird nicht als Shell-Skript ausgeführt. Eine fehlende Datenbank
wird nicht neu angelegt. Der aufrufende Benutzer benötigt die entsprechenden
Dateirechte für Datenbank und Datenverzeichnis.

### Bearbeitung über die API

```bash
python3 tools/python/create_route.py
python3 tools/python/update_route.py
python3 tools/python/append_route.py
python3 tools/python/delete_route.py
python3 tools/python/restore_route.py
```

## POIs

```bash
python3 tools/python/create_poi.py
python3 tools/python/update_poi.py
python3 tools/python/delete_poi.py
```

Beim Löschen eines POIs entfernt die API auch dessen Bilder und Audiodatei.

## Bilder

```bash
python3 tools/python/create_picture.py
python3 tools/python/update_picture.py
python3 tools/python/delete_picture.py
```

## Audio

```bash
python3 tools/python/create_audio.py
python3 tools/python/update_audio.py
python3 tools/python/delete_audio.py
```

## Beispiel mit Parametern

```bash
python3 tools/python/create_picture.py \
  --base-url https://wegwichtel.de \
  --route-id 1 \
  --poi-id 7 \
  --file ./eiche.jpg \
  --caption 'Blick auf die Baumkrone' \
  --sequence 0
```

Die Multipart-Hilfsfunktion sendet für Dateien absichtlich keinen behaupteten MIME-Typ. Der Server bestimmt das Format aus dem Dateiinhalt.

## Fehlerausgabe und Tests

Alle Werkzeuge kapseln ihre Aktion in der gemeinsamen `run()`-Funktion. Bei API-, Datei-, Eingabe- oder unerwarteten Laufzeitfehlern werden der Fehlertyp, die Fehlermeldung und der vollständige Python-Stacktrace auf `stderr` ausgegeben. Der Prozess endet anschließend mit Exitcode `1`; ein manueller Abbruch per Tastatur verwendet Exitcode `130`.

Die Python-Tests und der Cobertura-kompatible Bericht werden über die NPM-Skripte ausgeführt:

```bash
npm run test:python
npm run test:coverage:python
```

Der Coverage-Runner verwendet `unittest` und das Standardbibliotheksmodul `trace`. Der Cobertura-kompatible Bericht liegt anschließend unter `coverage/python/coverage.xml` und wird über `sonar.python.coverage.reportPaths` von SonarQube eingelesen.