Entwicklung

Entwicklung

Diese Seite beschreibt das Entwicklungs-Setup der Bibliothek selbst sowie den Workflow im Verbund mit den beiden Schwester-Repositories.

---

Lokales Setup

git clone https://github.com/mschabhuettl/libopenschichtplaner5.git
cd libopenschichtplaner5

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,postgres]"

Das dev-Extra installiert pytest, pytest-cov und ruff; das postgres-Extra psycopg2-binary für die PostgreSQL-Tests bzw. -Backends.

Tests und Lint

pytest          # Testsuite (187 Tests)
ruff check .    # Linting

Die Suite läuft komplett ohne externe Dienste: DBF-Tests arbeiten mit selbstgebauten Mini-DBF-Dateien in Temp-Verzeichnissen, ORM-Tests mit In-Memory-SQLite. Abgedeckt werden u. a. der ORM-Layer inkl. Sync-Härtefällen, die Rechenschicht (Berechnungen), DBF-Roundtrips mit Overflow-/Datums-Guards, die Byte-Parität des Schreibpfads inkl. -L-Journal/CDX/PACK, das CLI, die DBF↔PostgreSQL-Äquivalenz der Auswertungen und Thread-Sicherheit.

Golden-Regression gegen eine Original-Datenbank

Optional läuft eine zusätzliche Regressionssuite gegen eine lokale Original- Beispieldatenbank von Schichtplaner 5 (lokales Referenzmaterial, wird nie committet):

SP5_GOLDEN_DB=/pfad/zu/sp5/Daten pytest tests/test_golden_sample_db.py -v

Ohne gesetzte Variable SP5_GOLDEN_DB überspringt sich das Modul selbst.

Reproduzierbar im Container

Die Dockerfile-Stage test führt Lint + Tests in einer definierten Umgebung aus (python:3.12-slim):

docker compose run --rm test
# gleichwertig:
docker build --target test -t libopenschichtplaner5:test . && docker run --rm libopenschichtplaner5:test

Code-Konventionen

• ruff ist der Linter (Regelgruppen E, W, F, I, B, UP; Zeilenlänge 100, Ziel Python 3.10) — Konfiguration in pyproject.toml.
• Das Paket ist vollständig typannotiert (py.typed).
• Versionierung nach SemVer, Änderungen werden im CHANGELOG (Keep-a-Changelog-Format) gepflegt.

CI und Release

• CI (GitHub Actions): ruff + pytest auf Python 3.10–3.12 für jeden Push/PR.
• Release: Ein v*-Tag baut sdist + wheel und veröffentlicht nach PyPI über Trusted Publishing (OIDC, keine gespeicherten Tokens). Ein manueller workflow_dispatch macht einen TestPyPI-Probelauf.

---

Entwicklung im Repo-Verbund (dev-link)

Die drei Projekte sind unabhängige Repositories und werden als Geschwisterverzeichnisse ausgecheckt, damit die ../-Pfade auflösen:

~/Projects/
├── libopenschichtplaner5/      # diese Bibliothek (sp5lib)
├── openschichtplaner5-api/     # REST-API (sp5api)
└── openschichtplaner5/         # Web-App (Frontend + Compose)

• Release-Pfad: Die API deklariert libopenschichtplaner5[postgres]>=1.7.0 (PyPI); die App hängt von der API und direkt von der Bibliothek ab.

• Editable-Workflow: Wer alle drei Repos gemeinsam entwickelt, installiert die Bibliothek (und die API) editierbar in das jeweilige venv:

  # im App-Repo: Library + API aus den lokalen Schwester-Clones verlinken
  make dev-link
  
  # im API-Repo:
  pip install -e "../libopenschichtplaner5[postgres]"

  Änderungen an sp5lib sind dann ohne Re-Installation sofort in API und App wirksam.

Dokumentation der Schwesterprojekte: App-Wiki · API-Wiki.

---

Umgebungsvariablen der Bibliothek

Variable	Wirkung
DB_BACKEND	Backend-Wahl: dbf (Default) oder postgresql
DATABASE_URL	Verbindungs-URL für das PostgreSQL-Backend
SP5_DB_PATH	Pfad zum DBF-Datenverzeichnis für db_factory.get_database()
SP5_BACKEND_DIR	Backend-Verzeichnis der Host-App (JSON-Nebendaten, Alembic-Struktur)
AUTO_MIGRATE / AUTO_BACKUP	Startup-Migration bzw. Backup davor ein-/ausschalten
SP5_SMTP_HOST/PORT/USER/PASSWORD/FROM/TLS/ENABLED, SP5_APP_URL	E-Mail-Versand (email_service)
SP5_GOLDEN_DB	nur Tests: Pfad zur Original-Beispieldatenbank für die Golden-Suite