deprecate group by one element list get scalar keys

Author: natmokval

pandas/core/groupby/grouper.py

@@ -9,12 +9,14 @@
     TYPE_CHECKING,
     final,
 )
+import warnings
 
 import numpy as np
 
 from pandas._libs.tslibs import OutOfBoundsDatetime
 from pandas.errors import InvalidIndexError
 from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
 
 from pandas.core.dtypes.common import (
     is_list_like,
@@ -441,6 +443,7 @@ def __init__(
         in_axis: bool = False,
         dropna: bool = True,
         uniques: ArrayLike | None = None,
+        key_dtype_str: bool = False,
     ) -> None:
         self.level = level
         self._orig_grouper = grouper
@@ -453,6 +456,7 @@ def __init__(
         self.in_axis = in_axis
         self._dropna = dropna
         self._uniques = uniques
+        self.key_dtype_str = key_dtype_str
 
         # we have a single grouper which may be a myriad of things,
         # some of which are dependent on the passing in level
@@ -667,6 +671,15 @@ def groups(self) -> dict[Hashable, Index]:
         codes, uniques = self._codes_and_uniques
         uniques = Index._with_infer(uniques, name=self.name)
         cats = Categorical.from_codes(codes, uniques, validate=False)
+        if not self.key_dtype_str:
+            warnings.warn(
+                "`groups` by one element list returns scalar is deprecated "
+                "and will be removed. In a future version `groups` by one element "
+                "list will return tuple.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            cats = [(key,) for key in cats]
         return self._index.groupby(cats)
 
     @property
@@ -781,7 +794,9 @@ def get_grouper(
     elif isinstance(key, ops.BaseGrouper):
         return key, frozenset(), obj
 
+    key_dtype_str = False
     if not isinstance(key, list):
+        key_dtype_str = True
         keys = [key]
         match_axis_length = False
     else:
@@ -892,6 +907,7 @@ def is_in_obj(gpr) -> bool:
                 observed=observed,
                 in_axis=in_axis,
                 dropna=dropna,
+                key_dtype_str=key_dtype_str,
             )
             if not isinstance(gpr, Grouping)
             else gpr

pandas/tests/groupby/test_groupby.py

@@ -2996,3 +2996,15 @@ def test_groupby_multi_index_codes():
 
     index = df_grouped.index
     tm.assert_index_equal(index, MultiIndex.from_frame(index.to_frame()))
+
+
+def test_groupby_keys_1length_list():
+    # GH#58858
+    msg = "`groups` by one element list returns scalar is deprecated"
+
+    df = DataFrame({"x": [10, 20, 30], "y": ["a", "b", "c"]})
+    expected = {(10,): [0], (20,): [1], (30,): [2]}
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df.groupby(["x"]).groups
+    tm.assert_dict_equal(result, expected)
+    print(result, type(result))