diff --git a/narwhals/_pandas_like/dataframe.py b/narwhals/_pandas_like/dataframe.py index 5be8f15b4..c1b91a417 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 954583cb2..f174ea896 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 @@ -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,6 +2930,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( @@ -2934,7 +2943,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"],