XSCHOOL Exporter

Python-Tool zum automatisierten Login in XSCHOOL (inkl. TOTP-2FA), Abruf der Daten aus input#viewModel und Export als bereinigtes JSON.

Unterstützte Datenquellen:

• Noten: /Marks/Parent
• Vertretungsplan: /Substitution

Zusatz:

• Filter des Vertretungsplans auf definierte Schüler (Name + Klassenstufe) per .env
• Optionaler Lehrer-Filter für den Vertretungsplan per .env
• Optionaler Fach-Exclude-Filter (subject) für den Vertretungsplan per .env
• Zwei HTML-Viewer für Produktiv- und Debug-Nutzung

Inhalt

• xschool_export.py: Hauptskript (Login, Abruf, Verarbeitung, Export)
• processors/marks.py: Bereinigung/Normalisierung von Noten
• processors/substitutions.py: Bereinigung/Normalisierung von Vertretungen inkl. Schülerfilter
• viewer_productive.html: produktive Ansicht mit festen Daten aus result/result.json
• viewer_debug.html: lokale Debug-Ansicht mit manueller JSON-Zufuhr
• requirements.txt: Python-Abhängigkeiten

Voraussetzungen

• Python 3.10+ (getestet mit Python 3.13)
• Zugriff auf XSCHOOL-Account mit aktivierter 2FA (Google Authenticator / TOTP)

Installation

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Konfiguration (.env)

Lege eine .env im Projektroot an:

XSCHOOL_URL=https://ess.xschool.de
XSCHOOL_USERNAME=DEIN_USERNAME
XSCHOOL_PASSWORD=DEIN_PASSWORT
XSCHOOL_TOTP_SECRET=DEIN_BASE32_SECRET

XSCHOOL_DEBUG=false
XSCHOOL_STUDENTS=[{"firstname":"Max","lastname":"Mustermann","classes":["9c"]}]
XSCHOOL_TEACHERS=[]
XSCHOOL_SKIP_SUBJECTS=[]
XSCHOOL_OUTPUT_PATH=result/result.json

Bedeutung der Variablen

• XSCHOOL_URL: Basis-URL (z. B. https://ess.xschool.de)
• XSCHOOL_USERNAME: Login-Name
• XSCHOOL_PASSWORD: Passwort
• XSCHOOL_TOTP_SECRET: Base32-Secret für TOTP (nicht der 6-stellige Code)
• XSCHOOL_DEBUG: true|false für zusätzliche Laufzeit-Logs
• XSCHOOL_STUDENTS: JSON-Array für Vertretungsfilter
• XSCHOOL_TEACHERS: Optionales JSON-Array für Lehrerfilter im Vertretungsplan
• XSCHOOL_SKIP_SUBJECTS: Optionales JSON-Array für Fächer, die im Vertretungsplan ausgeschlossen werden
• XSCHOOL_OUTPUT_PATH: Standard-Ausgabepfad für die Ergebnisdatei

Format von XSCHOOL_STUDENTS

[
  {
    "firstname": "Max",
    "lastname": "Mustermann",
    "classes": ["7c"]
  },
  {
    "firstname": "Maria",
    "lastname": "Mustermann",
    "classes": ["8c"]
  }
]

Filter-Logik im Vertretungsplan:

• Name muss zu user_name passen (firstname + lastname, case-insensitive)
• Mindestens eine Klasse aus classes muss in der Plan-Zeile enthalten sein
• Wenn XSCHOOL_TEACHERS gesetzt ist, muss zusätzlich der Lehrer passen
• Wenn XSCHOOL_SKIP_SUBJECTS gesetzt ist, werden Einträge mit passendem subject ausgeschlossen

Format von XSCHOOL_TEACHERS

["Con", "Bar", "Schr"]

Lehrer-Filter-Logik:

• Vergleich case-insensitive
• Es wird nur replacement_teacher berücksichtigt
• Trennung mehrerer Lehrer in einer Zelle über ,, ;, / oder +

Format von XSCHOOL_SKIP_SUBJECTS

["Sp", "Mu"]

Fach-Exclude-Logik:

• Vergleich case-insensitive
• Es wird das Feld subject gefiltert
• Leere oder fehlende subject-Werte werden nicht ausgeschlossen

Nutzung

Export ausführen

python xschool_export.py --mode both

Optionen:

• --mode marks
• --mode substitutions
• --mode both (Default)
• --output <pfad> (überschreibt XSCHOOL_OUTPUT_PATH)

Beispiele:

python xschool_export.py --mode marks
python xschool_export.py --mode substitutions
python xschool_export.py --mode both --output result\my_export.json

Pfad-Priorität für die Ausgabe:

1. --output
2. XSCHOOL_OUTPUT_PATH aus .env
3. result/result.json (Fallback)

Ergebnisdatei

Standardausgabe:

• result/result.json

Struktur (vereinfacht):

• mode
• generated_at
• marks (falls geladen)
• substitutions (falls geladen)

Die Vertretungsdaten enthalten bei aktivem Filter:

• matched_students: Liste der passenden Schüler pro Eintrag
• matched_teachers: Liste der passenden Lehrer pro Eintrag
• Nach XSCHOOL_SKIP_SUBJECTS gefilterte Einträge sind nicht mehr enthalten

Viewer

viewer_productive.html

• Lädt immer result/result.json
• Zwei Reiter: Vertretungsplan und Noten
• Header zeigt generated_at deutsch formatiert
• Noten-Filter in der UI für Schüler/Schuljahr/Fach

viewer_debug.html

• Alternative lokale Ansicht für Debug-Zwecke
• Eignet sich für manuelle JSON-Analyse/Tests

Fehlerbehandlung

Fehlende .env-Werte

Das Skript prüft Pflichtwerte und meldet sauber:

• XSCHOOL_URL
• XSCHOOL_USERNAME
• XSCHOOL_PASSWORD
• XSCHOOL_TOTP_SECRET

Beispiel:

• Konfigurationsfehler: Fehlende .env-Werte: XSCHOOL_PASSWORD, XSCHOOL_TOTP_SECRET.

Ungültiges XSCHOOL_STUDENTS

Wenn XSCHOOL_STUDENTS kein gültiges JSON-Array ist, bricht das Skript mit klarer Meldung ab.

Ungültiges XSCHOOL_TEACHERS

Wenn XSCHOOL_TEACHERS kein gültiges JSON-Array ist, bricht das Skript mit klarer Meldung ab.

Ungültiges XSCHOOL_SKIP_SUBJECTS

Wenn XSCHOOL_SKIP_SUBJECTS kein gültiges JSON-Array ist, bricht das Skript mit klarer Meldung ab.

Sicherheit

• .env niemals committen.
• Zugangsdaten und TOTP-Secret als sensibel behandeln.
• Bei versehentlicher Offenlegung sofort Passwort und TOTP-Secret rotieren.

Entwicklung

Syntax-Check:

python -m py_compile xschool_export.py processors\marks.py processors\substitutions.py

Hinweise

• Das Tool ist auf den aktuell beobachteten XSCHOOL-Flow abgestimmt (inkl. AntiForgery + 2FA).
• Falls XSCHOOL die Login- oder Formularstruktur ändert, muss xschool_export.py ggf. angepasst werden.