Replacing reverse with descending (#277)

Replacing reverse argument with descending to match py-polars and rs-polars
pola-rs · Oct 16, 2024 · 0fc9dcc · 0fc9dcc
1 parent 8ac81c6
commit 0fc9dcc
Show file tree

Hide file tree

Showing 14 changed files with 170 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ const pl = require('nodejs-polars');
 // a lot operations support both positional and named arguments
 // you can see the full specs in the docs or the type definitions
 > fooSeries.sort(true)
-> fooSeries.sort({reverse: true})
+> fooSeries.sort({descending: true})
 shape: (3,)
 Series: 'foo' [f64]
 [

diff --git a/__tests__/dataframe.test.ts b/__tests__/dataframe.test.ts
@@ -1015,7 +1015,7 @@ describe("dataframe", () => {
     expect(actual).toFrameEqual(expected);
   });
   test("sort:named", () => {
-    const actual = pl
+    let actual = pl
       .DataFrame({
         foo: [1, 2, 3, 1],
         bar: [6, 7, 8, 1],
@@ -1026,6 +1026,13 @@ describe("dataframe", () => {
       bar: [8, 7, 6, 1],
     });
     expect(actual).toFrameEqual(expected);
+    actual = pl
+      .DataFrame({
+        foo: [1, 2, 3, 1],
+        bar: [6, 7, 8, 1],
+      })
+      .sort({ by: "bar", reverse: true }); // deprecated
+    expect(actual).toFrameEqual(expected);
   });
   test("sort:multi-args", () => {
     const actual = pl
@@ -1044,23 +1051,23 @@ describe("dataframe", () => {
     });
     expect(actual).toFrameEqual(expected);
   });
-  test("sort:nulls_last:false", () => {
+  test("sort:nullsLast:false", () => {
     const actual = pl
       .DataFrame({
         foo: [1, null, 2, 3],
       })
-      .sort({ by: "foo", nulls_last: false });
+      .sort({ by: "foo", nullsLast: false });
     const expected = pl.DataFrame({
       foo: [null, 1, 2, 3],
     });
     expect(actual).toFrameEqual(expected);
   });
-  test("sort:nulls_last:true", () => {
+  test("sort:nullsLast:true", () => {
     const actual = pl
       .DataFrame({
         foo: [1, null, 2, 3],
       })
-      .sort({ by: "foo", nulls_last: true });
+      .sort({ by: "foo", nullsLast: true });
     const expected = pl.DataFrame({
       foo: [1, 2, 3, null],
     });

diff --git a/__tests__/expr.test.ts b/__tests__/expr.test.ts
@@ -71,10 +71,11 @@ describe("expr", () => {
     expect(actual).toStrictEqual(0);
   });
   test.each`
-    args                 | expectedSort
-    ${undefined}         | ${[1, 0, 3, 2]}
-    ${true}              | ${[2, 3, 0, 1]}
-    ${{ reverse: true }} | ${[2, 3, 0, 1]}
+    args                    | expectedSort
+    ${undefined}            | ${[1, 0, 3, 2]}
+    ${true}                 | ${[2, 3, 0, 1]}
+    ${{ descending: true }} | ${[2, 3, 0, 1]}
+    ${{ reverse: true }}    | ${[2, 3, 0, 1]}
   `("argSort", ({ args, expectedSort }) => {
     const df = pl.DataFrame({ a: [1, 0, 2, 1.5] });
     const expected = pl.DataFrame({ argSort: expectedSort });
@@ -845,16 +846,16 @@ describe("expr", () => {
     const b = col("b");
     const actual = df.select(
       a.sort().as("a_sorted_default"),
-      a.sort({ reverse: true }).as("a_sorted_reverse"),
+      a.sort({ descending: true }).as("a_sorted_reverse"),
       a.sort({ nullsLast: true }).as("a_sorted_nulls_last"),
       a
-        .sort({ reverse: true, nullsLast: true })
+        .sort({ descending: true, nullsLast: true })
         .as("a_sorted_reverse_nulls_last"),
       b.sort().as("b_sorted_default"),
-      b.sort({ reverse: true }).as("b_sorted_reverse"),
+      b.sort({ descending: true }).as("b_sorted_reverse"),
       b.sort({ nullsLast: true }).as("b_sorted_nulls_last"),
       b
-        .sort({ reverse: true, nullsLast: true })
+        .sort({ descending: true, nullsLast: true })
         .as("b_sorted_reverse_nulls_last"),
     );
     expect(actual).toFrameEqual(expected);
@@ -903,7 +904,7 @@ describe("expr", () => {
     const actual = df.withColumns(
       pl
         .col(["name", "value"])
-        .sortBy({ by: [pl.col("value")], reverse: [true] })
+        .sortBy({ by: [pl.col("value")], descending: [true] })
         .last()
         .over("label")
         .suffix("_min"),
@@ -1829,12 +1830,12 @@ describe("expr.lst", () => {
     });
     const actual = df.select(
       col("a").lst.sort().as("sort"),
-      col("a").lst.sort({ reverse: true }).as("sort:reverse"),
+      col("a").lst.sort({ descending: true }).as("sort:reverse"),
     );
     const sortSeries = df.getColumn("a").lst.sort().rename("sort");
     const sortReverseSeries = df
       .getColumn("a")
-      .lst.sort({ reverse: true })
+      .lst.sort({ descending: true })
       .rename("sort:reverse");
 
     const actualFromSeries = pl.DataFrame([sortSeries, sortReverseSeries]);

diff --git a/__tests__/lazyframe.test.ts b/__tests__/lazyframe.test.ts
@@ -1011,7 +1011,7 @@ describe("lazyframe", () => {
         foo: [1, null, 2, 3],
       })
       .lazy()
-      .sort({ by: "foo", nulls_last: false })
+      .sort({ by: "foo", nullsLast: false })
       .collectSync();
     const expected = pl.DataFrame({
       foo: [null, 1, 2, 3],
@@ -1024,7 +1024,7 @@ describe("lazyframe", () => {
         foo: [1, null, 2, 3],
       })
       .lazy()
-      .sort({ by: "foo", nulls_last: true })
+      .sort({ by: "foo", nullsLast: true })
       .collectSync();
     const expected = pl.DataFrame({
       foo: [1, 2, 3, null],

diff --git a/__tests__/series.test.ts b/__tests__/series.test.ts
@@ -430,8 +430,8 @@ describe("series", () => {
     ${numSeries()}  | ${"sort"}            | ${[]}
     ${numSeries()}  | ${"sort"}            | ${[false]}
     ${numSeries()}  | ${"sort"}            | ${[true]}
-    ${numSeries()}  | ${"sort"}            | ${[{ reverse: true }]}
-    ${numSeries()}  | ${"sort"}            | ${[{ reverse: false }]}
+    ${numSeries()}  | ${"sort"}            | ${[{ descending: true }]}
+    ${numSeries()}  | ${"sort"}            | ${[{ descending: false }]}
     ${numSeries()}  | ${"sum"}             | ${[]}
     ${numSeries()}  | ${"tail"}            | ${[]}
     ${numSeries()}  | ${"gather"}          | ${[[1, 2]]}
@@ -462,7 +462,7 @@ describe("series", () => {
     ${"argMax"}          | ${pl.Series([1, 2, 3]).argMax()}                                                       | ${2}
     ${"argMin"}          | ${pl.Series([1, 2, 3]).argMin()}                                                       | ${0}
     ${"argSort"}         | ${pl.Series([3, 2, 1]).argSort()}                                                      | ${pl.Series([2, 1, 0])}
-    ${"argSort"}         | ${pl.Series([null, 3, 2, 1]).argSort({ reverse: true })}                               | ${pl.Series([1, 2, 3, 0])}
+    ${"argSort"}         | ${pl.Series([null, 3, 2, 1]).argSort({ descending: true })}                            | ${pl.Series([1, 2, 3, 0])}
     ${"argTrue"}         | ${pl.Series([true, false]).argTrue()}                                                  | ${pl.Series([0])}
     ${"argUnique"}       | ${pl.Series([1, 1, 2]).argUnique()}                                                    | ${pl.Series([0, 2])}
     ${"cast-Int16"}      | ${pl.Series("", [1, 1, 2]).cast(pl.Int16)}                                             | ${pl.Series("", [1, 1, 2], pl.Int16)}

diff --git a/polars/dataframe.ts b/polars/dataframe.ts
@@ -1361,24 +1361,38 @@ export interface DataFrame
   /**
    * Sort the DataFrame by column.
    * ___
-   * @param by - By which columns to sort. Only accepts string.
+   * @param by - Column(s) to sort by. Accepts expression input, including selectors. Strings are parsed as column names.
+   * @deprecated *since 0.16.0* @use descending
    * @param reverse - Reverse/descending sort.
+   * @param descending - Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans.
+   * @param nullsLast - Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control.
+   * @param maintainOrder - Whether the order should be maintained if elements are equal.
    */
   sort(
     by: ColumnsOrExpr,
     descending?: boolean,
-    nulls_last?: boolean,
-    maintain_order?: boolean,
+    nullsLast?: boolean,
+    maintainOrder?: boolean,
   ): DataFrame;
+  sort({
+    by,
+    reverse, // deprecated
+    maintainOrder,
+  }: {
+    by: ColumnsOrExpr;
+    reverse?: boolean; // deprecated
+    nullsLast?: boolean;
+    maintainOrder?: boolean;
+  }): DataFrame;
   sort({
     by,
     descending,
-    maintain_order,
+    maintainOrder,
   }: {
     by: ColumnsOrExpr;
     descending?: boolean;
-    nulls_last?: boolean;
-    maintain_order?: boolean;
+    nullsLast?: boolean;
+    maintainOrder?: boolean;
   }): DataFrame;
   /**
    * Aggregate the columns of this DataFrame to their standard deviation value.
@@ -2360,22 +2374,22 @@ export const _DataFrame = (_df: any): DataFrame => {
       }
       return wrap("slice", opts.offset, opts.length);
     },
-    sort(arg, descending = false, nulls_last = false, maintain_order = false) {
+    sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
       if (arg?.by !== undefined) {
         return this.sort(
           arg.by,
-          arg.descending,
-          arg.nulls_last,
-          arg.maintain_order,
+          arg.descending ?? arg.reverse ?? false,
+          arg.nullsLast,
+          arg.maintainOrder,
         );
       }
       if (Array.isArray(arg) || Expr.isExpr(arg)) {
         return _DataFrame(_df)
           .lazy()
-          .sort(arg, descending, nulls_last, maintain_order)
+          .sort(arg, descending, nullsLast, maintainOrder)
           .collectSync({ noOptimization: true });
       }
-      return wrap("sort", arg, descending, nulls_last, maintain_order);
+      return wrap("sort", arg, descending, nullsLast, maintainOrder);
     },
     std() {
       return this.lazy().std().collectSync();

diff --git a/polars/lazy/dataframe.ts b/polars/lazy/dataframe.ts
@@ -420,14 +420,14 @@ export interface LazyDataFrame extends Serialize, GroupByOps<LazyGroupBy> {
   sort(
     by: ColumnsOrExpr,
     descending?: ValueOrArray<boolean>,
-    nulls_last?: boolean,
-    maintain_order?: boolean,
+    nullsLast?: boolean,
+    maintainOrder?: boolean,
   ): LazyDataFrame;
   sort(opts: {
     by: ColumnsOrExpr;
     descending?: ValueOrArray<boolean>;
-    nulls_last?: boolean;
-    maintain_order?: boolean;
+    nullsLast?: boolean;
+    maintainOrder?: boolean;
   }): LazyDataFrame;
   /**
    * @see {@link DataFrame.std}
@@ -1026,20 +1026,20 @@ export const _LazyDataFrame = (_ldf: any): LazyDataFrame => {
       }
       return _LazyDataFrame(_ldf.slice(opt, len));
     },
-    sort(arg, descending = false, nulls_last = false, maintain_order = false) {
+    sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
       if (arg?.by !== undefined) {
         return this.sort(
           arg.by,
           arg.descending,
-          arg.nulls_last,
-          arg.maintain_order,
+          arg.nullsLast,
+          arg.maintainOrder,
         );
       }
       if (typeof arg === "string") {
-        return wrap("sort", arg, descending, nulls_last, maintain_order);
+        return wrap("sort", arg, descending, nullsLast, maintainOrder);
       }
       const by = selectionToExprList(arg, false);
-      return wrap("sortByExprs", by, descending, nulls_last, maintain_order);
+      return wrap("sortByExprs", by, descending, nullsLast, maintainOrder);
     },
     std() {
       return _LazyDataFrame(_ldf.std());