feat: display series in anywidget mode #2346

shuoweil · 2025-12-19T02:33:05Z

This PR introduces interactive table displays for bigframes.Series objects, aligning their notebook behavior with bigframes.DataFrame. Now, when using the "anywidget" display mode, Series are rendered as interactive tables, significantly improving data exploration. Additionally, the standard text representation for a Series has been enhanced to include the total row count, providing more context at a glance.

User-Impactful Changes

Interactive Series Display: When bigframes.options.display.repr_mode is set to "anywidget", displaying a bigframes.Series in a notebook will now render an interactive widget. The widget presents the Series as a two-column table, showing the index and the values.

Example Usage:

    import bigframes.pandas as bpd

    # Enable interactive mode
    bpd.options.display.repr_mode = "anywidget"

    # Create or load a DataFrame
    df = bpd.read_gbq(...)
    series = df["my_column"]

   # Displaying the series will now show an interactive table
   series

Enhanced Text Representation: The default text representation (e.g., when using print()) for a bigframes.Series now includes the total number of rows at the end, similar to DataFrames. For example:

   0       a
   1       b
   2       c
   ...
   Name: my_column, Length: 10, dtype: string

   [1000 rows]

These changes create a more consistent and intuitive user experience between Series and DataFrames within notebook environments.

Verified at:

vs code notebook: screen/6QWpRs5nuNESp6e
colab notebook: screen/4SPpQXtHxk5bRpk

Fixes #<460860439> 🦕

review-notebook-app · 2025-12-19T02:33:10Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

This reverts commit c39293a.

… be displayed in one page

…t _literal (#2337) This change can resolve two doctests failures in #2248: `groupby.GroupBy.rank` and `bigframes.ml.metrics.roc_curve` Fixes internal issue 417774347🦕 --------- Co-authored-by: Shenyang Cai <[email protected]>

tswast · 2025-12-19T22:06:43Z

bigframes/series.py

A lot of this code is nearly identical to the logic in https://github.com/googleapis/python-bigquery-dataframes/blob/main/bigframes/dataframe.py with the following differences:

Call self.to_frame() before rendering the TableWidget.

Use the Series object when rendering the text/html and text/plain.

Could you please refactor dataframe.py and this file to use shared helper functions to reduce duplication? https://github.com/googleapis/python-bigquery-dataframes/blob/main/bigframes/display/html.py seems like it'd be and appropriate place for such helpers.

tswast · 2025-12-19T22:08:02Z

bigframes/series.py

+        # Add text representation
+        widget_repr["text/plain"] = self._create_text_representation(
+            widget._cached_data, widget.row_count
+        )


Just like with dataframe, we should have the html rendering here too. See

python-bigquery-dataframes/bigframes/dataframe.py

Lines 871 to 883 in 3c54c68

# At this point, we have already executed the query as part of the

# widget construction. Let's use the information available to render

# the HTML and plain text versions.

widget_repr["text/html"] = self._create_html_representation(

widget._cached_data,

widget.row_count,

len(self.columns),

blob_cols,

)

widget_repr["text/plain"] = self._create_text_representation(

widget._cached_data, widget.row_count

)

Ideally we'd refactor so that the code is shared. One way to do this would be to call the respective Series._create_html_representation or DataFrame._create_html_representation from the helper function.

tswast · 2025-12-19T22:11:59Z

tests/js/series_widget.test.js

We don't actually need the SeriesWidget class, right? I believe this file can be deleted.

There is no SeriesWidget class. We are reusing the existing TableWidget to display Series data. This file is a test file. It checks if bf DataFrames Series is correctly rendered as a two-column table (one for the index, one for the data). But I agree that the file name is misleading, I will merge all tests to table_widget.test.js to avoid confusion.

tswast · 2025-12-19T22:12:31Z

tests/system/small/test_anywidget.py

        assert "text/plain" in data


-def test_repr_in_anywidget_mode_should_not_be_deferred(


Why was this test removed?

You are right, it is an important testcase. I will add them back.

bigframes/display/html.py

tswast · 2025-12-22T21:44:36Z

bigframes/display/html.py

    return "\n".join(table_html)
+
+
+def create_text_representation(


Nit: the html module seems an inappropriate place for this. bigframes.display.plaintext would make more sense to me.

Also, how does this differ from DataFrame._create_text_representation? Seems this is pretty redundant.

Just as I commented on create_html_representation below, it would be more object oriented to avoid the isinstance checks and put _create_text_representation on Series.

Thanks for the feedback! I have refactored the display logic significantly in the latest revision to address this:

Moved to bigframes.display.plaintext: As suggested, I created bigframes.display.plaintext and moved the text formatting logic there.

Removed Redundancy: I removed _create_text_representation from both DataFrame and Series (and _create_html_representation from DataFrame). Both classes now delegate to the centralized functions in bigframes.display.plaintext and bigframes.display.html.

Design Choice: I opted to centralize the display logic within the bigframes.display package to separate formatting concerns from the core data structures. This necessitates the isinstance checks within the display modules, but it keeps the DataFrame and Series classes cleaner and avoids circular dependency issues with the display logic.

tswast · 2025-12-22T21:46:07Z

bigframes/dataframe.py

+        from bigframes.display import html

-        return {"text/html": html_string, "text/plain": text_representation}
+        return html.repr_mimebundle(self, include=include, exclude=exclude)


I don't see any checks for deferred mode in html.repr_mimebundle.

Done. repr_mimebundle now checks for the display mode and will delegate to a new repr_mimebundle_deferred function when appropriate.

tswast · 2025-12-22T21:47:38Z

bigframes/display/html.py

+    return widget_repr, widget_metadata
+
+
+def repr_mimebundle(


Let's create separate methods for head and deferred, like repr_mimebundle_head and repr_mimebundle_deferred.

Done. I've split the logic into repr_mimebundle_head for standard display and repr_mimebundle_deferred for deferred execution mode.

tswast · 2025-12-22T21:51:14Z

bigframes/display/html.py

+    blob_cols: list[str],
+) -> str:
+    """Create an HTML representation of the DataFrame or Series."""
+    if isinstance(obj, bigframes.series.Series):


If we had obj._create_html_representation on Series, we could avoid this isinstance check.

We could even add the same to Index at some point.

I decided to keep the logic centralized in bigframes.display.html rather than adding a new method to Series. This follows the direction of the other refactors in this branch, centralizing all formatting concerns within the bigframes.display package to keep the core data classes cleaner and simplify dependency management.

This reverts commit 593f9ae.

…and fix mypy errors

tswast · 2025-12-23T18:03:44Z

bigframes/display/html.py

+    else:
+        # It's a DataFrame
+        opts = options.display
+        with display_options.pandas_repr(opts):


I think we should move this out one level so that the pandas formatting options also affect the series repr.

Done. I refactored create_html_representation to wrap both the Series and DataFrame logic within the display_options.pandas_repr(opts) context manager.

tswast · 2025-12-23T18:04:24Z

bigframes/display/html.py

+        except AttributeError:
+            html_string = f"<pre>{pd_series.to_string()}</pre>"
+
+        html_string += f"[{total_rows} rows]"


Let's only do this if len(pd_series.index) < total_rows. We can use the same logic as in the plain text:

Suggested change

html_string += f"[{total_rows} rows]"

is_truncated = total_rows is not None and total_rows > len(pandas_df)

if is_truncated:

html_string += f"<p>[{total_rows} rows]</p>"

Done. I updated the logic to check is_truncated = total_rows is not None and total_rows > len(pandas_df) and only append the row count if that condition is met.

tswast · 2025-12-23T18:06:15Z

bigframes/display/html.py

+            if options.display.blob_display and blob_cols:
+
+                def obj_ref_rt_to_html(obj_ref_rt) -> str:
+                    obj_ref_rt_json = json.loads(obj_ref_rt)
+                    obj_ref_details = obj_ref_rt_json["objectref"]["details"]
+                    if "gcs_metadata" in obj_ref_details:
+                        gcs_metadata = obj_ref_details["gcs_metadata"]
+                        content_type = typing.cast(
+                            str, gcs_metadata.get("content_type", "")
+                        )
+                        if content_type.startswith("image"):
+                            size_str = ""
+                            if options.display.blob_display_width:
+                                size_str = (
+                                    f' width="{options.display.blob_display_width}"'
+                                )
+                            if options.display.blob_display_height:
+                                size_str = (
+                                    size_str
+                                    + f' height="{options.display.blob_display_height}"'
+                                )
+                            url = obj_ref_rt_json["access_urls"]["read_url"]
+                            return f'<img src="{url}"{size_str}>'
+
+                    return f'uri: {obj_ref_rt_json["objectref"]["uri"]}, authorizer: {obj_ref_rt_json["objectref"]["authorizer"]}'


It seems to me that we'd want rich display for blob Series too. If possible refactor this out so that it can be used by both series and dataframe. If not, add a todo and internal bug for rich output for blob series.

I extracted the blob formatting logic into a helper function _obj_ref_rt_to_html for future reusability. I also added a TODO(b/464053870) to implement rich display for Blob Series in a follow-up, linking it to the bug for implementing a proper repr module for non-pandas types

shuoweil added 4 commits December 19, 2025 02:21

feat: Enhance Series and DataFrame display with anywidget

218b7c2

test: add more npm tests

9e3163f

test: add this file for faster and reliable npm tests

3227b23

docs: notebook update

c1a8f83

shuoweil self-assigned this Dec 19, 2025

shuoweil requested review from a team as code owners December 19, 2025 02:33

shuoweil requested a review from TrevorBergeron December 19, 2025 02:33

shuoweil marked this pull request as draft December 19, 2025 02:33

product-auto-label bot added size: l Pull request size is large. api: bigquery Issues related to the googleapis/python-bigquery-dataframes API. labels Dec 19, 2025

shuoweil removed the request for review from TrevorBergeron December 19, 2025 02:33

shuoweil and others added 6 commits December 19, 2025 02:45

test: update old testcase due to new feature implementation

c39293a

Revert "test: update old testcase due to new feature implementation"

9dff0f4

This reverts commit c39293a.

feat: only display row count when series is large than the number can…

f67e30f

… be displayed in one page

Merge branch 'main' into shuowei-anywidget-series-display

057f54d

Merge branch 'main' into shuowei-anywidget-series-display

f70d5c1

shuoweil requested review from TrevorBergeron and tswast December 19, 2025 20:34

shuoweil marked this pull request as ready for review December 19, 2025 20:35

tswast requested changes Dec 19, 2025

View reviewed changes

shuoweil added 3 commits December 19, 2025 22:21

Merge branch 'main' into shuowei-anywidget-series-display

58e357a

refactor: code refactor

fd04e6a

fix: fix mypy

4825aeb

shuoweil requested a review from tswast December 19, 2025 22:55

shuoweil marked this pull request as draft December 19, 2025 23:25

shuoweil marked this pull request as ready for review December 19, 2025 23:25

tswast reviewed Dec 22, 2025

View reviewed changes

shuoweil added 3 commits December 22, 2025 22:15

Merge branch 'main' into shuowei-anywidget-series-display

8845464

refactor: move code to plaintext file and add checks

d36fc0f

refactor: move code to plaintext file and add checks

593f9ae

shuoweil requested a review from tswast December 22, 2025 22:36

shuoweil added 4 commits December 22, 2025 22:37

Revert "refactor: move code to plaintext file and add checks"

400ea07

This reverts commit 593f9ae.

Merge branch 'main' into shuowei-anywidget-series-display

945616c

refactor: move create_text_representation to plaintext.py

a474606

refactor: move display logic to display/plaintext.py and display/html.py

bd56992

product-auto-label bot added size: xl Pull request size is extra large. and removed size: l Pull request size is large. labels Dec 23, 2025

shuoweil force-pushed the shuowei-anywidget-series-display branch from cfbab13 to bd56992 Compare December 23, 2025 02:44

shuoweil added 10 commits December 23, 2025 02:48

refactor: restore original order of max_results in __repr__

971ee33

docs: add todo back

1a73628

refactor: split repr_mimebundle logic, handle deferred mode in html, …

1b7952b

…and fix mypy errors

refactor: rename repr_mimebundle helpers and improve fallback comments

15b2ac6

style: fix repr_mimebundle docstring formatting

f8914c8

docs: update anywidget demo notebook with series display showcase

9fea10e

docs: update notebook

a20a5ee

Merge branch 'main' into shuowei-anywidget-series-display

9e92c2a

refactor: decouple plaintext representation from core objects

c0f4b4e

refactor: consolidate object metadata extraction for display

38899b7

tswast reviewed Dec 23, 2025

View reviewed changes

fix: refactor html display to address review comments

64230d1

shuoweil requested a review from tswast December 23, 2025 20:37

tswast approved these changes Dec 23, 2025

View reviewed changes

shuoweil merged commit 7395d41 into main Dec 23, 2025
24 of 25 checks passed

shuoweil deleted the shuowei-anywidget-series-display branch December 23, 2025 22:25

	# At this point, we have already executed the query as part of the
	# widget construction. Let's use the information available to render
	# the HTML and plain text versions.
	widget_repr["text/html"] = self._create_html_representation(
	widget._cached_data,
	widget.row_count,
	len(self.columns),
	blob_cols,
	)

	widget_repr["text/plain"] = self._create_text_representation(
	widget._cached_data, widget.row_count
	)

		assert "text/plain" in data


		def test_repr_in_anywidget_mode_should_not_be_deferred(

-        html_string += f"[{total_rows} rows]"
+        is_truncated = total_rows is not None and total_rows > len(pandas_df)
+        if is_truncated:
+            html_string += f"<p>[{total_rows} rows]</p>"

feat: display series in anywidget mode #2346

feat: display series in anywidget mode #2346

Uh oh!

Conversation

shuoweil commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

review-notebook-app bot commented Dec 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shuoweil Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shuoweil Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shuoweil commented Dec 19, 2025 •

edited

Loading

shuoweil Dec 22, 2025 •

edited

Loading

shuoweil Dec 22, 2025 •

edited

Loading