depr(python): Deprecate positional args in pivot to prepare new fun…

…ctionality (pola-rs#14428)

py-polars/polars/dataframe/frame.py

@@ -7251,6 +7251,15 @@ def explode(
         """
         return self.lazy().explode(columns, *more_columns).collect(_eager=True)
 
+    @deprecate_nonkeyword_arguments(
+        allowed_args=["self"],
+        message=(
+            "The order of the parameters of `pivot` will change in the next breaking release."
+            " The order will become `index, columns, values` with `values` as an optional parameter."
+            " Use keyword arguments to silence this warning."
+        ),
+        version="0.20.8",
+    )
     def pivot(
         self,
         values: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None,
@@ -7305,7 +7314,7 @@ def pivot(
         ...         "baz": [1, 2, 3, 4, 5, 6],
         ...     }
         ... )
-        >>> df.pivot(values="baz", index="foo", columns="bar", aggregate_function="sum")
+        >>> df.pivot(index="foo", columns="bar", values="baz", aggregate_function="sum")
         shape: (2, 3)
         ┌─────┬─────┬─────┐
         │ foo ┆ y   ┆ x   │
@@ -7320,9 +7329,9 @@ def pivot(
 
         >>> import polars.selectors as cs
         >>> df.pivot(
-        ...     values=cs.numeric(),
         ...     index=cs.string(),
         ...     columns=cs.string(),
+        ...     values=cs.numeric(),
         ...     aggregate_function="sum",
         ...     sort_columns=True,
         ... ).sort(
@@ -7374,17 +7383,10 @@ def pivot(
         >>> values = pl.col("col3")
         >>> unique_column_values = ["x", "y"]
         >>> aggregate_function = lambda col: col.tanh().mean()
-        >>> (
-        ...     df.lazy()
-        ...     .group_by(index)
-        ...     .agg(
-        ...         *[
-        ...             aggregate_function(values.filter(columns == value)).alias(value)
-        ...             for value in unique_column_values
-        ...         ]
-        ...     )
-        ...     .collect()
-        ... )  # doctest: +IGNORE_RESULT
+        >>> df.lazy().group_by(index).agg(
+        ...     aggregate_function(values.filter(columns == value)).alias(value)
+        ...     for value in unique_column_values
+        ... ).collect()  # doctest: +IGNORE_RESULT
         shape: (2, 3)
         ┌──────┬──────────┬──────────┐
         │ col1 ┆ x        ┆ y        │

py-polars/tests/unit/operations/test_pivot.py

@@ -22,7 +22,7 @@ def test_pivot() -> None:
             "bar": ["k", "l", "m", "n", "o"],
         }
     )
-    result = df.pivot(values="N", index="foo", columns="bar", aggregate_function=None)
+    result = df.pivot(index="foo", columns="bar", values="N", aggregate_function=None)
 
     expected = pl.DataFrame(
         [
@@ -47,7 +47,11 @@ def test_pivot_list() -> None:
         }
     )
     out = df.pivot(
-        "b", index="a", columns="a", aggregate_function="first", sort_columns=True
+        index="a",
+        columns="a",
+        values="b",
+        aggregate_function="first",
+        sort_columns=True,
     )
     assert_frame_equal(out, expected)
 
@@ -389,12 +393,36 @@ def test_pivot_negative_duration() -> None:
     }
 
 
-def test_aggregate_function_deprecation_warning() -> None:
+def test_aggregate_function_default() -> None:
     df = pl.DataFrame({"a": [1, 2], "b": ["foo", "foo"], "c": ["x", "x"]})
     with pytest.raises(
         pl.ComputeError, match="found multiple elements in the same group"
     ):
-        df.pivot("a", "b", "c")
+        df.pivot(values="a", index="b", columns="c")
+
+
+def test_pivot_positional_args_deprecated() -> None:
+    df = pl.DataFrame(
+        {
+            "foo": ["A", "A", "B", "B", "C"],
+            "N": [1, 2, 2, 4, 2],
+            "bar": ["k", "l", "m", "n", "o"],
+        }
+    )
+    with pytest.deprecated_call():
+        df.pivot("N", "foo", "bar", aggregate_function=None)
+
+
+def test_pivot_aggregate_function_count_deprecated() -> None:
+    df = pl.DataFrame(
+        {
+            "foo": ["A", "A", "B", "B", "C"],
+            "N": [1, 2, 2, 4, 2],
+            "bar": ["k", "l", "m", "n", "o"],
+        }
+    )
+    with pytest.deprecated_call():
+        df.pivot(index="foo", columns="bar", values="N", aggregate_function="count")  # type: ignore[arg-type]
 
 
 def test_pivot_struct() -> None: