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

data_engine/ui/gui/dialogs/__init__.py

@@ -0,0 +1,12 @@
+"""Dialog-layer helpers for the desktop UI."""
+
+from data_engine.ui.gui.dialogs.messages import show_message_box, structured_error_content
+from data_engine.ui.gui.dialogs.previews import show_config_preview, show_output_preview, show_run_log_preview
+
+__all__ = [
+    "show_config_preview",
+    "show_message_box",
+    "show_output_preview",
+    "show_run_log_preview",
+    "structured_error_content",
+]

data_engine/ui/gui/dialogs/messages.py

@@ -0,0 +1,88 @@
+"""Message dialog helpers for the desktop UI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QDialog, QGridLayout, QHBoxLayout, QLabel, QPushButton, QTextEdit, QVBoxLayout
+from data_engine.domain import StructuredErrorState
+from data_engine.ui.gui.widgets import make_label_selectable
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+def structured_error_content(text: str) -> StructuredErrorState | None:
+    """Parse one developer-facing flow-module error into dialog sections when possible."""
+    return StructuredErrorState.parse(text)
+
+
+def show_message_box(window: "DataEngineWindow", *, title: str, text: str, tone: str) -> None:
+    """Show one simple application dialog for info/error messages."""
+    dialog = QDialog(window)
+    dialog.setWindowTitle(title)
+    dialog.setModal(True)
+    dialog.resize(520, 220)
+    layout = QVBoxLayout(dialog)
+    layout.setContentsMargins(20, 18, 20, 18)
+    layout.setSpacing(14)
+
+    structured = structured_error_content(text) if tone == "error" else None
+    title_label = QLabel(structured.title if structured is not None else title)
+    title_label.setObjectName("sectionTitle")
+    layout.addWidget(title_label)
+
+    if structured is None:
+        body_label = QLabel(text)
+        body_label.setWordWrap(True)
+        body_label.setObjectName("errorText" if tone == "error" else "bodyText")
+        make_label_selectable(body_label)
+        layout.addWidget(body_label, 1)
+    else:
+        summary_grid = QGridLayout()
+        summary_grid.setContentsMargins(0, 0, 0, 0)
+        summary_grid.setHorizontalSpacing(10)
+        summary_grid.setVerticalSpacing(6)
+        for row_index, field in enumerate(structured.fields):
+            label = QLabel(field.label)
+            label.setObjectName("fieldLabel")
+            value = QLabel(field.value)
+            value.setObjectName("fieldValue")
+            value.setWordWrap(True)
+            make_label_selectable(value)
+            summary_grid.addWidget(label, row_index, 0)
+            summary_grid.addWidget(value, row_index, 1)
+        layout.addLayout(summary_grid)
+
+        detail_label = QLabel("Error")
+        detail_label.setObjectName("fieldLabel")
+        layout.addWidget(detail_label)
+
+        detail_body = QTextEdit()
+        detail_body.setObjectName("outputPreviewText")
+        detail_body.setReadOnly(True)
+        detail_body.setPlainText(structured.detail)
+        detail_body.setMinimumHeight(88)
+        layout.addWidget(detail_body, 1)
+
+        raw_label = QLabel("Details")
+        raw_label.setObjectName("fieldLabel")
+        layout.addWidget(raw_label)
+
+        raw_body = QTextEdit()
+        raw_body.setObjectName("outputPreviewText")
+        raw_body.setReadOnly(True)
+        raw_body.setPlainText(structured.raw_text)
+        raw_body.setMinimumHeight(88)
+        layout.addWidget(raw_body, 1)
+
+    action_row = QHBoxLayout()
+    action_row.addStretch(1)
+    close_button = QPushButton("OK")
+    close_button.clicked.connect(dialog.accept)
+    action_row.addWidget(close_button)
+    layout.addLayout(action_row)
+    dialog.exec()
+
+
+__all__ = ["show_message_box", "structured_error_content"]

data_engine/ui/gui/dialogs/previews.py

@@ -0,0 +1,222 @@
+"""Preview dialog helpers for the desktop UI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QDialog,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QListWidget,
+    QListWidgetItem,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from data_engine.ui.gui.preview_models import ConfigPreviewRequest, OutputPreviewRequest, RunLogPreviewRequest
+from data_engine.ui.gui.rendering import populate_output_preview, render_svg_icon_pixmap
+from data_engine.ui.gui.widgets import build_config_value, make_label_selectable
+
+if TYPE_CHECKING:
+    from data_engine.domain import FlowLogEntry, FlowRunState
+    from data_engine.views.models import QtFlowCard
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+def show_run_log_preview(window: "DataEngineWindow", request: RunLogPreviewRequest) -> QDialog:
+    detail = request.detail
+    dialog = QDialog(window)
+    dialog.setWindowTitle("Run Log")
+    dialog.setObjectName("outputPreviewDialog")
+    dialog.resize(760, 520)
+    layout = QVBoxLayout(dialog)
+    layout.setContentsMargins(18, 18, 18, 18)
+    layout.setSpacing(12)
+
+    header = QFrame()
+    header.setObjectName("outputPreviewHeader")
+    header_layout = QVBoxLayout(header)
+    header_layout.setContentsMargins(14, 14, 14, 14)
+    header_layout.setSpacing(4)
+
+    title_label = QLabel(detail.display_label)
+    title_label.setObjectName("heroTitle")
+    header_layout.addWidget(title_label)
+
+    summary_parts = [detail.status.title()]
+    if detail.elapsed_seconds is not None:
+        summary_parts.append(window._format_seconds(detail.elapsed_seconds))
+    summary_label = QLabel("  •  ".join(summary_parts))
+    summary_label.setObjectName("sectionMeta")
+    header_layout.addWidget(summary_label)
+    layout.addWidget(header)
+
+    log_list = QListWidget()
+    log_list.setObjectName("runLogList")
+    log_list.setSpacing(6)
+    for entry in request.run_group.entries:
+        item = QListWidgetItem(entry.line)
+        widget = _build_raw_log_entry_widget(window, entry, run_group=request.run_group)
+        item.setSizeHint(widget.sizeHint())
+        log_list.addItem(item)
+        log_list.setItemWidget(item, widget)
+    layout.addWidget(log_list, 1)
+
+    _present_dialog(dialog)
+    return dialog
+
+
+def _build_raw_log_entry_widget(window: "DataEngineWindow", entry: "FlowLogEntry", *, run_group: "FlowRunState") -> QFrame:
+    frame = QFrame()
+    frame.setObjectName("rawLogRow")
+    frame.setMinimumHeight(40)
+    layout = QHBoxLayout(frame)
+    layout.setContentsMargins(8, 6, 8, 6)
+    layout.setSpacing(10)
+
+    timestamp = QLabel(entry.created_at_utc.astimezone().strftime("%I:%M:%S %p"))
+    timestamp.setObjectName("rawLogTimestamp")
+    make_label_selectable(timestamp)
+    layout.addWidget(timestamp, 0, Qt.AlignmentFlag.AlignVCenter)
+
+    message = QLabel(window._format_raw_log_message(entry))
+    message.setObjectName("rawLogMessage")
+    message.setTextFormat(Qt.TextFormat.RichText)
+    message.setWordWrap(False)
+    make_label_selectable(message)
+    layout.addWidget(message, 1, Qt.AlignmentFlag.AlignVCenter)
+
+    event = entry.event
+    layout.addStretch(0)
+    inspect_slot = QWidget()
+    inspect_slot.setObjectName("rawLogInspectSlot")
+    inspect_slot.setFixedWidth(108)
+    inspect_slot_layout = QHBoxLayout(inspect_slot)
+    inspect_slot_layout.setContentsMargins(0, 0, 0, 0)
+    inspect_slot_layout.setSpacing(0)
+    inspect_slot_layout.addStretch(1)
+    inspect_button = QPushButton("Inspect")
+    inspect_button.setObjectName("inspectOutputButton")
+    inspect_button.setFixedWidth(96)
+    inspect_button.setEnabled(False)
+    inspect_slot_layout.addWidget(inspect_button, 0, Qt.AlignmentFlag.AlignVCenter)
+
+    icon_slot = QWidget()
+    icon_slot.setObjectName("rawLogIconSlot")
+    icon_slot.setFixedWidth(20)
+    icon_slot_layout = QHBoxLayout(icon_slot)
+    icon_slot_layout.setContentsMargins(0, 0, 0, 0)
+    icon_slot_layout.setSpacing(0)
+    icon_slot_layout.addStretch(1)
+
+    if event is not None:
+        if event.status == "failed":
+            inspect_button.setEnabled(True)
+            inspect_button.clicked.connect(
+                lambda _checked=False, group=run_group, failed_entry=entry: window._show_run_error_details(group, failed_entry)
+            )
+        if event.status in {"started", "failed", "success"}:
+            status_name = "failed" if event.status == "failed" else "started" if event.status == "started" else "finished"
+            status_icon = QLabel()
+            status_icon.setObjectName("rawLogStatusIcon")
+            fill = window._LOG_ICON_COLORS.get(status_name, window._group_icon_color().name())
+            status_icon.setPixmap(
+                render_svg_icon_pixmap(
+                    icon_name=window._LOG_ICON_NAMES[status_name],
+                    size=14,
+                    device_pixel_ratio=window.devicePixelRatioF(),
+                    fill_color=fill,
+                    default_fill_color=window._group_icon_color(),
+                )
+            )
+            status_icon.setToolTip(event.status.title())
+            icon_slot_layout.addWidget(status_icon, 0, Qt.AlignmentFlag.AlignVCenter)
+
+    layout.addWidget(inspect_slot, 0, Qt.AlignmentFlag.AlignVCenter)
+    layout.addWidget(icon_slot, 0, Qt.AlignmentFlag.AlignVCenter)
+    return frame
+
+
+def show_output_preview(window: "DataEngineWindow", request: OutputPreviewRequest) -> QDialog:
+    dialog = QDialog(window)
+    dialog.setWindowTitle("Inspect Output")
+    dialog.setObjectName("outputPreviewDialog")
+    dialog.resize(860, 520)
+    layout = QVBoxLayout(dialog)
+    layout.setContentsMargins(18, 18, 18, 18)
+    layout.setSpacing(12)
+
+    header = QFrame()
+    header.setObjectName("outputPreviewHeader")
+    header_layout = QVBoxLayout(header)
+    header_layout.setContentsMargins(14, 14, 14, 14)
+    header_layout.setSpacing(0)
+
+    path_label = QLabel(str(request.output_path))
+    path_label.setObjectName("outputPreviewPath")
+    path_label.setWordWrap(True)
+    make_label_selectable(path_label)
+    header_layout.addWidget(path_label)
+    layout.addWidget(header)
+
+    populate_output_preview(layout, request.output_path)
+
+    _present_dialog(dialog)
+    return dialog
+
+
+def show_config_preview(window: "DataEngineWindow", request: ConfigPreviewRequest) -> QDialog:
+    preview_state = request.preview
+    dialog = QDialog(window)
+    dialog.setWindowTitle(preview_state.title)
+    dialog.setObjectName("outputPreviewDialog")
+    dialog.resize(560, 420)
+    layout = QVBoxLayout(dialog)
+    layout.setContentsMargins(18, 18, 18, 18)
+    layout.setSpacing(12)
+
+    header = QFrame()
+    header.setObjectName("outputPreviewHeader")
+    header_layout = QVBoxLayout(header)
+    header_layout.setContentsMargins(14, 14, 14, 14)
+    header_layout.setSpacing(4)
+
+    title_label = QLabel(preview_state.title)
+    title_label.setObjectName("heroTitle")
+    title_label.setWordWrap(True)
+    header_layout.addWidget(title_label)
+    if preview_state.description:
+        description_label = QLabel(preview_state.description)
+        description_label.setObjectName("bodyText")
+        description_label.setWordWrap(True)
+        header_layout.addWidget(description_label)
+    layout.addWidget(header)
+
+    body = QFrame()
+    body.setObjectName("configPreviewBody")
+    body_layout = QVBoxLayout(body)
+    body_layout.setContentsMargins(14, 14, 14, 14)
+    body_layout.setSpacing(2)
+    for row in preview_state.summary.rows:
+        row_value = build_config_value(body_layout, row.label)
+        row_value.setText(row.value)
+    body_layout.addStretch(1)
+    layout.addWidget(body, 1)
+
+    _present_dialog(dialog)
+    return dialog
+
+
+def _present_dialog(dialog: QDialog) -> None:
+    dialog.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose, True)
+    dialog.show()
+    dialog.raise_()
+    dialog.activateWindow()
+
+
+__all__ = ["show_config_preview", "show_output_preview", "show_run_log_preview"]

data_engine/ui/gui/helpers/__init__.py

@@ -0,0 +1,62 @@
+"""Low-level helper functions for the desktop GUI shell."""
+
+from data_engine.ui.gui.helpers.inspection import (
+    artifact_key_for_operation,
+    capture_step_outputs,
+    inspect_step_output,
+    is_inspectable_operation,
+    refresh_operation_buttons,
+    rehydrate_step_outputs_from_ledger,
+    show_config_preview,
+    show_output_preview,
+)
+from data_engine.ui.gui.helpers.lifecycle import (
+    is_last_process_ui_window,
+    register_client_session,
+    shutdown_daemon_on_close,
+    start_worker_thread,
+    unregister_client_session_and_check_for_shutdown,
+    wait_for_worker_threads,
+)
+from data_engine.ui.gui.helpers.scroll import update_operation_scroll_cues, update_sidebar_scroll_cues
+from data_engine.ui.gui.helpers.theming import (
+    action_bar_icon,
+    apply_theme,
+    group_icon,
+    group_icon_color,
+    log_icon,
+    render_group_icon_pixmap,
+    render_svg_icon_pixmap,
+    sync_theme_to_system,
+    toggle_theme,
+    view_rail_icon,
+)
+
+__all__ = [
+    "action_bar_icon",
+    "apply_theme",
+    "artifact_key_for_operation",
+    "capture_step_outputs",
+    "group_icon",
+    "group_icon_color",
+    "is_last_process_ui_window",
+    "inspect_step_output",
+    "is_inspectable_operation",
+    "log_icon",
+    "register_client_session",
+    "refresh_operation_buttons",
+    "rehydrate_step_outputs_from_ledger",
+    "render_group_icon_pixmap",
+    "render_svg_icon_pixmap",
+    "show_config_preview",
+    "show_output_preview",
+    "shutdown_daemon_on_close",
+    "start_worker_thread",
+    "sync_theme_to_system",
+    "toggle_theme",
+    "unregister_client_session_and_check_for_shutdown",
+    "update_operation_scroll_cues",
+    "update_sidebar_scroll_cues",
+    "view_rail_icon",
+    "wait_for_worker_threads",
+]

data_engine/ui/gui/helpers/inspection.py

@@ -0,0 +1,81 @@
+"""Output inspection helper functions for the desktop GUI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from data_engine.views.state import artifact_key_for_operation as artifact_key_for_operation_helper
+from data_engine.views.state import capture_step_outputs as capture_step_outputs_helper
+from data_engine.views.state import is_inspectable_operation as is_inspectable_operation_helper
+from data_engine.domain import ConfigPreviewState
+from data_engine.ui.gui.dialogs import show_config_preview as show_config_preview_dialog
+from data_engine.ui.gui.dialogs import show_output_preview as show_output_preview_dialog
+from data_engine.ui.gui.preview_models import ConfigPreviewRequest, OutputPreviewRequest
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+def is_inspectable_operation(operation_name: str) -> bool:
+    return is_inspectable_operation_helper(operation_name)
+
+
+def artifact_key_for_operation(operation_name: str) -> str | None:
+    return artifact_key_for_operation_helper(operation_name)
+
+
+def capture_step_outputs(window: "DataEngineWindow", flow_name: str, results: object) -> None:
+    updated = capture_step_outputs_helper(
+        window.flow_cards[flow_name],
+        window.step_output_index.outputs_for(flow_name).outputs,
+        results,
+    )
+    window.step_output_index = window.step_output_index.with_flow_outputs(flow_name, updated)
+
+
+def rehydrate_step_outputs_from_ledger(window: "DataEngineWindow") -> None:
+    window.step_output_index = window.runtime_history_service.rebuild_step_outputs(
+        window.runtime_binding.runtime_ledger,
+        window.flow_cards,
+    )
+
+
+def refresh_operation_buttons(window: "DataEngineWindow", flow_name: str) -> None:
+    for row_widgets in window.operation_row_widgets:
+        if row_widgets.inspect_button is None:
+            continue
+        row_widgets.inspect_button.setEnabled(window.step_output_index.has_output(flow_name, row_widgets.operation_name))
+
+
+def inspect_step_output(window: "DataEngineWindow", operation_name: str) -> None:
+    request = build_output_preview_request(window, operation_name)
+    if request is None:
+        window._show_message_box(
+            title="Inspect Output",
+            text="No output is available for this step yet.",
+            tone="info",
+        )
+        return
+    window._show_output_preview(request.operation_name, request.output_path)
+
+
+def show_output_preview(window: "DataEngineWindow", operation_name: str, output_path: Path) -> None:
+    request = OutputPreviewRequest(operation_name=operation_name, output_path=output_path)
+    window.output_preview_dialog = show_output_preview_dialog(window, request)
+
+
+def show_config_preview(window: "DataEngineWindow") -> None:
+    card = window.flow_cards.get(window.selected_flow_name or "")
+    preview_state = ConfigPreviewState.from_flow(card, window.flow_states)
+    window.config_preview_dialog = show_config_preview_dialog(window, ConfigPreviewRequest(preview=preview_state))
+
+
+def build_output_preview_request(window: "DataEngineWindow", operation_name: str) -> OutputPreviewRequest | None:
+    """Build one explicit output-preview request for the selected flow."""
+    if window.selected_flow_name is None:
+        return None
+    output_path = window.step_output_index.output_path(window.selected_flow_name, operation_name)
+    if output_path is None or not output_path.exists():
+        return None
+    return OutputPreviewRequest(operation_name=operation_name, output_path=output_path)

data_engine/ui/gui/helpers/lifecycle.py

@@ -0,0 +1,112 @@
+"""Lifecycle and worker helpers for the desktop GUI surface."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from time import monotonic
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QApplication
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+def register_client_session(window: "DataEngineWindow") -> None:
+    """Register this UI process as one active local client for the workspace."""
+    window.runtime_binding_service.register_client_session(
+        window.runtime_binding,
+        client_id=window.client_session_id,
+        client_kind="ui",
+        pid=os.getpid(),
+    )
+
+
+def is_last_process_ui_window(window: "DataEngineWindow") -> bool:
+    """Return whether this is the last Data Engine window still open in this process."""
+    for widget in QApplication.topLevelWidgets():
+        if widget is window:
+            continue
+        if isinstance(widget, type(window)) and not getattr(widget, "ui_closing", False):
+            return False
+    return True
+
+
+def unregister_client_session_and_check_for_shutdown(
+    window: "DataEngineWindow",
+    *,
+    purge_process_ui_sessions: bool = False,
+) -> bool:
+    """Remove this UI session and return whether no local clients remain."""
+    try:
+        window.runtime_binding_service.remove_client_session(window.runtime_binding, window.client_session_id)
+        if purge_process_ui_sessions:
+            window.runtime_binding_service.purge_process_client_sessions(
+                window.runtime_binding,
+                client_kind="ui",
+                pid=os.getpid(),
+            )
+        remaining = window.runtime_binding_service.count_live_client_sessions(window.runtime_binding)
+        return remaining == 0
+    except Exception:
+        return False
+
+
+def shutdown_daemon_on_close(window: "DataEngineWindow") -> None:
+    """Best-effort local daemon shutdown when the last local client closes."""
+    client_error_type = window._daemon_client_error_type
+    try:
+        if not window._is_daemon_live(window.workspace_paths):
+            return
+        window._daemon_request(window.workspace_paths, {"command": "shutdown_daemon"}, timeout=1.5)
+        deadline = monotonic() + 2.0
+        while monotonic() < deadline:
+            if not window._is_daemon_live(window.workspace_paths):
+                break
+            time.sleep(0.05)
+    except client_error_type:
+        pass
+    except Exception:
+        pass
+
+
+def start_worker_thread(window: "DataEngineWindow", *, target, args=()) -> None:
+    """Start one tracked daemon worker thread for background UI tasks."""
+    thread = threading.Thread(target=run_tracked_worker, args=(window, target, args), daemon=True)
+    window._register_worker_thread(thread)
+    thread.start()
+
+
+def run_tracked_worker(window: "DataEngineWindow", target, args) -> None:
+    """Execute one worker target and remove its thread from the tracked set."""
+    current = threading.current_thread()
+    try:
+        target(*args)
+    finally:
+        window._discard_worker_thread(current)
+
+
+def wait_for_worker_threads(window: "DataEngineWindow", *, timeout_seconds: float) -> None:
+    """Wait briefly for tracked workers to honor stop requests before exit."""
+    deadline = time.monotonic() + max(timeout_seconds, 0.0)
+    for thread in window._worker_threads_snapshot():
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        is_alive = getattr(thread, "is_alive", None)
+        join = getattr(thread, "join", None)
+        alive = bool(is_alive()) if callable(is_alive) else False
+        if alive and callable(join):
+            join(timeout=min(remaining, 0.3))
+
+
+__all__ = [
+    "is_last_process_ui_window",
+    "register_client_session",
+    "shutdown_daemon_on_close",
+    "start_worker_thread",
+    "unregister_client_session_and_check_for_shutdown",
+    "wait_for_worker_threads",
+]

data_engine/ui/gui/helpers/scroll.py

@@ -0,0 +1,28 @@
+"""Scroll-surface helper functions for the desktop GUI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+def update_operation_scroll_cues(window: "DataEngineWindow", *args) -> None:
+    del args
+    scrollbar = window.operation_scroll.verticalScrollBar()
+    maximum = scrollbar.maximum()
+    value = scrollbar.value()
+    has_overflow = maximum > 0
+    window.operation_top_cue.setVisible(has_overflow and value > 0)
+    window.operation_bottom_cue.setVisible(has_overflow and value < maximum)
+
+
+def update_sidebar_scroll_cues(window: "DataEngineWindow", *args) -> None:
+    del args
+    scrollbar = window.sidebar_scroll.verticalScrollBar()
+    maximum = scrollbar.maximum()
+    value = scrollbar.value()
+    has_overflow = maximum > 0
+    window.sidebar_top_cue.setVisible(has_overflow and value > 0)
+    window.sidebar_bottom_cue.setVisible(has_overflow and value < maximum)