plotaviz 0.1.0__py3-none-any.whl

plotaviz/ui/table_model.py

@@ -0,0 +1,184 @@
+"""A virtualized table model for the data preview.
+
+``QTableView`` only asks for the cells it is about to paint, so backing it with a model that
+reads straight from the dataframe means a million-row file costs the same to display as a
+hundred-row one. The rule from the performance guardrails — *never render 1M rows* — is satisfied
+by never materializing them: no list of rows is ever built.
+
+A page cap is still applied on top, because scrolling through a million rows is not a feature
+anyone wants; the view shows the first :data:`MAX_PREVIEW_ROWS` and says so.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+from PySide6.QtCore import QAbstractTableModel, QModelIndex, QObject, Qt
+
+from ..core.profiler import DatasetProfile
+
+#: Rows exposed to the preview table. Beyond this the user is looking at data, not reading it.
+MAX_PREVIEW_ROWS = 5_000
+
+#: Role-specific tints, so a glance at the header tells you how each column was classified.
+_ROLE_COLOURS = {
+    "numeric": "#2E6DA4",
+    "categorical": "#7B4EA8",
+    "datetime": "#1F7A5C",
+    "boolean": "#A8681F",
+    "text": "#6B6B6B",
+}
+
+
+class DataFrameModel(QAbstractTableModel):
+    """Exposes a pandas DataFrame to a ``QTableView`` without copying it.
+
+    Args:
+        df: The frame to display.
+        profile: Optional profile, used to annotate headers with each column's role.
+        parent: Parent object.
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame | None = None,
+        profile: DatasetProfile | None = None,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self._df = df if df is not None else pd.DataFrame()
+        self._profile = profile
+        self._rows = min(len(self._df), MAX_PREVIEW_ROWS)
+
+    # ------------------------------------------------------------------ data access
+
+    def set_frame(self, df: pd.DataFrame, profile: DatasetProfile | None = None) -> None:
+        """Swap in a new frame and repaint."""
+        self.beginResetModel()
+        self._df = df
+        self._profile = profile
+        self._rows = min(len(df), MAX_PREVIEW_ROWS)
+        self.endResetModel()
+
+    @property
+    def frame(self) -> pd.DataFrame:
+        """The frame being displayed."""
+        return self._df
+
+    @property
+    def truncated(self) -> bool:
+        """Whether the view is showing fewer rows than the frame holds."""
+        return len(self._df) > self._rows
+
+    def status_text(self) -> str:
+        """A line describing what the preview is showing."""
+        rows, cols = len(self._df), len(self._df.columns)
+        if self.truncated:
+            return f"Previewing the first {self._rows:,} of {rows:,} rows × {cols} columns"
+        return f"{rows:,} rows × {cols} columns"
+
+    # ------------------------------------------------------------------ Qt model API
+
+    def rowCount(self, parent: QModelIndex | None = None) -> int:
+        """Rows the view should ask about."""
+        if parent is not None and parent.isValid():
+            return 0
+        return self._rows
+
+    def columnCount(self, parent: QModelIndex | None = None) -> int:
+        """Column count."""
+        if parent is not None and parent.isValid():
+            return 0
+        return len(self._df.columns)
+
+    def data(self, index: QModelIndex, role: int = Qt.ItemDataRole.DisplayRole) -> Any:
+        """Return one cell's display text or alignment."""
+        if not index.isValid():
+            return None
+
+        row, col = index.row(), index.column()
+        if row >= self._rows or col >= len(self._df.columns):
+            return None
+
+        if role == Qt.ItemDataRole.DisplayRole:
+            value = self._df.iat[row, col]
+            if pd.isna(value):
+                return "—"
+            if isinstance(value, float):
+                return f"{value:,.4g}"
+            if isinstance(value, pd.Timestamp):
+                return value.strftime(
+                    "%Y-%m-%d %H:%M" if value.time() != value.min.time() else "%Y-%m-%d"
+                )
+            return str(value)
+
+        if role == Qt.ItemDataRole.TextAlignmentRole:
+            column = self._df.columns[col]
+            if pd.api.types.is_numeric_dtype(self._df[column]):
+                return int(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
+            return int(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter)
+
+        if role == Qt.ItemDataRole.ForegroundRole and pd.isna(self._df.iat[row, col]):
+            from PySide6.QtGui import QColor
+
+            return QColor("#999999")
+
+        return None
+
+    def headerData(
+        self,
+        section: int,
+        orientation: Qt.Orientation,
+        role: int = Qt.ItemDataRole.DisplayRole,
+    ) -> Any:
+        """Column names with their inferred role, and row numbers down the side."""
+        if orientation == Qt.Orientation.Vertical:
+            if role == Qt.ItemDataRole.DisplayRole:
+                return str(section + 1)
+            return None
+
+        if section >= len(self._df.columns):
+            return None
+        name = str(self._df.columns[section])
+
+        if role == Qt.ItemDataRole.DisplayRole:
+            return name
+
+        if role == Qt.ItemDataRole.ToolTipRole:
+            return self._column_tooltip(name)
+
+        if role == Qt.ItemDataRole.ForegroundRole and self._profile:
+            prof = self._profile.columns.get(name)
+            if prof:
+                from PySide6.QtGui import QColor
+
+                return QColor(_ROLE_COLOURS.get(prof.role, "#333333"))
+
+        return None
+
+    def _column_tooltip(self, name: str) -> str:
+        """Per-column summary shown when hovering a header."""
+        if not self._profile:
+            return name
+        prof = self._profile.columns.get(name)
+        if prof is None:
+            return name
+
+        lines = [f"{name} — {prof.role}"]
+        if prof.is_identifier:
+            lines.append("Looks like an identifier, so it is excluded from chart suggestions.")
+        if prof.is_derived:
+            lines.append("Added by PlotaViz.")
+        lines.append(f"{prof.n_unique:,} distinct values")
+        if prof.pct_missing:
+            lines.append(f"{prof.pct_missing:.1f}% missing")
+        if prof.role == "numeric" and prof.stats:
+            lines.append(
+                f"min {prof.stats.get('min', 0):,.4g} · "
+                f"median {prof.stats.get('median', 0):,.4g} · "
+                f"max {prof.stats.get('max', 0):,.4g}"
+            )
+        if prof.note:
+            lines.append(prof.note)
+        return "\n".join(lines)

plotaviz/ui/type_override.py

@@ -0,0 +1,159 @@
+"""The column type override panel.
+
+Automatic type inference gets identifiers and dates wrong constantly — a zip code becomes a
+number, an order ID becomes a measure, a date column stays text — and every wrong type produces a
+wrong chart. Letting the user correct the inference *before* analysis proceeds is the single
+biggest frustration-preventer in the app, which is why this panel is a first-class part of the
+flow rather than a settings page.
+
+Corrections are cheap because the preprocessing pipeline is replayable: changing a type re-runs a
+short list of pure steps rather than reloading anything.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QComboBox,
+    QHBoxLayout,
+    QHeaderView,
+    QLabel,
+    QPushButton,
+    QTableWidget,
+    QTableWidgetItem,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.profiler import ROLES, DatasetProfile
+
+#: Roles offered in the dropdown, with the labels users actually recognise.
+_ROLE_LABELS = {
+    "numeric": "Number",
+    "categorical": "Category",
+    "datetime": "Date / time",
+    "boolean": "True / false",
+    "text": "Free text",
+}
+
+
+class TypeOverridePanel(QWidget):
+    """Shows every column's inferred type and lets the user correct it.
+
+    Signals:
+        types_changed: Emitted with ``{column: role}`` when the user applies corrections.
+    """
+
+    types_changed = Signal(dict)
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self._profile: DatasetProfile | None = None
+        self._combos: dict[str, QComboBox] = {}
+        self._inferred: dict[str, str] = {}
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(8, 8, 8, 8)
+
+        intro = QLabel(
+            "PlotaViz guessed these types. Correct any it got wrong — IDs read as numbers and "
+            "dates read as text are the usual culprits."
+        )
+        intro.setWordWrap(True)
+        intro.setStyleSheet("color: palette(mid);")
+        layout.addWidget(intro)
+
+        self.table = QTableWidget(0, 4, self)
+        self.table.setHorizontalHeaderLabels(["Column", "Detected as", "Treat as", "Notes"])
+        self.table.verticalHeader().setVisible(False)
+        self.table.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        self.table.setSelectionMode(QTableWidget.SelectionMode.NoSelection)
+        header = self.table.horizontalHeader()
+        header.setSectionResizeMode(0, QHeaderView.ResizeMode.ResizeToContents)
+        header.setSectionResizeMode(1, QHeaderView.ResizeMode.ResizeToContents)
+        header.setSectionResizeMode(2, QHeaderView.ResizeMode.ResizeToContents)
+        header.setSectionResizeMode(3, QHeaderView.ResizeMode.Stretch)
+        layout.addWidget(self.table, stretch=1)
+
+        buttons = QHBoxLayout()
+        self.reset_button = QPushButton("Reset to detected", self)
+        self.reset_button.clicked.connect(self.reset)
+        self.apply_button = QPushButton("Apply types", self)
+        self.apply_button.setDefault(True)
+        self.apply_button.clicked.connect(self._emit_changes)
+        buttons.addWidget(self.reset_button)
+        buttons.addStretch(1)
+        buttons.addWidget(self.apply_button)
+        layout.addLayout(buttons)
+
+    # ------------------------------------------------------------------ population
+
+    def set_profile(self, profile: DatasetProfile, overrides: dict[str, str] | None = None) -> None:
+        """Rebuild the panel for a dataset.
+
+        Args:
+            profile: The current profile, whose inferred roles seed the dropdowns.
+            overrides: Corrections already in force, so reopening the panel shows them.
+        """
+        self._profile = profile
+        overrides = overrides or {}
+        self._combos.clear()
+        self._inferred.clear()
+
+        columns = list(profile.columns.values())
+        self.table.setRowCount(len(columns))
+
+        for row, prof in enumerate(columns):
+            self._inferred[prof.name] = prof.role
+
+            name_item = QTableWidgetItem(prof.name)
+            name_item.setToolTip(
+                f"{prof.n_unique:,} distinct values, {prof.pct_missing:.1f}% missing"
+            )
+            self.table.setItem(row, 0, name_item)
+
+            detected = QTableWidgetItem(_ROLE_LABELS.get(prof.role, prof.role))
+            detected.setForeground(Qt.GlobalColor.gray)
+            self.table.setItem(row, 1, detected)
+
+            combo = QComboBox(self)
+            for role in ROLES:
+                combo.addItem(_ROLE_LABELS.get(role, role), role)
+            current = overrides.get(prof.name, prof.role)
+            index = combo.findData(current)
+            combo.setCurrentIndex(max(0, index))
+            combo.setEnabled(not prof.is_derived)
+            self._combos[prof.name] = combo
+            self.table.setCellWidget(row, 2, combo)
+
+            notes = []
+            if prof.note:
+                notes.append(prof.note)
+            if prof.is_identifier:
+                notes.append("Excluded from chart suggestions.")
+            if prof.is_derived:
+                notes.append("Added by PlotaViz.")
+            note_item = QTableWidgetItem(" ".join(notes))
+            note_item.setToolTip(" ".join(notes))
+            self.table.setItem(row, 3, note_item)
+
+    # ------------------------------------------------------------------ interaction
+
+    def overrides(self) -> dict[str, str]:
+        """The corrections the user has made — only entries that differ from inference."""
+        return {
+            name: combo.currentData()
+            for name, combo in self._combos.items()
+            if combo.currentData() != self._inferred.get(name)
+        }
+
+    def reset(self) -> None:
+        """Put every dropdown back to what inference chose, and apply."""
+        for name, combo in self._combos.items():
+            index = combo.findData(self._inferred.get(name))
+            combo.setCurrentIndex(max(0, index))
+        self._emit_changes()
+
+    def _emit_changes(self) -> None:
+        """Emit the current corrections."""
+        self.types_changed.emit(self.overrides())

plotaviz/ui/workers.py

@@ -0,0 +1,222 @@
+"""Background work — keeping long operations off the UI thread.
+
+Loading a 400 MB CSV, replaying a pipeline, and waiting on an LLM all take long enough to freeze
+a window, and a frozen window looks like a crash. Every one of those runs through :class:`Worker`
+on a ``QThread``, reports progress, and can be cancelled.
+
+The cancellation model is cooperative and honest: :meth:`Worker.cancel` sets a flag the task can
+check, and if the task is stuck inside pandas the flag is only honoured when it returns. The UI
+therefore says "Cancelling…" rather than pretending the work stopped instantly.
+"""
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+from PySide6.QtCore import QObject, QThread, Signal, Slot
+
+from ..core.errors import PlotaVizError
+
+
+class Worker(QObject):
+    """Runs one callable on a background thread.
+
+    The callable may accept a ``progress`` keyword — a ``Callable[[int, str], None]`` it can call
+    to report percentage and a status message — and a ``should_cancel`` keyword returning whether
+    the user has asked to stop.
+
+    Signals:
+        finished: Emitted with the return value on success.
+        failed: Emitted with a user-facing message and the traceback on failure.
+        progress: Emitted with ``(percent, message)``.
+        done: Emitted after either outcome, for teardown.
+    """
+
+    finished = Signal(object)
+    failed = Signal(str, str)
+    progress = Signal(int, str)
+    done = Signal()
+
+    def __init__(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> None:
+        super().__init__()
+        self._fn = fn
+        self._args = args
+        self._kwargs = kwargs
+        self._cancelled = False
+
+    def cancel(self) -> None:
+        """Ask the task to stop at its next checkpoint."""
+        self._cancelled = True
+
+    @property
+    def cancelled(self) -> bool:
+        """Whether cancellation has been requested."""
+        return self._cancelled
+
+    def run(self) -> None:
+        """Execute the callable. Connected to the thread's ``started`` signal."""
+        try:
+            import inspect
+
+            params = inspect.signature(self._fn).parameters
+            kwargs = dict(self._kwargs)
+            if "progress" in params:
+                kwargs["progress"] = self._emit_progress
+            if "should_cancel" in params:
+                kwargs["should_cancel"] = lambda: self._cancelled
+
+            result = self._fn(*self._args, **kwargs)
+        except PlotaVizError as exc:
+            # Already written for a human — pass the message straight through.
+            self.failed.emit(str(exc), traceback.format_exc())
+        except Exception as exc:
+            self.failed.emit(
+                f"Something went wrong: {exc}",
+                traceback.format_exc(),
+            )
+        else:
+            if not self._cancelled:
+                self.finished.emit(result)
+        finally:
+            self.done.emit()
+
+    def _emit_progress(self, percent: int, message: str = "") -> None:
+        """Progress callback handed to the task."""
+        self.progress.emit(int(percent), message)
+
+
+class TaskRunner(QObject):
+    """Owns a worker and its thread, and marshals results back to the UI thread.
+
+    Two problems this solves, both of which crash an app rather than merely annoying it:
+
+    * Qt garbage-collects a running ``QThread`` if nothing holds a reference, which shows up as
+      an intermittent segfault under load. This object holds that reference.
+    * A signal connected to a *plain callable* — a lambda, a nested function — is delivered
+      synchronously **in the emitting thread**. Callbacks written against the UI would then touch
+      widgets from the worker thread, which Qt does not allow. So worker signals are connected to
+      slots on this object (which lives in the UI thread, so Qt queues the delivery), and those
+      slots re-emit on the UI thread where the caller's callbacks are safe to run.
+
+    Args:
+        parent: Parent object, usually the main window.
+
+    Signals:
+        finished: Emitted on the UI thread with the task's return value.
+        failed: Emitted on the UI thread with ``(message, traceback)``.
+        progress: Emitted on the UI thread with ``(percent, message)``.
+    """
+
+    finished = Signal(object)
+    failed = Signal(str, str)
+    progress = Signal(int, str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._thread: QThread | None = None
+        self._worker: Worker | None = None
+        self._on_finished: Callable[[Any], None] | None = None
+        self._on_failed: Callable[[str, str], None] | None = None
+        self._on_progress: Callable[[int, str], None] | None = None
+
+    @property
+    def busy(self) -> bool:
+        """Whether a task is currently running."""
+        return self._thread is not None and self._thread.isRunning()
+
+    def start(
+        self,
+        fn: Callable[..., Any],
+        *args: Any,
+        on_finished: Callable[[Any], None] | None = None,
+        on_failed: Callable[[str, str], None] | None = None,
+        on_progress: Callable[[int, str], None] | None = None,
+        **kwargs: Any,
+    ) -> Worker:
+        """Run ``fn`` on a background thread.
+
+        Args:
+            fn: The callable to run.
+            *args: Positional arguments for it.
+            on_finished: Called with the result on the UI thread.
+            on_failed: Called with ``(message, traceback)`` on the UI thread.
+            on_progress: Called with ``(percent, message)`` on the UI thread.
+            **kwargs: Keyword arguments for ``fn``.
+
+        Returns:
+            The :class:`Worker`, so the caller can cancel it.
+
+        Raises:
+            RuntimeError: If a task is already running. Callers disable their triggers instead of
+                relying on this.
+        """
+        if self.busy:
+            raise RuntimeError("A background task is already running.")
+
+        thread = QThread()
+        worker = Worker(fn, *args, **kwargs)
+        worker.moveToThread(thread)
+
+        thread.started.connect(worker.run)
+
+        # Route through this object's slots so delivery is queued onto the UI thread; only then
+        # are the caller's plain callables safe to invoke.
+        self._on_finished = on_finished
+        self._on_failed = on_failed
+        self._on_progress = on_progress
+        worker.finished.connect(self._relay_finished)
+        worker.failed.connect(self._relay_failed)
+        worker.progress.connect(self._relay_progress)
+
+        worker.done.connect(thread.quit)
+        worker.done.connect(worker.deleteLater)
+        thread.finished.connect(thread.deleteLater)
+        thread.finished.connect(self._clear)
+
+        self._thread, self._worker = thread, worker
+        thread.start()
+        return worker
+
+    # ------------------------------------------------------------------ UI-thread relays
+
+    @Slot(object)
+    def _relay_finished(self, result: Any) -> None:
+        """Runs on the UI thread. Re-emit, then call the caller's success handler."""
+        self.finished.emit(result)
+        if self._on_finished is not None:
+            self._on_finished(result)
+
+    @Slot(str, str)
+    def _relay_failed(self, message: str, trace: str) -> None:
+        """Runs on the UI thread. Re-emit, then call the caller's failure handler."""
+        self.failed.emit(message, trace)
+        if self._on_failed is not None:
+            self._on_failed(message, trace)
+
+    @Slot(int, str)
+    def _relay_progress(self, percent: int, message: str) -> None:
+        """Runs on the UI thread. Re-emit, then call the caller's progress handler."""
+        self.progress.emit(percent, message)
+        if self._on_progress is not None:
+            self._on_progress(percent, message)
+
+    def cancel(self) -> None:
+        """Ask the running task to stop."""
+        if self._worker is not None:
+            self._worker.cancel()
+
+    def wait(self, timeout_ms: int = 5000) -> None:
+        """Block until the current task finishes. Used on window close."""
+        if self._thread is not None and self._thread.isRunning():
+            self._thread.quit()
+            self._thread.wait(timeout_ms)
+
+    def _clear(self) -> None:
+        """Drop references and per-task callbacks once the thread is done."""
+        self._thread = None
+        self._worker = None
+        self._on_finished = None
+        self._on_failed = None
+        self._on_progress = None