libopenschichtplaner5 1.1.0__py3-none-any.whl

libopenschichtplaner5-1.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: libopenschichtplaner5
+Version: 1.1.0
+Summary: Read and write the original Schichtplaner5 FoxPro .DBF database files, plus the SQLite/PostgreSQL ORM and sync layer used by OpenSchichtplaner5.
+Author-email: Matthias Schabhüttl <matthias@matthiasschabhuettl.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mschabhuettl/libopenschichtplaner5
+Project-URL: Source, https://github.com/mschabhuettl/libopenschichtplaner5
+Project-URL: Changelog, https://github.com/mschabhuettl/libopenschichtplaner5/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mschabhuettl/libopenschichtplaner5/issues
+Project-URL: Main application, https://github.com/mschabhuettl/openschichtplaner5
+Keywords: schichtplaner5,dbf,foxpro,shift-planning,dbase
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: SQLAlchemy>=2.0.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: pyotp>=2.9.0
+Requires-Dist: packaging>=21.0
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# libopenschichtplaner5
+
+[![CI](https://github.com/mschabhuettl/libopenschichtplaner5/actions/workflows/ci.yml/badge.svg)](https://github.com/mschabhuettl/libopenschichtplaner5/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The core library behind [**OpenSchichtplaner5**](https://github.com/mschabhuettl/openschichtplaner5) —
+a pip-installable package that reads **and writes** the original *Schichtplaner5*
+FoxPro/dBASE `.DBF` database files, so an open replacement can run on the exact same
+data as the proprietary Windows tool, with no migration.
+
+> **Import name:** the distribution is `libopenschichtplaner5`, but the importable
+> package keeps its historical name **`sp5lib`** (like `pip install PyYAML` → `import yaml`).
+> This keeps OpenSchichtplaner5's imports unchanged after the extraction.
+
+## What's inside
+
+| Module | Purpose |
+|---|---|
+| `sp5lib.dbf_reader` | Pure-Python DBF reader (UTF-16-LE detection, date parsing, field decode) |
+| `sp5lib.dbf_writer` | Safe DBF writer — exclusive `flock`, TOCTOU-safe record count, rollback, EOF marker preservation |
+| `sp5lib.database` | High-level `SP5Database` facade over the DBF tables (employees, shifts, schedule, absences, auth, 2FA …) |
+| `sp5lib.db_factory` / `sqlite_adapter` / `pg_database` | Optional SQLite / PostgreSQL backends |
+| `sp5lib.orm` | SQLAlchemy models (`models.py` SQLite, `models_pg.py` Postgres), `repository`, `sync` |
+| `sp5lib.auto_migrate` | Alembic-based automatic migrations |
+| `sp5lib.email_service` | SMTP notification emails (HTML-escaped templates) |
+| `sp5lib.color_utils` | FoxPro BGR ↔ hex/RGB color helpers |
+
+## Installation
+
+```bash
+pip install "libopenschichtplaner5 @ git+https://github.com/mschabhuettl/libopenschichtplaner5.git"
+# with the optional PostgreSQL backend:
+pip install "libopenschichtplaner5[postgres] @ git+https://github.com/mschabhuettl/libopenschichtplaner5.git"
+```
+
+## Usage
+
+```python
+from sp5lib.database import SP5Database
+
+db = SP5Database("/path/to/SP5/Daten")        # directory of .DBF files
+for emp in db.get_employees():
+    print(emp["ID"], emp["NAME"], emp["FIRSTNAME"])
+```
+
+Low-level DBF access:
+
+```python
+from sp5lib.dbf_reader import read_dbf
+from sp5lib.dbf_writer import append_record, get_table_fields
+
+rows   = read_dbf("/path/to/SP5/Daten/5EMPL.DBF")
+fields = get_table_fields("/path/to/SP5/Daten/5EMPL.DBF")
+append_record("/path/to/SP5/Daten/5NOTE.DBF", fields, {"ID": 1, "TEXT": "hello"})
+```
+
+## Dependencies
+
+Runtime: `SQLAlchemy`, `alembic`, `bcrypt`, `pyotp`, `packaging`.
+Optional: `psycopg2-binary` (via the `postgres` extra) for the PostgreSQL backend.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,postgres]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). Extracted (with full git history) from
+[OpenSchichtplaner5](https://github.com/mschabhuettl/openschichtplaner5)'s `backend/sp5lib/`.

libopenschichtplaner5-1.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+libopenschichtplaner5-1.1.0.dist-info/licenses/LICENSE,sha256=AR48Bxp-u4fRBkNgKZLE9NxZ30ENMrDgUVRTd4tPjUU,1077
+sp5lib/__init__.py,sha256=-gSQSDrTSETsnGjUoFVGpfl5t6na-c6MUwzkhQmKGX4,75
+sp5lib/_resource_paths.py,sha256=Dx0RszegjfLCyKDTrwLz-56HrJUIC0xrkyXExrrW59I,1565
+sp5lib/auto_migrate.py,sha256=PQrVgV9V2tkUVir5LNknIzEueR0tfhX2Vf-VJFXYJwY,14906
+sp5lib/color_utils.py,sha256=tLNKjsqZYsctRi4DtEbgCDS_SJu1LCrwrqtHDplAPS8,781
+sp5lib/database.py,sha256=UVfefYPI0ywQ_fYlFbqCIJq7xkZoPsRsKs4cmmnmB_Y,250986
+sp5lib/db_config.py,sha256=CaPEFcQwE8xBvAUAy8DXgaAngR8FbXTXBzF-NhfwMP0,1195
+sp5lib/db_factory.py,sha256=0_ISRa3YbWxcOofY2V2TMUudAT14roYG9YvUMF1N6XI,1845
+sp5lib/dbf_reader.py,sha256=7ywFrFMeOooFEnPi-Q1yuLOi4YizBR8bQPaVaq5z3bY,7378
+sp5lib/dbf_writer.py,sha256=DMPHyfCRylzSTcg464hZxiflSD5BGfY5r2CsgMu0cFI,15803
+sp5lib/email_service.py,sha256=dzh8IvmooqGJTjiYjrHRzZZVdWlWlGSZMdtiKWNZtEw,9801
+sp5lib/pg_database.py,sha256=aLpkuYY9cFdpjhpDjotqb3DX3KTDRx3vDl1qd3JliVE,49982
+sp5lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sp5lib/sqlite_adapter.py,sha256=MM_2vuYY2id_gSdBxyfY9t_SDYAJQJi-OSKVruPXuBA,11475
+sp5lib/orm/__init__.py,sha256=ONwaCSqR0uuWbLdCfNVCU7nJrlEMUIxshN6vOiPZNNI,741
+sp5lib/orm/base.py,sha256=mUeZj7RvMLxflSzUPk3EZ_tFw6qSopS0qNhFF3lM9l0,3199
+sp5lib/orm/models.py,sha256=ILCG12TMZK_1ePyHAQk6MuRm3ZCNq2RRECsQcGE7vCE,9078
+sp5lib/orm/models_pg.py,sha256=oFTO9sZS7WWXT_kd0HMIIRoDOukG2XdbNLn9vaEgeBw,16196
+sp5lib/orm/repository.py,sha256=dtkSv8541b8OEWlt9AD62OxPB533u3Krlg8Q-tun0Tc,6782
+sp5lib/orm/sync.py,sha256=5TcI9N1O03V76ILXMDPtDzi8oXb-X0p96iQ6DgYQCJU,5119
+libopenschichtplaner5-1.1.0.dist-info/METADATA,sha256=dLybGQrp3Z-atBR78ecPxCB0Y3cXf78Nt_5AYAPur0Y,4782
+libopenschichtplaner5-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+libopenschichtplaner5-1.1.0.dist-info/top_level.txt,sha256=5BuXleV-Wxx0nNkE7V-ig1pkPvHvUV5R7mZEE3zlQ6Q,7
+libopenschichtplaner5-1.1.0.dist-info/RECORD,,

libopenschichtplaner5-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

libopenschichtplaner5-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Schabhüttl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libopenschichtplaner5-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sp5lib

sp5lib/__init__.py

@@ -0,0 +1 @@
+# OpenSchichtplaner5 - Python library for reading Schichtplaner5 databases

sp5lib/_resource_paths.py

@@ -0,0 +1,40 @@
+"""Resolution of host-application resource directories.
+
+Historically these modules lived inside the OpenSchichtplaner5 ``backend/`` tree and
+located sibling resources (``backend/data``, ``backend/api/data``, the Alembic
+directory) via paths relative to ``__file__``. Once this library is installed as a
+standalone package (``libopenschichtplaner5``) that assumption no longer holds — the
+package lives in ``site-packages`` and the host app's data lives elsewhere.
+
+The host application therefore tells the library where its backend root is via the
+``SP5_BACKEND_DIR`` environment variable. When unset, we fall back to the legacy
+``<this_package_parent>`` location so an in-tree checkout keeps working unchanged.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def backend_dir() -> str:
+    """Return the host application's backend root directory.
+
+    Honors ``SP5_BACKEND_DIR``; otherwise falls back to the directory that contains
+    this package (the legacy in-tree layout ``<backend>/sp5lib/``).
+    """
+    env = os.environ.get("SP5_BACKEND_DIR")
+    if env:
+        return os.path.abspath(env)
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def data_dir() -> str:
+    """``<backend>/data`` — JSON-backed settings (changelog, swaps, comments …)."""
+    path = os.path.join(backend_dir(), "data")
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def api_data_dir() -> str:
+    """``<backend>/api/data`` — availability / skills JSON written by the API layer."""
+    return os.path.join(backend_dir(), "api", "data")

sp5lib/auto_migrate.py

@@ -0,0 +1,435 @@
+"""
+Automatic database migration on application startup.
+
+Compares the app's schema version against the DB's stored schema version.
+If the DB is behind, runs Alembic migrations automatically (for PostgreSQL)
+or applies schema extensions (for DBF).
+
+Configuration via environment variables:
+    AUTO_MIGRATE=false   → Disable auto-migration (default: true)
+    AUTO_BACKUP=false    → Disable pre-migration backup (default: true)
+
+Usage:
+    from sp5lib.auto_migrate import run_startup_migration
+    run_startup_migration()  # Call once during app lifespan startup
+"""
+
+import logging
+import os
+import shutil
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+
+from ._resource_paths import backend_dir as _backend_dir
+
+_log = logging.getLogger("sp5api.auto_migrate")
+
+# The current app schema version — bump this when adding new migrations.
+# Format: Alembic revision head. We read it dynamically from Alembic.
+APP_SCHEMA_VERSION = "head"
+
+def _backend_path() -> Path:
+    """Backend root directory (where alembic.ini lives), resolved lazily.
+
+    Honors SP5_BACKEND_DIR so the host app can point at its alembic/ tree when this
+    package is installed standalone. Evaluated on each call so it picks up the env
+    var regardless of import order.
+    """
+    return Path(_backend_dir())
+
+
+def _is_auto_migrate_enabled() -> bool:
+    """Check if auto-migration is enabled via AUTO_MIGRATE env var."""
+    val = os.environ.get("AUTO_MIGRATE", "true").lower().strip()
+    return val not in ("false", "0", "no", "off")
+
+
+def _is_auto_backup_enabled() -> bool:
+    """Check if pre-migration backup is enabled via AUTO_BACKUP env var."""
+    val = os.environ.get("AUTO_BACKUP", "true").lower().strip()
+    return val not in ("false", "0", "no", "off")
+
+
+def _get_alembic_head() -> str | None:
+    """Get the current Alembic head revision from the migration scripts."""
+    try:
+        from alembic.config import Config
+        from alembic.script import ScriptDirectory
+
+        alembic_cfg = Config(str(_backend_path() / "alembic.ini"))
+        script = ScriptDirectory.from_config(alembic_cfg)
+        head = script.get_current_head()
+        return head
+    except Exception as exc:
+        _log.warning("Could not determine Alembic head revision: %s", exc)
+        return None
+
+
+def _get_db_revision(database_url: str) -> str | None:
+    """Get the current Alembic revision stored in the database."""
+    try:
+        from sqlalchemy import create_engine, inspect, text
+
+        engine = create_engine(database_url)
+        with engine.connect() as conn:
+            # Check if alembic_version table exists
+            inspector = inspect(engine)
+            tables = inspector.get_table_names()
+            if "alembic_version" not in tables:
+                return None
+            result = conn.execute(text("SELECT version_num FROM alembic_version LIMIT 1"))
+            row = result.fetchone()
+            return row[0] if row else None
+    except Exception as exc:
+        _log.warning("Could not read DB revision: %s", exc)
+        return None
+
+
+def _create_pg_backup(database_url: str) -> str | None:
+    """Create a PostgreSQL backup before migration using pg_dump.
+
+    Returns the backup file path on success, None on failure.
+    """
+    backup_dir = _backend_path() / "backups" / "pre_migration"
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    backup_file = backup_dir / f"pre_migration_{timestamp}.sql"
+
+    try:
+        # Parse DATABASE_URL for pg_dump
+        # Format: postgresql://user:pass@host:port/dbname
+        from urllib.parse import urlparse
+
+        parsed = urlparse(database_url)
+        env = os.environ.copy()
+        if parsed.password:
+            env["PGPASSWORD"] = parsed.password
+
+        cmd = [
+            "pg_dump",
+            "-h", parsed.hostname or "localhost",
+            "-p", str(parsed.port or 5432),
+            "-U", parsed.username or "postgres",
+            "-d", parsed.path.lstrip("/"),
+            "-f", str(backup_file),
+            "--no-owner",
+            "--no-acl",
+        ]
+        result = subprocess.run(cmd, env=env, capture_output=True, text=True, timeout=120)
+        if result.returncode == 0:
+            _log.info("Pre-migration backup created: %s", backup_file)
+            return str(backup_file)
+        else:
+            _log.warning("pg_dump failed (rc=%d): %s", result.returncode, result.stderr)
+            return None
+    except FileNotFoundError:
+        _log.warning("pg_dump not found — skipping PostgreSQL backup")
+        return None
+    except Exception as exc:
+        _log.warning("Pre-migration backup failed: %s", exc)
+        return None
+
+
+def _create_dbf_backup(db_path: str) -> str | None:
+    """Create a DBF backup by copying the data directory.
+
+    Returns the backup directory path on success, None on failure.
+    """
+    if not os.path.isdir(db_path):
+        _log.warning("DBF path does not exist, skipping backup: %s", db_path)
+        return None
+
+    backup_base = _backend_path() / "backups" / "pre_migration"
+    backup_base.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    backup_dir = backup_base / f"dbf_pre_migration_{timestamp}"
+
+    try:
+        shutil.copytree(db_path, str(backup_dir))
+        _log.info("Pre-migration DBF backup created: %s", backup_dir)
+        return str(backup_dir)
+    except Exception as exc:
+        _log.warning("DBF backup failed: %s", exc)
+        return None
+
+
+def _run_alembic_upgrade() -> list[str]:
+    """Run Alembic upgrade to head. Returns list of applied revision IDs."""
+    applied = []
+    try:
+        from alembic import command
+        from alembic.config import Config
+
+        alembic_cfg = Config(str(_backend_path() / "alembic.ini"))
+        # Ensure DATABASE_URL is in the config
+        database_url = os.environ.get("DATABASE_URL")
+        if database_url:
+            alembic_cfg.set_main_option("sqlalchemy.url", database_url)
+
+        # Capture which revisions are applied
+        from alembic.script import ScriptDirectory
+
+        script = ScriptDirectory.from_config(alembic_cfg)
+        current_rev = _get_db_revision(
+            alembic_cfg.get_main_option("sqlalchemy.url") or database_url or ""
+        )
+
+        # Run upgrade
+        command.upgrade(alembic_cfg, "head")
+
+        # Determine which revisions were applied
+        new_rev = _get_db_revision(
+            alembic_cfg.get_main_option("sqlalchemy.url") or database_url or ""
+        )
+        if current_rev != new_rev:
+            # Walk from current to head to list applied revisions
+            for rev in script.walk_revisions(new_rev, current_rev):
+                if rev.revision != current_rev:
+                    applied.append(rev.revision)
+
+        _log.info("Alembic upgrade complete. Applied %d revision(s): %s",
+                   len(applied), applied)
+    except Exception as exc:
+        _log.error("Alembic upgrade failed: %s", exc, exc_info=True)
+        raise
+
+    return applied
+
+
+def _get_dbf_schema_version(db_path: str) -> str | None:
+    """Read the schema version from a .sp5_version file in the DBF directory."""
+    version_file = os.path.join(db_path, ".sp5_schema_version")
+    if os.path.exists(version_file):
+        try:
+            return Path(version_file).read_text().strip()
+        except Exception:
+            return None
+    return None
+
+
+def _set_dbf_schema_version(db_path: str, version: str) -> None:
+    """Write the schema version to a .sp5_version file in the DBF directory."""
+    version_file = os.path.join(db_path, ".sp5_schema_version")
+    try:
+        Path(version_file).write_text(version)
+    except Exception as exc:
+        _log.warning("Could not write DBF schema version: %s", exc)
+
+
+# Current DBF schema version — bump when adding new DBF schema extensions
+DBF_SCHEMA_VERSION = "1.0.0"
+
+# DBF schema extensions registry: version → callable
+# Each callable receives (db_path: str) and applies its schema changes.
+_DBF_EXTENSIONS: dict[str, list] = {
+    # Example for future use:
+    # "1.1.0": [_add_new_dbf_field],
+}
+
+
+def _apply_dbf_extensions(db_path: str, current_version: str | None) -> list[str]:
+    """Apply pending DBF schema extensions.
+
+    Returns list of version strings that were applied.
+    """
+    from packaging.version import InvalidVersion, Version
+
+    applied = []
+    try:
+        current = Version(current_version) if current_version else Version("0.0.0")
+    except InvalidVersion:
+        current = Version("0.0.0")
+
+    for ver_str, funcs in sorted(_DBF_EXTENSIONS.items()):
+        try:
+            ver = Version(ver_str)
+        except InvalidVersion:
+            continue
+        if ver > current:
+            _log.info("Applying DBF schema extension v%s...", ver_str)
+            for func in funcs:
+                func(db_path)
+            applied.append(ver_str)
+
+    if applied:
+        _set_dbf_schema_version(db_path, DBF_SCHEMA_VERSION)
+        _log.info("DBF schema updated to v%s. Applied: %s", DBF_SCHEMA_VERSION, applied)
+
+    return applied
+
+
+class MigrationResult:
+    """Result of a startup migration run."""
+
+    def __init__(self):
+        self.backend: str = ""
+        self.skipped: bool = False
+        self.skip_reason: str = ""
+        self.backup_path: str | None = None
+        self.migrations_applied: list[str] = []
+        self.previous_version: str | None = None
+        self.current_version: str | None = None
+        self.error: str | None = None
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+    @property
+    def had_migrations(self) -> bool:
+        return len(self.migrations_applied) > 0
+
+    def to_dict(self) -> dict:
+        return {
+            "backend": self.backend,
+            "skipped": self.skipped,
+            "skip_reason": self.skip_reason,
+            "backup_path": self.backup_path,
+            "migrations_applied": self.migrations_applied,
+            "previous_version": self.previous_version,
+            "current_version": self.current_version,
+            "error": self.error,
+            "success": self.success,
+        }
+
+    def __repr__(self) -> str:
+        if self.skipped:
+            return f"MigrationResult(skipped={self.skip_reason})"
+        if self.error:
+            return f"MigrationResult(error={self.error})"
+        return (
+            f"MigrationResult(backend={self.backend}, "
+            f"applied={len(self.migrations_applied)}, "
+            f"{self.previous_version} → {self.current_version})"
+        )
+
+
+def run_startup_migration() -> MigrationResult:
+    """Run automatic database migration on startup.
+
+    This is the main entry point. Call once during application lifespan startup.
+
+    Returns:
+        MigrationResult with details about what happened.
+    """
+    result = MigrationResult()
+
+    # Check if auto-migration is enabled
+    if not _is_auto_migrate_enabled():
+        result.skipped = True
+        result.skip_reason = "AUTO_MIGRATE=false"
+        _log.info("Auto-migration disabled (AUTO_MIGRATE=false)")
+        return result
+
+    from .db_config import BACKEND_POSTGRESQL, get_db_backend
+
+    backend = get_db_backend()
+    result.backend = backend
+
+    if backend == BACKEND_POSTGRESQL:
+        return _migrate_postgresql(result)
+    else:
+        return _migrate_dbf(result)
+
+
+def _migrate_postgresql(result: MigrationResult) -> MigrationResult:
+    """Handle PostgreSQL auto-migration via Alembic."""
+    from .db_config import get_database_url
+
+    database_url = get_database_url()
+    if not database_url:
+        result.skipped = True
+        result.skip_reason = "DATABASE_URL not set"
+        _log.warning("PostgreSQL backend but DATABASE_URL not set — skipping migration")
+        return result
+
+    # Get current DB revision
+    current_rev = _get_db_revision(database_url)
+    result.previous_version = current_rev
+
+    # Get target (head) revision
+    head_rev = _get_alembic_head()
+
+    if current_rev == head_rev and current_rev is not None:
+        result.current_version = current_rev
+        result.skipped = True
+        result.skip_reason = "already at head"
+        _log.info("Database already at head revision (%s) — no migration needed", current_rev)
+        return result
+
+    _log.info("Migration needed: DB=%s → head=%s", current_rev or "(empty)", head_rev)
+
+    # Create backup before migration
+    if _is_auto_backup_enabled():
+        result.backup_path = _create_pg_backup(database_url)
+
+    # Run Alembic upgrade
+    try:
+        applied = _run_alembic_upgrade()
+        result.migrations_applied = applied
+        result.current_version = _get_db_revision(database_url)
+        _log.info(
+            "PostgreSQL migration complete: %s → %s (%d revision(s))",
+            result.previous_version or "(empty)",
+            result.current_version,
+            len(applied),
+        )
+    except Exception as exc:
+        result.error = str(exc)
+        _log.error("PostgreSQL migration failed: %s", exc)
+
+    return result
+
+
+def _migrate_dbf(result: MigrationResult) -> MigrationResult:
+    """Handle DBF schema extensions."""
+    db_path = os.environ.get(
+        "SP5_DB_PATH",
+        os.path.join(os.path.dirname(__file__), "..", "..", "..", "sp5_db", "Daten"),
+    )
+    db_path = os.path.normpath(db_path)
+
+    if not os.path.isdir(db_path):
+        result.skipped = True
+        result.skip_reason = f"DBF path not found: {db_path}"
+        _log.warning("DBF directory not found: %s — skipping migration", db_path)
+        return result
+
+    current_version = _get_dbf_schema_version(db_path)
+    result.previous_version = current_version
+
+    if current_version == DBF_SCHEMA_VERSION:
+        result.current_version = current_version
+        result.skipped = True
+        result.skip_reason = "already at current version"
+        _log.info("DBF schema already at v%s — no migration needed", current_version)
+        return result
+
+    _log.info("DBF migration needed: %s → %s",
+              current_version or "(none)", DBF_SCHEMA_VERSION)
+
+    # Create backup before migration
+    if _is_auto_backup_enabled():
+        result.backup_path = _create_dbf_backup(db_path)
+
+    # Apply extensions
+    try:
+        applied = _apply_dbf_extensions(db_path, current_version)
+        result.migrations_applied = applied
+
+        # Even if no extensions to apply, stamp the version
+        _set_dbf_schema_version(db_path, DBF_SCHEMA_VERSION)
+        result.current_version = DBF_SCHEMA_VERSION
+
+        _log.info(
+            "DBF migration complete: %s → %s (%d extension(s))",
+            result.previous_version or "(none)",
+            result.current_version,
+            len(applied),
+        )
+    except Exception as exc:
+        result.error = str(exc)
+        _log.error("DBF migration failed: %s", exc)
+
+    return result

sp5lib/color_utils.py

@@ -0,0 +1,26 @@
+"""Color conversion utilities for Schichtplaner5 colors (stored as Windows BGR integers)."""
+
+
+def bgr_to_hex(bgr: int) -> str:
+    """Convert Windows BGR integer to HTML hex color string."""
+    if not isinstance(bgr, int) or bgr < 0:
+        return "#FFFFFF"
+    b = (bgr >> 16) & 0xFF
+    g = (bgr >> 8) & 0xFF
+    r = bgr & 0xFF
+    return f"#{r:02X}{g:02X}{b:02X}"
+
+
+def bgr_to_rgb(bgr: int) -> tuple:
+    """Convert Windows BGR integer to (R, G, B) tuple."""
+    b = (bgr >> 16) & 0xFF
+    g = (bgr >> 8) & 0xFF
+    r = bgr & 0xFF
+    return (r, g, b)
+
+
+def is_light_color(bgr: int) -> bool:
+    """Returns True if the color is light (use dark text on it)."""
+    r, g, b = bgr_to_rgb(bgr)
+    luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+    return luminance > 0.5