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

custom_widgets_pro/datatable/grouping.py

@@ -0,0 +1,309 @@
+########################################################################
+## SPINN DESIGN CODE
+# WEBSITE: customwidgets.org
+########################################################################
+"""Grouping / aggregation engine for DataTable Pro.
+
+Pure Python - no Qt - so it is unit-testable on its own and the Qt model
+(virtual_model.VirtualDataTableModel) is a thin adapter over it.
+
+The engine turns a flat list of row dicts into a **grouped outline**: an ordered
+list of *visible entries* where each entry is either a ``GroupRow`` (a group
+header carrying the group value, a row count and per-column aggregates) or a
+plain data-row dict. Nested grouping (group-by several keys) produces nested
+headers; each header can be expanded or collapsed independently.
+
+This is the "flat outline" strategy (headers interleaved with data rows in one
+flat list) rather than a Qt tree model, so the whole DataTable Pro chain -
+frozen-column overlay, the QTableView, the sort/filter proxy - keeps working
+unchanged; only the model's row set changes shape.
+
+Grouping is an aggregate-over-the-whole-result operation, so the caller
+materialises the current (sorted/filtered) result before grouping; when grouping
+is cleared the table returns to its lazy/virtualized flat mode.
+
+Aggregates: a spec maps a column key to a reducer - one of the names in
+``AGGREGATORS`` (sum/avg/count/min/max/first/last) or any callable
+``reducer(values) -> result`` over the list of that column's raw values in the
+group.
+"""
+
+AGGREGATORS = ("sum", "avg", "mean", "count", "min", "max", "first", "last")
+
+
+def _is_number(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def aggregate(reducer, values):
+    """Reduce a list of raw cell values to a single aggregate.
+
+    ``reducer`` is a name from AGGREGATORS or a callable. ``count`` counts all
+    rows (including ones whose value is None); every other reducer ignores
+    Nones. Returns None when there is nothing to reduce (except sum -> 0 and
+    count -> len).
+    """
+    if callable(reducer):
+        return reducer(list(values))
+    name = str(reducer).lower()
+    if name == "count":
+        return len(values)
+    non_null = [v for v in values if v is not None]
+    nums = [v for v in non_null if _is_number(v)]
+    if name == "sum":
+        return sum(nums) if nums else 0
+    if name in ("avg", "mean"):
+        return (sum(nums) / len(nums)) if nums else None
+    if name in ("min", "max"):
+        if not non_null:
+            return None
+        try:
+            return min(non_null) if name == "min" else max(non_null)
+        except TypeError:                       # mixed, non-orderable types
+            return None
+    if name == "first":
+        return non_null[0] if non_null else None
+    if name == "last":
+        return non_null[-1] if non_null else None
+    raise ValueError("unknown aggregate %r" % (reducer,))
+
+
+def _hkey(value):
+    """A hashable stand-in for a (possibly unhashable) group value, used for
+    path identity. The raw value is kept separately for display."""
+    try:
+        hash(value)
+        return value
+    except TypeError:
+        return ("\0unhashable", repr(value))
+
+
+class GroupRow(object):
+    """A group-header visible entry.
+
+    depth      0-based nesting level (0 = outermost group key).
+    key        the column key this level groups by.
+    keyTitle   that column's display title.
+    value      the raw group value (what ``key`` equals for this group).
+    count      number of data rows under this group (all descendants).
+    aggregates {column_key: aggregate_value} for the configured aggregate spec.
+    path       hashable identity tuple from the root to this group.
+    expanded   whether this group is currently expanded.
+    """
+
+    __slots__ = ("depth", "key", "keyTitle", "value", "count",
+                 "aggregates", "path", "expanded")
+
+    def __init__(self, depth, key, keyTitle, value, count, aggregates, path,
+                 expanded):
+        self.depth = depth
+        self.key = key
+        self.keyTitle = keyTitle
+        self.value = value
+        self.count = count
+        self.aggregates = aggregates
+        self.path = path
+        self.expanded = expanded
+
+    def __repr__(self):
+        return ("GroupRow(depth=%d, key=%r, value=%r, count=%d, expanded=%r)"
+                % (self.depth, self.key, self.value, self.count, self.expanded))
+
+
+class _Node(object):
+    __slots__ = ("depth", "key", "keyTitle", "value", "path",
+                 "children", "leaves", "aggregates", "count")
+
+
+class GroupingEngine(object):
+    """Builds and maintains the grouped outline for a set of rows.
+
+    keys        ordered list of column keys to group by (outer -> inner).
+    aggregates  {column_key: reducer} spec (reducer name or callable).
+    titles      optional {column_key: title} for header labels.
+    """
+
+    def __init__(self, keys, aggregates=None, titles=None):
+        self._keys = [k for k in (keys or [])]
+        self._aggregates = dict(aggregates or {})
+        self._titles = dict(titles or {})
+        self._collapsed = set()          # set of node paths that are collapsed
+        self._roots = []                 # top-level _Node list
+        self._nodes = {}                 # path -> _Node
+        self.visible = []                # flat list: GroupRow | row-dict
+        self._rows = []
+
+    # ------------------------------------------------------------------ #
+    ## Configuration / (re)build
+    # ------------------------------------------------------------------ #
+    def keys(self):
+        return list(self._keys)
+
+    def setRows(self, rows):
+        """(Re)build the whole outline from ``rows``. Collapse state is reset."""
+        self._rows = list(rows or [])
+        self._collapsed = set()
+        self._buildTree()
+        self._rebuildVisible()
+
+    def _title(self, key):
+        return self._titles.get(key, key)
+
+    def _aggregatesFor(self, rows):
+        out = {}
+        for col_key, reducer in self._aggregates.items():
+            out[col_key] = aggregate(reducer, [r.get(col_key) for r in rows])
+        return out
+
+    def _buildTree(self):
+        self._nodes = {}
+        self._roots = self._buildLevel(self._rows, self._keys, 0, ())
+
+    def _buildLevel(self, rows, keys, depth, parent_path):
+        key = keys[0]
+        title = self._title(key)
+        order = []                       # first-seen group order (stable)
+        buckets = {}                     # hkey -> (raw_value, [rows])
+        for r in rows:
+            value = r.get(key)
+            hk = _hkey(value)
+            bucket = buckets.get(hk)
+            if bucket is None:
+                buckets[hk] = (value, [r])
+                order.append(hk)
+            else:
+                bucket[1].append(r)
+        nodes = []
+        deeper = keys[1:]
+        for hk in order:
+            value, grp_rows = buckets[hk]
+            path = parent_path + (hk,)
+            node = _Node()
+            node.depth = depth
+            node.key = key
+            node.keyTitle = title
+            node.value = value
+            node.path = path
+            node.count = len(grp_rows)
+            node.aggregates = self._aggregatesFor(grp_rows)
+            if deeper:
+                node.children = self._buildLevel(grp_rows, deeper, depth + 1, path)
+                node.leaves = None
+            else:
+                node.children = None
+                node.leaves = grp_rows
+            self._nodes[path] = node
+            nodes.append(node)
+        return nodes
+
+    def _groupRow(self, node):
+        return GroupRow(node.depth, node.key, node.keyTitle, node.value,
+                        node.count, node.aggregates, node.path,
+                        node.path not in self._collapsed)
+
+    def _rebuildVisible(self):
+        out = []
+        for node in self._roots:
+            self._flatten(node, out)
+        self.visible = out
+
+    def _flatten(self, node, out):
+        out.append(self._groupRow(node))
+        if node.path in self._collapsed:
+            return
+        if node.children is not None:
+            for child in node.children:
+                self._flatten(child, out)
+        else:
+            out.extend(node.leaves)
+
+    # ------------------------------------------------------------------ #
+    ## Expand / collapse
+    # ------------------------------------------------------------------ #
+    def isExpanded(self, path):
+        return path not in self._collapsed
+
+    def _descendantCount(self, node):
+        """Number of visible rows shown *below* ``node``'s header when the node
+        itself is expanded, honouring the collapse state of its descendants."""
+        if node.children is None:
+            return len(node.leaves)
+        total = 0
+        for child in node.children:
+            total += 1                                  # the child's own header
+            if child.path not in self._collapsed:
+                total += self._descendantCount(child)
+        return total
+
+    def _visibleIndexOf(self, path):
+        for i, entry in enumerate(self.visible):
+            if isinstance(entry, GroupRow) and entry.path == path:
+                return i
+        return -1
+
+    def planToggle(self, path):
+        """Describe the row change a toggle of ``path`` will make, WITHOUT
+        applying it: ``(kind, start, count)`` where kind is "insert" (the group
+        is collapsed and will expand) or "remove" (expanded, will collapse),
+        start is the first affected visible row, count the number of rows.
+
+        Returns None if ``path`` is not a known group. Call applyToggle() to
+        commit the change (between a Qt begin/endInsert|RemoveRows bracket)."""
+        node = self._nodes.get(path)
+        if node is None:
+            return None
+        header_idx = self._visibleIndexOf(path)
+        if header_idx < 0:
+            return None
+        count = self._descendantCount(node)
+        kind = "insert" if path in self._collapsed else "remove"
+        return kind, header_idx + 1, count
+
+    def applyToggle(self, path):
+        """Flip the collapse state of ``path`` and rebuild the visible list.
+        Returns the new expanded state (True if now expanded)."""
+        if path in self._collapsed:
+            self._collapsed.discard(path)
+            expanded = True
+        else:
+            self._collapsed.add(path)
+            expanded = False
+        self._rebuildVisible()
+        return expanded
+
+    def toggle(self, path):
+        """Convenience (non-Qt callers): plan + apply in one step. Returns the
+        change descriptor from planToggle."""
+        plan = self.planToggle(path)
+        if plan is not None:
+            self.applyToggle(path)
+        return plan
+
+    def setAllExpanded(self, expanded):
+        """Expand (True) or collapse (False) every group."""
+        if expanded:
+            self._collapsed = set()
+        else:
+            self._collapsed = set(self._nodes.keys())
+        self._rebuildVisible()
+
+    # ------------------------------------------------------------------ #
+    ## Aggregate refresh (after an in-place edit of a data row)
+    # ------------------------------------------------------------------ #
+    def recomputeAggregates(self):
+        """Recompute every group's count + aggregates from its current leaf
+        rows (leaves are the same dict objects passed in, so an in-place edit is
+        reflected). Cheap relative to a full rebuild and keeps collapse state."""
+        for node in self._nodes.values():
+            leaves = self._leavesOf(node)
+            node.count = len(leaves)
+            node.aggregates = self._aggregatesFor(leaves)
+        self._rebuildVisible()
+
+    def _leavesOf(self, node):
+        if node.children is None:
+            return list(node.leaves)
+        out = []
+        for child in node.children:
+            out.extend(self._leavesOf(child))
+        return out

custom_widgets_pro/datatable/pivot.py

@@ -0,0 +1,100 @@
+########################################################################
+## SPINN DESIGN CODE
+# WEBSITE: customwidgets.org
+########################################################################
+"""Pivot (cross-tab) transform for DataTable Pro.
+
+Pure Python - no Qt. A pivot reshapes a flat row set into a matrix: one output
+row per distinct combination of the *index* (row-dimension) keys, one output
+column per distinct value of a single *columns* key, and each cell is the
+*values* key aggregated over the rows in that (row, column) bucket. An optional
+row-total column aggregates across the whole output row.
+
+Because the result is just another flat ``(columns, rows)`` pair, the widget
+renders a pivot through the ordinary table path - no special model. The value
+columns are keyed with a namespaced prefix so they can never collide with a real
+data key.
+
+Reuses the grouping module's ``aggregate`` reducer (sum/avg/count/min/max/
+first/last or a callable).
+"""
+from .grouping import aggregate
+
+#: Prefix for generated pivot value-column keys (namespaced with a NUL so it
+#: cannot clash with a genuine row-dict key).
+PIVOT_COL_PREFIX = "\0pivot\0"
+TOTAL_KEY = PIVOT_COL_PREFIX + "__total__"
+
+
+def _safe_key(value):
+    """A total-orderable sort key for an arbitrary cell value (Nones last)."""
+    return (value is None, str(value))
+
+
+def _distinct_sorted(values):
+    seen = set()
+    out = []
+    for v in values:
+        k = _safe_key(v)
+        if k not in seen:
+            seen.add(k)
+            out.append(v)
+    return sorted(out, key=_safe_key)
+
+
+def pivot_table(rows, index, columns, values, agg="sum", totals=True,
+                fill=None, total_title="Total"):
+    """Build a pivot table.
+
+    rows         iterable of row dicts.
+    index        row-dimension key, or a list of keys (nested row headers).
+    columns      a single key whose distinct values become output columns.
+    values       the key aggregated into each cell.
+    agg          reducer name or callable (see grouping.aggregate).
+    totals       add a trailing per-row total column.
+    fill         value for an empty (row, column) cell (default None).
+    total_title  header text for the total column.
+
+    Returns ``(col_defs, result_rows)`` where col_defs is a list of column
+    descriptor dicts (index columns keep their key as title; value columns are
+    titled by their column value) and result_rows is a list of row dicts."""
+    rows = list(rows or [])
+    index_keys = [index] if isinstance(index, str) else list(index)
+
+    col_values = _distinct_sorted(r.get(columns) for r in rows)
+
+    col_defs = [{"key": k, "title": k} for k in index_keys]
+    value_cols = []
+    for cv in col_values:
+        key = PIVOT_COL_PREFIX + str(cv)
+        title = "" if cv is None else str(cv)
+        col_defs.append({"key": key, "title": title, "type": "number"})
+        value_cols.append((key, _safe_key(cv)))
+    if totals:
+        col_defs.append({"key": TOTAL_KEY, "title": total_title, "type": "number"})
+
+    # bucket rows by the index-key tuple, in a deterministic sorted order
+    order = []
+    buckets = {}
+    for r in rows:
+        tup = tuple(r.get(k) for k in index_keys)
+        hk = tuple(_safe_key(x) for x in tup)
+        bucket = buckets.get(hk)
+        if bucket is None:
+            buckets[hk] = (tup, [r])
+            order.append(hk)
+        else:
+            bucket[1].append(r)
+    order.sort()
+
+    result = []
+    for hk in order:
+        tup, grp = buckets[hk]
+        out = {k: tup[i] for i, k in enumerate(index_keys)}
+        for key, cv_key in value_cols:
+            cell = [r.get(values) for r in grp if _safe_key(r.get(columns)) == cv_key]
+            out[key] = aggregate(agg, cell) if cell else fill
+        if totals:
+            out[TOTAL_KEY] = aggregate(agg, [r.get(values) for r in grp])
+        result.append(out)
+    return col_defs, result

custom_widgets_pro/datatable/provider.py

@@ -0,0 +1,98 @@
+########################################################################
+## SPINN DESIGN CODE
+# WEBSITE: customwidgets.org
+########################################################################
+"""Data providers for DataTable Pro virtualization.
+
+A DataProvider supplies rows to the virtualized model in windows, so the model
+never holds more than what has been scrolled to. Sort and filter are pushed
+DOWN to the provider - it returns rows already sorted/filtered from the source
+(DB, API, ...) - so ordering and filtering are correct across the whole dataset,
+not just the loaded window.
+
+  sort   : (column_key, ascending) tuple, or None
+  filter : free-text string, or None
+"""
+import inspect
+
+
+class DataProvider(object):
+    """Abstract row source. Subclass and implement ``fetch``; override
+    ``totalRowCount`` when the (filtered) total is known. Return None from
+    ``totalRowCount`` for streaming/unknown sources (fetch is then called until
+    it returns a short/empty window)."""
+
+    def totalRowCount(self, filter=None):
+        return None
+
+    def fetch(self, offset, limit, sort=None, filter=None):
+        """Return up to ``limit`` row dicts starting at ``offset`` of the
+        sorted+filtered result. Return a short/empty list at the end."""
+        raise NotImplementedError
+
+
+class ListDataProvider(DataProvider):
+    """In-memory provider with full sort/filter push-down. A working reference
+    (and handy for tests / feeding a large materialised dataset lazily). The
+    sorted+filtered view is memoised per (sort, filter)."""
+
+    def __init__(self, rows):
+        self._rows = list(rows or [])
+        self._cache_key = object()      # sentinel: nothing cached yet
+        self._cache = None
+
+    @staticmethod
+    def _matches(row, needle):
+        return any(needle in str(v).lower() for v in row.values())
+
+    def _resolved(self, sort, filter):
+        key = (sort, filter)
+        if key == self._cache_key:
+            return self._cache
+        if filter:
+            needle = str(filter).lower()
+            rows = [r for r in self._rows if self._matches(r, needle)]
+        else:
+            rows = list(self._rows)
+        if sort:
+            col, ascending = sort
+            rows.sort(key=lambda r: (r.get(col) is None, r.get(col)),
+                      reverse=not ascending)
+        self._cache_key = key
+        self._cache = rows
+        return rows
+
+    def totalRowCount(self, filter=None):
+        return len(self._resolved(None, filter))
+
+    def fetch(self, offset, limit, sort=None, filter=None):
+        return self._resolved(sort, filter)[offset:offset + limit]
+
+
+class CallableDataProvider(DataProvider):
+    """Adapt plain callables. ``fetch_fn`` may accept ``(offset, limit)`` or
+    ``(offset, limit, sort, filter)`` - the arity is detected. ``total`` is an
+    int, a zero-arg callable, or None for streaming."""
+
+    def __init__(self, fetch_fn, total=None):
+        self._fetch = fetch_fn
+        self._total = total
+        try:
+            params = list(inspect.signature(fetch_fn).parameters.values())
+            if any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in params):
+                self._arity = 4
+            else:
+                self._arity = sum(
+                    1 for p in params
+                    if p.kind in (inspect.Parameter.POSITIONAL_ONLY,
+                                  inspect.Parameter.POSITIONAL_OR_KEYWORD))
+        except (ValueError, TypeError):
+            self._arity = 2
+
+    def totalRowCount(self, filter=None):
+        return self._total() if callable(self._total) else self._total
+
+    def fetch(self, offset, limit, sort=None, filter=None):
+        if self._arity >= 4:
+            return list(self._fetch(offset, limit, sort, filter) or [])
+        return list(self._fetch(offset, limit) or [])