move the FutureWarning to GroupBy.groups

Author: natmokval

doc/source/whatsnew/v3.0.0.rst

@@ -278,6 +278,7 @@ Other Deprecations
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.all`, :meth:`DataFrame.min`, :meth:`DataFrame.max`, :meth:`DataFrame.sum`, :meth:`DataFrame.prod`, :meth:`DataFrame.mean`, :meth:`DataFrame.median`, :meth:`DataFrame.sem`, :meth:`DataFrame.var`, :meth:`DataFrame.std`, :meth:`DataFrame.skew`, :meth:`DataFrame.kurt`, :meth:`Series.all`,  :meth:`Series.min`, :meth:`Series.max`, :meth:`Series.sum`, :meth:`Series.prod`, :meth:`Series.mean`, :meth:`Series.median`, :meth:`Series.sem`, :meth:`Series.var`, :meth:`Series.std`, :meth:`Series.skew`, and :meth:`Series.kurt`. (:issue:`57087`)
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_markdown` except ``buf``. (:issue:`57280`)
 - Deprecated allowing non-keyword arguments in :meth:`Series.to_string` except ``buf``. (:issue:`57280`)
+- Deprecated behavior of :meth:`.DataFrameGroupBy.groups` and :meth:`.SeriesGroupBy.groups`, in a future version ``groups`` by one element list will return tuple instead of scalar. (:issue:`58858`)
 - Deprecated behavior of :meth:`Series.dt.to_pytimedelta`, in a future version this will return a :class:`Series` containing python ``datetime.timedelta`` objects instead of an ``ndarray`` of timedelta; this matches the behavior of other :meth:`Series.dt` properties. (:issue:`57463`)
 - Deprecated parameter ``method`` in :meth:`DataFrame.reindex_like` / :meth:`Series.reindex_like` (:issue:`58667`)
 - Deprecated strings ``w``, ``d``, ``MIN``, ``MS``, ``US`` and ``NS`` denoting units in :class:`Timedelta` in favour of ``W``, ``D``, ``min``, ``ms``, ``us`` and ``ns`` (:issue:`59051`)

pandas/core/groupby/groupby.py

@@ -654,6 +654,15 @@ def groups(self) -> dict[Hashable, Index]:
         >>> ser.resample("MS").groups
         {Timestamp('2023-01-01 00:00:00'): 2, Timestamp('2023-02-01 00:00:00'): 4}
         """
+        if isinstance(self.keys, list) and len(self.keys) == 1:
+            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. Use ``df.groupby(by='a').groups`` "
+                "instead of ``df.groupby(by=['a']).groups`` to avoid this warning",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
         return self._grouper.groups
 
     @final

pandas/core/groupby/grouper.py

@@ -9,14 +9,12 @@
     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,
@@ -443,7 +441,6 @@ 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
@@ -456,7 +453,6 @@ 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
@@ -671,15 +667,6 @@ 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. Use ``df.groupby(by='a').groups`` "
-                "instead of ``df.groupby(by=['a']).groups`` to avoid this warning",
-                FutureWarning,
-                stacklevel=find_stack_level(),
-            )
         return self._index.groupby(cats)
 
     @property
@@ -794,9 +781,7 @@ 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:
@@ -907,7 +892,6 @@ 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

@@ -2999,7 +2999,7 @@ def test_groupby_multi_index_codes():
 
 
 def test_groupby_keys_1length_list():
-    # GH#59179
+    # GH#58858
     msg = "`groups` by one element list returns scalar is deprecated"
 
     df = DataFrame({"x": [10, 20, 30], "y": ["a", "b", "c"]})

pandas/tests/groupby/test_grouping.py

@@ -1014,16 +1014,16 @@ def test_groups(self, df):
 
         with tm.assert_produces_warning(FutureWarning, match=msg):
             groups = grouped.groups
-        assert groups is grouped.groups  # caching works
+            assert groups is grouped.groups  # caching works
 
-        for k, v in grouped.groups.items():
+        for k, v in groups.items():
             assert (df.loc[v]["A"] == k).all()
 
         grouped = df.groupby(["A", "B"])
         groups = grouped.groups
         assert groups is grouped.groups  # caching works
 
-        for k, v in grouped.groups.items():
+        for k, v in groups.items():
             assert (df.loc[v]["A"] == k[0]).all()
             assert (df.loc[v]["B"] == k[1]).all()