docs: add docs for DataFrame and Series dunder methods (#562)

* docs: add docs for `DataFrame.{radd,__add__,__radd__}`

* fix rendering, revert ineffective changes, add __eq__

* newline

* docs for more df dunders

* fix mypy errors and couple of wordings

* fix sub and rmod, add docs for __bool__, __nonzero__, __getattr__

* add documentation for Series dunders

* fix doctest failure with python 3.12

* move docstrings to third_party for compliance safety

* add DataFrame.__getitem__ docstring and code samples

* add dunder doc overrides from third_party

Author: shobsi

bigframes/dataframe.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 import datetime
+import inspect
 import re
 import sys
 import textwrap
@@ -314,6 +315,8 @@ def __len__(self):
         rows, _ = self.shape
         return rows
 
+    __len__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__len__)
+
     def __iter__(self):
         return iter(self.columns)
 
@@ -466,7 +469,6 @@ def __getitem__(
             bigframes.series.Series,
         ],
     ):  # No return type annotations (like pandas) as type cannot always be determined statically
-        """Gets the specified column(s) from the DataFrame."""
         # NOTE: This implements the operations described in
         # https://pandas.pydata.org/docs/getting_started/intro_tutorials/03_subset_data.html
 
@@ -498,6 +500,8 @@ def __getitem__(
 
         return DataFrame(self._block.select_columns(selected_ids))
 
+    __getitem__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__getitem__)
+
     def _getitem_label(self, key: blocks.Label):
         col_ids = self._block.cols_matching_label(key)
         if len(col_ids) == 0:
@@ -642,14 +646,11 @@ def _repr_html_(self) -> str:
         return html_string
 
     def __setitem__(self, key: str, value: SingleItemValue):
-        """Modify or insert a column into the DataFrame.
-
-        Note: This does **not** modify the original table the DataFrame was
-        derived from.
-        """
         df = self._assign_single_item(key, value)
         self._set_block(df._get_block())
 
+    __setitem__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__setitem__)
+
     def _apply_binop(
         self,
         other: float | int | bigframes.series.Series | DataFrame,
@@ -838,32 +839,50 @@ def _apply_dataframe_binop(
     def eq(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
         return self._apply_binop(other, ops.eq_op, axis=axis)
 
+    def __eq__(self, other) -> DataFrame:  # type: ignore
+        return self.eq(other)
+
+    __eq__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__eq__)
+
     def ne(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
         return self._apply_binop(other, ops.ne_op, axis=axis)
 
-    __eq__ = eq  # type: ignore
+    def __ne__(self, other) -> DataFrame:  # type: ignore
+        return self.ne(other)
 
-    __ne__ = ne  # type: ignore
+    __ne__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__ne__)
 
     def le(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
         return self._apply_binop(other, ops.le_op, axis=axis)
 
+    def __le__(self, other) -> DataFrame:
+        return self.le(other)
+
+    __le__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__le__)
+
     def lt(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
         return self._apply_binop(other, ops.lt_op, axis=axis)
 
+    def __lt__(self, other) -> DataFrame:
+        return self.lt(other)
+
+    __lt__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__lt__)
+
     def ge(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
         return self._apply_binop(other, ops.ge_op, axis=axis)
 
-    def gt(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
-        return self._apply_binop(other, ops.gt_op, axis=axis)
+    def __ge__(self, other) -> DataFrame:
+        return self.ge(other)
 
-    __lt__ = lt
+    __ge__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__ge__)
 
-    __le__ = le
+    def gt(self, other: typing.Any, axis: str | int = "columns") -> DataFrame:
+        return self._apply_binop(other, ops.gt_op, axis=axis)
 
-    __gt__ = gt
+    def __gt__(self, other) -> DataFrame:
+        return self.gt(other)
 
-    __ge__ = ge
+    __gt__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__gt__)
 
     def add(
         self,
@@ -874,7 +893,21 @@ def add(
         # TODO(swast): Support level parameter with MultiIndex.
         return self._apply_binop(other, ops.add_op, axis=axis)
 
-    __radd__ = __add__ = radd = add
+    def radd(
+        self,
+        other: float | int | bigframes.series.Series | DataFrame,
+        axis: str | int = "columns",
+    ) -> DataFrame:
+        # TODO(swast): Support fill_value parameter.
+        # TODO(swast): Support level parameter with MultiIndex.
+        return self.add(other, axis=axis)
+
+    def __add__(self, other) -> DataFrame:
+        return self.add(other)
+
+    __add__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__add__)
+
+    __radd__ = __add__
 
     def sub(
         self,
@@ -883,7 +916,13 @@ def sub(
     ) -> DataFrame:
         return self._apply_binop(other, ops.sub_op, axis=axis)
 
-    __sub__ = subtract = sub
+    subtract = sub
+    subtract.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.sub)
+
+    def __sub__(self, other):
+        return self.sub(other)
+
+    __sub__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__sub__)
 
     def rsub(
         self,
@@ -892,7 +931,10 @@ def rsub(
     ) -> DataFrame:
         return self._apply_binop(other, ops.sub_op, axis=axis, reverse=True)
 
-    __rsub__ = rsub
+    def __rsub__(self, other):
+        return self.rsub(other)
+
+    __rsub__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__rsub__)
 
     def mul(
         self,
@@ -901,7 +943,25 @@ def mul(
     ) -> DataFrame:
         return self._apply_binop(other, ops.mul_op, axis=axis)
 
-    __rmul__ = __mul__ = rmul = multiply = mul
+    multiply = mul
+    multiply.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.mul)
+
+    def __mul__(self, other):
+        return self.mul(other)
+
+    __mul__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__mul__)
+
+    def rmul(
+        self,
+        other: float | int | bigframes.series.Series | DataFrame,
+        axis: str | int = "columns",
+    ) -> DataFrame:
+        return self.mul(other, axis=axis)
+
+    def __rmul__(self, other):
+        return self.rmul(other)
+
+    __rmul__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__rmul__)
 
     def truediv(
         self,
@@ -910,7 +970,13 @@ def truediv(
     ) -> DataFrame:
         return self._apply_binop(other, ops.div_op, axis=axis)
 
-    div = divide = __truediv__ = truediv
+    truediv.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.truediv)
+    div = divide = truediv
+
+    def __truediv__(self, other):
+        return self.truediv(other)
+
+    __truediv__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__truediv__)
 
     def rtruediv(
         self,
@@ -919,7 +985,13 @@ def rtruediv(
     ) -> DataFrame:
         return self._apply_binop(other, ops.div_op, axis=axis, reverse=True)
 
-    __rtruediv__ = rdiv = rtruediv
+    rdiv = rtruediv
+    rdiv.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.rtruediv)
+
+    def __rtruediv__(self, other):
+        return self.rtruediv(other)
+
+    __rtruediv__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__rtruediv__)
 
     def floordiv(
         self,
@@ -928,7 +1000,10 @@ def floordiv(
     ) -> DataFrame:
         return self._apply_binop(other, ops.floordiv_op, axis=axis)
 
-    __floordiv__ = floordiv
+    def __floordiv__(self, other):
+        return self.floordiv(other)
+
+    __floordiv__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__floordiv__)
 
     def rfloordiv(
         self,
@@ -937,31 +1012,48 @@ def rfloordiv(
     ) -> DataFrame:
         return self._apply_binop(other, ops.floordiv_op, axis=axis, reverse=True)
 
-    __rfloordiv__ = rfloordiv
+    def __rfloordiv__(self, other):
+        return self.rfloordiv(other)
+
+    __rfloordiv__.__doc__ = inspect.getdoc(
+        vendored_pandas_frame.DataFrame.__rfloordiv__
+    )
 
     def mod(self, other: int | bigframes.series.Series | DataFrame, axis: str | int = "columns") -> DataFrame:  # type: ignore
         return self._apply_binop(other, ops.mod_op, axis=axis)
 
+    def __mod__(self, other):
+        return self.mod(other)
+
+    __mod__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__mod__)
+
     def rmod(self, other: int | bigframes.series.Series | DataFrame, axis: str | int = "columns") -> DataFrame:  # type: ignore
         return self._apply_binop(other, ops.mod_op, axis=axis, reverse=True)
 
-    __mod__ = mod
+    def __rmod__(self, other):
+        return self.rmod(other)
 
-    __rmod__ = rmod
+    __rmod__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__rmod__)
 
     def pow(
         self, other: int | bigframes.series.Series, axis: str | int = "columns"
     ) -> DataFrame:
         return self._apply_binop(other, ops.pow_op, axis=axis)
 
+    def __pow__(self, other):
+        return self.pow(other)
+
+    __pow__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__pow__)
+
     def rpow(
         self, other: int | bigframes.series.Series, axis: str | int = "columns"
     ) -> DataFrame:
         return self._apply_binop(other, ops.pow_op, axis=axis, reverse=True)
 
-    __pow__ = pow
+    def __rpow__(self, other):
+        return self.rpow(other)
 
-    __rpow__ = rpow
+    __rpow__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__rpow__)
 
     def align(
         self,
@@ -1971,6 +2063,7 @@ def prod(
         return bigframes.series.Series(block.select_column("values"))
 
     product = prod
+    product.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.prod)
 
     def count(self, *, numeric_only: bool = False) -> bigframes.series.Series:
         if not numeric_only:
@@ -2010,6 +2103,7 @@ def agg(
             )
 
     aggregate = agg
+    aggregate.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.agg)
 
     def idxmin(self) -> bigframes.series.Series:
         return bigframes.series.Series(block_ops.idxmin(self._block))
@@ -2083,6 +2177,7 @@ def kurt(self, *, numeric_only: bool = False):
         return bigframes.series.Series(result_block)
 
     kurtosis = kurt
+    kurtosis.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.kurt)
 
     def _pivot(
         self,
@@ -2542,11 +2637,13 @@ def isna(self) -> DataFrame:
         return self._apply_unary_op(ops.isnull_op)
 
     isnull = isna
+    isnull.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.isna)
 
     def notna(self) -> DataFrame:
         return self._apply_unary_op(ops.notnull_op)
 
     notnull = notna
+    notnull.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.notna)
 
     def cumsum(self):
         is_numeric_types = [
@@ -2860,7 +2957,10 @@ def to_numpy(
     ) -> numpy.ndarray:
         return self.to_pandas().to_numpy(dtype, copy, na_value, **kwargs)
 
-    __array__ = to_numpy
+    def __array__(self, dtype=None) -> numpy.ndarray:
+        return self.to_numpy(dtype=dtype)
+
+    __array__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__array__)
 
     def to_parquet(
         self,
@@ -3227,6 +3327,7 @@ def first_valid_index(self):
         return
 
     applymap = map
+    applymap.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.map)
 
     def _slice(
         self,
@@ -3367,4 +3468,7 @@ def get_right_id(id):
     def plot(self):
         return plotting.PlotAccessor(self)
 
-    __matmul__ = dot
+    def __matmul__(self, other) -> DataFrame:
+        return self.dot(other)
+
+    __matmul__.__doc__ = inspect.getdoc(vendored_pandas_frame.DataFrame.__matmul__)