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
• Stundenplan: Kalender aus /Schedule, Termine aus /Calendar/Ajax_GetEvents

Zusatz:

• Filter des Vertretungsplans auf definierte Schüler (Name + Klassenstufe) per .env
• Optionaler Lehrer-Filter für den Vertretungsplan per .env
• Optionales Fach-Flagging (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
• processors/schedule.py: Normalisierung von Kalendern und Stundenplan-Terminen
• 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 (Authenticator-App / 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_TOKEN_PROVIDER=Authenticator

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_TOKEN_PROVIDER: Name des XSCHOOL-2FA-Providers (Default: Authenticator; alter Wert war teils Google Authenticator)
• 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 Vertretungs- und Stundenplan markiert werden
• XSCHOOL_OUTPUT_PATH: Standard-Ausgabepfad für die Ergebnisdatei

Für den Stundenplan ist keine zusätzliche Umgebungsvariable erforderlich. Das Tool liest die verfügbaren Kalender-IDs und Titel automatisch aus /Schedule.

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 und Stundenplan-Termine mit passendem subject als is_skipped_subject markiert

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-Flag-Logik:

• Vergleich case-insensitive
• Im Vertretungsplan wird das Feld subject geprüft
• Im Stundenplan werden subject und der sichtbare title geprüft; zum Beispiel wird La in 7. Std.: La erkannt
• Fachkürzel in zusammengesetzten Titeln werden nur als vollständige Bestandteile erkannt
• Leere oder fehlende Werte werden nicht markiert

Nutzung

Export ausführen

python xschool_export.py --mode all

Optionen:

• --mode marks
• --mode substitutions
• --mode schedule
• --mode all
• --mode both (Default; Kompatibilitätsalias für all)
• --output <pfad> (überschreibt XSCHOOL_OUTPUT_PATH)

Beispiele:

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

all und der weiterhin unterstützte Modus both laden Noten, Vertretungen und Stundenplan gemeinsam.

Abruf des Stundenplans

1. GET /Schedule liefert das eingebettete input#viewModel.
2. Aus TeacherSchedules, RoomSchedules und RoleSchedules werden alle Kalender mit ID und Titel übernommen.
3. Für jeden Kalender ruft das Tool die Termine separat per POST /Calendar/Ajax_GetEvents mit calendarIds[], start und end ab.

Abgerufen werden Termine ab heute bis zum Ende der direkt folgenden Kalenderwoche in der Zeitzone Europe/Berlin; vergangene Tage werden nicht geladen. Der Zeitraum beginnt heute um 00:00 Uhr. Standardmäßig endet er am Samstag nach der Folgewoche um 00:00 Uhr (exklusive Endgrenze); Ereignisse an Wochenenden werden ausgeblendet. Wenn die XSCHOOL-Konfiguration ShowWeekends aktiviert hat, endet der Zeitraum am Montag nach der Folgewoche um 00:00 Uhr und umfasst auch die Wochenenden.

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)
• schedule (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
• is_skipped_subject: Flag für per XSCHOOL_SKIP_SUBJECTS markierte Fächer in Vertretungs- und Stundenplan

Die Stundenplandaten enthalten:

• range: tatsächlich abgefragte Start- und Endgrenze
• config: normalisierte Anzeige-Konfiguration aus XSCHOOL
• calendars: alle gefundenen Kalender mit id, title und Typ (teacher, room oder role)
• events: normalisierte, chronologisch sortierte Termine mit Kalender-Zuordnung; nicht bekannte Quellfelder bleiben optional unter details erhalten
• summary: Anzahl der Kalender und Termine

Viewer

viewer_productive.html

• Lädt immer result/result.json
• Eigene Bereiche für Vertretungsplan, Noten und Stundenplan
• Header zeigt generated_at deutsch formatiert
• Noten-Filter in der UI für Schüler/Schuljahr/Fach
• Geflaggte Fächer im Vertretungsplan sind standardmäßig ausgeblendet und können per Option eingeblendet werden
• Geflaggte Fächer im Stundenplan sind ebenfalls standardmäßig ausgeblendet und können dort separat eingeblendet werden
• Die Einblend-Option für geflaggte Fächer wird nicht im Local Storage gespeichert

viewer_debug.html

• Alternative lokale Ansicht für Debug-Zwecke
• Eignet sich für manuelle JSON-Analyse/Tests
• Zeigt den Stundenplan in einem eigenen Bereich

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 processors\schedule.py
python -m unittest discover -v

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.