sorted markdown and added favicon
This commit is contained in:
Florian Zumpe
@@ -0,0 +1,124 @@
|
||||
# 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:
|
||||
|
||||
```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, 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](MODERATION-MEDIEN.md) beschrieben. Gerätekennung und
|
||||
erneutes Einsenden stehen in [CREATOR-ID.md](CREATOR-ID.md); noch offene
|
||||
Berechtigungen in [TODO-MODERATION.md](agents/TODO-MODERATION.md):
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user