QT-PyQt-PySide-Custom-Widgets-Pro 1.1.0__py3-none-any.whl

custom_widgets_pro/datatable/virtual_model.py

@@ -0,0 +1,451 @@
+########################################################################
+## SPINN DESIGN CODE
+# WEBSITE: customwidgets.org
+########################################################################
+"""Virtualized (lazy) table model for DataTable Pro.
+
+Subclasses the free core's ``QCustomDataTableModel`` so all display formatting,
+alignment and the ``Qt.UserRole`` raw-value sort seam are inherited. It holds
+only the rows fetched so far (in the base's ``_rows`` cache) and pulls more from
+a DataProvider on demand via Qt's ``canFetchMore`` / ``fetchMore`` protocol - so
+scrolling a 100k+ or streaming source loads windows lazily instead of
+materialising everything up front.
+
+QSortFilterProxyModel forwards canFetchMore/fetchMore to its source, so this
+model works unchanged inside the free table's model->proxy->view chain (with
+pagination disabled).
+"""
+from qtpy.QtCore import Qt, QModelIndex, Signal
+from qtpy.QtGui import QBrush, QColor, QFont
+
+from Custom_Widgets.QCustomDataTable import QCustomDataTableModel
+
+from .grouping import GroupingEngine, GroupRow
+
+#: Custom item-data role: on a grouped model, returns the ``GroupRow`` for a
+#: group-header row (or None for data rows). Lets the widget detect header
+#: clicks and tests introspect the outline without touching internals.
+GroupRole = Qt.UserRole + 1000
+
+
+class VirtualDataTableModel(QCustomDataTableModel):
+    cellEdited = Signal(int, str, object, object)          # row, key, old, new
+    validationFailed = Signal(int, str, object, str)       # row, key, value, message
+
+    def __init__(self, columns=None, provider=None, chunkSize=200, parent=None):
+        super().__init__(columns, [], parent)
+        self._provider = None
+        self._total = None
+        self._exhausted = True
+        self._chunk = max(1, int(chunkSize))
+        self._sort = None          # (column_key, ascending) pushed to the provider
+        self._filter = None        # free-text filter pushed to the provider
+        self._editableKeys = set()
+        self._validators = {}
+        self._engine = None        # GroupingEngine when grouping is active
+        self._groupBg = QColor("#f1f5f9")     # neutral defaults; token-set by the
+        self._groupFg = QColor("#0f172a")     # widget via setGroupColors()
+        if provider is not None:
+            self.setProvider(provider)
+
+    # ------------------------------------------------------------------ #
+    ## Inline editing
+    # ------------------------------------------------------------------ #
+    def setEditableColumns(self, keys):
+        self._editableKeys = set(keys or [])
+        if self._rows:
+            self.dataChanged.emit(self.index(0, 0),
+                                  self.index(self.rowCount() - 1, self.columnCount() - 1))
+
+    def editableColumns(self):
+        return set(self._editableKeys)
+
+    def setValidator(self, key, fn):
+        if fn is None:
+            self._validators.pop(key, None)
+        else:
+            self._validators[key] = fn
+
+    def rowCount(self, parent=QModelIndex()):
+        if parent.isValid():
+            return 0
+        if self._engine is not None:
+            return len(self._engine.visible)
+        return super().rowCount(parent)
+
+    def flags(self, index):
+        # Columns are resolved through _dataColumnAt, never by indexing
+        # self._columns raw: with setSelectable(True) the view gains a
+        # synthetic select column, shifting every data column by one and
+        # putting the last view column past len(self._columns). The raw
+        # lookup raised IndexError inside a C++ virtual call on every paint
+        # of that column — and an exception thrown across the binding there
+        # corrupts state and segfaults later, far from this line.
+        if not index.isValid():
+            return Qt.NoItemFlags
+        row, col_idx = index.row(), index.column()
+        if not (0 <= col_idx < self.columnCount()):
+            return Qt.NoItemFlags
+        col = self._dataColumnAt(col_idx)      # None for select/actions
+        if self._engine is not None:
+            if not (0 <= row < len(self._engine.visible)):
+                return Qt.NoItemFlags
+            entry = self._engine.visible[row]
+            if isinstance(entry, GroupRow):
+                return Qt.ItemIsEnabled                 # clickable, not selectable
+            if col is None:
+                return super().flags(index)             # synthetic column
+            base = Qt.ItemIsEnabled | Qt.ItemIsSelectable
+            if col.key in self._editableKeys:
+                return base | (Qt.ItemIsUserCheckable if col.type == "bool"
+                               else Qt.ItemIsEditable)
+            return base
+        base = super().flags(index)
+        if col is None:
+            return base
+        if col.key in self._editableKeys:
+            if col.type == "bool":
+                return base | Qt.ItemIsUserCheckable
+            return base | Qt.ItemIsEditable
+        return base
+
+    def data(self, index, role=Qt.DisplayRole):
+        if self._engine is not None:
+            return self._groupedData(index, role)
+        if index.isValid():
+            col = self._dataColumnAt(index.column())   # None for select/actions
+            if col is not None and col.type == "bool" and col.key in self._editableKeys:
+                if role == Qt.CheckStateRole and 0 <= index.row() < len(self._rows):
+                    return Qt.Checked if self._rows[index.row()].get(col.key) else Qt.Unchecked
+                if role in (Qt.DisplayRole, Qt.EditRole):
+                    return ""                              # show only the checkbox
+        return super().data(index, role)
+
+    def setData(self, index, value, role=Qt.EditRole):
+        if not index.isValid():
+            return False
+        row, col_idx = index.row(), index.column()
+        col = self._dataColumnAt(col_idx)      # None for select/actions
+        if col is None:
+            return False
+
+        # Resolve the target row dict (grouped: skip headers; flat: _rows[row]).
+        if self._engine is not None:
+            if not (0 <= row < len(self._engine.visible)):
+                return False
+            entry = self._engine.visible[row]
+            if isinstance(entry, GroupRow):
+                return False
+            record = entry
+        else:
+            if not (0 <= row < len(self._rows)):
+                return False
+            record = self._rows[row]
+
+        if col.key not in self._editableKeys:
+            return False
+
+        if role == Qt.CheckStateRole and col.type == "bool":
+            try:
+                new = int(value) == int(Qt.Checked)
+            except (TypeError, ValueError):
+                new = bool(value)
+        elif role == Qt.EditRole:
+            new = self._coerce(col, value)
+        else:
+            return False
+
+        # cellEdited reports the underlying (flat) row index for a stable contract.
+        src_row = self._rows.index(record) if record in self._rows else row
+
+        validator = self._validators.get(col.key)
+        if validator is not None:
+            result = validator(new)
+            if result is not True:
+                msg = result if isinstance(result, str) else "invalid value"
+                self.validationFailed.emit(src_row, col.key, new, msg)
+                return False
+
+        old = record.get(col.key)
+        if new == old:
+            return True
+        record[col.key] = new
+        self.dataChanged.emit(index, index,
+                              [Qt.DisplayRole, Qt.EditRole, Qt.CheckStateRole])
+        self.cellEdited.emit(src_row, col.key, old, new)
+        if self._engine is not None:
+            # an edited value may change a group's aggregates; refresh headers.
+            self._engine.recomputeAggregates()
+            self.dataChanged.emit(self.index(0, 0),
+                                  self.index(self.rowCount() - 1,
+                                             self.columnCount() - 1))
+        return True
+
+    # ------------------------------------------------------------------ #
+    ## Grouping / aggregation
+    # ------------------------------------------------------------------ #
+    def setGrouping(self, keys, aggregates=None):
+        """Group the currently-loaded rows by ``keys`` (a list of column keys),
+        computing the ``aggregates`` spec ({column_key: reducer}) per group.
+        Pass an empty ``keys`` to clear grouping and return to the flat model.
+
+        Grouping operates on the rows loaded so far, so the caller (the widget's
+        groupBy) fully materialises the current sorted/filtered result first."""
+        keys = list(keys or [])
+        self.beginResetModel()
+        if not keys:
+            self._engine = None
+        else:
+            titles = {c.key: c.title for c in self._columns}
+            engine = GroupingEngine(keys, aggregates or {}, titles=titles)
+            engine.setRows(self._rows)
+            self._engine = engine
+        self.endResetModel()
+
+    def isGrouped(self):
+        return self._engine is not None
+
+    def groupingEngine(self):
+        return self._engine
+
+    def setGroupColors(self, background, foreground):
+        """Set the group-header background / text colours (QColor or any value
+        QColor accepts). The widget derives these from the design tokens."""
+        self._groupBg = QColor(background)
+        self._groupFg = QColor(foreground)
+        if self._engine is not None and self._engine.visible:
+            self.dataChanged.emit(self.index(0, 0),
+                                  self.index(self.rowCount() - 1,
+                                             self.columnCount() - 1))
+
+    def toggleGroupRow(self, row):
+        """Expand/collapse the group whose header is at visible ``row``. Emits
+        the minimal insert/remove so the view animates instead of resetting.
+        Returns ``(path, expanded)`` or None if ``row`` is not a header."""
+        if self._engine is None:
+            return None
+        vis = self._engine.visible
+        if not (0 <= row < len(vis)):
+            return None
+        entry = vis[row]
+        if not isinstance(entry, GroupRow):
+            return None
+        plan = self._engine.planToggle(entry.path)
+        if plan is None:
+            return None
+        kind, start, count = plan
+        if count <= 0:
+            self._engine.applyToggle(entry.path)
+        elif kind == "remove":
+            self.beginRemoveRows(QModelIndex(), start, start + count - 1)
+            self._engine.applyToggle(entry.path)
+            self.endRemoveRows()
+        else:
+            self.beginInsertRows(QModelIndex(), start, start + count - 1)
+            self._engine.applyToggle(entry.path)
+            self.endInsertRows()
+        self.dataChanged.emit(self.index(row, 0),
+                              self.index(row, self.columnCount() - 1))
+        return (entry.path, self._engine.isExpanded(entry.path))
+
+    def setAllGroupsExpanded(self, expanded):
+        if self._engine is None:
+            return
+        self.beginResetModel()
+        self._engine.setAllExpanded(bool(expanded))
+        self.endResetModel()
+
+    # ----- grouped data() helpers ----------------------------------------
+    def _groupedData(self, index, role):
+        if not index.isValid():
+            return None
+        row, col_idx = index.row(), index.column()
+        vis = self._engine.visible
+        if not (0 <= row < len(vis)) or not (0 <= col_idx < self.columnCount()):
+            return None
+        entry = vis[row]
+        # None for the synthetic select/actions columns (see flags()).
+        column = self._dataColumnAt(col_idx)
+        if isinstance(entry, GroupRow):
+            return self._groupHeaderData(entry, col_idx, column, role)
+        return self._groupChildData(entry, col_idx, column, role)
+
+    def _groupHeaderData(self, entry, col_idx, column, role):
+        if role == GroupRole:
+            return entry
+        # The outline label lives in the first DATA column — with a select
+        # column present that is view column 1, not 0.
+        labelCol = self._selOffset()
+        if role in (Qt.DisplayRole, Qt.EditRole):
+            if col_idx == labelCol:
+                indent = "    " * entry.depth
+                arrow = "▾ " if entry.expanded else "▸ "   # down / right
+                value = self._displayForKey(entry.key, entry.value)
+                return "%s%s%s: %s (%d)" % (indent, arrow, entry.keyTitle,
+                                            value, entry.count)
+            if column is not None and column.key in entry.aggregates:
+                return self._display(column, entry.aggregates[column.key])
+            return ""
+        if role == Qt.FontRole:
+            font = QFont()
+            font.setBold(True)
+            return font
+        if role == Qt.BackgroundRole:
+            return QBrush(self._groupBg)
+        if role == Qt.ForegroundRole:
+            return QBrush(self._groupFg)
+        if role == Qt.TextAlignmentRole:
+            if column is None or col_idx == labelCol:
+                return int(Qt.AlignLeft | Qt.AlignVCenter)
+            align = column.align if column.align is not None else column.defaultAlign()
+            return int(align)
+        return None
+
+    def _groupChildData(self, record, col_idx, column, role):
+        if role == GroupRole:
+            return None
+        if column is None:
+            # Select/actions cells stay inert while grouped: their per-row
+            # state is keyed by flat row indices, which grouping reorders.
+            return None
+        value = record.get(column.key)
+        if column.type == "bool" and column.key in self._editableKeys:
+            if role == Qt.CheckStateRole:
+                return Qt.Checked if value else Qt.Unchecked
+            if role in (Qt.DisplayRole, Qt.EditRole):
+                return ""
+        if role in (Qt.DisplayRole, Qt.EditRole):
+            return self._display(column, value)
+        if role == Qt.TextAlignmentRole:
+            align = column.align if column.align is not None else column.defaultAlign()
+            return int(align)
+        if role == Qt.UserRole:
+            return value
+        return None
+
+    def _displayForKey(self, key, value):
+        for col in self._columns:
+            if col.key == key:
+                return self._display(col, value)
+        return "" if value is None else str(value)
+
+    @staticmethod
+    def _coerce(col, value):
+        if col.type == "number":
+            s = str(value).strip()
+            try:
+                return int(s) if s.lstrip("-").isdigit() else float(s)
+            except (TypeError, ValueError):
+                return value
+        if col.type == "bool":
+            return str(value).strip().lower() in ("1", "true", "yes", "y")
+        return str(value)
+
+    # ------------------------------------------------------------------ #
+    ## Provider wiring
+    # ------------------------------------------------------------------ #
+    def setProvider(self, provider):
+        self._provider = provider
+        self._reset()
+
+    def provider(self):
+        return self._provider
+
+    def _reset(self):
+        """Clear the loaded window and recompute the (filtered) total. Callers
+        prime the first window afterwards where a refresh is expected. Grouping
+        is dropped here (the row set is being rebuilt); the widget re-applies it
+        via _reapplyGrouping after the reload."""
+        self._engine = None
+        self.beginResetModel()
+        self._rows = []
+        self._total = (self._provider.totalRowCount(filter=self._filter)
+                       if self._provider is not None else None)
+        self._exhausted = self._provider is None
+        self.endResetModel()
+
+    # ------------------------------------------------------------------ #
+    ## Server-side sort / filter push-down
+    # ------------------------------------------------------------------ #
+    def setSort(self, column, order=Qt.AscendingOrder):
+        """Push a sort down to the provider by column index, then reload."""
+        if column is None or not (0 <= column < len(self._columns)):
+            self._sort = None
+        else:
+            self._sort = (self._columns[column].key, order == Qt.AscendingOrder)
+        self._reset()
+        if self.canFetchMore():
+            self.fetchMore()
+
+    def setFilter(self, text):
+        """Push a free-text filter down to the provider, then reload."""
+        self._filter = text or None
+        self._reset()
+        if self.canFetchMore():
+            self.fetchMore()
+
+    def sort(self, column, order=Qt.AscendingOrder):
+        # so a directly-bound view's header sort also pushes down
+        self.setSort(column, order)
+
+    def totalRowCount(self):
+        """Total rows in the source (loaded or not), or the loaded count when
+        the total is unknown/streaming."""
+        return self._total if self._total is not None else len(self._rows)
+
+    def loadedRowCount(self):
+        return len(self._rows)
+
+    # ------------------------------------------------------------------ #
+    ## Qt lazy-loading protocol
+    # ------------------------------------------------------------------ #
+    def canFetchMore(self, parent=QModelIndex()):
+        if self._engine is not None:
+            return False               # grouped rows are fully materialised
+        if parent.isValid() or self._provider is None or self._exhausted:
+            return False
+        if self._total is None:            # streaming / unknown total
+            return True
+        return len(self._rows) < self._total
+
+    def fetchMore(self, parent=QModelIndex()):
+        if not self.canFetchMore(parent):
+            return
+        offset = len(self._rows)
+        batch = list(self._provider.fetch(offset, self._chunk,
+                                          sort=self._sort, filter=self._filter) or [])
+        if not batch:
+            self._exhausted = True
+            return
+        self.beginInsertRows(QModelIndex(), offset, offset + len(batch) - 1)
+        self._rows.extend(batch)
+        self.endInsertRows()
+        if self._total is not None and len(self._rows) >= self._total:
+            self._exhausted = True
+
+    def iterAllRows(self, chunk=None):
+        """Yield every row of the current (sorted/filtered) result in windows,
+        without materialising all rows or disturbing the loaded view. Used by
+        export - 'what you see' = the current sort + filter."""
+        if self._provider is None:
+            for row in self._rows:
+                yield row
+            return
+        size = chunk or self._chunk
+        offset = 0
+        while True:
+            batch = list(self._provider.fetch(offset, size,
+                                              sort=self._sort, filter=self._filter) or [])
+            if not batch:
+                return
+            for row in batch:
+                yield row
+            offset += len(batch)
+
+    def fetchAll(self, cap=None):
+        """Eagerly load everything (or up to ``cap`` rows). For export or small
+        sources; defeats virtualization, so use deliberately."""
+        while self.canFetchMore():
+            self.fetchMore()
+            if cap is not None and len(self._rows) >= cap:
+                break

custom_widgets_pro/widgets/__init__.py

@@ -0,0 +1,7 @@
+"""Pro-only widgets.
+
+These ship compiled in the Pro wheel and are NOT in the free GPLv3 package.
+The free package keeps a stub at the same import path so Qt Designer .ui files
+that name Custom_Widgets.<Widget> still resolve, and so a free user gets an
+explanation instead of ModuleNotFoundError.
+"""