From 8939ad3e225927f32baeef03ac2f191dd8e70f12 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Sun, 22 Dec 2024 11:24:53 +0000 Subject: [PATCH 1/3] docs: Hide `maintain_order` in `pivot` (but silently keep around for backcompat) --- narwhals/_pandas_like/dataframe.py | 1 - narwhals/_polars/dataframe.py | 2 -- narwhals/dataframe.py | 10 +++++++--- 3 files changed, 7 insertions(+), 6 deletions(-) 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..521df95e9 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: @@ -2879,7 +2881,7 @@ def pivot( 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 +2929,9 @@ 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: # pragma: no cover + msg = "`maintain_order` has no effect and is only kept around for backwards-compatibility" + warn(message=msg, category=UserWarning, stacklevel=find_stacklevel()) return self._from_compliant_dataframe( self._compliant_frame.pivot( @@ -2934,7 +2939,6 @@ def pivot( index=index, values=values, aggregate_function=aggregate_function, - maintain_order=maintain_order, sort_columns=sort_columns, separator=separator, ) From a8390ef8cff54d529ad785413f0c33b536d72a00 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Sun, 22 Dec 2024 11:25:39 +0000 Subject: [PATCH 2/3] docs: Hide `maintain_order` in `pivot` (but silently keep around for backcompat) --- narwhals/dataframe.py | 1 + 1 file changed, 1 insertion(+) diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py index 521df95e9..27ef09bce 100644 --- a/narwhals/dataframe.py +++ b/narwhals/dataframe.py @@ -2877,6 +2877,7 @@ 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 From 4c0884a50af7521e7c910d5c28079f48feab6a43 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Sun, 22 Dec 2024 11:28:48 +0000 Subject: [PATCH 3/3] cover it --- narwhals/dataframe.py | 7 +++++-- tests/frame/pivot_test.py | 3 ++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py index 27ef09bce..f174ea896 100644 --- a/narwhals/dataframe.py +++ b/narwhals/dataframe.py @@ -2930,8 +2930,11 @@ 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: # pragma: no cover - msg = "`maintain_order` has no effect and is only kept around for backwards-compatibility" + 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( 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"],