tabulous.widgets package

Module contents

class tabulous.widgets.GroupBy(data: Any = None, name: str | None = None, editable: bool = True, metadata: dict[str, Any] | None = None)

Bases: tabulous.widgets._table.TableBase

A group of tables.

Parameters

• data (DataFrameGroupBy like, optional) – Groupby data to add.

• name (str, optional) – Name of the table.

• metadata (dict, optional) – Metadata of the table.

• update (bool, default is False) – If True, update the table data if a table of same name exists.

property current_group

Current group ID.

class tabulous.widgets.MagicSpreadSheet(data: Any | None = None, *, name: str = '', editable: bool = True, label: str = None, tooltip: str | None = None, visible: bool | None = None, enabled: bool = True, gui_only: bool = False)

Bases: magicgui.widgets.bases._widget.Widget, tabulous.widgets._table.SpreadSheet

property native

Return native backend widget.

Note this is the widget that contains the layout, and not any parent widgets of this (e.g. a parent widget that is used to enable scroll bars)

class tabulous.widgets.MagicTable(data: Any | None = None, *, name: str = '', editable: bool = False, label: str = None, tooltip: str | None = None, visible: bool | None = None, enabled: bool = True, gui_only: bool = False)

Bases: magicgui.widgets.bases._widget.Widget, tabulous.widgets._table.Table

property native

Return native backend widget.

Note this is the widget that contains the layout, and not any parent widgets of this (e.g. a parent widget that is used to enable scroll bars)

class tabulous.widgets.SpreadSheet(data: Any = None, name: str | None = None, editable: bool = True, metadata: dict[str, Any] | None = None)

Bases: tabulous.widgets._table._DataFrameTableLayer

A table that behaves like a spreadsheet.

Parameters

• data (DataFrame like, optional) – Table data to add.

• name (str, optional) – Name of the table.

• editable (bool, default is False) – Whether the table is editable via UI.

• metadata (dict, optional) – Metadata of the table.

add_item_widget(row: int, column: int, widget)

Add a widget to a cell.

dtypes

class tabulous.widgets.Table(data: Any = None, name: str | None = None, editable: bool = True, metadata: dict[str, Any] | None = None)

Bases: tabulous.widgets._table._DataFrameTableLayer

A table implemented with type checking.

Parameters

• data (DataFrame like, optional) – Table data to add.

• name (str, optional) – Name of the table.

• editable (bool, default is False) – Whether the table is editable via UI.

• metadata (dict, optional) – Metadata of the table.

class tabulous.widgets.TableBase(data: Any = None, name: str | None = None, editable: bool = True, metadata: dict[str, Any] | None = None)

Bases: tabulous.widgets._keymap_abc.SupportKeyMap

The base class for a table layer.

add_overlay_widget(widget: QtW.QWidget | Widget, *, label: str = '', topleft: tuple[float, float] = (0, 0), size: tuple[float, float] | None = None, grip: bool = True) → QOverlayFrame

Add a widget overlaid over the table.

An overlay widget is shown on top of the table, just like the chart in Excel.

Parameters

• widget (QWidget or magicgui Widget) – The widget to add.

• label (str, optional) – Label that is shown in the bottom of the widget.

• topleft (tuple of float, optional) – Top-left position of the widget described as the row and column indices.

add_side_widget(widget: QtW.QWidget | Widget, *, name: str = '')

Add a side widget to the table.

A side widget is a widget that is docked to the side area of the table. It is visible only when the table is active. Thus, it is a good place to add a widget specific to the table.

Parameters

• widget (QWidget or magicgui Widget) – The widget to add.

• name (str, optional) – Name of the size widget. Use the input widget name by default.

background_color

background_colormap(*args, **kwargs)

Deprecated method.

cell

Interface with table cells.

This object can be used to emulate editing cells in the table.

>>> table.cell[i, j]  # get the (i, j) cell value shown in the table
>>> table.cell[i, j] = value  # set the (i, j) cell value
>>> table.cell[i, j] = "&=np.mean(df.iloc[:, 0]"  # in-cell evaluation
>>> del table.cell[i, j]  # delete the (i, j) cell value

Label texts in the cell can be accessed by the label attribute.

>>> table.cell.label[i, j]  # get the (i, j) cell label text
>>> table.cell.label[i, j] = value  # set the (i, j) cell label text
>>> del table.cell.label[i, j]  # delete the (i, j) cell label text

Use register to register a contextmenu function.

>>> @table.cell.register("My Action")
>>> def my_action(table, index):
...     # do something

property cellref

columns

Interface to the table columns header.

Similar to pandas.DataFrame.columns, you can get/set labels.

>>> print(table.columns[0])
>>> table.columns[0] = 'new_label'

Use selected() to get/set selected ranges.

>>> table.columns.selected
>>> table.columns.selected = [0, 1, 2]
>>> table.columns.selected = [slice(0, 3), slice(6, 8)]

Use insert() / remove() to run insert/remove command in spreadsheet.

>>> table.columns.insert(at=0, count=2)
>>> table.columns.remove(at=0, count=2)

Use register to register a contextmenu function.

>>> @table.columns.register("My Action")
>>> def my_action(table, index):
...     # do something

Many other pandas.Index methods are also available.

>>> table.columns.str.contains('foo')
>>> table.columns.isin(['foo', 'bar'])
>>> table.columns.get_loc('foo')

property current_index: tuple[int, int]

The current index of the table.

data

Internal data of the table.

property data_shown: pd.DataFrame

Return the data shown in the table (filter considered).

property editable: bool

Editability of table.

foreground_colormap(*args, **kwargs)

Deprecated method.

formatter

highlights

A table data specific highlight list.

iloc

iloc indexer for Table widget.

>>> sheet = viewer.add_spreadsheet(np.zeros((10, 5)))
>>> sheet.iloc[:, 2:5].data

index

Interface to the table index header.

Similar to pandas.DataFrame.index, you can get/set labels.

>>> print(table.index[0])
>>> table.index[0] = 'new_label'

Use selected() to get/set selected ranges.

>>> table.index.selected
>>> table.index.selected = [0, 1, 2]
>>> table.index.selected = [slice(0, 3), slice(6, 8)]

Use insert() / remove() to run insert/remove command in spreadsheet.

>>> table.index.insert(at=0, count=2)
>>> table.index.remove(at=0, count=2)

Use register to register a contextmenu function.

>>> @table.index.register("My Action")
>>> def my_action(table, index):
...     # do something

Many other pandas.Index methods are also available.

>>> table.index.str.contains('foo')
>>> table.index.isin(['foo', 'bar'])
>>> table.index.get_loc('foo')

property layout: LayoutString

Table layout.

loc

loc indexer for Table widget.

>>> sheet = viewer.add_spreadsheet(np.zeros((10, 5)))
>>> sheet.loc[:, "B":"C"].data

metadata

Metadata dictionary of the table.

move_iloc(row: int | None, column: int | None, scroll: bool = True)

Move to a location in the table using indices. >>> table.move_iloc(2, 4)

move_loc(row: Hashable, column: Hashable)

Move to a location in the table using axis label. >>> table.move_loc(“index-2”, “column-4”)

property mutable

Mutability of the table type.

property name: str

Table name.

property native: QBaseTable

The backend widget.

plt

The interface of plotting.

proxy

Interface to the table sorting/filtering.

To sort table, use sort method.

>>> table.proxy.sort('A', ascending=True)  # sort by column "A"
>>> table.proxy.sort(['A', 'B'], ascending=True)  # sort by columns "A" and "B"

To filter table, use filter method.

>>> table.proxy.filter('A > 0')  # filter by column "A"
>>> table.proxy.filter('(A > 0) & (B < 0)')  # filter by columns "A" and "B"

To use custom proxy function, use set method. A proxy function must return a boolean array or an integer array of the same length as the number of rows.

>>> table.proxy.set(my_filter_func)
>>> @table.proxy.set
>>> def my_filter_func(df: pd.DataFrame):
...     # do something

To initialize the proxy, use reset method.

>>> table.proxy.reset()

refresh() → None

Refresh the table view and force table to update.

save(path: str | pathlib.Path) → None

Save table data to the given path.

save_screenshot(path: str)

Save screenshot of the widget.

screenshot() → np.ndarray

Get screenshot of the widget.

selections

A table data specific selection range list.

property source: tabulous.widgets._source.Source

The source of the table.

property table_shape: tuple[int, int]

Shape of table (filter considered).

property table_type: str

Return the table type in string.

text_color

text_formatter

property undo_manager: UndoManager

Return the undo manager.

validator

property view_mode: tabulous.widgets._table.ViewMode

View mode of the table.

property zoom: float

Zoom factor of table.

class tabulous.widgets.TableDisplay(data: Any = None, name: str | None = None, editable: bool = True, metadata: dict[str, Any] | None = None)

Bases: tabulous.widgets._table.TableBase

A table that is hotly reloaded by the given function.

Parameters

• data (callable, optional) – The loader function.

• name (str, optional) – Name of the table.

• metadata (dict, optional) – Metadata of the table.

• update (bool, default is False) – If True, update the table data if a table of same name exists.

property interval: int

Interval of table refresh.

property loader: Callable[[], Any]

Loader function.

property running: bool

True if the loading task is running

class tabulous.widgets.TableViewer(*, tab_position: tabulous.types.TabPosition | str = TabPosition.top, show: bool = True)

Bases: tabulous.widgets._mainwindow.TableViewerBase

The main table viewer widget.

add_dock_widget(widget: Widget | QWidget, *, name: str = '', area: str = 'right', allowed_areas: list[str] | None = None)

Add a Qt or magic widget as a dock widget of the table viewer.

Parameters

• widget (magicgui.widgets.Widget or QWidget) – Widget to add to the table viewer.

• name (str, optional) – Name of the widget.

• area (str, default is "right") – The initial area of the dock widget.

• allowed_areas (list of str, optional) – The allowed areas of the dock widget.

property config: mappingproxy

Return the config info.

events: TableViewerSignal

remove_dock_widget(name_or_widget: str | Widget | QWidget)

Remove dock widget from the table viewer.

reset_choices(*_)

Reset all the magicgui combo boxes.

class tabulous.widgets.TableViewerBase(*, tab_position: tabulous.types.TabPosition | str = TabPosition.top, show: bool = True)

Bases: tabulous.widgets._mainwindow._AbstractViewer, tabulous.widgets._keymap_abc.SupportKeyMap

The base class of a table viewer widget.

add_groupby(data, *, name: str | None = None, metadata: dict[str, Any] | None = None, update: bool = False) → tabulous.widgets._table.GroupBy

Add a groupby object.

Parameters

• data (DataFrameGroupBy like object) – The groupby object to add.

• {name}{metadata}{update} –

Returns

A groupby table.

Return type

GroupBy

add_layer(input: TableBase, *, update: bool = False)

Add any table object to the viewer.

add_loader(loader: Callable[[], Any], *, name: str | None = None, metadata: dict[str, Any] | None = None, update: bool = False) → tabulous.widgets._table.TableDisplay

Add a data frame loader function and continuously update the table.

Parameters

• loader (callable) – The loader function.

• {name}{metadata}{update} –

Returns

A table display object.

Return type

TableDisplay

add_spreadsheet(data: Any | None = None, *, name: str | None = None, editable: bool = True, copy: bool = True, metadata: dict[str, Any] | None = None, update: bool = False, dtyped: bool = False) → tabulous.widgets._table.SpreadSheet

Add data as a spreadsheet.

Parameters

• data (DataFrame like, optional) – Table data to add.

• {name}{editable}{copy}{metadata}{update} –

• dtyped (bool, default is False) – If True, dtypes of the dataframe columns will be saved in the spreadsheet. Typed spreadsheet is safer for data recovery but less flexible for editing.

Returns

The added spreadsheet object.

Return type

SpreadSheet

add_table(data: Any | None = None, *, name: str | None = None, editable: bool = False, copy: bool = True, metadata: dict[str, Any] | None = None, update: bool = False) → tabulous.widgets._table.Table

Add data as a table.

Parameters

• data (DataFrame like, optional) – Table data to add.

• name (str, optional) – Name of the table.

• editable (bool, default is False) – Whether the table is editable via UI.

• copy (bool, default is True) – Whether to copy the data before adding to avoid overwriting the original one.

• metadata (dict, optional) – Metadata of the table.

• update (bool, default is False) – If True, update the table data if a table of same name exists.

Returns

The added table object.

Return type

Table

property cell_namespace: Namespace

Return the namespace of the cell editor.

close()

Close the viewer.

command_palette

console

The QtConsole proxy.

copy_data(selections: Optional[Union[List[Tuple[Union[SupportsIndex, slice], Union[SupportsIndex, slice]]], Tuple[Union[SupportsIndex, slice], Union[SupportsIndex, slice]]]] = None, *, headers: bool = False, sep: str = '\t') → None

Copy selected cells to clipboard.

property current_index: int | None

Return the index of currently visible table.

current_table

Essentially identical to the getter-only property.

IPython runtime auto-completion checks if the evaluation has any side effects. If an attribute is a property, it immediately skips the auto-completion check.

events: TableViewerSignal

property history_manager

The file I/O history manager.

property native: _QtMainWidgetBase

Return the native widget.

open(path: Union[str, pathlib.Path, bytes], *, type: tabulous.widgets._mainwindow.TableType | str = TableType.table) → None

Read a table data and add to the viewer.

Parameters

path (path like) – File path.

open_sample(sample_name: str, *, plugin: str = 'seaborn', type: tabulous.widgets._mainwindow.TableType | str = TableType.table, asynchronous: bool = False) → tabulous.widgets._table.Table

Open a sample table.

paste_data(selections: Optional[Union[List[Tuple[Union[SupportsIndex, slice], Union[SupportsIndex, slice]]], Tuple[Union[SupportsIndex, slice], Union[SupportsIndex, slice]]]] = None) → None

Paste from clipboard.

resize(width: int, height: int)

Resize the table viewer.

save(path: Union[str, pathlib.Path, bytes]) → None

Save current table.

save_all(path: Union[str, pathlib.Path, bytes]) → None

Save all tables.

save_screenshot(path: str)

Save screenshot of the widget.

screenshot() → np.ndarray

Get screenshot of the widget.

show(*, run: bool = True) → None

Show the widget.

property size: tuple[int, int]

Return the size of the table viewer.

property status: str

Return the statup tip

tables

Essentially identical to the getter-only property.

IPython runtime auto-completion checks if the evaluation has any side effects. If an attribute is a property, it immediately skips the auto-completion check.

property theme: str

Get current widget theme name.

toolbar

The toolbar proxy.

class tabulous.widgets.TableViewerWidget(*, tab_position: tabulous.types.TabPosition | str = TabPosition.top, show: bool = True)

Bases: tabulous.widgets._mainwindow.TableViewerBase

The non-main table viewer widget.

add_widget(widget: Widget | QWidget, *, name: str = '')

Add a widget to the viewer as a child floating widget.

events: TableViewerSignal