5.1 KiB
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.
Alle Aufrufe erfolgen aus dem Projektverzeichnis. Die Skripte liegen weiterhin
unter tools/python/; nur diese Anleitung wurde nach docs/ verschoben.
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:
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, Freigabezeitpunkt und Ersteller-ID (creator_id) 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 beschrieben. Gerätekennung und
erneutes Einsenden stehen in CREATOR-ID.md; noch offene
Berechtigungen in TODO-MODERATION.md:
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:
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
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
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
python3 tools/python/create_picture.py
python3 tools/python/update_picture.py
python3 tools/python/delete_picture.py
Audio
python3 tools/python/create_audio.py
python3 tools/python/update_audio.py
python3 tools/python/delete_audio.py
Beispiel mit Parametern
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:
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.