docs: Note that maintains_order has no effect (but keep around for backwards-compatibility)

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:

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,
         )

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
@@ -2859,7 +2861,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:
@@ -2875,11 +2877,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
@@ -2927,14 +2930,19 @@ 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(
                 on=on,
                 index=index,
                 values=values,
                 aggregate_function=aggregate_function,
-                maintain_order=maintain_order,
                 sort_columns=sort_columns,
                 separator=separator,
             )

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"],