From 45f48f4bb8e0cf428ca0175ddafbd0d4c8112825 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sun, 22 Dec 2024 19:20:58 +0000
Subject: [PATCH] docs: Note that `maintains_order` has no effect (but keep
 around for backwards-compatibility) (#1643)

---
 narwhals/_pandas_like/dataframe.py |  1 -
 narwhals/_polars/dataframe.py      |  2 --
 narwhals/dataframe.py              | 14 +++++++++++---
 tests/frame/pivot_test.py          |  3 ++-
 4 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/narwhals/_pandas_like/dataframe.py b/narwhals/_pandas_like/dataframe.py
index 5212b27ff..6e640c98b 100644
--- a/narwhals/_pandas_like/dataframe.py
+++ b/narwhals/_pandas_like/dataframe.py
@@ -836,7 +836,6 @@ def pivot(
         index: str | list[str] | None,
         values: str | list[str] | None,
         aggregate_function: Any | None,
-        maintain_order: bool,
         sort_columns: bool,
         separator: str = "_",
     ) -> Self:
diff --git a/narwhals/_polars/dataframe.py b/narwhals/_polars/dataframe.py
index 643675d14..760b5f4b6 100644
--- a/narwhals/_polars/dataframe.py
+++ b/narwhals/_polars/dataframe.py
@@ -314,7 +314,6 @@ def pivot(
             "min", "max", "first", "last", "sum", "mean", "median", "len"
         ]
         | None,
-        maintain_order: bool,
         sort_columns: bool,
         separator: str,
     ) -> Self:
@@ -326,7 +325,6 @@ def pivot(
             index=index,
             values=values,
             aggregate_function=aggregate_function,
-            maintain_order=maintain_order,
             sort_columns=sort_columns,
             separator=separator,
         )
diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
index aa57b33fb..2b59dd952 100644
--- a/narwhals/dataframe.py
+++ b/narwhals/dataframe.py
@@ -11,11 +11,13 @@
 from typing import Sequence
 from typing import TypeVar
 from typing import overload
+from warnings import warn
 
 from narwhals.dependencies import get_polars
 from narwhals.dependencies import is_numpy_array
 from narwhals.schema import Schema
 from narwhals.translate import to_native
+from narwhals.utils import find_stacklevel
 from narwhals.utils import flatten
 from narwhals.utils import is_sequence_but_not_str
 from narwhals.utils import parse_version
@@ -2865,7 +2867,7 @@ def pivot(
             "min", "max", "first", "last", "sum", "mean", "median", "len"
         ]
         | None = None,
-        maintain_order: bool = True,
+        maintain_order: bool | None = None,
         sort_columns: bool = False,
         separator: str = "_",
     ) -> Self:
@@ -2881,11 +2883,12 @@ def pivot(
                 specified on `on` and `index` will be used. At least one of `index` and
                 `values` must be specified.
             aggregate_function: Choose from:
+
                 - None: no aggregation takes place, will raise error if multiple values
                     are in group.
                 - A predefined aggregate function string, one of
                     {'min', 'max', 'first', 'last', 'sum', 'mean', 'median', 'len'}
-            maintain_order: Sort the grouped keys so that the output order is predictable.
+            maintain_order: Has no effect and is kept around only for backwards-compatibility.
             sort_columns: Sort the transposed columns by name. Default is by order of
                 discovery.
             separator: Used as separator/delimiter in generated column names in case of
@@ -2933,6 +2936,12 @@ def pivot(
         if values is None and index is None:
             msg = "At least one of `values` and `index` must be passed"
             raise ValueError(msg)
+        if maintain_order is not None:
+            msg = (
+                "`maintain_order` has no effect and is only kept around for backwards-compatibility. "
+                "You can safely remove this argument."
+            )
+            warn(message=msg, category=UserWarning, stacklevel=find_stacklevel())
 
         return self._from_compliant_dataframe(
             self._compliant_frame.pivot(
@@ -2940,7 +2949,6 @@ def pivot(
                 index=index,
                 values=values,
                 aggregate_function=aggregate_function,
-                maintain_order=maintain_order,
                 sort_columns=sort_columns,
                 separator=separator,
             )
diff --git a/tests/frame/pivot_test.py b/tests/frame/pivot_test.py
index a21cab65e..98ef7466f 100644
--- a/tests/frame/pivot_test.py
+++ b/tests/frame/pivot_test.py
@@ -266,7 +266,8 @@ def test_pivot_no_index(
         # not implemented
         request.applymarker(pytest.mark.xfail)
     df = nw.from_native(constructor_eager(data_no_dups), eager_only=True)
-    result = df.pivot(on="col", values="foo").sort("ix", "bar")
+    with pytest.warns(UserWarning, match="has no effect"):
+        result = df.pivot(on="col", values="foo", maintain_order=True).sort("ix", "bar")
     expected = {
         "ix": [1, 1, 2, 2],
         "bar": ["x", "y", "w", "z"],