API Referenz

API-Referenz (Kurzüberblick)

Die öffentliche Schnittstelle der Bibliothek sind ihre Python-Module und das CLI; HTTP-Endpoints gibt es hier nicht (die REST-Schicht lebt im Schwesterprojekt openschichtplaner5-api). Submodule werden direkt importiert (from sp5lib.database import SP5Database).

---

sp5lib.database.SP5Database(db_path)

Die zentrale High-Level-Fassade über dem DBF-Datenverzeichnis — 171 öffentliche Methoden, gruppiert nach Funktionsbereich:

Methodengruppe	Beispiele	Inhalt
Stammdaten lesen	get_employees, get_groups, get_shifts, get_leave_types, get_workplaces, get_holidays, get_periods, get_extracharges	Mitarbeiter, Gruppen (inkl. Mitglieder), Schichtarten, Abwesenheitsarten, Arbeitsplätze, Feiertage, Perioden, Zuschläge
Stammdaten schreiben	create_employee, update_shift, hide_leave_type, create_holiday, add_group_member	CRUD für alle Stammdaten; Löschen meist als Soft-Delete/Hide mit Verwendungs-Zählern
Dienstplan	get_schedule, get_schedule_day/_week/_year, add_schedule_entry, add_absence, update_absence, add_spshi_entry, get_schedule_conflicts	Monats-/Wochen-/Jahresplan (inkl. expandierter Zyklusdienste), Sonderschichten, Abwesenheiten (auch teiltags), Konflikterkennung
Bedarf/Besetzung	get_staffing, set_staffing_requirement, create_special_staffing	Besetzungsbedarf je Schicht/Wochentag plus datumsbezogener Sonderbedarf
Zyklen (Schichtmodelle)	get_shift_cycles, create_shift_cycle, set_cycle_entry, assign_cycle, generate_schedule_from_cycle, set_cycle_exception	Modelle, Tagesfolgen, Zuweisungen, Ausnahmen und automatische Plangenerierung (mit Verfügbarkeits-/Skill-/Stunden-/Restriktions-Prüfung)
Restriktionen/Urlaubssperren	set_restriction, get_holiday_bans, create_holiday_ban	Mitarbeiter↔Schicht-Restriktionen, Urlaubssperren
Konten/Urlaub/Überstunden	get_leave_balance, set_leave_entitlement, get_bookings, create_booking, get_zeitkonto, calculate_time_balance, run_annual_close, forfeit_rest, calculate_extracharge_hours	Urlaubskonten, Kontobuchungen, Zeitkonto/Saldo, Jahresabschluss (Option keep_entitlements), Resturlaubs-Verfall, Zuschläge
Statistik/Auswertung	get_statistics, get_personnel_table, get_utilization, get_employee_stats_year/_month, get_sickness_statistics, get_burnout_radar	Auswertungen über Monat/Jahr/freien Zeitraum — alle über Berechnungen
Benutzer/Auth/2FA	get_users, create_user, verify_user_password, change_password, totp_enable, get_user_permissions, set_employee_access, set_group_access	Benutzerverwaltung mit granularen Rechte-Flags, Passwort-Verifikation (bcrypt mit Alt-Format-Migration), TOTP-2FA, Zugriffsrechte je Mitarbeiter/Gruppe
Notizen/Kommentare/Wünsche/Tausch	add_note, add_schedule_comment, add_wish, create_swap_request, resolve_swap_request	Notizen, Plan-Kommentare, Wunsch- und Tauschbörse mit Status-Historie und Ablauf
Templates/iCal/Changelog	create_schedule_template, apply_schedule_template, create_ical_token, assign_employee_to_workplace, get_changelog, log_action	Wochen-Templates, iCal-Token, Arbeitsplatz-Zuordnung, Audit-Changelog
Wartung	compact_database	PACK über alle Tabellen (physisches Entfernen gelöschter Records)

Auswertungs- und Berechnungsmethoden rechnen durchgängig über sp5lib.calculations (Berechnungen).

sp5lib.pg_database.SP5PostgresDatabase(database_url)

Gleiche Methodensignaturen wie SP5Database, aber als Teilmenge (76 der 171 Methoden): Stammdaten-CRUD, Dienstplan-Basis, Benutzer/2FA inkl. granularer Rechte, Notizen, Statistik/Personaltabelle/Auslastung, Urlaubskonten (lesen + Verfall), Changelog. Die Berechnungsmethoden sind paritätisch zum DBF-Backend; der Jahresabschluss wirft auf PostgreSQL NotImplementedError. Nicht abgedeckt sind u. a. Tausch-/Wunschbörse, iCal-Tokens, Templates, Besetzungsbedarf, Restriktionen und der Zyklen-Schreibpfad. Details: ORM-und-Sync.

Backend-Wahl: sp5lib.db_factory / sp5lib.db_config

• db_factory.get_database(db_path=None) liefert je nach Umgebung SP5Database oder (als Singleton) SP5PostgresDatabase.
• db_config: get_db_backend(), get_database_url(), is_postgresql() — gesteuert über DB_BACKEND, DATABASE_URL, SP5_DB_PATH (siehe Entwicklung).

---

Low-Level: sp5lib.dbf_reader / sp5lib.dbf_writer

Funktion	Zweck
read_dbf(filepath)	kompletten Tabelleninhalt lesen (ohne gelöschte Records)
get_table_fields(filepath)	Felddeskriptoren (name, type, len, dec)
append_record(filepath, fields, record)	Record anhängen, liefert neuen Record-Count
update_record(filepath, fields, record_index, data)	nur die übergebenen Felder eines Records ändern
delete_record(filepath, fields, record_index)	Record als gelöscht markieren (Soft-Delete)
find_all_records(filepath, fields=None, **filters)	(raw_index, record)-Treffer mit UND-Filter; der Index ist direkt an update_record/delete_record übergebbar
pack_table(filepath)	PACK: gelöschte Records physisch entfernen (inkl. Journal-Reset)
Modul-Schalter INVALIDATE_CDX	CDX-Invalidierung nach Schreibzugriffen abschalten

Format- und Encoding-Verhalten im Detail: Datenbankformat.

sp5lib.calculations

Reine Rechenfunktionen (Soll/Ist/Saldo, Urlaubskonto, Zuschläge, Personaltabelle, Bedarf/Auslastung, Zyklen-Expansion) — eigene Seite: Berechnungen.

sp5lib.orm

Engine/Session (get_engine, get_session, init_db, session_scope), Modelle, Repositories und der DBF→SQL-Sync (sync_all) — eigene Seite: ORM-und-Sync.

Querschnittsmodule

Modul	Schnittstelle
sp5lib.auto_migrate	run_startup_migration() -> MigrationResult — automatische Schema-Migration beim Start (PostgreSQL: Alembic-Upgrade mit vorherigem pg_dump-Backup; DBF: versionsgestempelte Schema-Erweiterungen mit Verzeichnis-Backup)
sp5lib.email_service	EmailConfig, get_config(), send_email(...), send_email_async(...), send_notification_email(...) — SMTP-Benachrichtigungen mit HTML-escapten Templates, Konfiguration über SP5_SMTP_*
sp5lib.color_utils	bgr_to_hex, bgr_to_rgb, is_light_color — Konvertierung der FoxPro-/Windows-BGR-Farbwerte
sp5lib.sqlite_adapter	SP5SQLiteAdapter — älterer Roh-SQLite-Spiegel der Kerntabellen (durch sp5lib.orm konzeptionell abgelöst, noch vom SQLite-Export der API genutzt)

---

Versionsabfrage zur Laufzeit

Das Paket exportiert kein __version__; die installierte Version liefert die Standardbibliothek:

from importlib.metadata import version
version("libopenschichtplaner5")   # z. B. "1.7.0"