feat(data frame): Add .update_cell() and .update_data()

CHANGELOG.md

@@ -66,6 +66,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Fixed bug in `@render.data_frame` where `bool` or `object` columns were not being rendered. (#1570)
 
+* Fixed output controller `OutputDataFrame` in `shiny.playwright.controller` to correctly assert the number of rows in `.expect_nrow()` as the total number of virtual rows, not the number of currently displaying rows. (#1719)
+
 
 ## [1.1.0] - 2024-09-03
 

shiny/playwright/controller/_output.py

@@ -673,8 +673,9 @@ def __init__(self, page: Page, id: str) -> None:
             loc_container=f"#{id}.html-fill-item",
             loc="> div > div.shiny-data-grid",
         )
-        self.loc_head = self.loc.locator("> table > thead")
-        self.loc_body = self.loc.locator("> table > tbody")
+        self.loc_table = self.loc.locator("> table")
+        self.loc_head = self.loc_table.locator("> thead")
+        self.loc_body = self.loc_table.locator("> tbody")
         self.loc_column_filter = self.loc_head.locator(
             "> tr.filters > th:not(.table-corner)"
         )
@@ -723,8 +724,10 @@ def expect_nrow(self, value: int, *, timeout: Timeout = None):
         timeout
             The maximum time to wait for the expectation to pass. Defaults to `None`.
         """
-        playwright_expect(self.loc_body.locator("> tr")).to_have_count(
-            value, timeout=timeout
+        playwright_expect(self.loc_table).to_have_attribute(
+            "aria-rowcount",
+            str(value),
+            timeout=timeout,
         )
 
     def expect_selected_num_rows(self, value: int, *, timeout: Timeout = None):

shiny/render/_data_frame.py

@@ -109,21 +109,45 @@ class data_frame(
     be able to edit the cells in the table. After a cell has been edited, the edited
     value will be sent to the server for processing. The handling methods are set via
     `@<data_frame_renderer>.set_patch_fn` or `@<data_frame_renderer>.set_patches_fn`
-    decorators. By default, both decorators will return a string value.
-
-    To access the data viewed by the user, use `<data_frame_renderer>.data_view()`. This
-    method will sort, filter, and apply any patches to the data frame as viewed by the
-    user within the browser. This is a shallow copy of the original data frame. It is
-    possible that alterations to `data_view` could alter the original `data` data frame.
-
-    To access the original data, use `<data_frame_renderer>.data()`. This is a quick
-    reference to the original pandas or polars data frame that was returned from the
-    app's render function. If it is mutated in place, it **will** modify the original
-    data.
-
-    Note... if the data frame renderer is re-rendered due to reactivity, then
-    the user's edits, sorting, and filtering will be lost. We hope to improve upon this
-    in the future.
+    decorators. By default, both decorators will return the corresponding value as a
+    string.
+
+    Data methods
+    ------------
+
+    There are several methods available to inspect and update data frame renderer. It is
+    important to know the side effects of each method to know how they interact with
+    each other.
+
+    * Data frame render method:
+        * When called, returns the original data frame (possibly wrapped in a `DataGrid`
+          or `DataTable`) that was returned from the app's render function.
+        * When this method is reactively executed, **all user state is reset**. This
+          includes the user's edits, sorting, and filtering.
+    * `.data()`:
+        * Returns the render method's underlying data frame or the data frame supplied to
+          `.update_data(data)`, which ever has been most recently set.
+    * `.cell_patches()`:
+        * Returns a list of user edits (or updated cell values) that will be applied to
+          the `.data_patched()` data frame.
+    * `.data_patched()`:
+        * Returns the `.data()` data frame with any user edits or `.update_cell_value()`
+          patches applied.
+    * `.data_view(*, selected: bool)`:
+        * Returns the `.data_patched()` data frame with the user's sorting and filtering
+          applied. It represents the data frame as seen in the browser.
+        * If `selected=True`, only the selected rows are returned.
+    * `.update_cell_value(value, row, col)`:
+        * Sets a new entry in `.cell_patches()`.
+        * Calling this method will **not** reset the user's sorting or filtering.
+    * `.update_data(data)`:
+        * Updates the `.data()` data frame with new data.
+        * Calling this method will remove all `.cell_patches()`.
+        * Calling this method will **not** reset the user's sorting or filtering.
+
+    Note: All data methods are shallow copies of each other. If they are mutated in
+    place, it **will modify** the underlying data object and possibly alter other data
+    objects.
 
     Narwhals
     -------------------
@@ -148,7 +172,6 @@ class data_frame(
       it will not insert any tags, but it will cause the column to be interpreted as
       `html` where possible.   (tl/dr: Use consistent typing in your columns!)
 
-
     Tip
     ---
     This decorator should be applied **before** the ``@output`` decorator (if that
@@ -298,7 +321,7 @@ def cell_patches(self) -> list[CellPatch]:
         return list(self._cell_patch_map().values())
 
     @reactive_calc_method
-    def _data_patched(self) -> DataFrame[IntoDataFrameT]:
+    def _nw_data_patched(self) -> DataFrame[IntoDataFrameT]:
         """
         Reactive calculation of the data frame's patched data.
 
@@ -309,6 +332,18 @@ def _data_patched(self) -> DataFrame[IntoDataFrameT]:
         """
         return apply_frame_patches(self._nw_data(), self.cell_patches())
 
+    @reactive_calc_method
+    def data_patched(self) -> IntoDataFrameT:
+        """
+        Get the patched data frame.
+
+        Returns
+        -------
+        :
+            The patched data frame.
+        """
+        return self._nw_data_to_original_type(self._nw_data_patched())
+
     # Apply filtering and sorting
     # https://github.com/posit-dev/py-shiny/issues/1240
     def _subset_data_view(self, selected: bool) -> IntoDataFrameT:
@@ -347,7 +382,7 @@ def _subset_data_view(self, selected: bool) -> IntoDataFrameT:
         else:
             rows = self.data_view_rows()
 
-        nw_data = subset_frame(self._data_patched(), rows=rows)
+        nw_data = subset_frame(self._nw_data_patched(), rows=rows)
 
         patched_subsetted_into_data = self._nw_data_to_original_type(nw_data)
 
@@ -718,10 +753,10 @@ def _set_cell_patch_map_patches(
 
             assert isinstance(
                 row_index, int
-            ), f"Expected `row_index` to be an `int`, got {type(row_index)}"
+            ), f"Expected `row_index` to be an `int`, received {type(row_index)}"
             assert isinstance(
                 column_index, int
-            ), f"Expected `column_index` to be an `int`, got {type(column_index)}"
+            ), f"Expected `column_index` to be an `int`, received {type(column_index)}"
 
             # TODO-render.data_frame; Possibly check for cell type and compare against type hints
             # TODO-render.data_frame; The `value` should be coerced by pandas to the correct type
@@ -766,7 +801,7 @@ async def _attempt_update_cell_style(self) -> None:
         if not callable(styles_fn):
             return
 
-        patched_into_data = self._nw_data_to_original_type(self._data_patched())
+        patched_into_data = self._nw_data_to_original_type(self._nw_data_patched())
         new_styles = as_browser_style_infos(styles_fn, into_data=patched_into_data)
 
         await self._send_message_to_browser(
@@ -798,19 +833,31 @@ async def update_cell_value(
         if isinstance(col, str):
             with reactive.isolate():
                 column_names = self._nw_data().columns
-                assert col in column_names, f"Column '{col}' not found in data frame."
+                if col not in column_names:
+                    raise ValueError(f"Column '{col}' not found in data frame.")
                 column_index = self._nw_data().columns.index(col)
         else:
             column_index = col
-            assert isinstance(
-                column_index, int
-            ), f"Expected `column_index` to be an `int`, got {type(column_index)}"
-            assert (
-                column_index >= 0
-            ), f"Expected `column_index` to be greater than or equal to 0, got {column_index}"
+            if (not isinstance(col, int)) or isinstance(col, bool):
+                raise TypeError(
+                    f"Expected `col` to be an `int` or `str, received {type(column_index)}"
+                )
+            if column_index < 0:
+                raise ValueError(
+                    f"Expected `col` to be greater than or equal to 0, received {column_index}"
+                )
+            column_length = self._nw_data().shape[1]
+            if column_index >= column_length:
+                raise ValueError(
+                    f"Expected `col` to be less than {column_length}, received {column_index}"
+                )
 
-        assert isinstance(row, int), f"Expected `row` to be an `int`, got {type(row)}"
-        assert row >= 0, f"Expected `row` to be greater than or equal to 0, got {row}"
+        if (not isinstance(row, int)) or isinstance(row, bool):
+            raise TypeError(f"Expected `row` to be an `int`, received {type(row)}")
+        if row < 0:
+            raise ValueError(
+                f"Expected `row` to be greater than or equal to 0, received {row}"
+            )
 
         patch: CellPatch = {
             "value": value,

tests/playwright/shiny/components/data_frame/update_cell_value/app.py

@@ -3,27 +3,51 @@
 from __future__ import annotations
 
 import palmerpenguins  # pyright: ignore[reportMissingTypeStubs]
+import polars as pl
 
 from shiny import reactive
 from shiny.express import input, render, ui
 
-pd_df = palmerpenguins.load_penguins_raw().iloc[0:2, 0:2]
+pd_data = palmerpenguins.load_penguins_raw().iloc[0:2, 0:2]
+pl_data = pl.DataFrame(pd_data)
 
-with ui.card():
+with ui.layout_column_wrap(width=1 / 2):
 
-    ui.input_action_button("update_btn", "Update cell")
+    with ui.card():
 
-    @render.data_frame
-    def dt():
-        return pd_df
+        ui.h3("Pandas")
 
+        ui.input_action_button("update_pd_btn", "Update cell")
 
-@reactive.effect
-@reactive.event(input.update_btn)
-async def update_cell():
+        @render.data_frame
+        def pd_df():
+            return pd_data
 
-    await dt.update_cell_value(
-        "new_value - " + str(input.update_btn()),
-        row=0,
-        col=0,
-    )
+    @reactive.effect
+    @reactive.event(input.update_pd_btn)
+    async def _():
+
+        await pd_df.update_cell_value(
+            "pandas - " + str(input.update_pd_btn()),
+            row=0,
+            col=0,
+        )
+
+    with ui.card():
+
+        ui.h3("Polars")
+        ui.input_action_button("update_pl_btn", "Update cell")
+
+        @render.data_frame
+        def pl_df():
+            return pl_data
+
+    @reactive.effect
+    @reactive.event(input.update_pl_btn)
+    async def _():
+
+        await pl_df.update_cell_value(
+            "polars - " + str(input.update_pl_btn()),
+            row=0,
+            col=0,
+        )

tests/playwright/shiny/components/data_frame/update_cell_value/test_cell_value.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from playwright.sync_api import Page
+
+from shiny.playwright import controller
+from shiny.run import ShinyAppProc
+
+
+def test_update_cell_value(page: Page, local_app: ShinyAppProc) -> None:
+    page.goto(local_app.url)
+
+    pd_df = controller.OutputDataFrame(page, "pd_df")
+    pd_df.expect_cell("PAL0708", row=0, col=0)
+
+    pl_df = controller.OutputDataFrame(page, "pl_df")
+    pl_df.expect_cell("PAL0708", row=0, col=0)
+
+    pd_btn = controller.InputActionButton(page, "update_pd_btn")
+    pl_btn = controller.InputActionButton(page, "update_pl_btn")
+
+    # Update pandas
+    pd_btn.click()
+    pd_df.expect_cell("pandas - 1", row=0, col=0)
+    pl_df.expect_cell("PAL0708", row=0, col=0)
+
+    # Update polars
+    pl_btn.click()
+    pl_btn.click()
+    pl_btn.click()
+
+    pd_df.expect_cell("pandas - 1", row=0, col=0)
+    pl_df.expect_cell("polars - 3", row=0, col=0)
+
+    # Verify other cells do not change
+    pd_df.expect_cell("PAL0708", row=1, col=0)
+    pd_df.expect_cell("1", row=0, col=1)
+    pd_df.expect_cell("2", row=1, col=1)
+
+    pl_df.expect_cell("PAL0708", row=1, col=0)
+    pl_df.expect_cell("1", row=0, col=1)
+    pl_df.expect_cell("2", row=1, col=1)

tests/playwright/shiny/components/data_frame/update_data/app.py

@@ -8,7 +8,7 @@
 from shiny import reactive
 from shiny.express import input, render, ui
 
-pd_df = palmerpenguins.load_penguins_raw()
+pd_data = palmerpenguins.load_penguins_raw()
 
 
 with ui.card():
@@ -19,9 +19,9 @@
     ui.h4("Data")
 
     @render.data_frame
-    def dt():
+    def df():
         return render.DataGrid(
-            pd_df.iloc[:, 0:2],
+            pd_data.iloc[:, 0:2],
             selection_mode="rows",
             filters=True,
             editable=True,
@@ -30,17 +30,12 @@ def dt():
     ui.h4("Selected data")
 
     @render.data_frame
-    def dt_selected():
-        return dt.data_view(selected=True)
-
-    @reactive.effect
-    @reactive.event(dt.cell_selection)
-    def _on_cell_selection():
-        print("Cell selected", dt.cell_selection())
-        return
+    def df_selected():
+        return df.data_view(selected=True)
 
 
-data_val = reactive.value(pd_df)
+# Reactive value to store the un-subsetted data
+full_data = reactive.value(pd_data)
 
 
 @reactive.effect
@@ -51,8 +46,9 @@ async def shift_data():
         raise ValueError("update_btn must exist")
 
     k = 2
-    shift = (k * input.shift_btn()) % data_val().shape[0]
-    await dt.update_data(data_val().iloc[(0 + shift) : (k + shift), 0:2])
+    shift = (k * input.shift_btn()) % full_data().shape[0]
+    subsetted_data = full_data().iloc[(0 + shift) : (k + shift), 0:2]
+    await df.update_data(subsetted_data)
     return
 
 
@@ -67,14 +63,13 @@ async def different_data():
         "input.different_btn()", input.different_btn(), input.different_btn() % 2 == 0
     )
     if input.different_btn() % 2 == 0:
-        # await dt.update_data(pd_df.iloc[:, 0:2])
-        await dt.update_data(pd_df)
-        data_val.set(pd_df)
+        await df.update_data(pd_data)
+        full_data.set(pd_data)
         return
 
     new_df = pd.DataFrame(
         {
-            "studyName": [
+            "Letter": [
                 "a",
                 "b",
                 "c",
@@ -102,9 +97,9 @@ async def different_data():
                 "y",
                 "z",
             ],
-            "Sample Number": [-1 * i for i in range(1, 27)],
+            "Negative index": [-1 * i for i in range(1, 27)],
         },
     )
-    await dt.update_data(new_df)
-    data_val.set(new_df)
+    await df.update_data(new_df)
+    full_data.set(new_df)
     return