spacr.qt.widgets.sortable_table

Consistent three-state sorting for Qt tables and trees.

The sorting cycle is:

• the first click on a column sorts it descending;

• the second click sorts it ascending;

• the third click clears the sort and restores the original row order;

• the fourth click starts the cycle again.

Formatted numeric values, including scientific notation, are sorted numerically. Missing values such as blank cells, NaN, pandas.NA, and NaT sort after populated values in both directions.

Build cells with table_item() or tree_item() and pass the view to install_sorting():

self.table = QTableWidget(0, 3)
install_sorting(self.table)
...
self.table.setItem(row, 0, table_item(coefficient))

install_sorting() temporarily suspends sorting while a view is repopulated, preventing Qt from moving partially populated rows, and restores the selected ordering after the update completes.

Classes

SortableProxyModel	Proxy model providing semantic sorting for model-backed views.
SortableTableItem	Table item with semantic numeric and missing-value sorting.
SortableTreeItem	Tree item with semantic sorting for the selected column.

Functions

install_sorting(view)	Install three-state semantic sorting on view and return it.
is_missing(→ bool)	Return whether value is empty or a recognized missing sentinel.
numeric_value(→ Optional[float])	Return the numeric value represented by a cell, if one is present.
restore_natural_order(→ None)	Restore rows to the order in which the view was populated.
sort_key_of(value)	Return the (is_missing, numeric_value) comparison key.
sorts_as_missing(→ bool)	Return whether value should sort as missing table data.
table_item(→ SortableTableItem)	Return a SortableTableItem for value and optional key.
tree_item(→ SortableTreeItem)	Return a SortableTreeItem using QTreeWidgetItem arguments.

Module Contents

class spacr.qt.widgets.sortable_table.SortableProxyModel

Bases: PySide6.QtCore.QSortFilterProxyModel

Proxy model providing semantic sorting for model-backed views.

Numeric values sort numerically, missing values follow populated values in either direction, and the initial header order is descending. This is the model-backed equivalent of SortableTableItem.

headerData(section, orientation, role=Qt.DisplayRole)

One header label, taken from the source model.

Parameters:

• section – the row or column number.

• orientation – which header.

• role – the Qt display role.

Returns:

the label, or None.

lessThan(left, right)

Order two cells, comparing what they MEAN rather than how they read.

A column of numbers rendered as text sorts 10 before 9 under a string comparison, which is the bug this exists to prevent.

Parameters:

• left – the left cell’s index.

• right – the right cell’s index.

Returns:

True when left sorts first.

class spacr.qt.widgets.sortable_table.SortableTableItem(value='', key=None)

Bases: _SortableMixin, PySide6.QtWidgets.QTableWidgetItem

Table item with semantic numeric and missing-value sorting.

Parameters:

• value – Cell value. Missing values are rendered as empty cells.

• key – Optional explicit numeric sort key for display text that cannot be parsed directly.

Create a table cell that sorts on a value rather than on its text.

Parameters:

• value – what the cell shows; a missing value renders blank.

• key – an explicit sort key, for a cell whose text does not order the way the value does – a formatted duration, say. None derives one from value.

setData(role, value)

Update the sort key when displayed or edited text changes.

Non-text roles do not modify the key, and editing does not change the item’s position in the table’s unsorted order.

Parameters:

• role – the Qt item data role; only DisplayRole and EditRole refresh the sort key, which then comes from SORT_KEY_ROLE when set and from the text otherwise.

• value – the data stored for role.

class spacr.qt.widgets.sortable_table.SortableTreeItem(*args, **kwargs)

Bases: _SortableMixin, PySide6.QtWidgets.QTreeWidgetItem

Tree item with semantic sorting for the selected column.

See SortableTableItem. A tree item contains multiple columns, so its comparison key is resolved from the column currently being sorted.

Create a tree row that sorts on its values and remembers its insertion order.

The serial is what restores the original order when sorting is turned off – a tree has no unsorted model to fall back to.

Parameters:

• args – passed through to QTreeWidgetItem.

• kwargs – passed through to QTreeWidgetItem.

__lt__(other)

Order two rows by value, keeping missing values last in both directions.

While the original order is being restored this compares insertion serials instead, which is what lets “no sort” mean the order the rows arrived in.

Parameters:

other – the row to compare against; a plain QTreeWidgetItem is compared on its text, and anything without one is declined so Python can try the reflected comparison.

Returns:

True when this row sorts first.

spacr.qt.widgets.sortable_table.install_sorting(view)

Install three-state semantic sorting on view and return it.

Accepts a QTableWidget, QTreeWidget, or QTableView. A QTableView is wrapped in SortableProxyModel; call this function immediately after setModel and obtain the view’s selection model afterwards.

Parameters:

view – the view to make sortable; a view with no header is returned untouched, and one already installed only has its initial order re-stamped.

spacr.qt.widgets.sortable_table.is_missing(value) → bool

Return whether value is empty or a recognized missing sentinel.

This includes None, blank strings, NaN, pandas NA, and NaT. Array-like values are not treated as individual missing cells.

Parameters:

value – a cell value of any type.

spacr.qt.widgets.sortable_table.numeric_value(text) → float | None

Return the numeric value represented by a cell, if one is present.

Accepted formats include ordinary numbers, scientific notation, comma thousands separators, percentages, and a unit separated from the value by a space, such as "3.2 s". Alphanumeric identifiers such as "TP53" return None. Use SORT_KEY_ROLE to provide an explicit numeric key for other display formats.

Parameters:

text – cell text or number; None, booleans, blanks and NaN give None.

spacr.qt.widgets.sortable_table.restore_natural_order(view) → None

Restore rows to the order in which the view was populated.

This completes the third state of the sorting cycle after Qt clears the header’s sort indicator.

spacr.qt.widgets.sortable_table.sort_key_of(value)

Return the (is_missing, numeric_value) comparison key.

Parameters:

value – a cell value; see sorts_as_missing() and numeric_value().

spacr.qt.widgets.sortable_table.sorts_as_missing(value) → bool

Return whether value should sort as missing table data.

Parameters:

value – a cell value; missing per is_missing(), or a placeholder string such as "n/a", "-" or "?" (case-insensitive), sorts as missing.

spacr.qt.widgets.sortable_table.table_item(value='', key=None) → SortableTableItem

Return a SortableTableItem for value and optional key.

spacr.qt.widgets.sortable_table.tree_item(*args, **kwargs) → SortableTreeItem

Return a SortableTreeItem using QTreeWidgetItem arguments.