feat: Implement item() for Series and Index

bigframes/core/indexes/base.py

@@ -618,6 +618,22 @@ def to_numpy(self, dtype=None, *, allow_large_results=None, **kwargs) -> np.ndar
     def __len__(self):
         return self.shape[0]
 
+    def item(self):
+        """
+        Return the first element of the underlying data as a Python scalar.
+
+        Returns:
+            scalar: The first element of the Index.
+
+        Raises:
+            ValueError: If the Index does not contain exactly one element.
+        """
+        peeked = self.to_series().peek(2)
+        if len(peeked) == 1:
+            return peeked.iloc[0]
+        else:
+            raise ValueError("can only convert an array of size 1 to a Python scalar")
+
 
 def _should_create_datetime_index(block: blocks.Block) -> bool:
     if len(block.index.dtypes) != 1:

bigframes/series.py

@@ -960,6 +960,22 @@ def peek(
         as_series.name = self.name
         return as_series
 
+    def item(self):
+        """
+        Return the first element of the underlying data as a Python scalar.
+
+        Returns:
+            scalar: The first element of the Series.
+
+        Raises:
+            ValueError: If the Series does not contain exactly one element.
+        """
+        peeked = self.peek(2)
+        if len(peeked) == 1:
+            return peeked.iloc[0]
+        else:
+            raise ValueError("can only convert an array of size 1 to a Python scalar")
+
     def nlargest(self, n: int = 5, keep: str = "first") -> Series:
         if keep not in ("first", "last", "all"):
             raise ValueError("'keep must be one of 'first', 'last', or 'all'")

tests/system/small/test_index.py

@@ -458,3 +458,23 @@ def test_multiindex_repr_includes_all_names(session):
     )
     index = session.read_pandas(df).set_index(["A", "B"]).index
     assert "names=['A', 'B']" in repr(index)
+
+
+def test_index_item(session):
+    # Test with a single item
+    idx_single = bpd.Index([42], session=session)
+    assert idx_single.item() == 42
+
+    # Test with multiple items
+    idx_multiple = bpd.Index([1, 2, 3], session=session)
+    with pytest.raises(
+        ValueError, match="can only convert an array of size 1 to a Python scalar"
+    ):
+        idx_multiple.item()
+
+    # Test with an empty Index
+    idx_empty = bpd.Index([], dtype="Int64", session=session)
+    with pytest.raises(
+        ValueError, match="can only convert an array of size 1 to a Python scalar"
+    ):
+        idx_empty.item()

tests/system/small/test_series.py

@@ -4636,3 +4636,23 @@ def test_series_to_pandas_dry_run(scalars_df_index):
 
     assert isinstance(result, pd.Series)
     assert len(result) > 0
+
+
+def test_series_item(session):
+    # Test with a single item
+    s_single = bigframes.pandas.Series([42], session=session)
+    assert s_single.item() == 42
+
+    # Test with multiple items
+    s_multiple = bigframes.pandas.Series([1, 2, 3], session=session)
+    with pytest.raises(
+        ValueError, match="can only convert an array of size 1 to a Python scalar"
+    ):
+        s_multiple.item()
+
+    # Test with an empty Series
+    s_empty = bigframes.pandas.Series([], dtype="Int64", session=session)
+    with pytest.raises(
+        ValueError, match="can only convert an array of size 1 to a Python scalar"
+    ):
+        s_empty.item()