New df property and setter, make some traits private

Author: mwouts

docs/ipywidgets.md

@@ -16,103 +16,102 @@ kernelspec:
 
 ITables is available as a [Jupyter Widget](https://ipywidgets.readthedocs.io) since v2.2.
 
-## Using `show`
+## The `ITable` widget
 
-If you only want to _display_ the table, you **do not need**
-our Jupyter widget. The `show` function is enough!
+The `ITable` widget has a few dependencies that you can install with
+```bash
+pip install itables[widget]
+```
 
-```{code-cell}
-import ipywidgets as widgets
+The `ITable` class accepts the same arguments as the `show` method, but
+the `df` argument is optional.
 
-from itables import show
+```{code-cell}
 from itables.sample_dfs import get_dict_of_test_dfs
+from itables.widget import ITable
 
-sample_dfs = get_dict_of_test_dfs()
-
+df = get_dict_of_test_dfs()["int_float_str"]
 
-def use_show_in_interactive_output(table_name: str):
-    show(
-        sample_dfs[table_name],
-        caption=table_name,
-        style="table-layout:auto;width:auto;float:left;caption-side:bottom",
-    )
+table = ITable(df, selected_rows=[0, 2, 5], select=True)
+table
+```
 
+## The `selected_rows` traits
 
-table_selector = widgets.Dropdown(options=sample_dfs.keys(), value="int_float_str")
-out = widgets.interactive_output(
-    use_show_in_interactive_output, {"table_name": table_selector}
-)
+The `selected_rows` attribute of the `ITable` object provides a view on the
+rows that have been selected in the table (remember to pass `select=True`
+to activate the row selection). You can use it to either retrieve
+or change the current row selection:
 
-widgets.VBox([table_selector, out])
+```{code-cell}
+table.selected_rows
 ```
 
-```{tip}
-Jupyter widgets only work in a live notebook.
-Click on the rocket icon at the top of the page to run this demo in Binder.
+```{code-cell}
+table.selected_rows = [3, 4]
 ```
 
-## Using the ITable widget
-
-The `ITable` widget has a few dependencies that you can install with
-```bash
-pip install itables[widget]
-```
+## The `df` property
 
-The `ITable` class accepts the same arguments as the `show` method, but
-the `df` argument is optional.
+Use it to retrieve the table data:
 
 ```{code-cell}
-from itables.widget import ITable
-
-table = ITable(selected_rows=[0, 2, 5, 99])
+table.df.iloc[table.selected_rows]
+```
 
+or to update it
 
-def update_selected_table(change):
-    table_name = table_selector.value
-    table.update(
-        sample_dfs[table_name],
-        caption=table_name,
-        select=True,
-        style="table-layout:auto;width:auto;float:left",
-    )
+```{code-cell}
+table.df = df.head(6)
+```
 
+```{tip}
+`ITable` will raise an `IndexError` if the `selected_rows` are not consistent with the
+updated data. If you need to update the two simultaneously, use `table.update(df, selected_rows=...)`, see below.
+```
 
-# Update the table when the selector changes
-table_selector.observe(update_selected_table, "value")
+## The `caption`, `style` and `classes` traits
 
-# Set the table to the initial table selected
-update_selected_table(None)
+You can update these traits from Python, e.g.
 
-widgets.VBox([table_selector, table])
+```{code-cell}
+table.caption = "numbers and strings"
 ```
 
-## Get the selected rows
+## The `update` method
 
-The `ITable` widget let you access the state of the table
-and in particular, it has an `.selected_rows` attribute
-that you can use to determine the rows that have been
-selected by the user (allow selection by passing `select=True`
-to the `ITable` widget).
+Last but not least, you can update the `ITable` arguments simultaneously using the `update` method:
 
 ```{code-cell}
-out = widgets.Output()
+table.update(df.head(20), selected_rows=[7, 8])
+```
 
+## Limitations
 
-def show_selected_rows(change):
-    with out:
-        out.clear_output()
-        print("selected_rows: ", table.selected_rows)
+Compared to `show`, the `ITable` widget has the same limitations as the [streamlit component](streamlit.md#limitations),
+e.g. structured headers are not available, you can't pass JavaScript callback, etc.
 
+The good news is that if you only want to _display_ the table, you **do not need**
+the `ITables` widget. Below is an example in which we use `show` to display a different
+table depending on the value of a drop-down component:
 
-table.observe(show_selected_rows, "selected_rows")
+```python
+import ipywidgets as widgets
+from itables import show
+from itables.sample_dfs import get_dict_of_test_dfs
 
-# Display the initial selection
-show_selected_rows(None)
+def use_show_in_interactive_output(table_name: str):
+    show(
+        sample_dfs[table_name],
+        caption=table_name,
+    )
 
-out
-```
+sample_dfs = get_dict_of_test_dfs()
+table_selector = widgets.Dropdown(options=sample_dfs.keys(), value="int_float_str")
 
-## Limitations
+out = widgets.interactive_output(
+    use_show_in_interactive_output, {"table_name": table_selector}
+)
 
-Compared to `show`, the `ITable` widget has the same limitations as the [streamlit component](streamlit.md#limitations),
-e.g. structured headers are not available, you can't pass JavaScript callback, etc.
+widgets.VBox([table_selector, out])
+```

docs/streamlit.md

@@ -49,9 +49,3 @@ A sample application is available at https://to-html-datatable.streamlit.app (so
 <iframe src="https://to-html-datatable.streamlit.app?embed=true"
 style="height: 600px; width: 100%;"></iframe>
 ```
-
-## Future developments
-
-ITables' Streamlit component might see the following developments in the future
-- Return the selected cells
-- Make the table editable (will require a DataTable [editor license](https://editor.datatables.net/purchase/))

packages/itables_anywidget/js/widget.ts

@@ -52,31 +52,32 @@ function render({ model, el }: RenderContext<WidgetModel>) {
 	function set_selected_rows_from_model() {
 		// We use this variable to avoid triggering model updates!
 		setting_selected_rows_from_model = true;
-		DataTable.set_selected_rows(dt, model.get('filtered_row_count'), model.get('selected_rows'));
+		DataTable.set_selected_rows(dt, model.get('_filtered_row_count'), model.get('selected_rows'));
 		setting_selected_rows_from_model = false;
 	};
 
 	function create_table(destroy = false) {
-		let dt_args = model.get('dt_args');
 		if (destroy) {
 			dt.destroy();
 			jQuery(table).empty();
 		}
 
+		let dt_args = model.get('_dt_args');
+		dt_args['data'] = model.get('_data');
+		dt_args['columns'] = model.get('_columns');
 		dt_args["fnInfoCallback"] = function (oSettings: any, iStart: number, iEnd: number, iMax: number, iTotal: number, sPre: string) {
-			let msg = model.get("downsampling_warning");
+			let msg = model.get("_downsampling_warning");
 			if (msg)
-				return sPre + ' (' + model.get("downsampling_warning") + ')';
+				return sPre + ' (' + msg + ')';
 			else
 				return sPre;
 		}
-		dt_args['data'] = model.get('data');
 		dt = new DataTable(table, dt_args);
+		set_selected_rows_from_model();
 	}
 	create_table();
-	set_selected_rows_from_model();
 
-	model.on('change:destroy_and_recreate', () => {
+	model.on('change:_destroy_and_recreate', () => {
 		create_table(true);
 	});
 
@@ -86,7 +87,7 @@ function render({ model, el }: RenderContext<WidgetModel>) {
 		if (setting_selected_rows_from_model)
 			return;
 
-		model.set('selected_rows', DataTable.get_selected_rows(dt, model.get('filtered_row_count')));
+		model.set('selected_rows', DataTable.get_selected_rows(dt, model.get('_filtered_row_count')));
 		model.save_changes();
 	};
 

src/itables/javascript.py

@@ -486,11 +486,15 @@ def get_itables_extension_arguments(df, caption=None, selected_rows=None, **kwar
             "Pandas style objects can't be used with the extension"
         )
 
+    if df is None:
+        df = pd.DataFrame()
+
     set_default_options(
         kwargs,
         use_to_html=False,
-        context="the streamlit extension",
+        context="the itable widget or streamlit extension",
         not_available=[
+            "columns",
             "tags",
             "dt_url",
             "pre_dt_code",

src/itables/widget/__init__.py

@@ -2,7 +2,6 @@
 import pathlib
 
 import anywidget
-import pandas as pd
 import traitlets
 
 from itables.javascript import get_itables_extension_arguments
@@ -17,62 +16,106 @@ class ITable(anywidget.AnyWidget):
     _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
     _css = pathlib.Path(__file__).parent / "static" / "widget.css"
 
-    data = traitlets.List(traitlets.List()).tag(sync=True)
-    filtered_row_count = traitlets.Int().tag(sync=True)
-    selected_rows = traitlets.List(traitlets.Int).tag(sync=True)
-    destroy_and_recreate = traitlets.Int(0).tag(sync=True)
-
+    # public traits
     caption = traitlets.Unicode().tag(sync=True)
     classes = traitlets.Unicode().tag(sync=True)
     style = traitlets.Unicode().tag(sync=True)
-    downsampling_warning = traitlets.Unicode().tag(sync=True)
-    dt_args = traitlets.Dict().tag(sync=True)
+    selected_rows = traitlets.List(traitlets.Int).tag(sync=True)
+
+    # private traits that relate to df or to the DataTable arguments
+    # (use .update() to update them)
+    _data = traitlets.List(traitlets.List()).tag(sync=True)
+    _columns = traitlets.List(traitlets.Dict()).tag(sync=True)
+    _filtered_row_count = traitlets.Int().tag(sync=True)
+    _downsampling_warning = traitlets.Unicode().tag(sync=True)
+    _dt_args = traitlets.Dict().tag(sync=True)
+    _destroy_and_recreate = traitlets.Int(0).tag(sync=True)
 
     def __init__(self, df=None, caption=None, selected_rows=None, **kwargs) -> None:
         super().__init__()
 
-        if df is None:
-            df = pd.DataFrame()
-
         dt_args, other_args = get_itables_extension_arguments(
             df, caption, selected_rows, **kwargs
         )
-        self.data = dt_args.pop("data")
-        self.dt_args = dt_args
+        self._df = df
+        self.caption = other_args.pop("caption") or ""
         self.classes = other_args.pop("classes")
         self.style = other_args.pop("style")
-        self.caption = other_args.pop("caption") or ""
-        self.downsampling_warning = other_args.pop("downsampling_warning") or ""
         self.selected_rows = other_args.pop("selected_rows") or []
-        self.filtered_row_count = other_args.pop("filtered_row_count", 0)
+
+        self._data = dt_args.pop("data")
+        self._columns = dt_args.pop("columns")
+        self._dt_args = dt_args
+        self._downsampling_warning = other_args.pop("downsampling_warning") or ""
+        self._filtered_row_count = other_args.pop("filtered_row_count", 0)
         assert not other_args, other_args
 
     def update(self, df=None, caption=None, selected_rows=None, **kwargs):
+        """
+        Update either the table data, attributes, or the arguments passed
+        to DataTable. Arguments that are not mentioned
+        """
+        data_or_dt_args_changed = False
+        for key, value in list(kwargs.items()):
+            if value is None:
+                data_or_dt_args_changed = True
+                self._dt_args.pop(key, None)
+                del kwargs[key]
+
+        if df is None:
+            df = self._df
+        if selected_rows is None:
+            selected_rows = self.selected_rows
+        if caption is None:
+            caption = self.caption
+        if "classes" not in kwargs:
+            kwargs["classes"] = self.classes
+        if "style" not in kwargs:
+            kwargs["style"] = self.style
+
         dt_args, other_args = get_itables_extension_arguments(
             df, caption, selected_rows, **kwargs
         )
 
-        if df is not None:
-            data = dt_args.pop("data")
-            self.downsampling_warning = other_args.pop("downsampling_warning") or ""
-            self.filtered_row_count = other_args.pop("filtered_row_count", 0)
-            if self.dt_args != dt_args:
-                self.dt_args = dt_args
-            if self.data != data:
-                self.data = data
-        else:
-            data = dt_args.pop("data")
-            if "columns" not in dt_args:
-                dt_args["columns"] = self.dt_args["columns"]
-            if self.dt_args != dt_args:
-                self.dt_args = dt_args
-
         self.classes = other_args.pop("classes")
         self.style = other_args.pop("style")
-        self.caption = other_args.pop("caption") or ""
+        self.caption = other_args.pop("caption")
+
+        if df is None:
+            del dt_args["data"]
+            del dt_args["columns"]
+
+            # Don't trigger an update if nor data nor the dt args changed
+            data_or_dt_args_changed = data_or_dt_args_changed or self._update_dt_args(
+                dt_args
+            )
+        else:
+            self._df = df
+            self._data = dt_args.pop("data")
+            self._columns = dt_args.pop("columns")
+            self._update_dt_args(dt_args)
+            self._downsampling_warning = other_args.pop("downsampling_warning") or ""
+            self._filtered_row_count = other_args.pop("filtered_row_count", 0)
+            data_or_dt_args_changed = True
+
+        if data_or_dt_args_changed:
+            self._destroy_and_recreate += 1
+
+        self.selected_rows = other_args.pop("selected_rows")
+
+    def _update_dt_args(self, dt_args):
+        changed = False
+        for key, value in dt_args.items():
+            if key not in self._dt_args or (self._dt_args[key] != value):
+                self._dt_args[key] = value
+                changed = True
+
+        return changed
 
-        selected_rows = other_args.pop("selected_rows")
-        if selected_rows is not None and self.selected_rows != selected_rows:
-            self.selected_rows = selected_rows
+    @property
+    def df(self):
+        return self._df
 
-        self.destroy_and_recreate += 1
+    @df.setter
+    def df(self, df):
+        self.update(df)