Deprecate mutated

Author: topper-123

doc/source/whatsnew/v1.0.0.rst

@@ -215,7 +215,8 @@ Deprecations
   value in ``idx`` of ``idx_val`` and a new value of ``val``, ``idx.set_value(arr, idx_val, val)``
   is equivalent to ``arr[idx.get_loc(idx_val)] = val``, which should be used instead (:issue:`28621`).
 - :func:`is_extension_type` is deprecated, :func:`is_extension_array_dtype` should be used instead (:issue:`29457`)
-
+- :meth:`DataFrame.groupby` and :meth:`Series.groupby` accepted a ``mutated`` parameter, which is actually
+  an implementation detail. It has been deprecated in the public interface (:issue:`29511`).
 
 .. _whatsnew_1000.prior_deprecations:
 

pandas/core/generic.py

@@ -7875,8 +7875,10 @@ def groupby(
             If False: show all values for categorical groupers.
 
             .. versionadded:: 0.23.0
-        mutated : bool, False
-            `mutated` is passed to groupby.
+        mutated : bool, default False
+            .. deprecated:: 1.0
+               This is an internal parameter and will be removed from the public
+               interface in the future
 
         Returns
         -------
@@ -7939,12 +7941,18 @@ def groupby(
         Captive      210.0
         Wild         185.0
         """
-        from pandas.core.groupby.groupby import groupby
+        from pandas.core.groupby.groupby import get_groupby
 
         if level is None and by is None:
             raise TypeError("You have to supply one of 'by' and 'level'")
         axis = self._get_axis_number(axis)
-        return groupby(
+
+        if mutated is not False:
+            warnings.warn(
+                "Parameter 'mutated' is deprecated", FutureWarning, stacklevel=2
+            )
+
+        return get_groupby(
             self,
             by=by,
             axis=axis,

pandas/core/groupby/generic.py

@@ -62,7 +62,7 @@
     GroupBy,
     _apply_docs,
     _transform_template,
-    groupby,
+    get_groupby,
 )
 from pandas.core.index import Index, MultiIndex, _all_indexes_same
 import pandas.core.indexes.base as ibase
@@ -997,7 +997,7 @@ def _cython_agg_blocks(
                     #  reductions; see GH#28949
                     obj = obj.iloc[:, 0]
 
-                s = groupby(obj, self.grouper)
+                s = get_groupby(obj, self.grouper)
                 try:
                     result = s.aggregate(lambda x: alt(x, axis=self.axis))
                 except TypeError:

pandas/core/groupby/groupby.py

@@ -2486,18 +2486,42 @@ def _reindex_output(self, output):
 
 
 @Appender(GroupBy.__doc__)
-def groupby(obj: NDFrame, by, **kwds):
+def get_groupby(
+    obj: NDFrame,
+    by=None,
+    axis: int = 0,
+    level=None,
+    grouper=None,
+    exclusions=None,
+    selection=None,
+    as_index: bool = True,
+    sort: bool = True,
+    group_keys: bool = True,
+    squeeze: bool = False,
+    observed: bool = False,
+    mutated: bool = False,
+):
     if isinstance(obj, Series):
         from pandas.core.groupby.generic import SeriesGroupBy
-
-        klass = (
-            SeriesGroupBy
-        )  # type: Union[Type["SeriesGroupBy"], Type["DataFrameGroupBy"]]
+        klass = SeriesGroupBy
     elif isinstance(obj, DataFrame):
         from pandas.core.groupby.generic import DataFrameGroupBy
-
         klass = DataFrameGroupBy
     else:
         raise TypeError("invalid type: {obj}".format(obj=obj))
 
-    return klass(obj, by, **kwds)
+    return klass(
+        obj=obj,
+        keys=by,
+        axis=axis,
+        level=level,
+        grouper=grouper,
+        exclusions=exclusions,
+        selection=selection,
+        as_index=as_index,
+        sort=sort,
+        group_keys=group_keys,
+        squeeze=squeeze,
+        observed=observed,
+        mutated=mutated,
+    )

pandas/core/resample.py

@@ -21,7 +21,7 @@
 from pandas.core.generic import _shared_docs
 from pandas.core.groupby.base import GroupByMixin
 from pandas.core.groupby.generic import SeriesGroupBy
-from pandas.core.groupby.groupby import GroupBy, _GroupBy, _pipe_template, groupby
+from pandas.core.groupby.groupby import GroupBy, _GroupBy, _pipe_template, get_groupby
 from pandas.core.groupby.grouper import Grouper
 from pandas.core.groupby.ops import BinGrouper
 from pandas.core.indexes.datetimes import DatetimeIndex, date_range
@@ -334,7 +334,7 @@ def _gotitem(self, key, ndim, subset=None):
         grouper = self.grouper
         if subset is None:
             subset = self.obj
-        grouped = groupby(subset, by=None, grouper=grouper, axis=self.axis)
+        grouped = get_groupby(subset, by=None, grouper=grouper, axis=self.axis)
 
         # try the key selection
         try:
@@ -353,7 +353,7 @@ def _groupby_and_aggregate(self, how, grouper=None, *args, **kwargs):
 
         obj = self._selected_obj
 
-        grouped = groupby(obj, by=None, grouper=grouper, axis=self.axis)
+        grouped = get_groupby(obj, by=None, grouper=grouper, axis=self.axis)
 
         try:
             if isinstance(obj, ABCDataFrame) and callable(how):

pandas/tests/groupby/test_groupby.py

@@ -953,6 +953,13 @@ def test_no_mutate_but_looks_like():
     tm.assert_series_equal(result1, result2)
 
 
+def test_mutated_deprecated():
+    # GH-29511
+    df = DataFrame({"key": [1, 1, 1, 2, 2, 2, 3, 3, 3], "value": range(9)})
+    with tm.assert_produces_warning(FutureWarning, check_stacklevel=True):
+        df.groupby("key", mutated=True)
+
+
 def test_groupby_series_indexed_differently():
     s1 = Series(
         [5.0, -9.0, 4.0, 100.0, -5.0, 55.0, 6.7],

pandas/tests/window/test_grouper.py

@@ -3,6 +3,7 @@
 
 import pandas as pd
 from pandas import DataFrame, Series
+from pandas.core.groupby.groupby import get_groupby
 import pandas.util.testing as tm
 
 
@@ -19,12 +20,12 @@ def test_mutated(self):
 
         g = self.frame.groupby("A")
         assert not g.mutated
-        g = self.frame.groupby("A", mutated=True)
+        g = get_groupby(self.frame, by="A", mutated=True)
         assert g.mutated
 
     def test_getitem(self):
         g = self.frame.groupby("A")
-        g_mutated = self.frame.groupby("A", mutated=True)
+        g_mutated = get_groupby(self.frame, by="A", mutated=True)
 
         expected = g_mutated.B.apply(lambda x: x.rolling(2).mean())
 
@@ -45,7 +46,7 @@ def test_getitem_multiple(self):
         # GH 13174
         g = self.frame.groupby("A")
         r = g.rolling(2)
-        g_mutated = self.frame.groupby("A", mutated=True)
+        g_mutated = get_groupby(self.frame, by="A", mutated=True)
         expected = g_mutated.B.apply(lambda x: x.rolling(2).count())
 
         result = r.B.count()