chore(python): Properly deprecate groupby.pivot (#6000)

py-polars/polars/internals/dataframe/groupby.py

@@ -414,6 +414,9 @@ def pivot(
         The pivot operation is based on the group key, a pivot column and an aggregation
         function on the values column.
 
+        .. deprecated:: 0.13.23
+            `DataFrame.groupby.pivot` will be removed in favour of `DataFrame.pivot`.
+
         Parameters
         ----------
         pivot_column
@@ -449,6 +452,12 @@ def pivot(
         └─────┴─────┴─────┴─────┘
 
         """
+        warnings.warn(
+            "`DataFrame.groupby.pivot` is deprecated and will be removed in a future"
+            " version. Use `DataFrame.pivot` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if isinstance(pivot_column, str):
             pivot_column = [pivot_column]
         if isinstance(values_column, str):

py-polars/tests/unit/test_df.py

@@ -2086,10 +2086,11 @@ class SubClassedDataFrame(pl.DataFrame):
     )
 
     # Round-trips to PivotOps and back should also preserve subclass
-    assert isinstance(
-        groupby.pivot(pivot_column="a", values_column="b").first(),
-        SubClassedDataFrame,
-    )
+    with pytest.deprecated_call():
+        assert isinstance(
+            groupby.pivot(pivot_column="a", values_column="b").first(),
+            SubClassedDataFrame,
+        )
 
 
 def test_explode_empty() -> None:
@@ -2493,15 +2494,19 @@ def test_glimpse() -> None:
     )
     result = df.glimpse()
 
-    expected = """Rows: 3
-Columns: 6
-$ a <Float64> 1.0, 2.8, 3.0                                                                             
-$ b   <Int64> 4, 5, None                                                                                
-$ c <Boolean> True, False, True                                                                         
-$ d    <Utf8> None, b, c                                                                                
-$ e    <Utf8> usd, eur, None                                                                            
-$ f    <Date> 2020-01-01, 2021-01-02, 2022-01-01"""
-    assert result.strip() == expected
+    # Strip trailing whitespace for the purposes of this test
+    result_lines = [line.strip() for line in result.strip().split("\n")]
+    expected_lines = [
+        "Rows: 3",
+        "Columns: 6",
+        "$ a <Float64> 1.0, 2.8, 3.0",
+        "$ b   <Int64> 4, 5, None",
+        "$ c <Boolean> True, False, True",
+        "$ d    <Utf8> None, b, c",
+        "$ e    <Utf8> usd, eur, None",
+        "$ f    <Date> 2020-01-01, 2021-01-02, 2022-01-01",
+    ]
+    assert result_lines == expected_lines
 
 
 def test_item() -> None:

py-polars/tests/unit/test_pivot.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING
 
+import pytest
+
 import polars as pl
 
 if TYPE_CHECKING:
@@ -31,10 +33,12 @@ def test_pivot() -> None:
             "c": [2, 4, None, 8, 10],
         }
     )
-    gb = df.groupby("b").pivot(
-        pivot_column="a",
-        values_column="c",
-    )
+
+    with pytest.deprecated_call():
+        gb = df.groupby("b").pivot(
+            pivot_column="a",
+            values_column="c",
+        )
     assert gb.count().rows() == [("a", 2, None, None), ("b", None, 2, 1)]
     assert gb.first().rows() == [("a", 2, None, None), ("b", None, None, 10)]
     assert gb.max().rows() == [("a", 4, None, None), ("b", None, 8, 10)]
@@ -59,7 +63,9 @@ def test_pivot() -> None:
             "bar": ["k", "l", "m", "n", "o"],
         }
     )
-    out = df.groupby("foo").pivot(pivot_column="bar", values_column="N").first()
+    with pytest.deprecated_call():
+        out = df.groupby("foo").pivot(pivot_column="bar", values_column="N").first()
+
     assert out.shape == (3, 6)
     assert out.rows() == [
         ("A", 1, 2, None, None, None),