A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: standardize supported dataframe backends across UI elements (#9583)
Myles Scolnick1c7c29a18197
diff --git a/docs/api/inputs/dataframe.md b/docs/api/inputs/dataframe.mdindex 82ba25341e..a1deb9fe83 100644--- a/docs/api/inputs/dataframe.md+++ b/docs/api/inputs/dataframe.md@@ -2,10 +2,9 @@The dataframe UI element outputs a visual editor to apply "transforms" to a dataframe, such as filtering rows, applying group-bys and aggregations, and more. The transformed dataframe is shown below the transform editor. The UI output also includes the generated Python used to generate the resulting dataframe, which you can copy paste into a cell. You can programmatically access the resulting dataframe by accessing the element's `.value` attribute.-!!! note "Pandas or Polars Required"+!!! note "Dataframe library required"- In order to use the dataframe UI element, you must have the `pandas` or `polars` package installed.- You can install it with `pip install pandas` or `pip install polars`.+ To use the dataframe UI element, you must have a supported dataframe library installed (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).Supported transforms are:diff --git a/marimo/_plugins/ui/_impl/altair_chart.py b/marimo/_plugins/ui/_impl/altair_chart.pyindex c5edff4609..5e9af95ded 100644--- a/marimo/_plugins/ui/_impl/altair_chart.py+++ b/marimo/_plugins/ui/_impl/altair_chart.py@@ -476,7 +476,7 @@ class altair_chart(UIElement[ChartSelection, ChartDataType]):Use `mo.ui.altair_chart` to make Altair charts reactive: select chart datawith your cursor on the frontend, get them as a dataframe in Python!- Supports polars, pandas, and arrow DataFrames.+ Supports any dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).Examples:```pythondiff --git a/marimo/_plugins/ui/_impl/data_editor.py b/marimo/_plugins/ui/_impl/data_editor.pyindex eea0660936..3a8e17beb6 100644--- a/marimo/_plugins/ui/_impl/data_editor.py+++ b/marimo/_plugins/ui/_impl/data_editor.py@@ -128,7 +128,7 @@ class data_editor(https://github.com/marimo-team/marimo/issues.The data can be supplied as:- 1. a Pandas, Polars, or Pyarrow DataFrame+ 1. an eager dataframe (e.g., Polars, Pandas, PyArrow)2. a list of dicts, with one dict for each row, keyed by column names3. a dict of lists, with each list representing a column@@ -240,7 +240,14 @@ class data_editor(self, value: DataEdits) -> RowOrientedData | ColumnOrientedData | IntoDataFrame:self._edits = value- return apply_edits(deepcopy(self._data), value)+ # list/dict edit paths mutate in place, so deepcopy first.+ # The dataframe path constructs a new native frame via narwhals+ # without mutating the input — and not all dataframes are picklable+ # (e.g., DuckDBPyRelation), so skip the deepcopy in that case.+ data = self._data+ if isinstance(data, (list, dict)):+ data = deepcopy(data)+ return apply_edits(data, value)def __hash__(self) -> int:return id(self)diff --git a/marimo/_plugins/ui/_impl/data_explorer.py b/marimo/_plugins/ui/_impl/data_explorer.pyindex 9d99eed80a..8ef6420a56 100644--- a/marimo/_plugins/ui/_impl/data_explorer.py+++ b/marimo/_plugins/ui/_impl/data_explorer.py@@ -30,7 +30,7 @@ class data_explorer(UIElement[dict[str, Any], dict[str, Any]]):initial selections if provided via keyword arguments.Args:- df (IntoDataFrame): The DataFrame to visualize.+ df (IntoDataFrame): The dataframe to visualize (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).on_change (Callable[[dict[str, Any]], None], optional): Optional callbackto run when this element's value changes.x (Optional[str]): Initial column for the x-axis. Defaults to None.diff --git a/marimo/_plugins/ui/_impl/dataframes/dataframe.py b/marimo/_plugins/ui/_impl/dataframes/dataframe.pyindex fc6c4de117..3703fa6bea 100644--- a/marimo/_plugins/ui/_impl/dataframes/dataframe.py+++ b/marimo/_plugins/ui/_impl/dataframes/dataframe.py@@ -104,7 +104,7 @@ class GetDataFrameError(Exception):class dataframe(UIElement[dict[str, Any], DataFrameType]):"""Run transformations on a DataFrame or series.- Currently supports Pandas, Polars, Ibis, Pyarrow, and DuckDB.+ Supports any dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).Examples:```pythondiff --git a/marimo/_plugins/ui/_impl/table.py b/marimo/_plugins/ui/_impl/table.pyindex a165e37596..cae97c3874 100644--- a/marimo/_plugins/ui/_impl/table.py+++ b/marimo/_plugins/ui/_impl/table.py@@ -319,10 +319,7 @@ class table(1. a list of dicts, with one dict for each row, keyed by column names;2. a list of values, representing a table with a single column;- 3. a Pandas dataframe; or- 4. a Polars dataframe; or- 5. an Ibis dataframe; or- 6. a PyArrow table.+ 3. a dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).Examples:Create a table from a list of dicts, one for each row:@@ -492,7 +489,7 @@ class table(preload: bool = False,) -> table:"""- Create a table from a Polars LazyFrame.+ Create a table from a lazy dataframe (e.g., Polars LazyFrame, Ibis Table, DuckDB Relation).This won't load the data into memory until requested by the user.Once requested, only the first 10 rows will be loaded.diff --git a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py b/tests/_plugins/ui/_impl/dataframes/test_dataframe.pyindex 8d24d694ac..0703434795 100644--- a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py+++ b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py@@ -1,7 +1,7 @@from __future__ import annotationsimport json-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Anyfrom unittest.mock import Mock, patchimport narwhals.stable.v2 as nw@@ -61,12 +61,22 @@ def is_not_narwhals_dataframe(df: IntoDataFrame | IntoLazyFrame) -> bool:@pytest.mark.skipif(not HAS_DEPS, reason="optional dependencies not installed")class TestDataframes:+ @staticmethod+ @pytest.mark.parametrize(+ "df",+ create_dataframes({"A": [1, 2, 3], "B": ["a", "a", "a"]}),+ )+ def test_dataframe_supports_dataframe_backends(df: Any) -> None:+ subject = ui.dataframe(df)+ # Construction should succeed and the value should round-trip to the+ # original native type for each supported dataframe backend.+ assert type(subject.value) is type(df)+@staticmethod@pytest.mark.parametrize("df",create_dataframes({"A": [1, 2, 3], "B": ["a", "a", "a"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe(df: IntoDataFrame) -> None:@@ -82,6 +92,8 @@ class TestDataframes:[["A", "integer", "int64"], ["B", "string", "string"]],# pandas 3.x[["A", "integer", "int64"], ["B", "string", "str"]],+ # pyarrow / duckdb (via narwhals)+ [["A", "integer", "Int64"], ["B", "string", "String"]],]assert subject._get_column_values(GetColumnValuesArgs(column="A")@@ -136,7 +148,6 @@ class TestDataframes:"df",create_dataframes({"1": [1, 2, 3], "2": ["a", "a", "a"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_page_size(df: IntoDataFrame) -> None:@@ -171,7 +182,6 @@ class TestDataframes:"df",create_dataframes({"A": [1, 2], "B": ["a", "b"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_format_mapping(df: IntoDataFrame) -> None:@@ -193,18 +203,15 @@ class TestDataframes:[*create_dataframes({"A": [], "B": []},- exclude=["pyarrow", "duckdb", "lazy-polars"],), # Empty DataFrame*create_dataframes({"A": [1], "B": ["a"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],), # Single row DataFrame*create_dataframes({"A": range(1, 1001),"B": [f"value_{i}" for i in range(1, 1001)],},- exclude=["pyarrow", "duckdb", "lazy-polars"],), # Large DataFrame],)@@ -236,7 +243,6 @@ class TestDataframes:"df",create_dataframes({"A": range(100), "B": ["a"] * 100},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_with_custom_page_size(df: IntoDataFrame) -> None:@@ -285,7 +291,6 @@ class TestDataframes:"df",create_dataframes({"A": range(1000), "B": ["a"] * 1000},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_with_limit(df: IntoDataFrame) -> None:@@ -474,7 +479,6 @@ class TestDataframes:"df",create_dataframes({"A": [1, 2, 3], "B": ["x", "y", "z"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_download_different_backends(df) -> None:@@ -541,7 +545,6 @@ class TestDataframes:"df",create_dataframes({"A": [1, 2, 3], "B": ["a", "b", "c"]},- exclude=["pyarrow", "duckdb", "lazy-polars"],),)def test_dataframe_error_handling(df: IntoDataFrame) -> None:diff --git a/tests/_plugins/ui/_impl/test_data_editor.py b/tests/_plugins/ui/_impl/test_data_editor.pyindex 6bdd62d088..101562bb32 100644--- a/tests/_plugins/ui/_impl/test_data_editor.py+++ b/tests/_plugins/ui/_impl/test_data_editor.py@@ -15,6 +15,7 @@ from marimo._plugins.ui._impl.data_editor import (_convert_value,apply_edits,)+from tests._data.mocks import create_dataframesdata_editor = ui.data_editor@@ -412,6 +413,27 @@ def test_data_editor_with_polars_dataframe():assert df.equals(editor.data)+ "df",+ # data_editor uses narwhals with eager_only=True, so it only supports+ # eager dataframe backends (pandas, polars, pyarrow), not lazy/relation+ # types like Ibis and DuckDB.+ create_dataframes(+ {"A": [1, 2, 3], "B": ["a", "b", "c"]},+ exclude=["lazy-polars", "ibis", "duckdb"],+ ),+)+def test_data_editor_supports_dataframe_backends(df: Any) -> None:+ editor = data_editor(data=df)+ assert type(editor.data) is type(df)+ # An applied edit should round-trip back to the same native type.+ edits: DataEdits = {+ "edits": [{"rowIdx": 1, "columnId": "B", "value": "x"}]+ }+ result = editor._convert_value(edits)+ assert type(result) is type(df)++@pytest.mark.skipif(not DependencyManager.polars.has(), reason="Polars not installed")diff --git a/tests/_plugins/ui/_impl/test_table.py b/tests/_plugins/ui/_impl/test_table.pyindex 8894545592..7fba3c5a2c 100644--- a/tests/_plugins/ui/_impl/test_table.py+++ b/tests/_plugins/ui/_impl/test_table.py@@ -1012,7 +1012,7 @@ def test_show_column_summaries_modes():class TestTableBinValues:@pytest.mark.parametrize("df",- create_dataframes({"a": [None] * 20}, exclude=["duckdb"]),+ create_dataframes({"a": [None] * 20}),)def test_bin_values_all_nulls(self, df: Any) -> None:table = ui.table(df)