DEPR: returning tuple when grouping by a list containing single element

doc/source/whatsnew/v1.5.0.rst

@@ -773,6 +773,7 @@ Other Deprecations
 - Deprecated :class:`Series` and :class:`Resampler` reducers (e.g. ``min``, ``max``, ``sum``, ``mean``) raising a ``NotImplementedError`` when the dtype is non-numric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
 - Deprecated :meth:`Series.rank` returning an empty result when the dtype is non-numeric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
 - Deprecated argument ``errors`` for :meth:`Series.mask`, :meth:`Series.where`, :meth:`DataFrame.mask`, and :meth:`DataFrame.where` as ``errors`` had no effect on this methods (:issue:`47728`)
+- Deprecated producing a single element when using :meth:`Pandas.groupby` with a single list element. A tuple of length one will be returned instead.
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.performance:

pandas/core/groupby/generic.py

@@ -465,7 +465,9 @@ def _transform_general(self, func: Callable, *args, **kwargs) -> Series:
         klass = type(self.obj)
 
         results = []
-        for name, group in self:
+        for name, group in self.grouper.get_iterator(
+            self._selected_obj, axis=self.axis
+        ):
             # this setattr is needed for test_transform_lambda_with_datetimetz
             object.__setattr__(group, "name", name)
             res = func(group, *args, **kwargs)

pandas/core/groupby/groupby.py

@@ -821,6 +821,18 @@ def __iter__(self) -> Iterator[tuple[Hashable, NDFrameT]]:
         Generator yielding sequence of (name, subsetted object)
         for each group
         """
+        result = self.grouper.get_iterator(self._selected_obj, axis=self.axis)
+        if result.gi_frame.f_locals["self"].raise_warning_single_grouper:
+            warnings.warn(
+                (
+                    "In a future version of pandas, a length 1 "
+                    "tuple will be returned when grouping by a "
+                    "list of length 1. Don't supply a list with "
+                    "a single grouper to avoid this warning."
+                ),
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
         return self.grouper.get_iterator(self._selected_obj, axis=self.axis)
 
 

pandas/core/groupby/grouper.py

@@ -733,6 +733,11 @@ def get_grouper(
     """
     group_axis = obj._get_axis(axis)
 
+    raise_warning_single_grouper = False
+    if isinstance(key, list):
+        if len(key) == 1 and isinstance(key[0], str):
+            raise_warning_single_grouper = True
+
     # validate that the passed single level is compatible with the passed
     # axis of the object
     if level is not None:
@@ -918,7 +923,12 @@ def is_in_obj(gpr) -> bool:
 
     # create the internals grouper
     grouper = ops.BaseGrouper(
-        group_axis, groupings, sort=sort, mutated=mutated, dropna=dropna
+        group_axis,
+        groupings,
+        raise_warning_single_grouper=raise_warning_single_grouper,
+        sort=sort,
+        mutated=mutated,
+        dropna=dropna,
     )
     return grouper, frozenset(exclusions), obj
 

pandas/core/groupby/ops.py

@@ -11,6 +11,7 @@
 import functools
 from typing import (
     Callable,
+    Generator,
     Generic,
     Hashable,
     Iterator,
@@ -711,6 +712,7 @@ def __init__(
         self,
         axis: Index,
         groupings: Sequence[grouper.Grouping],
+        raise_warning_single_grouper: bool = False,
         sort: bool = True,
         group_keys: bool = True,
         mutated: bool = False,
@@ -721,6 +723,7 @@ def __init__(
 
         self.axis = axis
         self._groupings: list[grouper.Grouping] = list(groupings)
+        self.raise_warning_single_grouper = raise_warning_single_grouper
         self._sort = sort
         self.group_keys = group_keys
         self.mutated = mutated
@@ -744,7 +747,7 @@ def nkeys(self) -> int:
 
     def get_iterator(
         self, data: NDFrameT, axis: int = 0
-    ) -> Iterator[tuple[Hashable, NDFrameT]]:
+    ) -> Generator[tuple[Hashable, NDFrameT], None, None]:
         """
         Groupby iterator
 
@@ -1123,11 +1126,13 @@ def __init__(
         binlabels,
         mutated: bool = False,
         indexer=None,
+        raise_warning_single_grouper: bool = False,
     ) -> None:
         self.bins = ensure_int64(bins)
         self.binlabels = ensure_index(binlabels)
         self.mutated = mutated
         self.indexer = indexer
+        self.raise_warning_single_grouper = False
 
         # These lengths must match, otherwise we could call agg_series
         #  with empty self.bins, which would raise in libreduction.

pandas/core/reshape/merge.py

@@ -150,7 +150,7 @@ def _groupby_and_merge(by, left: DataFrame, right: DataFrame, merge_pieces):
     if all(item in right.columns for item in by):
         rby = right.groupby(by, sort=False)
 
-    for key, lhs in lby:
+    for key, lhs in lby.grouper.get_iterator(lby._selected_obj, axis=lby.axis):
 
         if rby is None:
             rhs = right

pandas/core/reshape/pivot.py

@@ -161,6 +161,9 @@ def __internal_pivot_table(
                 pass
         values = list(values)
 
+    if isinstance(keys, list):
+        if len(keys) == 1 and isinstance(keys[0], str):
+            keys = keys[0]
     grouped = data.groupby(keys, observed=observed, sort=sort)
     agged = grouped.agg(aggfunc)
     if dropna and isinstance(agged, ABCDataFrame) and len(agged.columns):
@@ -364,7 +367,10 @@ def _all_key(key):
             return (key, margins_name) + ("",) * (len(cols) - 1)
 
         if len(rows) > 0:
-            margin = data[rows + values].groupby(rows, observed=observed).agg(aggfunc)
+            modifiedrow = fix_groupby_singlelist_input(rows)
+            margin = (
+                data[rows + values].groupby(modifiedrow, observed=observed).agg(aggfunc)
+            )
             cat_axis = 1
 
             for key, piece in table.groupby(level=0, axis=cat_axis, observed=observed):
@@ -404,7 +410,10 @@ def _all_key(key):
         margin_keys = table.columns
 
     if len(cols) > 0:
-        row_margin = data[cols + values].groupby(cols, observed=observed).agg(aggfunc)
+        modifiedcol = fix_groupby_singlelist_input(cols)
+        row_margin = (
+            data[cols + values].groupby(modifiedcol, observed=observed).agg(aggfunc)
+        )
         row_margin = row_margin.stack()
 
         # slight hack
@@ -844,3 +853,10 @@ def get_duplicates(names):
     ]
 
     return rownames_mapper, unique_rownames, colnames_mapper, unique_colnames
+
+
+def fix_groupby_singlelist_input(keys):
+    if isinstance(keys, list):
+        if len(keys) == 1 and isinstance(keys[0], str):
+            keys = keys[0]
+    return keys

pandas/plotting/_matplotlib/core.py

@@ -175,7 +175,8 @@ def __init__(
         # For `hist` plot, need to get grouped original data before `self.data` is
         # updated later
         if self.by is not None and self._kind == "hist":
-            self._grouped = data.groupby(self.by)
+            bymodi = fix_groupby_singlelist_input(by)
+            self._grouped = data.groupby(bymodi)
 
         self.kind = kind
 
@@ -1832,3 +1833,10 @@ def blank_labeler(label, value):
             leglabels = labels if labels is not None else idx
             for p, l in zip(patches, leglabels):
                 self._append_legend_handles_labels(p, l)
+
+
+def fix_groupby_singlelist_input(keys):
+    if isinstance(keys, list):
+        if len(keys) == 1 and isinstance(keys[0], str):
+            keys = keys[0]
+    return keys

pandas/plotting/_matplotlib/groupby.py

@@ -108,7 +108,8 @@ def reconstruct_data_with_by(
     1  3.0   4.0   NaN   NaN
     2  NaN   NaN   5.0   6.0
     """
-    grouped = data.groupby(by)
+    bymodi = fix_groupby_singlelist_input(by)
+    grouped = data.groupby(bymodi)
 
     data_list = []
     for key, group in grouped:
@@ -134,3 +135,10 @@ def reformat_hist_y_given_by(
     if by is not None and len(y.shape) > 1:
         return np.array([remove_na_arraylike(col) for col in y.T]).T
     return remove_na_arraylike(y)
+
+
+def fix_groupby_singlelist_input(keys):
+    if isinstance(keys, list):
+        if len(keys) == 1 and isinstance(keys[0], str):
+            keys = keys[0]
+    return keys

pandas/plotting/_matplotlib/hist.py

@@ -67,7 +67,8 @@ def _args_adjust(self):
         # where subplots are created based on by argument
         if is_integer(self.bins):
             if self.by is not None:
-                grouped = self.data.groupby(self.by)[self.columns]
+                bymodi = fix_groupby_singlelist_input(self.by)
+                grouped = self.data.groupby(bymodi)[self.columns]
                 self.bins = [self._calculate_bins(group) for key, group in grouped]
             else:
                 self.bins = self._calculate_bins(self.data)
@@ -271,6 +272,8 @@ def _grouped_plot(
     grouped = data.groupby(by)
     if column is not None:
         grouped = grouped[column]
+        if isinstance(by, list) and len(by) == 1:
+            by = [by]
 
     naxes = len(grouped)
     fig, axes = create_subplots(
@@ -528,3 +531,10 @@ def hist_frame(
     maybe_adjust_figure(fig, wspace=0.3, hspace=0.3)
 
     return axes
+
+
+def fix_groupby_singlelist_input(keys):
+    if isinstance(keys, list):
+        if len(keys) == 1 and isinstance(keys[0], str):
+            keys = keys[0]
+    return keys

pandas/tests/groupby/test_groupby.py

@@ -2795,3 +2795,16 @@ def test_groupby_none_column_name():
     result = df.groupby(by=[None]).sum()
     expected = DataFrame({"b": [2, 5], "c": [9, 13]}, index=Index([1, 2], name=None))
     tm.assert_frame_equal(result, expected)
+
+
+def test_single_element_list_grouping():
+    df = DataFrame(columns=["a", "b", "c"], index=["x", "y"])
+    df.loc["y"] = Series({"a": 1, "b": 5, "c": 2})
+    msg = (
+        "In a future version of pandas, a length 1 "
+        "tuple will be returned when grouping by a "
+        "list of length 1. Don't supply a list with "
+        "a single grouper to avoid this warning."
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        values, _ = next(iter(df.groupby(["a"])))