depr(python): Rename parameter descending to reverse in top_k m…

…ethods

py-polars/polars/dataframe/frame.py

@@ -4720,18 +4720,19 @@ def sql(self, query: str, *, table_name: str = "self") -> Self:
             ctx.register(name=name, frame=self)
             return ctx.execute(query)  # type: ignore[return-value]
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def top_k(
         self,
         k: int,
         *,
         by: IntoExpr | Iterable[IntoExpr],
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> DataFrame:
         """
         Return the `k` largest rows.
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -4742,7 +4743,7 @@ def top_k(
         by
             Column(s) used to determine the top rows.
             Accepts expression input. Strings are parsed as column names.
-        descending
+        reverse
             Consider the `k` smallest elements of the `by` column(s) (instead of the `k`
             largest). This can be specified per column by passing a sequence of
             booleans.
@@ -4792,7 +4793,7 @@ def top_k(
         """
         return (
             self.lazy()
-            .top_k(k, by=by, descending=descending)
+            .top_k(k, by=by, reverse=reverse)
             .collect(
                 projection_pushdown=False,
                 predicate_pushdown=False,
@@ -4801,18 +4802,19 @@ def top_k(
             )
         )
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def bottom_k(
         self,
         k: int,
         *,
         by: IntoExpr | Iterable[IntoExpr],
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> DataFrame:
         """
         Return the `k` smallest rows.
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -4823,7 +4825,7 @@ def bottom_k(
         by
             Column(s) used to determine the bottom rows.
             Accepts expression input. Strings are parsed as column names.
-        descending
+        reverse
             Consider the `k` largest elements of the `by` column(s) (instead of the `k`
             smallest). This can be specified per column by passing a sequence of
             booleans.
@@ -4873,7 +4875,7 @@ def bottom_k(
         """
         return (
             self.lazy()
-            .bottom_k(k, by=by, descending=descending)
+            .bottom_k(k, by=by, reverse=reverse)
             .collect(
                 projection_pushdown=False,
                 predicate_pushdown=False,

py-polars/polars/expr/expr.py

@@ -26,7 +26,11 @@
 import polars._reexport as pl
 from polars import functions as F
 from polars._utils.convert import negate_duration_string, parse_as_duration_string
-from polars._utils.deprecation import deprecate_function, issue_deprecation_warning
+from polars._utils.deprecation import (
+    deprecate_function,
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 from polars._utils.parse_expr_input import (
     parse_as_expression,
     parse_as_list_of_expressions,
@@ -1876,18 +1880,19 @@ def top_k(self, k: int | IntoExprColumn = 5) -> Self:
         k = parse_as_expression(k)
         return self._from_pyexpr(self._pyexpr.top_k(k))
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def top_k_by(
         self,
         by: IntoExpr | Iterable[IntoExpr],
         k: int | IntoExprColumn = 5,
         *,
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> Self:
         r"""
         Return the elements corresponding to the `k` largest elements of the `by` column(s).
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -1902,7 +1907,7 @@ def top_k_by(
             Accepts expression input. Strings are parsed as column names.
         k
             Number of elements to return.
-        descending
+        reverse
             Consider the `k` smallest elements of the `by` column(s) (instead of the `k`
             largest). This can be specified per column by passing a sequence of
             booleans.
@@ -1995,8 +2000,8 @@ def top_k_by(
         """  # noqa: W505
         k = parse_as_expression(k)
         by = parse_as_list_of_expressions(by)
-        descending = extend_bool(descending, len(by), "descending", "by")
-        return self._from_pyexpr(self._pyexpr.top_k_by(by, k=k, descending=descending))
+        reverse = extend_bool(reverse, len(by), "reverse", "by")
+        return self._from_pyexpr(self._pyexpr.top_k_by(by, k=k, reverse=reverse))
 
     def bottom_k(self, k: int | IntoExprColumn = 5) -> Self:
         r"""
@@ -2048,18 +2053,19 @@ def bottom_k(self, k: int | IntoExprColumn = 5) -> Self:
         k = parse_as_expression(k)
         return self._from_pyexpr(self._pyexpr.bottom_k(k))
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def bottom_k_by(
         self,
         by: IntoExpr | Iterable[IntoExpr],
         k: int | IntoExprColumn = 5,
         *,
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> Self:
         r"""
         Return the elements corresponding to the `k` smallest elements of the `by` column(s).
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -2074,7 +2080,7 @@ def bottom_k_by(
             Accepts expression input. Strings are parsed as column names.
         k
             Number of elements to return.
-        descending
+        reverse
             Consider the `k` largest elements of the `by` column(s) (instead of the `k`
             smallest). This can be specified per column by passing a sequence of
             booleans.
@@ -2167,10 +2173,8 @@ def bottom_k_by(
         """  # noqa: W505
         k = parse_as_expression(k)
         by = parse_as_list_of_expressions(by)
-        descending = extend_bool(descending, len(by), "descending", "by")
-        return self._from_pyexpr(
-            self._pyexpr.bottom_k_by(by, k=k, descending=descending)
-        )
+        reverse = extend_bool(reverse, len(by), "reverse", "by")
+        return self._from_pyexpr(self._pyexpr.bottom_k_by(by, k=k, reverse=reverse))
 
     def arg_sort(self, *, descending: bool = False, nulls_last: bool = False) -> Self:
         """

py-polars/polars/lazyframe/frame.py

@@ -1371,18 +1371,19 @@ def sql(self, query: str, *, table_name: str = "self") -> Self:
             ctx.register(name=name, frame=self)
             return ctx.execute(query)  # type: ignore[return-value]
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def top_k(
         self,
         k: int,
         *,
         by: IntoExpr | Iterable[IntoExpr],
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> Self:
         """
         Return the `k` largest rows.
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -1393,7 +1394,7 @@ def top_k(
         by
             Column(s) used to determine the top rows.
             Accepts expression input. Strings are parsed as column names.
-        descending
+        reverse
             Consider the `k` smallest elements of the `by` column(s) (instead of the `k`
             largest). This can be specified per column by passing a sequence of
             booleans.
@@ -1442,21 +1443,22 @@ def top_k(
         └─────┴─────┘
         """
         by = parse_as_list_of_expressions(by)
-        descending = extend_bool(descending, len(by), "descending", "by")
-        return self._from_pyldf(self._ldf.top_k(k, by=by, descending=descending))
+        reverse = extend_bool(reverse, len(by), "reverse", "by")
+        return self._from_pyldf(self._ldf.top_k(k, by=by, reverse=reverse))
 
+    @deprecate_renamed_parameter("descending", "reverse", version="1.0.0")
     def bottom_k(
         self,
         k: int,
         *,
         by: IntoExpr | Iterable[IntoExpr],
-        descending: bool | Sequence[bool] = False,
+        reverse: bool | Sequence[bool] = False,
     ) -> Self:
         """
         Return the `k` smallest rows.
 
         Non-null elements are always preferred over null elements, regardless of
-        the value of `descending`. The output is not guaranteed to be in any
+        the value of `reverse`. The output is not guaranteed to be in any
         particular order, call :func:`sort` after this function if you wish the
         output to be sorted.
 
@@ -1467,7 +1469,7 @@ def bottom_k(
         by
             Column(s) used to determine the bottom rows.
             Accepts expression input. Strings are parsed as column names.
-        descending
+        reverse
             Consider the `k` largest elements of the `by` column(s) (instead of the `k`
             smallest). This can be specified per column by passing a sequence of
             booleans.
@@ -1516,8 +1518,8 @@ def bottom_k(
         └─────┴─────┘
         """
         by = parse_as_list_of_expressions(by)
-        descending = extend_bool(descending, len(by), "descending", "by")
-        return self._from_pyldf(self._ldf.bottom_k(k, by=by, descending=descending))
+        reverse = extend_bool(reverse, len(by), "reverse", "by")
+        return self._from_pyldf(self._ldf.bottom_k(k, by=by, reverse=reverse))
 
     def profile(
         self,

py-polars/src/expr/general.rs

@@ -304,9 +304,9 @@ impl PyExpr {
     }
 
     #[cfg(feature = "top_k")]
-    fn top_k_by(&self, by: Vec<Self>, k: Self, descending: Vec<bool>) -> Self {
+    fn top_k_by(&self, by: Vec<Self>, k: Self, reverse: Vec<bool>) -> Self {
         let by = by.into_iter().map(|e| e.inner).collect::<Vec<_>>();
-        self.inner.clone().top_k_by(k.inner, by, descending).into()
+        self.inner.clone().top_k_by(k.inner, by, reverse).into()
     }
 
     #[cfg(feature = "top_k")]
@@ -315,12 +315,9 @@ impl PyExpr {
     }
 
     #[cfg(feature = "top_k")]
-    fn bottom_k_by(&self, by: Vec<Self>, k: Self, descending: Vec<bool>) -> Self {
+    fn bottom_k_by(&self, by: Vec<Self>, k: Self, reverse: Vec<bool>) -> Self {
         let by = by.into_iter().map(|e| e.inner).collect::<Vec<_>>();
-        self.inner
-            .clone()
-            .bottom_k_by(k.inner, by, descending)
-            .into()
+        self.inner.clone().bottom_k_by(k.inner, by, reverse).into()
     }
 
     #[cfg(feature = "peaks")]

py-polars/src/lazyframe/mod.rs

@@ -555,24 +555,24 @@ impl PyLazyFrame {
         .into()
     }
 
-    fn top_k(&self, k: IdxSize, by: Vec<PyExpr>, descending: Vec<bool>) -> Self {
+    fn top_k(&self, k: IdxSize, by: Vec<PyExpr>, reverse: Vec<bool>) -> Self {
         let ldf = self.ldf.clone();
         let exprs = by.to_exprs();
         ldf.top_k(
             k,
             exprs,
-            SortMultipleOptions::new().with_order_descending_multi(descending),
+            SortMultipleOptions::new().with_order_descending_multi(reverse),
         )
         .into()
     }
 
-    fn bottom_k(&self, k: IdxSize, by: Vec<PyExpr>, descending: Vec<bool>) -> Self {
+    fn bottom_k(&self, k: IdxSize, by: Vec<PyExpr>, reverse: Vec<bool>) -> Self {
         let ldf = self.ldf.clone();
         let exprs = by.to_exprs();
         ldf.bottom_k(
             k,
             exprs,
-            SortMultipleOptions::new().with_order_descending_multi(descending),
+            SortMultipleOptions::new().with_order_descending_multi(reverse),
         )
         .into()
     }