pycontrol-gui 3.0.0a1__py3-none-any.whl

pycontrol_gui/__init__.py

@@ -0,0 +1,15 @@
+"""Qt frontend package for pycontrol-core.
+
+The stable package-level surface is intentionally small. GUI widgets,
+controllers, and workspace models are application internals unless documented
+in the public integration guides.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pycontrol-gui")
+except PackageNotFoundError:  # pragma: no cover - editable tree before install.
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

pycontrol_gui/__main__.py

@@ -0,0 +1,5 @@
+from pycontrol_gui.app import launch_gui
+
+
+if __name__ == "__main__":
+    raise SystemExit(launch_gui())

pycontrol_gui/app.py

@@ -0,0 +1,102 @@
+"""QApplication bootstrap."""
+
+from __future__ import annotations
+
+import logging
+import sys
+import threading
+import traceback
+from pathlib import Path
+from types import TracebackType
+
+from PySide6.QtCore import QObject, Qt, Signal
+from PySide6.QtGui import QFont
+from PySide6.QtWidgets import QApplication
+
+from pycontrol.workspace import Workspace
+from pycontrol_gui.error_logging import configure_error_logging
+from pycontrol_gui.main_window import MainWindow
+from pycontrol_gui.resources import icon
+
+logger = logging.getLogger(__name__)
+
+
+class _ExceptionNotifier(QObject):
+    message = Signal(str)
+
+
+def launch_gui(start_path: str | Path | None = None) -> int:
+    resolved_start_path = _resolve_start_path(start_path)
+    configure_error_logging(resolved_start_path)
+    app = QApplication.instance()
+    created_here = app is None
+    if app is None:
+        app = QApplication(sys.argv)
+
+    app.setStyle("Fusion")
+    app.setWindowIcon(icon("logo"))
+    app.setApplicationDisplayName("pyControl GUI")
+    app.setAttribute(Qt.ApplicationAttribute.AA_DontShowIconsInMenus, False)
+
+    font = QFont()
+    font.setPixelSize(13)
+    app.setFont(font)
+
+    window = MainWindow(start_path=resolved_start_path)
+    _install_excepthook(window)
+    window.show()
+    if created_here:
+        return app.exec()
+    return 0
+
+
+def _resolve_start_path(start_path: str | Path | None = None) -> Path | None:
+    if start_path is not None:
+        return Path(start_path).expanduser()
+    cli_path = _workspace_path_from_argv(sys.argv[1:])
+    if cli_path is not None:
+        return cli_path
+    try:
+        if Workspace.discover(Path.cwd()) is not None:
+            return Path.cwd()
+    except OSError:
+        return None
+    return None
+
+
+def _workspace_path_from_argv(args: list[str]) -> Path | None:
+    for arg in args:
+        if not arg or arg.startswith("-"):
+            continue
+        return Path(arg).expanduser()
+    return None
+
+
+def _install_excepthook(window: MainWindow) -> None:
+    notifier = _ExceptionNotifier(window)
+    notifier.message.connect(window.run_task_tab.on_error_message, Qt.ConnectionType.QueuedConnection)
+    window._exception_notifier = notifier  # type: ignore[attr-defined]
+
+    def _forward_exception_to_ui(prefix: str, message: str) -> None:
+        try:
+            notifier.message.emit(f"{prefix}\n{message}")
+        except Exception:
+            logger.exception("Failed to forward exception text to Run task tab.")
+
+    def excepthook(ex_type: type[BaseException], ex_value: BaseException, ex_traceback: TracebackType | None) -> None:
+        logger.error("Uncaught exception in GUI thread.", exc_info=(ex_type, ex_value, ex_traceback))
+        message = "".join(traceback.format_exception(ex_type, ex_value, ex_traceback))
+        _forward_exception_to_ui("Uncaught exception:", message)
+
+    def thread_excepthook(args: threading.ExceptHookArgs) -> None:
+        thread_name = args.thread.name if args.thread is not None else "<unknown>"
+        logger.error(
+            "Uncaught exception in thread %s.",
+            thread_name,
+            exc_info=(args.exc_type, args.exc_value, args.exc_traceback),
+        )
+        message = "".join(traceback.format_exception(args.exc_type, args.exc_value, args.exc_traceback))
+        _forward_exception_to_ui(f"Uncaught thread exception ({thread_name}):", message)
+
+    sys.excepthook = excepthook
+    threading.excepthook = thread_excepthook

pycontrol_gui/bus_adapter.py

@@ -0,0 +1,54 @@
+"""Qt signal bridge for pycontrol bus events."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QObject, Signal
+
+from pycontrol.bus.events import (
+    Error,
+    EventsBatch,
+    SessionEnded,
+    SessionStarted,
+    TaskStatusUpdated,
+    VariableChanged,
+    Warning,
+)
+
+
+class QtBusAdapter(QObject):
+    """Subscriber implementation that re-emits typed events as Qt signals.
+
+    Core calls these methods on the board pump thread. The signal emissions also
+    originate from that thread; GUI safety depends on connecting them to
+    GUI-thread ``QObject`` receivers so Qt delivers the calls as queued
+    cross-thread signals.
+    """
+
+    session_started = Signal(object)  # SessionStarted
+    session_ended = Signal(object)  # SessionEnded
+    events_batch = Signal(object)  # EventsBatch
+    variable_changed = Signal(object)  # VariableChanged
+    task_status_updated = Signal(object)  # TaskStatusUpdated
+    warning = Signal(object)  # Warning
+    error = Signal(object)  # Error
+
+    def on_session_start(self, ev: SessionStarted) -> None:
+        self.session_started.emit(ev)
+
+    def on_data(self, batch: EventsBatch) -> None:
+        self.events_batch.emit(batch)
+
+    def on_variable_changed(self, ev: VariableChanged) -> None:
+        self.variable_changed.emit(ev)
+
+    def on_task_status_updated(self, ev: TaskStatusUpdated) -> None:
+        self.task_status_updated.emit(ev)
+
+    def on_warning(self, ev: Warning) -> None:
+        self.warning.emit(ev)
+
+    def on_error(self, ev: Error) -> None:
+        self.error.emit(ev)
+
+    def on_session_end(self, ev: SessionEnded) -> None:
+        self.session_ended.emit(ev)

pycontrol_gui/error_logging.py

@@ -0,0 +1,134 @@
+"""Diagnostic logging bootstrap for the Qt frontend."""
+
+from __future__ import annotations
+
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from pycontrol.workspace import Workspace
+
+ERROR_LOG_FILENAME = "ErrorLog.txt"
+_FILE_HANDLER_NAME = "pycontrol_gui.error_file"
+_STREAM_HANDLER_NAME = "pycontrol_gui.stderr"
+_MAX_BYTES = 1_000_000
+_BACKUP_COUNT = 5
+
+_ACTIVE_ERROR_LOG_PATH: Path | None = None
+
+
+def _workspace_root(start_path: str | Path | None) -> Path | None:
+    try:
+        workspace = Workspace.discover(start_path)
+    except Exception:
+        return None
+    if workspace is None:
+        return None
+    return workspace.root
+
+
+def _candidate_log_dirs(start_path: str | Path | None) -> tuple[Path, ...]:
+    candidates: list[Path] = []
+    workspace_root = _workspace_root(start_path)
+    if workspace_root is not None:
+        candidates.append(workspace_root)
+    candidates.append(Path.home() / ".pycontrol-gui" / "logs")
+    candidates.append(Path.cwd())
+    return tuple(candidates)
+
+
+def _choose_log_path(start_path: str | Path | None) -> Path:
+    for directory in _candidate_log_dirs(start_path):
+        try:
+            directory.mkdir(parents=True, exist_ok=True)
+            return directory / ERROR_LOG_FILENAME
+        except OSError:
+            continue
+    return Path.cwd() / ERROR_LOG_FILENAME
+
+
+def _upsert_file_handler(root_logger: logging.Logger, target_path: Path, formatter: logging.Formatter) -> None:
+    existing = next((h for h in root_logger.handlers if getattr(h, "name", "") == _FILE_HANDLER_NAME), None)
+    if isinstance(existing, RotatingFileHandler):
+        if Path(existing.baseFilename) == target_path:
+            existing.setLevel(logging.ERROR)
+            existing.setFormatter(formatter)
+            return
+        root_logger.removeHandler(existing)
+        existing.close()
+    elif existing is not None:
+        root_logger.removeHandler(existing)
+        existing.close()
+
+    file_handler = RotatingFileHandler(
+        target_path, maxBytes=_MAX_BYTES, backupCount=_BACKUP_COUNT, encoding="utf-8", delay=True
+    )
+    file_handler.set_name(_FILE_HANDLER_NAME)
+    file_handler.setLevel(logging.ERROR)
+    file_handler.setFormatter(formatter)
+    root_logger.addHandler(file_handler)
+
+
+def _upsert_stream_handler(root_logger: logging.Logger, formatter: logging.Formatter) -> None:
+    existing = next((h for h in root_logger.handlers if getattr(h, "name", "") == _STREAM_HANDLER_NAME), None)
+    if isinstance(existing, logging.StreamHandler):
+        existing.setLevel(logging.WARNING)
+        existing.setFormatter(formatter)
+        return
+    if existing is not None:
+        root_logger.removeHandler(existing)
+        existing.close()
+
+    stream_handler = logging.StreamHandler()
+    stream_handler.set_name(_STREAM_HANDLER_NAME)
+    stream_handler.setLevel(logging.WARNING)
+    stream_handler.setFormatter(formatter)
+    root_logger.addHandler(stream_handler)
+
+
+def configure_error_logging(start_path: str | Path | None = None) -> Path:
+    """Configure process-wide GUI diagnostics and return active log path.
+
+    This mutates the root logger so uncaught errors from worker threads, plugin
+    imports, and Qt-facing callbacks land in the same rotating diagnostics file.
+    Repeated calls update the handlers installed by pycontrol-gui rather than
+    stacking duplicate handlers.
+    """
+    global _ACTIVE_ERROR_LOG_PATH
+
+    target_path = _choose_log_path(start_path)
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+    root_logger = logging.getLogger()
+    # Keep INFO+ records available to stderr while persisting only ERROR+ to file.
+    root_logger.setLevel(logging.INFO)
+    _upsert_file_handler(root_logger, target_path, formatter)
+    _upsert_stream_handler(root_logger, formatter)
+    _ACTIVE_ERROR_LOG_PATH = target_path
+    return target_path
+
+
+def get_error_log_path() -> Path:
+    """Return the currently configured error-log path."""
+    global _ACTIVE_ERROR_LOG_PATH
+    if _ACTIVE_ERROR_LOG_PATH is None:
+        _ACTIVE_ERROR_LOG_PATH = _choose_log_path(None)
+    return _ACTIVE_ERROR_LOG_PATH
+
+
+def clear_error_log(path: Path | None = None) -> Path:
+    """Truncate the active diagnostics file and keep handlers alive."""
+    target = path if path is not None else get_error_log_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    for handler in logging.getLogger().handlers:
+        if not isinstance(handler, logging.FileHandler):
+            continue
+        base = getattr(handler, "baseFilename", None)
+        if base is None:
+            continue
+        if Path(base) == target:
+            handler.flush()
+    target.write_text("", encoding="utf-8")
+    return target
+
+
+__all__ = ["ERROR_LOG_FILENAME", "clear_error_log", "configure_error_logging", "get_error_log_path"]

pycontrol_gui/experiment_extensions.py

@@ -0,0 +1,39 @@
+"""Shared helpers for GUI experiment extension loading."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pycontrol.config import Settings
+from pycontrol.extension import ExperimentExtension
+from pycontrol.extension.loader import instantiate_experiment_extension
+
+
+def resolve_experiment_extension_path(directory: str | Path | None, stem: str) -> Path | None:
+    if directory in (None, ""):
+        return None
+    candidate = Path(directory) / f"{stem}.py"
+    return candidate if candidate.exists() else None
+
+
+def load_experiment_extension(
+    path: Path, *, settings: Settings | None = None, run_control: object | None = None
+) -> ExperimentExtension:
+    extension = instantiate_experiment_extension(path)
+    if settings is not None:
+        extension_settings = dict(settings.extensions.experiment_extensions.get(path.stem, {}))
+        extension.configure_settings(extension_settings, settings)
+    if run_control is not None:
+        extension.attach_run_control(run_control)
+    return extension
+
+
+def validate_experiment_extension(path: Path) -> str | None:
+    try:
+        load_experiment_extension(path)
+    except Exception as exc:  # noqa: BLE001 - user plugin diagnostics.
+        return str(exc)
+    return None
+
+
+__all__ = ["load_experiment_extension", "resolve_experiment_extension_path", "validate_experiment_extension"]