Implement an ITable component for Dash (#358)

Author: mwouts

.github/workflows/continuous-integration.yml

@@ -53,7 +53,7 @@ jobs:
             pandas-version: pre
             polars: true
           - python-version: "3.13"
-            uninstall_jinja2: true
+            uninstall_jinja2_and_dash: true
     runs-on: ubuntu-20.04
     steps:
       - name: Checkout
@@ -91,9 +91,9 @@ jobs:
         if: matrix.python-version != '3.7'
         run: pip install "shiny>=1.0"
 
-      - name: Uninstall jinja2
-        if: matrix.uninstall_jinja2
-        run: pip uninstall jinja2 -y
+      - name: Uninstall jinja2 and dash
+        if: matrix.uninstall_jinja2_and_dash
+        run: pip uninstall jinja2 dash -y
 
       - name: Install a Jupyter Kernel
         run: python -m ipykernel install --name itables --user

.gitignore

@@ -28,7 +28,11 @@ node_modules
 dt_bundle.js
 dt_bundle.css
 
-# Streamlit package
+# Dash component
+src/itables_for_dash/*.js*
+src/itables_for_dash/_imports_.py
+
+# Streamlit component
 src/itables/itables_for_streamlit
 
 # Jupyter Widget

.pre-commit-config.yaml

@@ -1,6 +1,7 @@
 # Install pre-commit hooks via
 # pre-commit install
 
+exclude: ^src/itables_for_dash/ITable.py$  # auto-generated
 repos:
 
   - repo: https://github.com/pre-commit/pre-commit-hooks

apps/dash/1_display_only.py

@@ -0,0 +1,18 @@
+from dash import Dash, html
+
+from itables.dash import ITable
+from itables.sample_dfs import get_countries
+
+app = Dash(__name__)
+
+df = get_countries(html=False)
+
+app.layout = html.Div(
+    [
+        html.H1("ITables in a Dash application"),
+        ITable(id="my_dataframe", df=df, caption="A DataFrame displayed with ITables"),
+    ]
+)
+
+if __name__ == "__main__":
+    app.run(debug=True)

apps/dash/2_selected_rows.py

@@ -0,0 +1,33 @@
+from dash import Dash, Input, Output, callback, html
+
+from itables.dash import ITable
+from itables.sample_dfs import get_countries
+
+app = Dash(__name__)
+
+df = get_countries(html=False)
+
+app.layout = html.Div(
+    [
+        html.H1("ITables in a Dash application"),
+        ITable(
+            id="my_dataframe",
+            df=df,
+            caption="A DataFrame displayed with ITables",
+            select=True,
+        ),
+        html.Div(id="output"),
+    ]
+)
+
+
+@callback(
+    Output("output", "children"),
+    Input("my_dataframe", "selected_rows"),
+)
+def show_selection(selected_rows):
+    return f"Selected rows: {selected_rows}"
+
+
+if __name__ == "__main__":
+    app.run(debug=True)

apps/dash/3_update_table.py

@@ -0,0 +1,75 @@
+"""
+This is an example Dash application that uses the ITable component.
+
+Launch the app by running `python app.py`.
+"""
+
+import logging
+
+from dash import Dash, Input, Output, State, callback, callback_context, dcc, html
+
+from itables.dash import ITable, ITableOutputs, updated_itable_outputs
+from itables.sample_dfs import get_countries
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+app = Dash(__name__)
+
+df = get_countries(html=False)
+
+
+app.layout = html.Div(
+    [
+        html.H1("DataTable in a Dash application"),
+        dcc.Checklist(
+            ["Select", "Buttons", "HTML"],
+            ["Select"],
+            id="checklist",
+        ),
+        dcc.Input(id="caption", value="table caption"),
+        ITable(id="my_dataframe", df=df),
+        html.Div(id="output"),
+    ]
+)
+
+
+@callback(
+    ITableOutputs("my_dataframe"),
+    [
+        Input("checklist", "value"),
+        Input("caption", "value"),
+        State("my_dataframe", "selected_rows"),
+        State("my_dataframe", "dt_args"),
+    ],
+)
+def update_table(checklist, caption, selected_rows, dt_args):
+    if checklist is None:
+        checklist = []
+
+    kwargs = {}
+
+    # When df=None and when the dt_args don't change, the table is not updated
+    if callback_context.triggered_id == "checklist":
+        kwargs["df"] = get_countries(html="HTML" in checklist)
+
+    kwargs["select"] = "Select" in checklist
+    if "Buttons" in checklist:
+        kwargs["buttons"] = ["copyHtml5", "csvHtml5", "excelHtml5"]
+
+    return updated_itable_outputs(
+        caption=caption, selected_rows=selected_rows, current_dt_args=dt_args, **kwargs
+    )
+
+
+@callback(
+    Output("output", "children"),
+    Input("my_dataframe", "selected_rows"),
+)
+def show_selection(selected_rows):
+    return f"Selected rows: {selected_rows}"
+
+
+if __name__ == "__main__":
+    app.run(debug=True)

docs/changelog.md

@@ -4,6 +4,10 @@ ITables ChangeLog
 2.3.0-dev
 ---------
 
+**Added**
+- ITable now has a component for Dash! You can render your Python DataFrames in your Dash application with `from itables.dash import ITable` ([#245](https://github.com/mwouts/itables/issues/245))
+
+
 **Changed**
 - We have upgraded `datatables.net-dt==2.2.2` and `datatables.net-select-dt==3.0.0`, and the dependency of both the Jupyter widget and the Streamlit component.
 

docs/dash.md

@@ -1,4 +1,76 @@
+---
+jupytext:
+  formats: md:myst
+  notebook_metadata_filter: -jupytext.text_representation.jupytext_version
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+kernelspec:
+  display_name: itables
+  language: python
+  name: itables
+---
+
 # Dash
 
-ITables does not have a [Dash](https://dash.plotly.com/) component, but might get one in the future.
-You are welcome to subscribe or contribute to [#245](https://github.com/mwouts/itables/issues/245).
+ITables includes a Dash component since v2.3.0.
+
+## Displaying a DataFrame
+
+If you wish to display a DataFrame which content is fixed (not reacting to the other controls in the application), you just need to import `ITable` from `itables.dash` and add it to your layout like here:
+
+```{include} ../apps/dash/1_display_only.py
+:code: python
+```
+
+## Selected rows
+
+Listening to the selected rows is simply done by adding `select=True` to the `ITable` call, and then implementing a callback on `Input("my_dataframe", "selected_rows")`.
+
+```{include} ../apps/dash/2_selected_rows.py
+:code: python
+```
+
+## Updating the DataFrame
+
+The `ITable` fonction returns an `ITableComponent` that has many properties. These properties (data, columns, selected rows etc) need to be updated in a consistent way. Therefore we recommend that you list the outputs with `ITableOutputs("my_dataframe")` in your callback, and update them with `updated_itable_outputs` which takes the same arguments as `show`, e.g. `df`, `caption`,`selected_rows`, etc, like in the below (extracted from this [example app](https://github.com/mwouts/itables/tree/main/apps/dash/3_update_table.py)):
+
+```python
+from itables.dash import ITable, ITableOutputs, updated_itable_outputs
+
+# (...)
+
+@callback(
+    ITableOutputs("my_dataframe"),
+    [
+        Input("checklist", "value"),
+        Input("caption", "value"),
+        State("my_dataframe", "selected_rows"),
+        State("my_dataframe", "dt_args"),
+    ],
+)
+def update_table(checklist, caption, selected_rows, dt_args):
+    if checklist is None:
+        checklist = []
+
+    kwargs = {}
+
+    # When df=None and when the dt_args don't change, the table is not updated
+    if callback_context.triggered_id == "checklist":
+        kwargs["df"] = get_countries(html="HTML" in checklist)
+
+    kwargs["select"] = "Select" in checklist
+    if "Buttons" in checklist:
+        kwargs["buttons"] = ["copyHtml5", "csvHtml5", "excelHtml5"]
+
+    return updated_itable_outputs(
+        caption=caption, selected_rows=selected_rows, current_dt_args=dt_args, **kwargs
+    )
+```
+
+## Limitations
+
+Compared to `show`, the `ITable` component has the same limitations as the [Jupyter Widget](widget.md#limitations)
+or the [Streamlit component](streamlit.md#limitations),
+e.g. structured headers are not available, you can't pass JavaScript callback, etc.

docs/references.md

@@ -1,19 +1,38 @@
 # References
 
-## DataTables
+ITables is a wrapper for the [datatables-net](https://datatables.net) Javascript library, for Python. That library is developped by [SpryMedia](https://sprymedia.co.uk/) and made available under a MIT license. It has an extensive [documentation](https://datatables.net/manual/), as well as a large set of [examples](https://datatables.net/examples/index).
 
-- DataTables is a plug-in for the jQuery Javascript library. It has a great [documentation](https://datatables.net/manual/), and a large set of [examples](https://datatables.net/examples/index).
-- The R package [DT](https://rstudio.github.io/DT/) uses [DataTables](https://datatables.net/) as the underlying library for both R notebooks and Shiny applications. In addition to the standard functionalities of the library (display, sort, filtering and row selection), RStudio seems to have implemented cell edition.
+## ITables and its alternatives
 
-## Alternatives
+### Jupyter Widgets
 
-ITables uses basic Javascript. It is not a Jupyter widget, which means that it does not allows you to **edit** the content of the dataframe.
+In Jupyter or VS Code, ITables can render your dataframes using either HTML (with  `init_notebook_mode(all_interactive=True)` or `show`) or the [`ITable` widget](widget.md).
 
-If you are looking for Jupyter widgets, have a look at
+Other Jupyter widgets that let you render a dataframe in Jupyter are
 - [QGrid](https://github.com/quantopian/qgrid) by Quantopian
 - [IPyaggrid](https://dgothrek.gitlab.io/ipyaggrid/) by Louis Raison and Olivier Borderies
 - [IPySheet](https://github.com/QuantStack/ipysheet) by QuantStack.
 
-If you are looking for a table component that will fit in Dash applications, see [datatable by Dash](https://github.com/plotly/dash-table/).
+### Dash component
 
-Please also checkout [D-Tale](https://github.com/man-group/dtale) for exploring your Python DataFrames in the browser, using a local server.
+Since ITables v2.3.0 you can use our [`ITable` component](dash.md) in Dash applications.
+
+Alternatives for rendering DataFrames in Dash are
+- [Dash DataTable](https://dash.plotly.com/datatable)
+- [Dash AG Grid](https://dash.plotly.com/dash-ag-grid).
+
+### Streamlit
+
+In ITables v2.1.0 we added the [`interactive_table` component](streamlit.md) that can be used in Streamlit applications.
+
+Alternative for rendering DataFrames in Streamlit are
+- [`st.dataframe`](https://docs.streamlit.io/develop/api-reference/data/st.dataframe)
+- [`streamlit-aggrid`](https://github.com/PablocFonseca/streamlit-aggrid).
+
+### DT in R
+
+The R package [DT](https://rstudio.github.io/DT/) is a wrapper for [DataTables](https://datatables.net/) that you can use both in R notebooks and R Shiny applications.
+
+### D-Tale
+
+[D-Tale](https://github.com/man-group/dtale) lets you explore your Python DataFrames in the browser, using a local server.

packages/itables_for_dash/.babelrc

@@ -0,0 +1,14 @@
+{
+"presets": ["@babel/preset-env", "@babel/preset-react"],
+"env": {
+    "production": {
+        "plugins": ["@babel/plugin-proposal-object-rest-spread", "styled-jsx/babel"]
+    },
+    "development": {
+        "plugins": ["@babel/plugin-proposal-object-rest-spread", "styled-jsx/babel"]
+    },
+    "test": {
+        "plugins": ["@babel/plugin-proposal-object-rest-spread", "styled-jsx/babel-test"]
+    }
+}
+}