py-data-engine 0.1.0__py3-none-any.whl

data_engine/ui/gui/support.py

@@ -0,0 +1,214 @@
+"""Mixin support methods for the GUI application shell."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from time import monotonic
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QWidget
+
+from data_engine.platform.workspace_models import authored_workspace_is_available
+from data_engine.ui.gui.dialogs import show_message_box, structured_error_content
+from data_engine.ui.gui.helpers import (
+    is_last_process_ui_window as helper_is_last_process_ui_window,
+)
+from data_engine.ui.gui.presenters import (
+    browse_workspace_collection_root_override as present_browse_workspace_collection_root_override,
+    create_docs_browser as present_create_docs_browser,
+    docs_build_dir as present_docs_build_dir,
+    force_shutdown_daemon as present_force_shutdown_daemon,
+    finish_docs_build as present_finish_docs_build,
+    initialize_docs_view as present_initialize_docs_view,
+    load_docs_page as present_load_docs_page,
+    provision_selected_workspace as present_provision_selected_workspace,
+    rebind_workspace_context as present_rebind_workspace_context,
+    refresh_workspace_visibility_panel as present_refresh_workspace_visibility_panel,
+    refresh_workspace_root_controls as present_refresh_workspace_root_controls,
+    reset_workspace_collection_root_override as present_reset_workspace_collection_root_override,
+    run_docs_build_worker as present_run_docs_build_worker,
+    save_workspace_collection_root_override as present_save_workspace_collection_root_override,
+    start_docs_build as present_start_docs_build,
+)
+from data_engine.ui.gui.surface import show_message_box_later as surface_show_message_box_later
+from data_engine.views.state import build_flow_summary
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+    from data_engine.views.models import QtFlowCard
+
+
+class GuiWindowSupportMixin:
+    """Shared window-support methods kept separate from the main GUI app shell."""
+
+    def _resolve_workspace_paths(
+        self: "DataEngineWindow",
+        *,
+        workspace_id: str | None = None,
+        workspace_collection_root: Path | None | object = ...,
+    ):
+        """Resolve workspace paths using the current machine-local collection-root override."""
+        if workspace_collection_root is ...:
+            workspace_collection_root = self.workspace_collection_root_override
+        return self.workspace_service.resolve_paths(
+            workspace_id=workspace_id,
+            workspace_collection_root=workspace_collection_root,
+        )
+
+    def _daemon_request(self: "DataEngineWindow", paths, payload, *, timeout: float = 0.0):
+        """Send one request to the local workspace daemon."""
+        return self.daemon_service.request(paths, payload, timeout=timeout)
+
+    def _is_daemon_live(self: "DataEngineWindow", paths) -> bool:
+        """Return whether the local workspace daemon is currently reachable."""
+        return self.daemon_service.is_live(paths)
+
+    def _daemon_client_error_type(self: "DataEngineWindow"):
+        """Return the daemon client error type used by this module."""
+        return self.daemon_service.client_error_type
+
+    def _unregister_client_session_and_check_for_shutdown(
+        self: "DataEngineWindow", *, purge_process_ui_sessions: bool
+    ) -> bool:
+        """Unregister this window's client session and report whether daemon shutdown is needed."""
+        from data_engine.ui.gui.helpers import unregister_client_session_and_check_for_shutdown as helper_unregister
+
+        return helper_unregister(self, purge_process_ui_sessions=purge_process_ui_sessions)
+
+    def _is_last_process_ui_window(self: "DataEngineWindow") -> bool:
+        """Return whether this is the last live GUI window in the current process."""
+        return helper_is_last_process_ui_window(self)
+
+    def _shutdown_daemon_on_close(self: "DataEngineWindow") -> None:
+        """Shut down the daemon as part of final GUI process teardown."""
+        from data_engine.ui.gui.helpers import shutdown_daemon_on_close as helper_shutdown
+
+        helper_shutdown(self)
+
+    def _wait_for_worker_threads(self: "DataEngineWindow", *, timeout_seconds: float) -> None:
+        """Join outstanding GUI worker threads during shutdown."""
+        from data_engine.ui.gui.helpers import wait_for_worker_threads as helper_wait
+
+        helper_wait(self, timeout_seconds=timeout_seconds)
+
+    def _register_worker_thread(self: "DataEngineWindow", thread) -> None:
+        """Track one GUI worker thread under the window-local lock."""
+        if not hasattr(self, "_worker_threads_lock") or not hasattr(self, "_worker_threads"):
+            return
+        with self._worker_threads_lock:
+            self._worker_threads.add(thread)
+
+    def _discard_worker_thread(self: "DataEngineWindow", thread) -> None:
+        """Stop tracking one GUI worker thread under the window-local lock."""
+        if not hasattr(self, "_worker_threads_lock") or not hasattr(self, "_worker_threads"):
+            return
+        with self._worker_threads_lock:
+            self._worker_threads.discard(thread)
+
+    def _worker_threads_snapshot(self: "DataEngineWindow") -> tuple:
+        """Return a stable snapshot of tracked GUI worker threads."""
+        if not hasattr(self, "_worker_threads_lock") or not hasattr(self, "_worker_threads"):
+            return ()
+        with self._worker_threads_lock:
+            return tuple(self._worker_threads)
+
+    def _switch_view(self: "DataEngineWindow", index: int) -> None:
+        self.view_stack.setCurrentIndex(index)
+        if hasattr(self, "workspace_counts_footer_label"):
+            self.workspace_counts_footer_label.setVisible(index == 0)
+
+    def _monotonic(self: "DataEngineWindow") -> float:
+        """Return the current monotonic clock value."""
+        return monotonic()
+
+    def _structured_error_content(self: "DataEngineWindow", text: str):
+        """Parse one developer-facing flow-module error into dialog sections when possible."""
+        return structured_error_content(text)
+
+    def _show_message_box(self: "DataEngineWindow", *, title: str, text: str, tone: str) -> None:
+        """Show one simple application dialog for info/error messages."""
+        show_message_box(self, title=title, text=text, tone=tone)
+
+    def _show_message_box_later(self: "DataEngineWindow", *, title: str, text: str, tone: str) -> None:
+        """Defer one application dialog until the current UI update cycle completes."""
+        surface_show_message_box_later(self, title=title, text=text, tone=tone)
+
+    def _docs_source_dir(self: "DataEngineWindow") -> Path:
+        """Return the authored Sphinx source directory."""
+        return self.workspace_paths.sphinx_source_dir
+
+    def _docs_build_dir(self: "DataEngineWindow") -> Path:
+        """Return the generated Sphinx HTML output directory."""
+        return present_docs_build_dir(self)
+
+    def _refresh_workspace_root_controls(self: "DataEngineWindow") -> None:
+        """Refresh local workspace-root override copy in the Settings view."""
+        present_refresh_workspace_root_controls(self)
+
+    def _rebind_workspace_context(self: "DataEngineWindow", *, workspace_id: str | None = None) -> None:
+        """Re-resolve paths and rebuild local UI state after workspace settings change."""
+        present_rebind_workspace_context(self, workspace_id=workspace_id)
+
+    def _save_workspace_collection_root_override(self: "DataEngineWindow") -> None:
+        """Persist one machine-local workspace collection root override."""
+        present_save_workspace_collection_root_override(self)
+
+    def _reset_workspace_collection_root_override(self: "DataEngineWindow") -> None:
+        """Clear the machine-local workspace collection root override."""
+        present_reset_workspace_collection_root_override(self)
+
+    def _browse_workspace_collection_root_override(self: "DataEngineWindow") -> None:
+        """Open a folder picker for the local workspace collection root override."""
+        present_browse_workspace_collection_root_override(self)
+
+    def _provision_selected_workspace(self: "DataEngineWindow") -> None:
+        """Provision the selected authored workspace without overwriting existing files."""
+        present_provision_selected_workspace(self)
+
+    def _force_shutdown_daemon(self: "DataEngineWindow") -> None:
+        """Force-stop the local workspace daemon for the selected workspace."""
+        present_force_shutdown_daemon(self)
+
+    def _refresh_workspace_visibility_panel(self: "DataEngineWindow") -> None:
+        """Refresh the read-only workspace visibility stats shown in Settings."""
+        present_refresh_workspace_visibility_panel(self)
+
+    def _create_docs_browser(self: "DataEngineWindow") -> QWidget:
+        return present_create_docs_browser(self)
+
+    def _initialize_docs_view(self: "DataEngineWindow") -> None:
+        present_initialize_docs_view(self)
+
+    def _start_docs_build(self: "DataEngineWindow") -> None:
+        """Launch the Sphinx HTML build in a background thread."""
+        present_start_docs_build(self)
+
+    def _run_docs_build_worker(self: "DataEngineWindow") -> None:
+        """Build the authored Sphinx site and report completion back to the UI thread."""
+        present_run_docs_build_worker(self)
+
+    def _finish_docs_build(self: "DataEngineWindow", succeeded: bool, message: str) -> None:
+        """Refresh the Docs tab after a build completes."""
+        present_finish_docs_build(self, succeeded, message)
+
+    def _load_docs_page(self: "DataEngineWindow", file_name: str) -> None:
+        present_load_docs_page(self, file_name)
+
+    def _config_summary(self: "DataEngineWindow", card: "QtFlowCard | None"):
+        from data_engine.domain import ConfigPreviewState
+
+        return ConfigPreviewState.from_flow(card, self.flow_states)
+
+    def _has_authored_workspace(self: "DataEngineWindow") -> bool:
+        """Return whether the selected workspace currently has authored flow modules."""
+        return authored_workspace_is_available(self.workspace_paths)
+
+    def _is_bootstrap_ready_error(self: "DataEngineWindow", message: str) -> bool:
+        """Return whether one flow-load error is expected before bootstrap."""
+        return "No flow modules discovered" in message or ("Flow module" in message and "is not available" in message)
+
+    def _empty_flow_message_for_error(self: "DataEngineWindow", message: str) -> str:
+        """Return the UI empty-state copy for one flow-load failure."""
+        if self._is_bootstrap_ready_error(message):
+            return "No discoverable flows were found yet in this workspace folder."
+        return message

data_engine/ui/gui/surface.py

@@ -0,0 +1,209 @@
+"""Surface-level helper functions for the GUI application shell."""
+
+from __future__ import annotations
+
+import logging
+from queue import Empty
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QTimer
+
+from data_engine.ui.gui.bootstrap import GuiServices, build_gui_services, default_gui_service_kwargs
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QCloseEvent, QShowEvent
+
+    from data_engine.domain import FlowLogEntry
+    from data_engine.ui.gui.app import DataEngineWindow
+def build_default_gui_services(theme_name: str) -> GuiServices:
+    """Build the default GUI service bundle for the main window."""
+    return build_gui_services(
+        **default_gui_service_kwargs(theme_name),
+    )
+
+
+def handle_show_event(window: "DataEngineWindow", event: "QShowEvent") -> None:
+    """Run the GUI show-event side effects."""
+    super(type(window), window).showEvent(event)
+    if not window._auto_daemon_enabled:
+        window._auto_daemon_enabled = True
+        QTimer.singleShot(0, window._ensure_daemon_started)
+
+
+def handle_close_event(window: "DataEngineWindow", event: "QCloseEvent") -> None:
+    """Run the GUI close-event shutdown path."""
+    window.ui_closing = True
+    log_handler = getattr(window, "log_handler", None)
+    if log_handler is not None:
+        logging.getLogger("data_engine").removeHandler(log_handler)
+    runtime_stop_event = getattr(window, "engine_runtime_stop_event", None)
+    if runtime_stop_event is not None:
+        runtime_stop_event.set()
+    flow_stop_event = getattr(window, "engine_flow_stop_event", None)
+    if flow_stop_event is not None:
+        flow_stop_event.set()
+    for stop_event in getattr(window, "manual_flow_stop_events", {}).values():
+        stop_event.set()
+    if hasattr(window, "log_timer"):
+        window.log_timer.stop()
+    if hasattr(window, "ui_refresh_timer"):
+        window.ui_refresh_timer.stop()
+    if hasattr(window, "operation_timer"):
+        window.operation_timer.stop()
+    if hasattr(window, "daemon_timer"):
+        window.daemon_timer.stop()
+    if hasattr(window, "_unregister_client_session_and_check_for_shutdown") and hasattr(window, "_is_last_process_ui_window"):
+        should_shutdown_daemon = window._unregister_client_session_and_check_for_shutdown(
+            purge_process_ui_sessions=window._is_last_process_ui_window(),
+        )
+        if should_shutdown_daemon and hasattr(window, "_shutdown_daemon_on_close"):
+            window._shutdown_daemon_on_close()
+    if hasattr(window, "_wait_for_worker_threads"):
+        window._wait_for_worker_threads(timeout_seconds=1.5)
+    if hasattr(window, "runtime_binding_service") and hasattr(window, "runtime_binding"):
+        window.runtime_binding_service.close_binding(window.runtime_binding)
+    super(type(window), window).closeEvent(event)
+
+
+def show_message_box_later(window: "DataEngineWindow", *, title: str, text: str, tone: str) -> None:
+    """Defer one application dialog until the current UI update cycle completes."""
+    if window.ui_closing:
+        return
+    if not str(text).strip():
+        return
+    window._pending_message_box = (title, text, tone)
+    if window._message_box_scheduled or window._message_box_open:
+        return
+    generation = window._message_box_generation
+
+    def _show_pending_message_box() -> None:
+        if generation != window._message_box_generation:
+            return
+        window._message_box_scheduled = False
+        if window.ui_closing:
+            return
+        payload = window._pending_message_box
+        window._pending_message_box = None
+        if payload is None:
+            return
+        next_title, next_text, next_tone = payload
+        window._message_box_open = True
+        try:
+            window._show_message_box(title=next_title, text=next_text, tone=next_tone)
+        finally:
+            window._message_box_open = False
+        if (
+            generation == window._message_box_generation
+            and window._pending_message_box is not None
+            and not window.ui_closing
+        ):
+            show_message_box_later(
+                window,
+                title=window._pending_message_box[0],
+                text=window._pending_message_box[1],
+                tone=window._pending_message_box[2],
+            )
+
+    window._message_box_scheduled = True
+    QTimer.singleShot(0, _show_pending_message_box)
+
+
+def log_matches_selection(window: "DataEngineWindow", entry: "FlowLogEntry") -> bool:
+    """Return whether one log entry belongs to the currently selected flow."""
+    return entry.kind == "flow" and window.selected_flow_name is not None and entry.flow_name == window.selected_flow_name
+
+
+def append_log_entry(window: "DataEngineWindow", entry: "FlowLogEntry") -> None:
+    """Append one log entry and schedule affected UI refresh work."""
+    window.log_service.append_entry(window.runtime_binding.log_store, entry)
+    if log_matches_selection(window, entry):
+        schedule_ui_refresh(window, log_view=True, action_buttons=True)
+
+
+def schedule_ui_refresh(window: "DataEngineWindow", *, log_view: bool = False, action_buttons: bool = False) -> None:
+    """Schedule one deferred GUI refresh cycle."""
+    if log_view:
+        window._log_view_refresh_pending = True
+    if action_buttons:
+        window._action_buttons_refresh_pending = True
+    if not window.ui_refresh_timer.isActive():
+        window.ui_refresh_timer.start(0)
+
+
+def flush_deferred_ui_updates(window: "DataEngineWindow") -> None:
+    """Flush any deferred GUI refresh work."""
+    if window._log_view_refresh_pending:
+        window._log_view_refresh_pending = False
+        window._refresh_log_view()
+    if window._action_buttons_refresh_pending:
+        window._action_buttons_refresh_pending = False
+        window._refresh_action_buttons()
+
+
+def append_log_line(window: "DataEngineWindow", line: str, *, flow_name: str | None = None) -> None:
+    """Append one simple textual log line."""
+    from data_engine.domain import FlowLogEntry
+
+    kind = "flow" if flow_name is not None else "system"
+    append_log_entry(window, FlowLogEntry(line=line, kind=kind, flow_name=flow_name))
+
+
+def poll_log_queue(window: "DataEngineWindow") -> None:
+    """Drain queued runtime log entries and schedule the minimum UI refresh work."""
+    selected_flow_dirty = False
+    action_buttons_dirty = False
+    processed = 0
+    while processed < window._MAX_LOG_EVENTS_PER_TICK:
+        try:
+            entry = window.log_queue.get_nowait()
+        except Empty:
+            break
+        window.log_service.append_entry(window.runtime_binding.log_store, entry)
+        if log_matches_selection(window, entry):
+            selected_flow_dirty = True
+            action_buttons_dirty = True
+        elif entry.kind == "flow":
+            action_buttons_dirty = True
+        if entry.event is not None:
+            window._apply_runtime_event(entry.event)
+        processed += 1
+    if selected_flow_dirty or action_buttons_dirty:
+        schedule_ui_refresh(window, log_view=selected_flow_dirty, action_buttons=action_buttons_dirty)
+    if not window.log_queue.empty() and not window.ui_closing:
+        QTimer.singleShot(0, window._poll_log_queue)
+
+
+def safe_emit_run_finished(window: "DataEngineWindow", flow_name: str, results: object, error: object) -> None:
+    """Emit the queued run-finished signal unless the GUI is closing."""
+    if window.ui_closing:
+        return
+    try:
+        window.signals.run_finished.emit(flow_name, results, error)
+    except RuntimeError:
+        pass
+
+
+def safe_emit_runtime_finished(window: "DataEngineWindow", flow_names: tuple[str, ...], results: object, error: object) -> None:
+    """Emit the queued runtime-finished signal unless the GUI is closing."""
+    if window.ui_closing:
+        return
+    try:
+        window.signals.runtime_finished.emit(flow_names, results, error)
+    except RuntimeError:
+        pass
+
+
+__all__ = [
+    "append_log_entry",
+    "append_log_line",
+    "build_default_gui_services",
+    "flush_deferred_ui_updates",
+    "handle_close_event",
+    "handle_show_event",
+    "log_matches_selection",
+    "poll_log_queue",
+    "safe_emit_run_finished",
+    "safe_emit_runtime_finished",
+    "schedule_ui_refresh",
+    "show_message_box_later",
+]