add docstrings

Author: TrevorBergeron

bigframes/core/col.py

@@ -16,6 +16,8 @@
 import dataclasses
 from typing import Any, Hashable
 
+import bigframes_vendored.pandas.core.col as pd_col
+
 import bigframes.core.expression as bf_expression
 import bigframes.operations as bf_ops
 
@@ -24,6 +26,8 @@
 # Name collision unintended
 @dataclasses.dataclass(frozen=True)
 class Expression:
+    __doc__ = pd_col.Expression.__doc__
+
     _value: bf_expression.Expression
 
     def _apply_unary(self, op: bf_ops.UnaryOp) -> Expression:
@@ -117,3 +121,6 @@ def __invert__(self) -> Expression:
 
 def col(col_name: Hashable) -> Expression:
     return Expression(bf_expression.free_var(col_name))
+
+
+col.__doc__ = pd_col.col.__doc__

third_party/bigframes_vendored/pandas/core/col.py

@@ -0,0 +1,36 @@
+# Contains code from https://github.com/pandas-dev/pandas/blob/main/pandas/core/col.py
+from __future__ import annotations
+
+from collections.abc import Hashable
+
+from bigframes import constants
+
+
+class Expression:
+    """
+    Class representing a deferred column.
+
+    This is not meant to be instantiated directly. Instead, use :meth:`pandas.col`.
+    """
+
+
+def col(col_name: Hashable) -> Expression:
+    """
+    Generate deferred object representing a column of a DataFrame.
+
+    Any place which accepts ``lambda df: df[col_name]``, such as
+    :meth:`DataFrame.assign` or :meth:`DataFrame.loc`, can also accept
+    ``pd.col(col_name)``.
+
+    Args:
+        col_name (Hashable):
+            Column name.
+
+    Returns:
+        Expression:
+            A deferred object representing a column of a DataFrame.
+    """
+    raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
+
+
+__all__ = ["Expression", "col"]

third_party/bigframes_vendored/pandas/core/common.py

@@ -1,68 +1,53 @@
 # Contains code from https://github.com/pandas-dev/pandas/blob/main/pandas/core/common.py
 from __future__ import annotations
 
-from typing import Callable, TYPE_CHECKING
+from collections.abc import Hashable
 
-from bigframes_vendored.pandas.core.dtypes.inference import iterable_not_string
+from bigframes import constants
 
-if TYPE_CHECKING:
-    from bigframes_vendored.pandas.pandas._typing import T
 
+class Expression:
+    """
+    Class representing a deferred column.
 
-def pipe(
-    obj, func: Callable[..., T] | tuple[Callable[..., T], str], *args, **kwargs
-) -> T:
+    This is not meant to be instantiated directly. Instead, use :meth:`pandas.col`.
     """
-    Apply a function ``func`` to object ``obj`` either by passing obj as the
-    first argument to the function or, in the case that the func is a tuple,
-    interpret the first element of the tuple as a function and pass the obj to
-    that function as a keyword argument whose key is the value of the second
-    element of the tuple.
 
-    Args:
-        func (callable or tuple of (callable, str)):
-            Function to apply to this object or, alternatively, a
-            ``(callable, data_keyword)`` tuple where ``data_keyword`` is a
-            string indicating the keyword of ``callable`` that expects the
-            object.
-        args (iterable, optional):
-            Positional arguments passed into ``func``.
-        kwargs (dict, optional):
-            A dictionary of keyword arguments passed into ``func``.
 
-    Returns:
-        object: the return type of ``func``.
-    """
-    if isinstance(func, tuple):
-        func, target = func
-        if target in kwargs:
-            msg = f"{target} is both the pipe target and a keyword argument"
-            raise ValueError(msg)
-        kwargs[target] = obj
-        return func(*args, **kwargs)
-    else:
-        return func(obj, *args, **kwargs)
-
-
-def flatten(line):
+def col(col_name: Hashable) -> Expression:
     """
-    Flatten an arbitrarily nested sequence.
+    Generate deferred object representing a column of a DataFrame.
+
+    Any place which accepts ``lambda df: df[col_name]``, such as
+    :meth:`DataFrame.assign` or :meth:`DataFrame.loc`, can also accept
+    ``pd.col(col_name)``.
+
+    **Examples:**
+
+        You can use `col` in `assign`.
 
-    Parameters
-    ----------
-    line : sequence
-        The non string sequence to flatten
+        >>> df = bpd.DataFrame({"name": ["beluga", "narwhal"], "speed": [100, 110]})
+        >>> df.assign(name_titlecase=bpd.col("name").str.title())
+            name  speed name_titlecase
+        0   beluga    100         Beluga
+        1  narwhal    110        Narwhal
 
-    Notes
-    -----
-    This doesn't consider strings sequences.
+        You can also use it for filtering.
 
-    Returns
-    -------
-    flattened : generator
+        >>> df.loc[bpd.col("speed") > 105]
+            name  speed
+        1  narwhal    110
+
+
+    Args:
+        col_name (Hashable):
+            Column name.
+
+    Returns:
+        Expression:
+            A deferred object representing a column of a DataFrame.
     """
-    for element in line:
-        if iterable_not_string(element):
-            yield from flatten(element)
-        else:
-            yield element
+    raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
+
+
+__all__ = ["Expression", "col"]