Add doc string to GroupBy methods

Author: topper-123

pandas/core/groupby/generic.py

@@ -79,28 +79,6 @@
 if TYPE_CHECKING:
     from pandas.core.internals import Block
 
-_agg_template = """
-Compute {fname} of group values.
-
-Parameters
-----------
-numeric_only : bool, default {no}
-    Include only float, int, boolean columns. If None, will attempt to use
-    everything, then use only numeric data.
-min_count : int, default {mc}
-    The required number of valid values to perform the operation. If fewer
-    than ``min_count`` non-NA values are present the result will be NA.
-
-Returns
--------
-{return_type}
-    Computed {fname} of values within each group.
-
-See Also
---------
-{return_type}.groupby
-"""
-
 
 NamedAgg = namedtuple("NamedAgg", ["column", "aggfunc"])
 # TODO(typing) the return value on this callable should be any *scalar*.
@@ -811,27 +789,27 @@ def count(self) -> Series:
         )
         return self._reindex_output(result, fill_value=0)
 
-    @doc(_agg_template, fname="sum", no=True, mc=0, return_type="Series")
+    @doc(GroupBy.sum.__doc__)
     def sum(self, numeric_only: bool = True, min_count: int = 0) -> Series:
         return super().sum(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="prod", no=True, mc=0, return_type="Series")
+    @doc(GroupBy.prod.__doc__)
     def prod(self, numeric_only: bool = True, min_count: int = 0) -> Series:
         return super().prod(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="min", no=False, mc=-1, return_type="Series")
+    @doc(GroupBy.min.__doc__)
     def min(self, numeric_only: bool = False, min_count: int = -1) -> Series:
         return super().min(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="max", no=False, mc=-1, return_type="Series")
+    @doc(GroupBy.max.__doc__)
     def max(self, numeric_only: bool = False, min_count: int = -1) -> Series:
         return super().max(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="first", no=False, mc=-1, return_type="Series")
+    @doc(GroupBy.first.__doc__)
     def first(self, numeric_only: bool = False, min_count: int = -1) -> Series:
         return super().first(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="last", no=False, mc=-1, return_type="Series")
+    @doc(GroupBy.last.__doc__)
     def last(self, numeric_only: bool = False, min_count: int = -1) -> Series:
         return super().last(numeric_only=numeric_only, min_count=min_count)
 
@@ -1909,27 +1887,27 @@ def groupby_series(obj, col=None):
             results.index = ibase.default_index(len(results))
         return results
 
-    @doc(_agg_template, fname="sum", no=True, mc=0, return_type="DataFrame")
+    @doc(GroupBy.sum.__doc__)
     def sum(self, numeric_only: bool = True, min_count: int = 0) -> DataFrame:
         return super().sum(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="prod", no=True, mc=0, return_type="DataFrame")
+    @doc(GroupBy.prod.__doc__)
     def prod(self, numeric_only: bool = True, min_count: int = 0) -> DataFrame:
         return super().prod(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="min", no=False, mc=-1, return_type="DataFrame")
+    @doc(GroupBy.min.__doc__)
     def min(self, numeric_only: bool = False, min_count: int = -1) -> DataFrame:
         return super().min(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="max", no=False, mc=-1, return_type="DataFrame")
+    @doc(GroupBy.max.__doc__)
     def max(self, numeric_only: bool = False, min_count: int = -1) -> DataFrame:
         return super().max(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="first", no=False, mc=-1, return_type="DataFrame")
+    @doc(GroupBy.first.__doc__)
     def first(self, numeric_only: bool = False, min_count: int = -1) -> DataFrame:
         return super().first(numeric_only=numeric_only, min_count=min_count)
 
-    @doc(_agg_template, fname="last", no=False, mc=-1, return_type="DataFrame")
+    @doc(GroupBy.last.__doc__)
     def last(self, numeric_only: bool = False, min_count: int = -1) -> DataFrame:
         return super().last(numeric_only=numeric_only, min_count=min_count)
 

pandas/core/groupby/groupby.py

@@ -33,10 +33,10 @@ class providing the base-class of operations.
 
 from pandas._libs import Timestamp
 import pandas._libs.groupby as libgroupby
-from pandas._typing import FrameOrSeries, Scalar
+from pandas._typing import FrameOrSeries, FrameOrSeriesUnion, Scalar
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
-from pandas.util._decorators import Appender, Substitution, cache_readonly
+from pandas.util._decorators import Appender, Substitution, cache_readonly, doc
 
 from pandas.core.dtypes.cast import maybe_downcast_to_dtype
 from pandas.core.dtypes.common import (
@@ -188,6 +188,29 @@ class providing the base-class of operations.
     """,
 )
 
+_agg_template = """
+Compute {fname} of group values.
+
+Parameters
+----------
+numeric_only : bool, default {no}
+    Include only float, int, boolean columns. If None, will attempt to use
+    everything, then use only numeric data.
+min_count : int, default {mc}
+    The required number of valid values to perform the operation. If fewer
+    than ``min_count`` non-NA values are present the result will be NA.
+
+Returns
+-------
+Series or DataFrame
+    Computed {fname} of values within each group.
+
+See Also
+--------
+DataFrame.groupby
+Series.groupby
+"""
+
 _pipe_template = """
 Apply a function `func` with arguments to this %(klass)s object and return
 the function's result.
@@ -1366,21 +1389,25 @@ def size(self):
             result.name = self.obj.name
         return self._reindex_output(result, fill_value=0)
 
+    @doc(_agg_template, fname="sum", no=True, mc=0)
     def sum(self, numeric_only: bool = True, min_count: int = 0):
         return self._agg_general(
             numeric_only=numeric_only, min_count=min_count, alias="add", npfunc=np.sum
         )
 
+    @doc(_agg_template, fname="prod", no=True, mc=0)
     def prod(self, numeric_only: bool = True, min_count: int = 0):
         return self._agg_general(
             numeric_only=numeric_only, min_count=min_count, alias="prod", npfunc=np.prod
         )
 
+    @doc(_agg_template, fname="min", no=False, mc=-1)
     def min(self, numeric_only: bool = False, min_count: int = -1):
         return self._agg_general(
             numeric_only=numeric_only, min_count=min_count, alias="min", npfunc=np.min
         )
 
+    @doc(_agg_template, fname="max", no=False, mc=-1)
     def max(self, numeric_only: bool = False, min_count: int = -1):
         return self._agg_general(
             numeric_only=numeric_only, min_count=min_count, alias="max", npfunc=np.max
@@ -1403,6 +1430,7 @@ def get_loc_notna(x, loc: int):
         else:
             return get_loc_notna(x, loc=loc)
 
+    @doc(_agg_template, fname="first", no=False, mc=-1)
     def first(self, numeric_only: bool = False, min_count: int = -1):
         first_compat = partial(self._get_loc, loc=0)
 
@@ -1413,6 +1441,7 @@ def first(self, numeric_only: bool = False, min_count: int = -1):
             npfunc=first_compat,
         )
 
+    @doc(_agg_template, fname="last", no=False, mc=-1)
     def last(self, numeric_only: bool = False, min_count: int = -1):
         last_compat = partial(self._get_loc, loc=-1)
 

pandas/util/_decorators.py

@@ -245,7 +245,7 @@ def wrapper(*args, **kwargs) -> Callable[..., Any]:
     return decorate
 
 
-def doc(*args: Union[str, Callable], **kwargs: Any) -> Callable[[F], F]:
+def doc(*args: Union[str, Callable, None], **kwargs: Any) -> Callable[[F], F]:
     """
     A decorator take docstring templates, concatenate them and perform string
     substitution on it.
@@ -270,6 +270,8 @@ def wrapper(*args, **kwargs) -> Callable:
 
         templates = [func.__doc__ if func.__doc__ else ""]
         for arg in args:
+            if arg is None:
+                continue
             if isinstance(arg, str):
                 templates.append(arg)
             elif hasattr(arg, "_docstr_template"):