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

data_engine/views/actions.py

@@ -0,0 +1,80 @@
+"""Shared operator action-state view models across GUI and TUI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from data_engine.domain import OperatorActionContext
+
+
+@dataclass(frozen=True)
+class GuiActionState:
+    """Button and control state for the desktop GUI surface."""
+
+    flow_run_label: str
+    flow_run_enabled: bool
+    flow_config_enabled: bool
+    engine_enabled: bool
+    engine_label: str
+    engine_state: str
+    refresh_enabled: bool
+    clear_flow_log_enabled: bool
+    request_control_visible: bool
+    request_control_enabled: bool
+
+    @classmethod
+    def from_context(cls, context: OperatorActionContext) -> "GuiActionState":
+        """Return the GUI action state derived from one operator action context."""
+        session = context.runtime_session
+        selected = context.selected_flow
+        active = session.runtime_active or session.runtime_stopping
+        return cls(
+            flow_run_label="Running..." if selected.running else "Run Once",
+            flow_run_enabled=selected.valid and not selected.group_active and session.control_available and context.workspace_available,
+            flow_config_enabled=selected.present,
+            engine_enabled=(
+                session.runtime_active
+                or (context.has_automated_flows and session.control_available and context.workspace_available)
+            ) and not session.runtime_stopping,
+            engine_label="Stopping..." if session.runtime_stopping else "Stop Engine" if active else "Start Engine",
+            engine_state="running" if active else "stopped",
+            refresh_enabled=not session.runtime_active and not session.manual_run_active,
+            clear_flow_log_enabled=selected.present and selected.has_logs,
+            request_control_visible=True,
+            request_control_enabled=not session.workspace_owned,
+        )
+
+
+@dataclass(frozen=True)
+class TuiActionState:
+    """Button and control state for the terminal UI surface."""
+
+    refresh_disabled: bool
+    run_once_disabled: bool
+    start_engine_disabled: bool
+    stop_engine_disabled: bool
+    view_config_disabled: bool
+    view_log_disabled: bool
+    clear_flow_log_disabled: bool
+    workspace_select_disabled: bool
+    @classmethod
+    def from_context(cls, context: OperatorActionContext) -> "TuiActionState":
+        """Return the TUI action state derived from one operator action context."""
+        session = context.runtime_session
+        busy = session.runtime_active or session.manual_run_active or session.runtime_stopping
+        return cls(
+            refresh_disabled=busy,
+            run_once_disabled=busy or not session.control_available or not context.workspace_available,
+            start_engine_disabled=busy or not session.control_available or not context.workspace_available,
+            stop_engine_disabled=not busy,
+            view_config_disabled=not context.selected_flow.present,
+            view_log_disabled=not context.selected_run_group_present,
+            clear_flow_log_disabled=not context.selected_flow.present,
+            workspace_select_disabled=False,
+        )
+
+
+__all__ = [
+    "GuiActionState",
+    "TuiActionState",
+]

data_engine/views/artifacts.py

@@ -0,0 +1,58 @@
+"""Shared artifact-preview presentation decisions across operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import mimetypes
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ArtifactPreviewSpec:
+    """Describe how one artifact should be previewed."""
+
+    kind: str
+    label: str
+    previewable: bool
+    placeholder_message: str | None = None
+
+
+def classify_artifact_preview(path: Path) -> ArtifactPreviewSpec:
+    """Return the preview strategy for one output artifact."""
+    suffix = path.suffix.lower()
+    if suffix in {".parquet"}:
+        return ArtifactPreviewSpec(kind="parquet", label="Parquet table preview", previewable=True)
+    if suffix in {".xlsx", ".xls", ".xlsm", ".xlsb"}:
+        return ArtifactPreviewSpec(kind="excel", label="Excel table preview", previewable=True)
+    if suffix in {".pdf"}:
+        return ArtifactPreviewSpec(
+            kind="pdf",
+            label="PDF inspection",
+            previewable=False,
+            placeholder_message="PDF artifacts are recognized, but in-app PDF text inspection is not available yet.",
+        )
+    if is_text_artifact(path):
+        return ArtifactPreviewSpec(kind="text", label="Text preview", previewable=True)
+    return ArtifactPreviewSpec(
+        kind="unsupported",
+        label="Artifact inspection",
+        previewable=False,
+        placeholder_message="This artifact type is not previewable in the UI yet.",
+    )
+
+
+def is_text_artifact(path: Path) -> bool:
+    """Return whether one artifact should use text-preview treatment."""
+    suffix = path.suffix.lower()
+    if suffix in {
+        ".txt", ".log", ".md", ".json", ".csv", ".tsv", ".yaml", ".yml",
+        ".xml", ".html", ".htm", ".sql", ".py", ".toml", ".ini", ".cfg",
+    }:
+        return True
+    guessed_type, _encoding = mimetypes.guess_type(path.name)
+    if guessed_type is None:
+        return False
+    return guessed_type.startswith("text/") or guessed_type in {"application/json", "application/xml", "application/x-yaml"}
+
+
+__all__ = ["ArtifactPreviewSpec", "classify_artifact_preview", "is_text_artifact"]

data_engine/views/flow_display.py

@@ -0,0 +1,69 @@
+"""Shared flow/group row display models across GUI and TUI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from data_engine.views.models import QtFlowCard
+from data_engine.views.presentation import FlowGroupBucket, flow_secondary_text, group_label, group_secondary_text, state_dot, status_color_name
+
+
+@dataclass(frozen=True)
+class FlowRowDisplay:
+    """Display metadata for one flow row in a list/tree surface."""
+
+    primary: str
+    secondary: str
+    state_color: str
+    dot: str
+    tooltip: str
+
+    @classmethod
+    def from_card(cls, card: QtFlowCard, state: str, *, primary: str = "title") -> "FlowRowDisplay":
+        """Return display metadata for one flow row."""
+        primary_text = card.title if primary == "title" else card.name
+        resolved_state = state if card.valid else "failed"
+        tooltip = f"{card.name} | {card.title} | {state}"
+        if card.group:
+            tooltip = f"{tooltip} | group={card.group}"
+        return cls(
+            primary=primary_text,
+            secondary=flow_secondary_text(card.mode, state),
+            state_color=status_color_name(state),
+            dot=state_dot(resolved_state),
+            tooltip=tooltip,
+        )
+
+
+@dataclass(frozen=True)
+class GroupRowDisplay:
+    """Display metadata for one grouped flow header."""
+
+    title: str
+    secondary: str
+    uppercase_title: str
+    @classmethod
+    def from_group(
+        cls,
+        group_name: str,
+        entries: list[QtFlowCard] | tuple[QtFlowCard, ...],
+        flow_states: dict[str, str],
+    ) -> "GroupRowDisplay":
+        """Return display metadata for one flow group header."""
+        title = group_label(group_name)
+        return cls(
+            title=title,
+            secondary=group_secondary_text(list(entries), flow_states),
+            uppercase_title=title.upper(),
+        )
+
+    @classmethod
+    def from_bucket(cls, bucket: FlowGroupBucket, flow_states: dict[str, str]) -> "GroupRowDisplay":
+        """Return display metadata for one grouped flow bucket."""
+        return cls.from_group(bucket.group_name, bucket.entries, flow_states)
+
+
+__all__ = [
+    "FlowRowDisplay",
+    "GroupRowDisplay",
+]

data_engine/views/logs.py

@@ -0,0 +1,54 @@
+"""Shared log storage helpers for Data Engine operator surfaces."""
+
+from __future__ import annotations
+
+from data_engine.domain import FlowLogEntry, FlowRunState, LogKind, RuntimeStepEvent
+
+CollapsedLogKey = tuple[str, str, str]
+
+
+class FlowLogStore:
+    """Keep operator log history and expose per-flow filtered views."""
+
+    def __init__(self, entries: tuple[FlowLogEntry, ...] = ()) -> None:
+        self._entries: list[FlowLogEntry] = list(entries)
+
+    def append_entry(self, entry: FlowLogEntry) -> None:
+        self._entries.append(entry)
+
+    def append_line(self, line: str, *, kind: LogKind, flow_name: str | None = None) -> FlowLogEntry:
+        entry = FlowLogEntry(line=line, kind=kind, flow_name=flow_name)
+        self.append_entry(entry)
+        return entry
+
+    def clear(self) -> None:
+        self._entries.clear()
+
+    def clear_flow(self, flow_name: str | None) -> None:
+        if flow_name is None:
+            return
+        self._entries = [
+            entry
+            for entry in self._entries
+            if not (entry.kind == "flow" and entry.flow_name == flow_name)
+        ]
+
+    def entries_for_flow(self, flow_name: str | None) -> tuple[FlowLogEntry, ...]:
+        if flow_name is None:
+            return ()
+        return tuple(entry for entry in self._entries if entry.kind == "flow" and entry.flow_name == flow_name)
+
+    def runs_for_flow(self, flow_name: str | None) -> tuple[FlowRunState, ...]:
+        entries = self.entries_for_flow(flow_name)
+        if not entries:
+            return ()
+        return FlowRunState.group_entries(entries)
+
+__all__ = [
+    "CollapsedLogKey",
+    "FlowLogStore",
+    "FlowLogEntry",
+    "FlowRunState",
+    "LogKind",
+    "RuntimeStepEvent",
+]

data_engine/views/models.py

@@ -0,0 +1,96 @@
+"""Shared UI-facing card models and small display helpers across Data Engine surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from data_engine.domain import FlowCatalogEntry, default_flow_state, flow_category
+
+if TYPE_CHECKING:
+    from data_engine.services.flow_catalog import FlowCatalogService
+
+
+@dataclass(frozen=True)
+class QtFlowCard:
+    """Display model for one discovered flow."""
+
+    name: str
+    group: str | None
+    title: str
+    description: str
+    source_root: str
+    target_root: str
+    mode: str
+    interval: str
+    operations: str
+    operation_items: tuple[str, ...]
+    state: str
+    valid: bool
+    category: str
+    error: str = ""
+
+def qt_flow_card_from_entry(entry: FlowCatalogEntry) -> QtFlowCard:
+    """Map one catalog entry into a shared surface card."""
+    return QtFlowCard(
+        name=entry.name,
+        group=entry.group,
+        title=entry.title,
+        description=entry.description,
+        source_root=entry.source_root,
+        target_root=entry.target_root,
+        mode=entry.mode,
+        interval=entry.interval,
+        operations=entry.operations,
+        operation_items=entry.operation_items,
+        state=entry.state,
+        valid=entry.valid,
+        category=entry.category,
+        error=entry.error,
+    )
+
+
+def flow_catalog_entry_from_qt_card(card: QtFlowCard) -> FlowCatalogEntry:
+    """Map one shared surface card back into a catalog entry."""
+    return FlowCatalogEntry(
+        name=card.name,
+        group=card.group,
+        title=card.title,
+        description=card.description,
+        source_root=card.source_root,
+        target_root=card.target_root,
+        mode=card.mode,
+        interval=card.interval,
+        operations=card.operations,
+        operation_items=card.operation_items,
+        state=card.state,
+        valid=card.valid,
+        category=card.category,
+        error=card.error,
+    )
+
+
+def qt_flow_cards_from_entries(entries: tuple[FlowCatalogEntry, ...] | list[FlowCatalogEntry]) -> tuple[QtFlowCard, ...]:
+    """Map discovered catalog entries into shared surface cards."""
+    return tuple(qt_flow_card_from_entry(entry) for entry in entries)
+
+
+def load_qt_flow_cards(
+    flow_catalog_service: "FlowCatalogService",
+    *,
+    workspace_root: Path | None = None,
+) -> tuple[QtFlowCard, ...]:
+    """Load discovered catalog entries and map them into shared surface cards."""
+    return qt_flow_cards_from_entries(flow_catalog_service.load_entries(workspace_root=workspace_root))
+
+
+__all__ = [
+    "QtFlowCard",
+    "default_flow_state",
+    "flow_category",
+    "flow_catalog_entry_from_qt_card",
+    "load_qt_flow_cards",
+    "qt_flow_card_from_entry",
+    "qt_flow_cards_from_entries",
+]

data_engine/views/presentation.py

@@ -0,0 +1,133 @@
+"""Shared presentation helpers across GUI and TUI surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+from data_engine.domain.catalog import FlowCatalogLike
+
+
+@dataclass(frozen=True)
+class FlowGroupBucket:
+    """One grouped bucket of flow cards in shared surface order."""
+
+    group_name: str
+    entries: tuple[FlowCatalogLike, ...]
+
+    @property
+    def title(self) -> str:
+        """Return the user-facing label for this grouped flow section."""
+        return group_label(self.group_name)
+
+
+def flow_group_name(card: FlowCatalogLike) -> str:
+    """Return the display/runtime group bucket for one flow card."""
+    return card.group or card.mode
+
+
+def group_label(group_name: str) -> str:
+    """Return the user-facing label for one grouped flow section."""
+    if group_name in {"poll", "schedule", "manual"}:
+        return group_name.title()
+    return group_name
+
+
+def group_cards(cards: tuple[FlowCatalogLike, ...] | list[FlowCatalogLike]) -> tuple[FlowGroupBucket, ...]:
+    """Group cards by display bucket in the shared surface order."""
+    grouped: dict[str, list[FlowCatalogLike]] = {}
+    for card in cards:
+        grouped.setdefault(flow_group_name(card), []).append(card)
+    priority = {"manual": 0, "poll": 1, "schedule": 2}
+    return tuple(
+        FlowGroupBucket(group_name=group_name, entries=tuple(entries))
+        for group_name, entries in sorted(grouped.items(), key=lambda item: (priority.get(item[0], 10), item[0].lower()))
+    )
+
+
+def flow_secondary_text(mode: str, state: str) -> str:
+    """Return the secondary status line for one flow card."""
+    if mode == "poll":
+        return "Polling" if state in {"poll ready", "polling"} else f"Polling  {state}"
+    if mode == "schedule":
+        return "Scheduled" if state in {"schedule ready", "scheduled"} else f"Scheduled  {state}"
+    return "Manual" if state == "manual" else f"Manual  {state}"
+
+
+def group_secondary_text(entries: list[FlowCatalogLike], flow_states: dict[str, str]) -> str:
+    """Return one compact group summary line for sidebar/list displays."""
+    total = len(entries)
+    active = sum(1 for card in entries if flow_states.get(card.name, card.state) in {"running", "polling", "scheduled"})
+    failed = sum(1 for card in entries if flow_states.get(card.name, card.state) == "failed")
+    if failed:
+        return f"{total} flow(s)  Error: {failed}"
+    if active:
+        return f"{total} flow(s)  Running: {active}"
+    return f"{total} flow(s)"
+
+
+def status_color_name(state: str) -> str:
+    """Return the named status color token for one flow state."""
+    if state == "failed":
+        return "error"
+    if state == "started":
+        return "started"
+    if state in {"running", "polling", "scheduled", "success", "finished"}:
+        return "success"
+    if state in {"stopping flow", "stopping runtime"}:
+        return "warning"
+    return "idle"
+
+
+def state_dot(state: str) -> str:
+    """Return one small textual state marker for compact terminal displays."""
+    if state == "failed":
+        return "!"
+    if state in {"running", "polling", "scheduled", "success", "finished"}:
+        return "*"
+    if state in {"stopping flow", "stopping runtime"}:
+        return "~"
+    return "·"
+
+
+def operation_marker(status: str) -> str:
+    """Return one small textual marker for operation-level progress."""
+    if status == "running":
+        return ">"
+    if status == "success":
+        return "+"
+    if status == "failed":
+        return "!"
+    return "·"
+
+
+def format_seconds(seconds: float) -> str:
+    """Render elapsed seconds into the compact duration text used across surfaces."""
+
+    def truncate(value: float, decimals: int = 1) -> float:
+        factor = 10**decimals
+        return math.trunc(value * factor) / factor
+
+    if seconds < 0.001:
+        return "<1ms"
+    if seconds < 1:
+        return f"{math.trunc(seconds * 1000)}ms"
+    if seconds < 60:
+        return f"{truncate(seconds):.1f}s"
+    if seconds < 3600:
+        return f"{truncate(seconds / 60):.1f}m"
+    return f"{truncate(seconds / 3600):.1f}h"
+
+
+__all__ = [
+    "FlowGroupBucket",
+    "flow_secondary_text",
+    "flow_group_name",
+    "format_seconds",
+    "group_cards",
+    "group_label",
+    "group_secondary_text",
+    "operation_marker",
+    "state_dot",
+    "status_color_name",
+]

data_engine/views/runs.py

@@ -0,0 +1,62 @@
+"""Shared run-group presentation helpers across operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from data_engine.domain import FlowLogEntry, FlowRunState, RunDetailState
+from data_engine.views.presentation import format_seconds
+
+
+@dataclass(frozen=True)
+class RunGroupDisplay:
+    """Canonical GUI-first presentation state for one grouped run."""
+
+    primary_label: str
+    source_label: str
+    status_text: str
+    status_visual_state: str
+    duration_text: str | None
+
+    @classmethod
+    def from_run(cls, run_state: FlowRunState) -> "RunGroupDisplay":
+        detail = RunDetailState.from_run(run_state)
+        return cls(
+            primary_label=detail.display_label,
+            source_label=detail.source_label,
+            status_text=detail.status.title(),
+            status_visual_state=_status_visual_state(detail.status),
+            duration_text=format_seconds(detail.elapsed_seconds) if detail.elapsed_seconds is not None else None,
+        )
+
+
+def format_raw_log_message(entry: FlowLogEntry) -> str:
+    """Return canonical user-facing log text for one raw runtime/log entry."""
+    from html import escape
+
+    event = entry.event
+    if event is None:
+        return escape(entry.line)
+    flow_name = escape(event.flow_name)
+    source_label = escape(event.source_label)
+    status = escape(event.status)
+    has_source = event.source_label not in {"", "-"}
+    if event.step_name is None:
+        if has_source:
+            return f"{flow_name} &gt; {source_label} &gt; <i>{status}</i>"
+        return f"{flow_name} &gt; <i>{status}</i>"
+    step_name = escape(event.step_name.replace(":", "::", 1))
+    if has_source:
+        return f"{flow_name} &gt; {source_label} &gt; <b>{step_name}</b> - <i>{status}</i>"
+    return f"{flow_name} &gt; <b>{step_name}</b> - <i>{status}</i>"
+
+
+def _status_visual_state(status: str) -> str:
+    if status in {"failed", "stopped"}:
+        return "failed"
+    if status == "started":
+        return "started"
+    return "finished"
+
+
+__all__ = ["RunGroupDisplay", "format_raw_log_message"]

data_engine/views/state.py

@@ -0,0 +1,39 @@
+"""Shared state and presentation helpers for Data Engine operator surfaces."""
+
+from __future__ import annotations
+
+from data_engine.domain.details import FlowSummaryState, OperationArtifactState
+from data_engine.domain.operations import OperationFlowState, OperationRowState, OperationSessionState
+from data_engine.views.models import QtFlowCard
+
+def build_flow_summary(card: QtFlowCard | None, flow_states: dict[str, str]) -> FlowSummaryState:
+    """Return summary rows for the selected flow."""
+    return FlowSummaryState.from_flow(card, flow_states)
+
+
+def is_inspectable_operation(operation_name: str) -> bool:
+    """Return whether an operation can surface a previewable output path."""
+    return OperationArtifactState(operation_name).inspectable
+
+
+def artifact_key_for_operation(operation_name: str) -> str | None:
+    """Return the runtime metadata key produced by one operation."""
+    return OperationArtifactState(operation_name).artifact_key
+
+
+def capture_step_outputs(flow_card: QtFlowCard, existing: dict[str, "Path"], results: object) -> dict[str, "Path"]:
+    """Return updated output-path mappings extracted from completed flow results."""
+    return OperationArtifactState.capture_outputs(flow_card, existing, results)
+
+
+OperationDisplayState = OperationFlowState
+
+
+__all__ = [
+    "OperationDisplayState",
+    "OperationRowState",
+    "artifact_key_for_operation",
+    "build_flow_summary",
+    "capture_step_outputs",
+    "is_inspectable_operation",
+]

data_engine/views/status.py

@@ -0,0 +1,13 @@
+"""Shared surface-facing status-copy helpers."""
+
+from __future__ import annotations
+
+WORKSPACE_UNAVAILABLE_TEXT = "Workspace root is no longer available."
+
+
+def surface_control_status_text(control_status_text: str | None, *, empty_flow_message: str = "") -> str:
+    """Return the shared control/status line text shown by operator surfaces."""
+    return control_status_text or empty_flow_message
+
+
+__all__ = ["WORKSPACE_UNAVAILABLE_TEXT", "surface_control_status_text"]