81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
# Python-Werkzeuge für die Wegwichtel-REST-API
|
|
|
|
Die Skripte benötigen für den regulären Betrieb nur Python 3 und die Standardbibliothek. Node.js, `curl` und zusätzliche Python-Pakete sind auf dem aufrufenden Rechner nicht erforderlich. Nur die automatisierte Coverage-Erzeugung verwendet das in `requirements-dev.txt` festgelegte Paket `coverage`.
|
|
|
|
## 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
|
|
|
|
```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
|
|
python3 -m pip install -r requirements-dev.txt
|
|
npm run test:python
|
|
npm run test:coverage:python
|
|
```
|
|
|
|
Der Bericht liegt anschließend unter `coverage/python/coverage.xml` und wird über `sonar.python.coverage.reportPaths` von SonarQube eingelesen.
|