DEPR: DataFrame GroupBy indexing with single items DeprecationWarning (#30546)

Author: yehoshuadimarsky

doc/source/getting_started/comparison/comparison_with_sas.rst

@@ -629,7 +629,7 @@ for more details and examples.
 
 .. ipython:: python
 
-   tips_summed = tips.groupby(['sex', 'smoker'])['total_bill', 'tip'].sum()
+   tips_summed = tips.groupby(['sex', 'smoker'])[['total_bill', 'tip']].sum()
    tips_summed.head()
 
 

doc/source/getting_started/comparison/comparison_with_stata.rst

@@ -617,7 +617,7 @@ for more details and examples.
 
 .. ipython:: python
 
-   tips_summed = tips.groupby(['sex', 'smoker'])['total_bill', 'tip'].sum()
+   tips_summed = tips.groupby(['sex', 'smoker'])[['total_bill', 'tip']].sum()
    tips_summed.head()
 
 

doc/source/whatsnew/v1.0.0.rst

@@ -577,6 +577,37 @@ Deprecations
 - :meth:`DataFrame.to_stata`, :meth:`DataFrame.to_feather`, and :meth:`DataFrame.to_parquet` argument "fname" is deprecated, use "path" instead (:issue:`23574`)
 - The deprecated internal attributes ``_start``, ``_stop`` and ``_step`` of :class:`RangeIndex` now raise a ``FutureWarning`` instead of a ``DeprecationWarning`` (:issue:`26581`)
 
+**Selecting Columns from a Grouped DataFrame**
+
+When selecting columns from a :class:`DataFrameGroupBy` object, passing individual keys (or a tuple of keys) inside single brackets is deprecated,
+a list of items should be used instead. (:issue:`23566`) For example:
+
+.. code-block:: ipython
+
+    df = pd.DataFrame({
+        "A": ["foo", "bar", "foo", "bar", "foo", "bar", "foo", "foo"],
+        "B": np.random.randn(8),
+        "C": np.random.randn(8),
+    })
+    g = df.groupby('A')
+
+    # single key, returns SeriesGroupBy
+    g['B']
+
+    # tuple of single key, returns SeriesGroupBy
+    g[('B',)]
+
+    # tuple of multiple keys, returns DataFrameGroupBy, raises FutureWarning
+    g[('B', 'C')]
+
+    # multiple keys passed directly, returns DataFrameGroupBy, raises FutureWarning
+    # (implicitly converts the passed strings into a single tuple)
+    g['B', 'C']
+
+    # proper way, returns DataFrameGroupBy
+    g[['B', 'C']]
+
+
 .. _whatsnew_1000.prior_deprecations:
 
 

pandas/core/groupby/generic.py

@@ -25,6 +25,7 @@
     Union,
     cast,
 )
+import warnings
 
 import numpy as np
 
@@ -326,7 +327,7 @@ def _aggregate_multiple_funcs(self, arg):
         return DataFrame(results, columns=columns)
 
     def _wrap_series_output(
-        self, output: Mapping[base.OutputKey, Union[Series, np.ndarray]], index: Index,
+        self, output: Mapping[base.OutputKey, Union[Series, np.ndarray]], index: Index
     ) -> Union[Series, DataFrame]:
         """
         Wraps the output of a SeriesGroupBy operation into the expected result.
@@ -1578,6 +1579,19 @@ def filter(self, func, dropna=True, *args, **kwargs):
 
         return self._apply_filter(indices, dropna)
 
+    def __getitem__(self, key):
+        # per GH 23566
+        if isinstance(key, tuple) and len(key) > 1:
+            # if len == 1, then it becomes a SeriesGroupBy and this is actually
+            # valid syntax, so don't raise warning
+            warnings.warn(
+                "Indexing with multiple keys (implicitly converted to a tuple "
+                "of keys) will be deprecated, use a list instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+        return super().__getitem__(key)
+
     def _gotitem(self, key, ndim: int, subset=None):
         """
         sub-classes to define

pandas/tests/groupby/test_grouping.py

@@ -71,14 +71,12 @@ def test_getitem_list_of_columns(self):
         )
 
         result = df.groupby("A")[["C", "D"]].mean()
-        result2 = df.groupby("A")["C", "D"].mean()
-        result3 = df.groupby("A")[df.columns[2:4]].mean()
+        result2 = df.groupby("A")[df.columns[2:4]].mean()
 
         expected = df.loc[:, ["A", "C", "D"]].groupby("A").mean()
 
         tm.assert_frame_equal(result, expected)
         tm.assert_frame_equal(result2, expected)
-        tm.assert_frame_equal(result3, expected)
 
     def test_getitem_numeric_column_names(self):
         # GH #13731
@@ -91,14 +89,40 @@ def test_getitem_numeric_column_names(self):
             }
         )
         result = df.groupby(0)[df.columns[1:3]].mean()
-        result2 = df.groupby(0)[2, 4].mean()
-        result3 = df.groupby(0)[[2, 4]].mean()
+        result2 = df.groupby(0)[[2, 4]].mean()
 
         expected = df.loc[:, [0, 2, 4]].groupby(0).mean()
 
         tm.assert_frame_equal(result, expected)
         tm.assert_frame_equal(result2, expected)
-        tm.assert_frame_equal(result3, expected)
+
+        # per GH 23566 this should raise a FutureWarning
+        with tm.assert_produces_warning(FutureWarning):
+            df.groupby(0)[2, 4].mean()
+
+    def test_getitem_single_list_of_columns(self, df):
+        # per GH 23566 this should raise a FutureWarning
+        with tm.assert_produces_warning(FutureWarning):
+            df.groupby("A")["C", "D"].mean()
+
+    def test_getitem_single_column(self):
+        df = DataFrame(
+            {
+                "A": ["foo", "bar", "foo", "bar", "foo", "bar", "foo", "foo"],
+                "B": ["one", "one", "two", "three", "two", "two", "one", "three"],
+                "C": np.random.randn(8),
+                "D": np.random.randn(8),
+                "E": np.random.randn(8),
+            }
+        )
+
+        result = df.groupby("A")["C"].mean()
+
+        as_frame = df.loc[:, ["A", "C"]].groupby("A").mean()
+        as_series = as_frame.iloc[:, 0]
+        expected = as_series
+
+        tm.assert_series_equal(result, expected)
 
 
 # grouping

pandas/tests/groupby/test_transform.py

@@ -319,7 +319,7 @@ def test_dispatch_transform(tsframe):
 
 def test_transform_select_columns(df):
     f = lambda x: x.mean()
-    result = df.groupby("A")["C", "D"].transform(f)
+    result = df.groupby("A")[["C", "D"]].transform(f)
 
     selection = df[["C", "D"]]
     expected = selection.groupby(df["A"]).transform(f)