feat: Refactor anywidget display to use _ipython_display_

Author: shuoweil

README.rst

@@ -110,6 +110,19 @@ For details, see the `third_party
 directory.
 
 
+Display Enhancements
+--------------------
+
+**DataFrame `_repr_html_()` and `_ipython_display_()` Integration**
+
+The `bigframes.pandas.DataFrame._repr_html_()` method has been updated. When `bpd.options.display.repr_mode` is set to “anywidget”, it will:
+
+*   Wrap the import of `anywidget` in a `try...except ImportError` block. If the dependency is not found, it will issue a `warnings.warn` message and fall back to returning the deferred representation.
+*   If the import is successful, it instantiates a new `TableWidget`, passing the DataFrame's data.
+*   Return the widget instance, which Jupyter automatically renders. A new widget instance is created for each `_repr_html_()` call to ensure cell outputs are isolated.
+
+A new `_ipython_display_()` method has been introduced to handle the actual widget rendering, separating concerns from `_repr_html_()`.
+
 Contact Us
 ----------
 

bigframes/dataframe.py

@@ -837,10 +837,12 @@ def _repr_html_(self) -> str:
         """
         opts = bigframes.options.display
         max_results = opts.max_rows
-        if opts.repr_mode == "deferred":
+        # For anywidget mode, return deferred representation
+        # The actual widget display is handled by _ipython_display_()
+        if opts.repr_mode in ("deferred", "anywidget"):
             return formatter.repr_query_job(self._compute_dry_run())
 
-        # Process blob columns first, regardless of display mode
+        # Process blob columns first for non-deferred modes
         self._cached()
         df = self.copy()
         if bigframes.options.display.blob_display:
@@ -855,29 +857,6 @@ def _repr_html_(self) -> str:
         else:
             blob_cols = []
 
-        if opts.repr_mode == "anywidget":
-            try:
-                from IPython.display import display as ipython_display
-
-                from bigframes import display
-
-                # Always create a new widget instance for each display call
-                # This ensures that each cell gets its own widget and prevents
-                # unintended sharing between cells
-                widget = display.TableWidget(df.copy())
-
-                ipython_display(widget)
-                return ""  # Return empty string since we used display()
-
-            except (AttributeError, ValueError, ImportError):
-                # Fallback if anywidget is not available
-                warnings.warn(
-                    "Anywidget mode is not available. "
-                    "Please `pip install anywidget traitlets` or `pip install 'bigframes[anywidget]'` to use interactive tables. "
-                    f"Falling back to deferred mode. Error: {traceback.format_exc()}"
-                )
-                return formatter.repr_query_job(self._compute_dry_run())
-
         # Continue with regular HTML rendering for non-anywidget modes
         # TODO(swast): pass max_columns and get the true column count back. Maybe
         # get 1 more column than we have requested so that pandas can add the
@@ -937,6 +916,55 @@ def obj_ref_rt_to_html(obj_ref_rt) -> str:
         html_string += f"[{row_count} rows x {column_count} columns in total]"
         return html_string
 
+    def _ipython_display_(self):
+        """
+        Custom display method for IPython/Jupyter environments.
+        This is called by IPython's display system when the object is displayed.
+        """
+        opts = bigframes.options.display
+
+        # Only handle widget display in anywidget mode
+        if opts.repr_mode == "anywidget":
+            try:
+                from bigframes import display
+
+                # Process blob columns if needed
+                self._cached()
+                df = self.copy()
+                if bigframes.options.display.blob_display:
+                    blob_cols = [
+                        series_name
+                        for series_name, series in df.items()
+                        if series.dtype == bigframes.dtypes.OBJ_REF_DTYPE
+                    ]
+                    for col in blob_cols:
+                        df[col] = df[col].blob._get_runtime(
+                            mode="R", with_metadata=True
+                        )
+
+                # Create and display the widget
+                widget = display.TableWidget(df)
+
+                # IPython will automatically display the widget
+                # since we're returning it from _ipython_display_()
+                from IPython.display import display as ipython_display
+
+                ipython_display(widget)
+                return  # Important: return None to signal we handled display
+
+            except (AttributeError, ValueError, ImportError):
+                # Fallback: let IPython use _repr_html_() instead
+                warnings.warn(
+                    "Anywidget mode is not available. "
+                    "Please `pip install anywidget traitlets` or `pip install 'bigframes[anywidget]'` to use interactive tables. "
+                    f"Falling back to deferred mode. Error: {traceback.format_exc()}"
+                )
+                # Don't return anything - let IPython fall back to _repr_html_()
+                return
+
+        # For other modes, don't handle display - let IPython use _repr_html_()
+        return
+
     def __delitem__(self, key: str):
         df = self.drop(columns=[key])
         self._set_block(df._get_block())

notebooks/dataframes/anywidget_mode.ipynb

@@ -36,6 +36,7 @@
    "id": "ca22f059",
    "metadata": {},
    "outputs": [],
+   "outputs": [],
    "source": [
     "import bigframes.pandas as bpd"
    ]
@@ -143,6 +144,7 @@
      "data": {
       "application/vnd.jupyter.widget-view+json": {
        "model_id": "8fcad7b7e408422cae71d519cd2d4980",
+       "model_id": "4cc789c49be246bb94967e625986900a",
        "version_major": 2,
        "version_minor": 1
       },
@@ -152,17 +154,6 @@
      },
      "metadata": {},
      "output_type": "display_data"
-    },
-    {
-     "data": {
-      "text/html": [],
-      "text/plain": [
-       "Computation deferred. Computation will process 171.4 MB"
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
     }
    ],
    "source": [
@@ -206,6 +197,7 @@
      "data": {
       "application/vnd.jupyter.widget-view+json": {
        "model_id": "06cb98c577514d5c9654a7792d93f8e6",
+       "model_id": "b1089664ce03440d81ef206da1210229",
        "version_major": 2,
        "version_minor": 1
       },
@@ -284,6 +276,8 @@
     {
      "data": {
       "text/html": [
+       "✅ Completed. \n",
+       "    Query processed 171.4 MB in a moment of slot time.\n",
        "✅ Completed. \n",
        "    Query processed 171.4 MB in a moment of slot time.\n",
        "    "
@@ -306,6 +300,7 @@
      "data": {
       "application/vnd.jupyter.widget-view+json": {
        "model_id": "1672f826f7a347e38539dbb5fb72cd43",
+       "model_id": "f18925fc13304fb2ae34056f2cb1c68b",
        "version_major": 2,
        "version_minor": 1
       },
@@ -346,6 +341,7 @@
       "text/html": [
        "✅ Completed. \n",
        "    Query processed 85.9 kB in 12 seconds of slot time.\n",
+       "    Query processed 85.9 kB in 15 seconds of slot time.\n",
        "    "
       ],
       "text/plain": [
@@ -359,6 +355,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
+      "/usr/local/google/home/shuowei/src/python-bigquery-dataframes/bigframes/dtypes.py:987: JSONDtypeWarning: JSON columns will be represented as pandas.ArrowDtype(pyarrow.json_())\n",
       "/usr/local/google/home/shuowei/src/python-bigquery-dataframes/bigframes/dtypes.py:987: JSONDtypeWarning: JSON columns will be represented as pandas.ArrowDtype(pyarrow.json_())\n",
       "instead of using `db_dtypes` in the future when available in pandas\n",
       "(https://github.com/pandas-dev/pandas/issues/60958) and pyarrow.\n",
@@ -381,6 +378,7 @@
      "data": {
       "application/vnd.jupyter.widget-view+json": {
        "model_id": "127a2e356b834c18b6f07c58ee2c4228",
+       "model_id": "2335d3161b704a6da85165dbebf5ca0f",
        "version_major": 2,
        "version_minor": 1
       },
@@ -390,17 +388,6 @@
      },
      "metadata": {},
      "output_type": "display_data"
-    },
-    {
-     "data": {
-      "text/html": [],
-      "text/plain": [
-       "Computation deferred. Computation will process 0 Bytes"
-      ]
-     },
-     "execution_count": 10,
-     "metadata": {},
-     "output_type": "execute_result"
     }
    ],
    "source": [