feat: Add display.render_mode option to control DataFrame visualization

Author: shuoweil

bigframes/display/html.py

@@ -361,7 +361,7 @@ def repr_mimebundle(
     if opts.repr_mode == "deferred":
         return repr_mimebundle_deferred(obj)
 
-    if opts.repr_mode == "anywidget":
+    if opts.render_mode == "anywidget":
         try:
             return get_anywidget_bundle(obj, include=include, exclude=exclude)
         except ImportError:
@@ -374,4 +374,8 @@ def repr_mimebundle(
                 f"Falling back to static HTML. Error: {traceback.format_exc()}"
             )
 
-    return repr_mimebundle_head(obj)
+    bundle = repr_mimebundle_head(obj)
+    if opts.render_mode == "plaintext":
+        bundle.pop("text/html", None)
+
+    return bundle

notebooks/dataframes/anywidget_mode.ipynb

@@ -63,7 +63,7 @@
    "outputs": [],
    "source": [
     "bpd.options.bigquery.ordering_mode = \"partial\"\n",
-    "bpd.options.display.repr_mode = \"anywidget\""
+    "bpd.options.display.render_mode = \"anywidget\""
    ]
   },
   {

notebooks/ml/timeseries_analysis.ipynb

@@ -19,7 +19,7 @@
    "source": [
     "import bigframes.pandas as bpd\n",
     "from bigframes.ml import forecasting\n",
-    "bpd.options.display.repr_mode = \"anywidget\""
+    "bpd.options.display.render_mode = \"anywidget\""
    ]
   },
   {

tests/system/small/test_anywidget.py

@@ -70,7 +70,7 @@ def table_widget(paginated_bf_df: bigframes.dataframe.DataFrame):
     from bigframes.display import TableWidget
 
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         # Delay context manager cleanup of `max_rows` until after tests finish.
         yield TableWidget(paginated_bf_df)
@@ -100,7 +100,7 @@ def small_widget(small_bf_df):
     """Helper fixture for tests using a DataFrame smaller than the page size."""
     from bigframes.display import TableWidget
 
-    with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 5):
+    with bf.option_context("display.render_mode", "anywidget", "display.max_rows", 5):
         yield TableWidget(small_bf_df)
 
 
@@ -126,7 +126,9 @@ def unknown_row_count_widget(session):
         mock_batches.return_value = blocks.PandasBatches(
             batches_iterator, total_rows=None
         )
-        with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 2):
+        with bf.option_context(
+            "display.render_mode", "anywidget", "display.max_rows", 2
+        ):
             widget = TableWidget(bf_df)
             yield widget
 
@@ -206,7 +208,7 @@ def test_widget_initialization_should_calculate_total_row_count(
     from bigframes.display import TableWidget
 
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(paginated_bf_df)
 
@@ -316,7 +318,7 @@ def test_widget_pagination_should_work_with_custom_page_size(
 ):
     """Test that a widget paginates correctly with a custom page size."""
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 3
+        "display.render_mode", "anywidget", "display.max_rows", 3
     ):
         from bigframes.display import TableWidget
 
@@ -370,7 +372,7 @@ def test_global_options_change_should_not_affect_existing_widget_page_size(
     then the widget's page size should remain unchanged.
     """
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         from bigframes.display import TableWidget
 
@@ -395,7 +397,7 @@ def test_widget_with_empty_dataframe_should_have_zero_row_count(
     then its row_count should be 0.
     """
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         from bigframes.display import TableWidget
 
         widget = TableWidget(empty_bf_df)
@@ -421,7 +423,7 @@ def test_widget_with_empty_dataframe_should_render_table_headers(
 
     """
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
 
         from bigframes.display import TableWidget
 
@@ -550,7 +552,7 @@ def test_widget_row_count_should_be_immutable_after_creation(
 
     # Use a context manager to ensure the option is reset
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(paginated_bf_df)
         initial_row_count = widget.row_count
@@ -585,7 +587,7 @@ def test_widget_should_show_error_on_batch_failure(
     )
 
     # Create the TableWidget under the error condition.
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         from bigframes.display import TableWidget
 
         # The widget should handle the faulty data from the mock without crashing.
@@ -609,7 +611,7 @@ def test_widget_row_count_reflects_actual_data_available(
 
     # Set up display options that define a page size.
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(paginated_bf_df)
 
@@ -639,7 +641,7 @@ def test_widget_with_unknown_row_count_should_auto_navigate_to_last_page(
     bf_df = session.read_pandas(test_data)
 
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(bf_df)
 
@@ -681,7 +683,7 @@ def test_widget_with_unknown_row_count_should_set_none_state_for_frontend(
     bf_df = session.read_pandas(test_data)
 
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(bf_df)
 
@@ -718,7 +720,7 @@ def test_widget_with_unknown_row_count_should_allow_forward_navigation(
     bf_df = session.read_pandas(test_data)
 
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         widget = TableWidget(bf_df)
         widget.row_count = None
@@ -755,7 +757,7 @@ def test_widget_with_unknown_row_count_empty_dataframe(
     empty_data = pd.DataFrame(columns=["id", "value"])
     bf_df = session.read_pandas(empty_data)
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         widget = TableWidget(bf_df)
         widget.row_count = None
 
@@ -908,7 +910,7 @@ def test_repr_mimebundle_should_fallback_to_html_if_anywidget_is_unavailable(
     Test that _repr_mimebundle_ falls back to static html when anywidget is not available.
     """
     with bigframes.option_context(
-        "display.repr_mode", "anywidget", "display.max_rows", 2
+        "display.render_mode", "anywidget", "display.max_rows", 2
     ):
         # Mock the ANYWIDGET_INSTALLED flag to simulate absence of anywidget
         with mock.patch("bigframes.display.anywidget._ANYWIDGET_INSTALLED", False):
@@ -927,7 +929,7 @@ def test_repr_mimebundle_should_return_widget_view_if_anywidget_is_available(
     """
     Test that _repr_mimebundle_ returns a widget view when anywidget is available.
     """
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         bundle = paginated_bf_df._repr_mimebundle_()
         assert isinstance(bundle, tuple)
         data, metadata = bundle
@@ -943,7 +945,7 @@ def test_repr_in_anywidget_mode_should_not_be_deferred(
     Test that repr(df) is not deferred in anywidget mode.
     This is to ensure that print(df) works as expected.
     """
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         representation = repr(paginated_bf_df)
         assert "Computation deferred" not in representation
         assert "page_1_row_1" in representation
@@ -954,7 +956,7 @@ def test_dataframe_repr_mimebundle_should_return_widget_with_metadata_in_anywidg
     session: bigframes.Session,  # Add session as a fixture
 ):
     """Test that _repr_mimebundle_ returns a widget view with metadata when anywidget is available."""
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         # Create a real DataFrame object (or a mock that behaves like one minimally)
         # for _repr_mimebundle_ to operate on.
         test_df = bigframes.dataframe.DataFrame(
@@ -1051,7 +1053,7 @@ def test_widget_with_default_index_should_display_index_column_with_empty_header
 
     from bigframes.display.anywidget import TableWidget
 
-    with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 2):
+    with bf.option_context("display.render_mode", "anywidget", "display.max_rows", 2):
         widget = TableWidget(paginated_bf_df)
         html = widget.table_html
 
@@ -1075,7 +1077,7 @@ def test_widget_with_custom_index_should_display_index_column(
     """
     from bigframes.display.anywidget import TableWidget
 
-    with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 2):
+    with bf.option_context("display.render_mode", "anywidget", "display.max_rows", 2):
         widget = TableWidget(custom_index_bf_df)
         html = widget.table_html
 
@@ -1095,7 +1097,7 @@ def test_widget_with_custom_index_pagination_preserves_index(
     """
     from bigframes.display.anywidget import TableWidget
 
-    with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 2):
+    with bf.option_context("display.render_mode", "anywidget", "display.max_rows", 2):
         widget = TableWidget(custom_index_bf_df)
 
         widget.page = 1  # Navigate to page 2
@@ -1116,7 +1118,7 @@ def test_widget_with_custom_index_matches_pandas_output(
     """
     from bigframes.display.anywidget import TableWidget
 
-    with bf.option_context("display.repr_mode", "anywidget", "display.max_rows", 3):
+    with bf.option_context("display.render_mode", "anywidget", "display.max_rows", 3):
         widget = TableWidget(custom_index_bf_df)
         html = widget.table_html
 
@@ -1137,7 +1139,7 @@ def test_series_anywidget_integration_with_notebook_display(
     """Test Series display integration in Jupyter-like environment."""
     pytest.importorskip("anywidget")
 
-    with bf.option_context("display.repr_mode", "anywidget"):
+    with bf.option_context("display.render_mode", "anywidget"):
         series = paginated_bf_df["value"]
 
         # Test the full display pipeline
@@ -1162,7 +1164,7 @@ def test_series_different_data_types_anywidget(session: bf.Session):
     )
     bf_df = session.read_pandas(test_data)
 
-    with bf.option_context("display.repr_mode", "anywidget"):
+    with bf.option_context("display.render_mode", "anywidget"):
         for col_name in test_data.columns:
             series = bf_df[col_name]
             widget = bigframes.display.TableWidget(series.to_frame())

tests/system/small/test_progress_bar.py

@@ -151,7 +151,7 @@ def test_query_job_dry_run_series(penguins_df_default_index: bf.dataframe.DataFr
 
 def test_repr_anywidget_dataframe(penguins_df_default_index: bf.dataframe.DataFrame):
     pytest.importorskip("anywidget")
-    with bf.option_context("display.repr_mode", "anywidget"):
+    with bf.option_context("display.render_mode", "anywidget"):
         actual_repr = repr(penguins_df_default_index)
         assert "species" in actual_repr
         assert "island" in actual_repr
@@ -160,7 +160,7 @@ def test_repr_anywidget_dataframe(penguins_df_default_index: bf.dataframe.DataFr
 
 def test_repr_anywidget_index(penguins_df_default_index: bf.dataframe.DataFrame):
     pytest.importorskip("anywidget")
-    with bf.option_context("display.repr_mode", "anywidget"):
+    with bf.option_context("display.render_mode", "anywidget"):
         index = penguins_df_default_index.index
         actual_repr = repr(index)
         # In non-interactive environments, should still get a useful summary.

tests/unit/display/test_anywidget.py

@@ -43,7 +43,7 @@ def test_navigation_to_invalid_page_resets_to_valid_page_without_deadlock():
     # We mock _initial_load to avoid complex setup
     with mock.patch.object(TableWidget, "_initial_load"):
         with bigframes.option_context(
-            "display.repr_mode", "anywidget", "display.max_rows", 10
+            "display.render_mode", "anywidget", "display.max_rows", 10
         ):
             widget = TableWidget(mock_df)
 
@@ -130,7 +130,7 @@ def test_sorting_single_column(mock_df):
     """Test that the widget can be sorted by a single column."""
     from bigframes.display.anywidget import TableWidget
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         widget = TableWidget(mock_df)
 
     # Verify initial state
@@ -149,7 +149,7 @@ def test_sorting_multi_column(mock_df):
     """Test that the widget can be sorted by multiple columns."""
     from bigframes.display.anywidget import TableWidget
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         widget = TableWidget(mock_df)
 
     # Apply multi-column sort
@@ -165,7 +165,7 @@ def test_page_size_change_resets_sort(mock_df):
     """Test that changing the page size resets the sorting."""
     from bigframes.display.anywidget import TableWidget
 
-    with bigframes.option_context("display.repr_mode", "anywidget"):
+    with bigframes.option_context("display.render_mode", "anywidget"):
         widget = TableWidget(mock_df)
 
     # Set sort state