chore(python): Deprecate Expr.agg_groups() and pl.groups()

py-polars/src/polars/expr/expr.py

@@ -1124,10 +1124,16 @@ def agg_groups(self) -> Expr:
         """
         Get the group indexes of the group by operation.
 
+        .. deprecated:: X.Y
+            use `df.with_row_index().group_by(...).agg(pl.col('index'))` instead.
+            This method will be removed in Polars 2.0.
+
         Should be used in aggregation context only.
 
         Examples
         --------
+        >>> import warnings
+        >>> warnings.filterwarnings("ignore", category=DeprecationWarning)
         >>> df = pl.DataFrame(
         ...     {
         ...         "group": [
@@ -1151,7 +1157,29 @@ def agg_groups(self) -> Expr:
         │ one   ┆ [0, 1, 2] │
         │ two   ┆ [3, 4, 5] │
         └───────┴───────────┘
+
+        New recommended approach:
+        >>> (
+        ...     df.with_row_index()
+        ...     .group_by("group", maintain_order=True)
+        ...     .agg(pl.col("index"))
+        ... )
+        shape: (2, 2)
+        ┌───────┬───────────┐
+        │ group ┆ index     │
+        │ ---   ┆ ---       │
+        │ str   ┆ list[u32] │
+        ╞═══════╪═══════════╡
+        │ one   ┆ [0, 1, 2] │
+        │ two   ┆ [3, 4, 5] │
+        └───────┴───────────┘
         """
+        warnings.warn(
+            "agg_groups() is deprecated and will be removed in Polars 2.0. "
+            "Use df.with_row_index().group_by(...).agg(pl.col('index')) instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return wrap_expr(self._pyexpr.agg_groups())
 
     def count(self) -> Expr:

py-polars/src/polars/functions/lazy.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextlib
+import warnings
 from typing import TYPE_CHECKING, Any, Callable, overload
 
 import polars._reexport as pl
@@ -1876,7 +1877,19 @@ def exclude(
 
 
 def groups(column: str) -> Expr:
-    """Syntactic sugar for `pl.col("foo").agg_groups()`."""
+    """
+    Syntactic sugar for `pl.col("foo").agg_groups()`.
+
+    .. deprecated:: X.Y
+        Use `df.with_row_index().group_by(...).agg(pl.col('index'))` instead.
+        This method will be removed in Polars 2.0.
+    """
+    warnings.warn(
+        "pl.groups() is deprecated and will be removed in Polars 2.0. "
+        "Use df.with_row_index().group_by(...).agg(pl.col('index')) instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return F.col(column).agg_groups()
 
 

py-polars/tests/unit/datatypes/test_array.py

@@ -27,6 +27,7 @@ def test_cast_list_array() -> None:
         s.cast(pl.Array(pl.Int64, 2))
 
 
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
 def test_array_in_group_by_iter() -> None:
     df = pl.DataFrame(
         [