feat: define list accessor for bigframes Series (#946)

* feat: define list accessor for bigframes Series

* Add doc for list accessor

* Fix bug in docstring and inheritance

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* Skip test if Pandas version is too old

* Fix docstring format, and provide notebook examples.

* Use func link under see also

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: sycai

bigframes/operations/_op_converters.py

@@ -0,0 +1,37 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import bigframes.operations as ops
+
+
+def convert_index(key: int) -> ops.ArrayIndexOp:
+    if key < 0:
+        raise NotImplementedError("Negative indexing is not supported.")
+    return ops.ArrayIndexOp(index=key)
+
+
+def convert_slice(key: slice) -> ops.ArraySliceOp:
+    if key.step is not None and key.step != 1:
+        raise NotImplementedError(f"Only a step of 1 is allowed, got {key.step}")
+
+    if (key.start is not None and key.start < 0) or (
+        key.stop is not None and key.stop < 0
+    ):
+        raise NotImplementedError("Slicing with negative numbers is not allowed.")
+
+    return ops.ArraySliceOp(
+        start=key.start if key.start is not None else 0,
+        stop=key.stop,
+        step=key.step,
+    )

bigframes/operations/lists.py

@@ -0,0 +1,46 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import inspect
+from typing import Union
+
+import bigframes_vendored.pandas.core.arrays.arrow.accessors as vendoracessors
+
+from bigframes.core import log_adapter
+import bigframes.operations as ops
+from bigframes.operations._op_converters import convert_index, convert_slice
+import bigframes.operations.base
+import bigframes.series as series
+
+
+@log_adapter.class_logger
+class ListAccessor(
+    bigframes.operations.base.SeriesMethods, vendoracessors.ListAccessor
+):
+    __doc__ = vendoracessors.ListAccessor.__doc__
+
+    def len(self):
+        return self._apply_unary_op(ops.len_op)
+
+    def __getitem__(self, key: Union[int, slice]) -> series.Series:
+        if isinstance(key, int):
+            return self._apply_unary_op(convert_index(key))
+        elif isinstance(key, slice):
+            return self._apply_unary_op(convert_slice(key))
+        else:
+            raise ValueError(f"key must be an int or slice, got {type(key).__name__}")
+
+    __getitem__.__doc__ = inspect.getdoc(vendoracessors.ListAccessor.__getitem__)

bigframes/operations/strings.py

@@ -23,6 +23,7 @@
 from bigframes.core import log_adapter
 import bigframes.dataframe as df
 import bigframes.operations as ops
+from bigframes.operations._op_converters import convert_index, convert_slice
 import bigframes.operations.base
 import bigframes.series as series
 
@@ -40,28 +41,9 @@ class StringMethods(bigframes.operations.base.SeriesMethods, vendorstr.StringMet
 
     def __getitem__(self, key: Union[int, slice]) -> series.Series:
         if isinstance(key, int):
-            if key < 0:
-                raise NotImplementedError("Negative indexing is not supported.")
-            return self._apply_unary_op(ops.ArrayIndexOp(index=key))
+            return self._apply_unary_op(convert_index(key))
         elif isinstance(key, slice):
-            if key.step is not None and key.step != 1:
-                raise NotImplementedError(
-                    f"Only a step of 1 is allowed, got {key.step}"
-                )
-            if (key.start is not None and key.start < 0) or (
-                key.stop is not None and key.stop < 0
-            ):
-                raise NotImplementedError(
-                    "Slicing with negative numbers is not allowed."
-                )
-
-            return self._apply_unary_op(
-                ops.ArraySliceOp(
-                    start=key.start if key.start is not None else 0,
-                    stop=key.stop,
-                    step=key.step,
-                )
-            )
+            return self._apply_unary_op(convert_slice(key))
         else:
             raise ValueError(f"key must be an int or slice, got {type(key).__name__}")
 

bigframes/series.py

@@ -53,6 +53,7 @@
 import bigframes.operations.aggregations as agg_ops
 import bigframes.operations.base
 import bigframes.operations.datetimes as dt
+import bigframes.operations.lists as lists
 import bigframes.operations.plotting as plotting
 import bigframes.operations.strings as strings
 import bigframes.operations.structs as structs
@@ -66,6 +67,8 @@
     " Try converting it to a remote function."
 )
 
+_list = list  # Type alias to escape Series.list property
+
 
 @log_adapter.class_logger
 class Series(bigframes.operations.base.SeriesMethods, vendored_pandas_series.Series):
@@ -161,6 +164,10 @@ def query_job(self) -> Optional[bigquery.QueryJob]:
     def struct(self) -> structs.StructAccessor:
         return structs.StructAccessor(self._block)
 
+    @property
+    def list(self) -> lists.ListAccessor:
+        return lists.ListAccessor(self._block)
+
     @property
     @validations.requires_ordering()
     def T(self) -> Series:
@@ -1708,7 +1715,7 @@ def to_latex(
             buf, columns=columns, header=header, index=index, **kwargs
         )
 
-    def tolist(self) -> list:
+    def tolist(self) -> _list:
         return self.to_pandas().to_list()
 
     to_list = tolist

docs/reference/bigframes.pandas/series.rst

@@ -35,6 +35,14 @@ String handling
     :inherited-members:
     :undoc-members:
 
+List handling
+^^^^^^^^^^^^^
+
+.. automodule:: bigframes.operations.lists
+    :members:
+    :inherited-members:
+    :undoc-members:
+
 Struct handling
 ^^^^^^^^^^^^^^^