subjectdb 1.0.0__py3-none-any.whl

subjectdb/__init__.py

@@ -0,0 +1,13 @@
+"""SubjectDB: register study participants across research projects.
+
+The package is split in two layers:
+
+* ``vocabulary``, ``db``, ``upgrade`` and ``excel`` hold all rules and all
+  database work. They never import Qt, so they can be tested and scripted alone.
+* ``gui`` is the PySide6 interface. It never talks to SQLite directly; every
+  read and write goes through :class:`subjectdb.db.Registry`.
+
+``app`` glues both together (command line, start-up checks, main window).
+"""
+
+__version__ = "1.0.0"

subjectdb/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m subjectdb`` (researcher) and ``python -m subjectdb --pi`` (PI)."""
+
+import sys
+
+from subjectdb.app import main
+
+sys.exit(main())

subjectdb/app.py

@@ -0,0 +1,305 @@
+"""Start-up of SubjectDB: command line, installation check, Qt application, error handling.
+
+    subjectdb             researcher mode            subjectdb-pi           PI mode
+    --data-dir PATH       use this data folder. Otherwise: $SUBJECTDB_DATA_DIR, then the folder
+                          remembered from last time, then a dialog asks ("Where are your databases?")
+    --check               print an installation check without opening a window: Python, SQLite,
+                          Qt, the display, missing system libraries, access to each database file
+    --version             print the version and stop
+
+Qt is imported only when a window is needed, so --check and --version work even when the Qt
+libraries cannot be loaded. Unexpected errors are logged to a file and shown in a dialog.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import logging.handlers
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import traceback
+from pathlib import Path
+
+from . import __version__
+
+LOG = logging.getLogger("subjectdb")
+MIN_SQLITE = (3, 27)
+LIBS = Path.home() / "subjectdb-libs"  # where the no-admin fix unpacks missing libraries
+LAUNCHER = """#!/bin/sh
+export LD_LIBRARY_PATH="$HOME/subjectdb-libs/usr/lib/x86_64-linux-gnu${{LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}}"
+exec {command} "$@\""""
+# Debian package that provides a library Qt's X11 plugin may need (for the no-admin fix).
+DEBIAN_PACKAGES = {
+    "libxcb-cursor.so.0": "libxcb-cursor0", "libxkbcommon-x11.so.0": "libxkbcommon-x11-0",
+    "libxkbcommon.so.0": "libxkbcommon0", "libxcb-icccm.so.4": "libxcb-icccm4", "libxcb-image.so.0": "libxcb-image0",
+    "libxcb-keysyms.so.1": "libxcb-keysyms1", "libxcb-render-util.so.0": "libxcb-render-util0",
+    "libxcb-shape.so.0": "libxcb-shape0", "libxcb-randr.so.0": "libxcb-randr0", "libxcb-xkb.so.1": "libxcb-xkb1",
+    "libxcb-xinerama.so.0": "libxcb-xinerama0", "libEGL.so.1": "libegl1", "libGL.so.1": "libgl1",
+    "libOpenGL.so.0": "libopengl0", "libfontconfig.so.1": "libfontconfig1", "libdbus-1.so.3": "libdbus-1-3",
+}
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="subjectdb", description="Register study participants across projects.")
+    parser.add_argument("--pi", action="store_true", help="start in PI mode (same as the subjectdb-pi command)")
+    parser.add_argument("--data-dir", type=Path, help="folder with the three database files")
+    parser.add_argument("--check", action="store_true", help="check the installation and print what to fix")
+    parser.add_argument("--version", action="version", version=f"SubjectDB {__version__}")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point of ``subjectdb`` (researcher mode; --pi switches to PI mode)."""
+    return run(argv, pi=False)
+
+
+def main_pi(argv: list[str] | None = None) -> int:
+    """Entry point of ``subjectdb-pi``."""
+    return run(argv, pi=True)
+
+
+def run(argv: list[str] | None, *, pi: bool) -> int:
+    args = parse_args(argv)
+    pi = pi or args.pi
+    if args.check:
+        return check(args.data_dir, pi)
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError as exc:
+        print(f"SubjectDB cannot load Qt: {exc}\nRun  subjectdb --check  to see what is missing.", file=sys.stderr)
+        return 1
+    app = QApplication.instance() or QApplication(sys.argv[:1])
+    app.setApplicationName("SubjectDB")
+    app.setOrganizationName("SubjectDB")
+    app.setApplicationVersion(__version__)
+    log_file = setup_logging()
+    install_excepthook(log_file)
+    from .gui import theme
+    from .gui.main_window import environment_folder, run_window
+
+    theme.apply(app)
+    return run_window(pi, args.data_dir.expanduser() if args.data_dir else environment_folder())
+
+
+# --- Logging and unexpected errors --------------------------------------------------------------
+
+
+def log_folder() -> Path:
+    from PySide6.QtCore import QStandardPaths
+
+    folder = Path(QStandardPaths.writableLocation(QStandardPaths.StandardLocation.AppLocalDataLocation))
+    return folder if str(folder) not in ("", ".") else Path.home() / ".subjectdb"
+
+
+def setup_logging() -> Path:
+    """Errors go to <user data folder>/subjectdb.log (never personal data: only technical details)."""
+    folder = log_folder()
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / "subjectdb.log"
+    handler = logging.handlers.RotatingFileHandler(path, maxBytes=1_000_000, backupCount=2, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    LOG.addHandler(handler)
+    LOG.setLevel(logging.INFO)
+    LOG.info("SubjectDB %s started (Python %s)", __version__, platform.python_version())
+    return path
+
+
+def install_excepthook(log_file: Path) -> None:
+    """Show unexpected errors in a dialog (and log them) instead of dying silently."""
+
+    def hook(kind, exc, tb):
+        if issubclass(kind, KeyboardInterrupt):
+            sys.__excepthook__(kind, exc, tb)
+            return
+        LOG.error("Unexpected error\n%s", "".join(traceback.format_exception(kind, exc, tb)))
+        try:
+            from PySide6.QtWidgets import QApplication
+
+            from . import db
+            from .gui import widgets
+
+            widgets.inform(QApplication.activeWindow(), "Something went wrong",
+                           f"{db.friendly_error(exc)}<br><br>Your data is safe: a save either happens completely or "
+                           f"not at all. Technical details are in <b>{log_file}</b>.", tone="danger")
+        except Exception:  # the dialog itself failed: at least print
+            traceback.print_exception(kind, exc, tb)
+
+    sys.excepthook = hook
+
+
+# --- subjectdb --check --------------------------------------------------------------------------
+
+
+class _Report:
+    """Collects the lines of the installation check; the exit code is the number of failures (max 1)."""
+
+    def __init__(self):
+        self.failures = 0
+
+    def line(self, status: str, text: str, fix: str = "") -> None:
+        if status or text:
+            print(f"  {status:<5} {text}")
+        for fix_line in fix.splitlines():
+            print(f"        {fix_line}")
+        if status == "FAIL":
+            self.failures += 1
+
+
+def _missing_libraries(pyside_dir: Path) -> list[str] | None:
+    """Libraries that Qt's X11 plugin cannot find (ldd), or None when that cannot be checked."""
+    plugin = pyside_dir / "Qt" / "plugins" / "platforms" / "libqxcb.so"
+    if not plugin.is_file() or not shutil.which("ldd"):
+        return None
+    try:
+        result = subprocess.run(["ldd", str(plugin)], capture_output=True, text=True, timeout=20, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return sorted({m.group(1) for m in re.finditer(r"^\s*(\S+) => not found", result.stdout, re.M)})
+
+
+def _library_fix(missing: list[str], pi: bool) -> str:
+    """How to get the missing libraries: from IT, or unpacked into ~/subjectdb-libs without admin rights."""
+    packages = sorted({DEBIAN_PACKAGES[lib] for lib in missing if lib in DEBIAN_PACKAGES})
+    command = Path(sys.executable).parent / ("subjectdb-pi" if pi else "subjectdb")
+    lines = []
+    if packages:
+        lines += [f"Ask IT to install: {' '.join(packages)}", "Or, without admin rights:",
+                  f"  cd /tmp && apt-get download {' '.join(packages)}",
+                  *(f"  dpkg -x {package}_*.deb ~/subjectdb-libs" for package in packages),
+                  "then start SubjectDB (and this check) through this launcher script:",
+                  *(f"  {line}" for line in LAUNCHER.format(command=command).splitlines())]
+    lines += [f"For {lib}: ask IT which Debian package provides it (apt-file search {lib})."
+              for lib in missing if lib not in DEBIAN_PACKAGES]
+    if LIBS.is_dir() and str(LIBS) not in os.environ.get("LD_LIBRARY_PATH", ""):
+        lines.append("~/subjectdb-libs exists, but this run did not use it: start it through the launcher script.")
+    return "\n".join(lines)
+
+
+def _folder_to_check(cli: Path | None) -> tuple[Path | None, str]:
+    if cli:
+        return cli.expanduser(), "from --data-dir"
+    if os.environ.get("SUBJECTDB_DATA_DIR"):
+        return Path(os.environ["SUBJECTDB_DATA_DIR"]).expanduser(), "from SUBJECTDB_DATA_DIR"
+    try:
+        from PySide6.QtCore import QSettings
+
+        remembered = QSettings(QSettings.Format.IniFormat, QSettings.Scope.UserScope, "SubjectDB",
+                               "SubjectDB").value("data_folder")
+        if remembered:
+            return Path(str(remembered)), "remembered from the last start"
+    except ImportError:
+        pass
+    return None, ""
+
+
+def check(data_dir: Path | None, pi: bool) -> int:
+    """Print what works and what to fix. Needs no display; never changes anything."""
+    report = _Report()
+    print(f"SubjectDB {__version__} – installation check{' (PI mode)' if pi else ''}\n")
+    version = sys.version_info
+    report.line("OK" if version >= (3, 10) else "FAIL", f"Python {platform.python_version()} ({sys.executable})",
+                "" if version >= (3, 10) else "SubjectDB needs Python 3.10 or newer: python3.11 -m venv …")
+    from . import db
+
+    sqlite = tuple(int(x) for x in db.sqlite_version().split(".")[:2])
+    report.line("OK" if sqlite >= MIN_SQLITE else "FAIL", f"SQLite {db.sqlite_version()}",
+                "" if sqlite >= MIN_SQLITE else "SQLite 3.27 or newer is needed.")
+    try:
+        import openpyxl
+
+        report.line("OK", f"openpyxl {openpyxl.__version__} (Excel files)")
+    except ImportError:
+        report.line("FAIL", "openpyxl is missing", "pip install openpyxl")
+    try:
+        import PySide6
+        from PySide6.QtCore import qVersion
+
+        report.line("OK", f"PySide6 {PySide6.__version__} (Qt {qVersion()})")
+        pyside_dir = Path(PySide6.__file__).parent
+    except ImportError as exc:
+        report.line("FAIL", f"PySide6 cannot be loaded: {exc}", "pip install 'PySide6-Essentials>=6.8'")
+        pyside_dir = None
+    if pyside_dir:
+        try:
+            from PySide6 import QtGui, QtWidgets  # noqa: F401  (loads libGL, fontconfig, …)
+
+            report.line("OK", "Qt graphics libraries load")
+        except ImportError as exc:
+            lib = re.search(r"(lib[\w.+-]+\.so[\d.]*)", str(exc))
+            package = DEBIAN_PACKAGES.get(lib.group(1), "") if lib else ""
+            report.line("FAIL", f"Qt graphics libraries: {exc}",
+                        f"Ask IT to install {package}, or see 'Missing libraries' in databases.md." if package else
+                        "See 'Missing libraries' in databases.md.")
+    if sys.platform.startswith("linux"):
+        display = os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")
+        report.line("OK" if display else "FAIL", f"Display: {display}" if display else "No display found",
+                    "" if display else "Connect with  ssh -X user@server  (or -Y), or use the lab's remote desktop.")
+        missing = _missing_libraries(pyside_dir) if pyside_dir else None
+        if pyside_dir and missing is None:
+            report.line("WARN", "Qt's X11 plugin could not be checked (ldd or the plugin file is missing).")
+        elif missing:
+            for lib in missing:
+                report.line("FAIL", f"Qt needs {lib}, which is not installed.")
+            report.line("", "", _library_fix(missing, pi))
+        elif pyside_dir:
+            report.line("OK", "Qt's X11 plugin finds all its libraries")
+    folder, source = _folder_to_check(data_dir)
+    print()
+    if folder is None:
+        report.line("WARN", "No data folder given, so the access to the databases was not checked.",
+                    "Run the check again with  --data-dir /path/to/the/database/folder")
+    else:
+        _check_folder(report, folder, source, pi)
+    if report.failures:
+        print(f"\n{report.failures} problem{'s' if report.failures > 1 else ''} found: see the lines marked FAIL.")
+    else:
+        print("\nAll checks passed." if folder else "\nNo problems found, but the data folder was not checked.")
+    return 1 if report.failures else 0
+
+
+def _check_folder(report: _Report, folder: Path, source: str, pi: bool) -> None:
+    from . import db
+
+    if not folder.is_dir():
+        report.line("FAIL", f"Data folder {folder} ({source}) does not exist.",
+                    "Check the path, or choose another one.")
+        return
+    state = db.inspect_folder(folder)
+    report.line("OK", f"Data folder {folder} ({source})")
+    if state.no_access:
+        report.line("FAIL", "You may not look inside this folder.", db.NO_ACCESS)
+        return
+    report.line("OK" if state.folder_writable else "FAIL", "The folder is writable (SQLite writes a journal file next "
+                "to the databases)" if state.folder_writable else "You cannot create files in this folder.",
+                "" if state.folder_writable else "Ask your PI: the folder needs group write permission (chmod g+w).")
+    for name in db.DB_FILES:
+        if not state.present[name]:
+            report.line("WARN" if name == db.GENERAL_DB else "FAIL", f"{name} is missing",
+                        "The PI app creates it at its next save." if name == db.GENERAL_DB else "Wrong folder?")
+            continue
+        if not state.readable[name]:
+            report.line("FAIL", f"{name}: you may not read it",
+                        "A permission problem, not a damaged file: ask your PI to fix the file's group and mode "
+                        "(see “Permissions” in databases.md). Do not restore a backup.")
+            continue
+        version = state.versions[name]
+        status = "read and write" if state.writable[name] else "read only for you"
+        if name == db.PROJECT_DB and not state.writable[name]:
+            report.line("FAIL" if pi else "OK", f"{name}: {status}" + ("" if pi else " (normal for researchers)"),
+                        "PI mode needs write access to this file." if pi else "")
+        elif not state.writable[name] and name != db.PROJECT_DB:
+            report.line("FAIL", f"{name}: {status}", "Ask your PI to give the lab group write access (chmod g+w).")
+        else:
+            report.line("OK", f"{name}: {status}")
+        if name in state.errors:  # the sentence says what to do (restore only for a damaged file)
+            report.line("WARN" if name == db.GENERAL_DB else "FAIL", f"{name} cannot be opened",
+                        state.errors[name] + (" The PI app rebuilds this copy." if name == db.GENERAL_DB else ""))
+        elif version == 0:
+            report.line("WARN", f"{name} was made by the old app", "Open the PI app once to upgrade it.")
+        elif version is not None and version > db.SCHEMA_VERSION:
+            report.line("FAIL", f"{name} is from a newer SubjectDB", db.UPDATE_HINT)