feat(python)!: Only accept a single column in set_sorted (pola-rs#1…

…6800)

py-polars/polars/dataframe/frame.py

@@ -10313,26 +10313,32 @@ def merge_sorted(self, other: DataFrame, key: str) -> DataFrame:
 
     def set_sorted(
         self,
-        column: str | Iterable[str],
-        *more_columns: str,
+        column: str,
+        *,
         descending: bool = False,
     ) -> DataFrame:
         """
         Indicate that one or multiple columns are sorted.
 
+        This can speed up future operations.
+
         Parameters
         ----------
         column
-            Columns that are sorted
-        more_columns
-            Additional columns that are sorted, specified as positional arguments.
+            Column that are sorted
         descending
             Whether the columns are sorted in descending order.
+
+        Warnings
+        --------
+        This can lead to incorrect results if the data is NOT sorted!!
+        Use with care!
+
         """
+        # NOTE: Only accepts 1 column on purpose! User think they are sorted by
+        # the combined multicolumn values.
         return (
-            self.lazy()
-            .set_sorted(column, *more_columns, descending=descending)
-            .collect(_eager=True)
+            self.lazy().set_sorted(column, descending=descending).collect(_eager=True)
         )
 
     @unstable()

py-polars/polars/expr/expr.py

@@ -9833,7 +9833,7 @@ def set_sorted(self, *, descending: bool = False) -> Self:
 
         Warnings
         --------
-        This can lead to incorrect results if this `Series` is not sorted!!
+        This can lead to incorrect results if the data is NOT sorted!!
         Use with care!
 
         Examples

py-polars/polars/lazyframe/frame.py

@@ -5905,27 +5905,34 @@ def merge_sorted(self, other: LazyFrame, key: str) -> Self:
 
     def set_sorted(
         self,
-        column: str | Iterable[str],
-        *more_columns: str,
+        column: str,
+        *,
         descending: bool = False,
     ) -> Self:
         """
         Indicate that one or multiple columns are sorted.
 
+        This can speed up future operations.
+
         Parameters
         ----------
         column
             Columns that are sorted
-        more_columns
-            Additional columns that are sorted, specified as positional arguments.
         descending
             Whether the columns are sorted in descending order.
-        """
-        columns = parse_as_list_of_expressions(column, *more_columns)
 
-        return self.with_columns(
-            wrap_expr(e).set_sorted(descending=descending) for e in columns
-        )
+        Warnings
+        --------
+        This can lead to incorrect results if the data is NOT sorted!!
+        Use with care!
+
+        """
+        # NOTE: Only accepts 1 column on purpose! User think they are sorted by
+        # the combined multicolumn values.
+        if not isinstance(column, str):
+            msg = "expected a 'str' for argument 'column' in 'set_sorted'"
+            raise TypeError(msg)
+        return self.with_columns(F.col(column).set_sorted(descending=descending))
 
     @unstable()
     def update(

py-polars/tests/unit/test_errors.py

@@ -658,3 +658,10 @@ def test_raise_invalid_arithmetic() -> None:
 
     with pytest.raises(pl.InvalidOperationError):
         df.select(pl.col("a") - pl.col("a"))
+
+
+def test_raise_on_sorted_multi_args() -> None:
+    with pytest.raises(TypeError):
+        pl.DataFrame({"a": [1], "b": [1]}).set_sorted(
+            ["a", "b"]  # type: ignore[arg-type]
+        )