Skip to content

Commit 0fc9dcc

Browse files
Bidek56Bidek56
authored
Replacing reverse with descending (pola-rs#277)
Replacing reverse argument with descending to match py-polars and rs-polars
1 parent 8ac81c6 commit 0fc9dcc

14 files changed

+170
-102
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ const pl = require('nodejs-polars');
4242
// a lot operations support both positional and named arguments
4343
// you can see the full specs in the docs or the type definitions
4444
> fooSeries.sort(true)
45-
> fooSeries.sort({reverse: true})
45+
> fooSeries.sort({descending: true})
4646
shape: (3,)
4747
Series: 'foo' [f64]
4848
[

‎__tests__/dataframe.test.ts

+12-5
Original file line numberDiff line numberDiff line change
@@ -1015,7 +1015,7 @@ describe("dataframe", () => {
10151015
expect(actual).toFrameEqual(expected);
10161016
});
10171017
test("sort:named", () => {
1018-
const actual = pl
1018+
let actual = pl
10191019
.DataFrame({
10201020
foo: [1, 2, 3, 1],
10211021
bar: [6, 7, 8, 1],
@@ -1026,6 +1026,13 @@ describe("dataframe", () => {
10261026
bar: [8, 7, 6, 1],
10271027
});
10281028
expect(actual).toFrameEqual(expected);
1029+
actual = pl
1030+
.DataFrame({
1031+
foo: [1, 2, 3, 1],
1032+
bar: [6, 7, 8, 1],
1033+
})
1034+
.sort({ by: "bar", reverse: true }); // deprecated
1035+
expect(actual).toFrameEqual(expected);
10291036
});
10301037
test("sort:multi-args", () => {
10311038
const actual = pl
@@ -1044,23 +1051,23 @@ describe("dataframe", () => {
10441051
});
10451052
expect(actual).toFrameEqual(expected);
10461053
});
1047-
test("sort:nulls_last:false", () => {
1054+
test("sort:nullsLast:false", () => {
10481055
const actual = pl
10491056
.DataFrame({
10501057
foo: [1, null, 2, 3],
10511058
})
1052-
.sort({ by: "foo", nulls_last: false });
1059+
.sort({ by: "foo", nullsLast: false });
10531060
const expected = pl.DataFrame({
10541061
foo: [null, 1, 2, 3],
10551062
});
10561063
expect(actual).toFrameEqual(expected);
10571064
});
1058-
test("sort:nulls_last:true", () => {
1065+
test("sort:nullsLast:true", () => {
10591066
const actual = pl
10601067
.DataFrame({
10611068
foo: [1, null, 2, 3],
10621069
})
1063-
.sort({ by: "foo", nulls_last: true });
1070+
.sort({ by: "foo", nullsLast: true });
10641071
const expected = pl.DataFrame({
10651072
foo: [1, 2, 3, null],
10661073
});

‎__tests__/expr.test.ts

+12-11
Original file line numberDiff line numberDiff line change
@@ -71,10 +71,11 @@ describe("expr", () => {
7171
expect(actual).toStrictEqual(0);
7272
});
7373
test.each`
74-
args | expectedSort
75-
${undefined} | ${[1, 0, 3, 2]}
76-
${true} | ${[2, 3, 0, 1]}
77-
${{ reverse: true }} | ${[2, 3, 0, 1]}
74+
args | expectedSort
75+
${undefined} | ${[1, 0, 3, 2]}
76+
${true} | ${[2, 3, 0, 1]}
77+
${{ descending: true }} | ${[2, 3, 0, 1]}
78+
${{ reverse: true }} | ${[2, 3, 0, 1]}
7879
`("argSort", ({ args, expectedSort }) => {
7980
const df = pl.DataFrame({ a: [1, 0, 2, 1.5] });
8081
const expected = pl.DataFrame({ argSort: expectedSort });
@@ -845,16 +846,16 @@ describe("expr", () => {
845846
const b = col("b");
846847
const actual = df.select(
847848
a.sort().as("a_sorted_default"),
848-
a.sort({ reverse: true }).as("a_sorted_reverse"),
849+
a.sort({ descending: true }).as("a_sorted_reverse"),
849850
a.sort({ nullsLast: true }).as("a_sorted_nulls_last"),
850851
a
851-
.sort({ reverse: true, nullsLast: true })
852+
.sort({ descending: true, nullsLast: true })
852853
.as("a_sorted_reverse_nulls_last"),
853854
b.sort().as("b_sorted_default"),
854-
b.sort({ reverse: true }).as("b_sorted_reverse"),
855+
b.sort({ descending: true }).as("b_sorted_reverse"),
855856
b.sort({ nullsLast: true }).as("b_sorted_nulls_last"),
856857
b
857-
.sort({ reverse: true, nullsLast: true })
858+
.sort({ descending: true, nullsLast: true })
858859
.as("b_sorted_reverse_nulls_last"),
859860
);
860861
expect(actual).toFrameEqual(expected);
@@ -903,7 +904,7 @@ describe("expr", () => {
903904
const actual = df.withColumns(
904905
pl
905906
.col(["name", "value"])
906-
.sortBy({ by: [pl.col("value")], reverse: [true] })
907+
.sortBy({ by: [pl.col("value")], descending: [true] })
907908
.last()
908909
.over("label")
909910
.suffix("_min"),
@@ -1829,12 +1830,12 @@ describe("expr.lst", () => {
18291830
});
18301831
const actual = df.select(
18311832
col("a").lst.sort().as("sort"),
1832-
col("a").lst.sort({ reverse: true }).as("sort:reverse"),
1833+
col("a").lst.sort({ descending: true }).as("sort:reverse"),
18331834
);
18341835
const sortSeries = df.getColumn("a").lst.sort().rename("sort");
18351836
const sortReverseSeries = df
18361837
.getColumn("a")
1837-
.lst.sort({ reverse: true })
1838+
.lst.sort({ descending: true })
18381839
.rename("sort:reverse");
18391840

18401841
const actualFromSeries = pl.DataFrame([sortSeries, sortReverseSeries]);

‎__tests__/lazyframe.test.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -1011,7 +1011,7 @@ describe("lazyframe", () => {
10111011
foo: [1, null, 2, 3],
10121012
})
10131013
.lazy()
1014-
.sort({ by: "foo", nulls_last: false })
1014+
.sort({ by: "foo", nullsLast: false })
10151015
.collectSync();
10161016
const expected = pl.DataFrame({
10171017
foo: [null, 1, 2, 3],
@@ -1024,7 +1024,7 @@ describe("lazyframe", () => {
10241024
foo: [1, null, 2, 3],
10251025
})
10261026
.lazy()
1027-
.sort({ by: "foo", nulls_last: true })
1027+
.sort({ by: "foo", nullsLast: true })
10281028
.collectSync();
10291029
const expected = pl.DataFrame({
10301030
foo: [1, 2, 3, null],

‎__tests__/series.test.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -430,8 +430,8 @@ describe("series", () => {
430430
${numSeries()} | ${"sort"} | ${[]}
431431
${numSeries()} | ${"sort"} | ${[false]}
432432
${numSeries()} | ${"sort"} | ${[true]}
433-
${numSeries()} | ${"sort"} | ${[{ reverse: true }]}
434-
${numSeries()} | ${"sort"} | ${[{ reverse: false }]}
433+
${numSeries()} | ${"sort"} | ${[{ descending: true }]}
434+
${numSeries()} | ${"sort"} | ${[{ descending: false }]}
435435
${numSeries()} | ${"sum"} | ${[]}
436436
${numSeries()} | ${"tail"} | ${[]}
437437
${numSeries()} | ${"gather"} | ${[[1, 2]]}
@@ -462,7 +462,7 @@ describe("series", () => {
462462
${"argMax"} | ${pl.Series([1, 2, 3]).argMax()} | ${2}
463463
${"argMin"} | ${pl.Series([1, 2, 3]).argMin()} | ${0}
464464
${"argSort"} | ${pl.Series([3, 2, 1]).argSort()} | ${pl.Series([2, 1, 0])}
465-
${"argSort"} | ${pl.Series([null, 3, 2, 1]).argSort({ reverse: true })} | ${pl.Series([1, 2, 3, 0])}
465+
${"argSort"} | ${pl.Series([null, 3, 2, 1]).argSort({ descending: true })} | ${pl.Series([1, 2, 3, 0])}
466466
${"argTrue"} | ${pl.Series([true, false]).argTrue()} | ${pl.Series([0])}
467467
${"argUnique"} | ${pl.Series([1, 1, 2]).argUnique()} | ${pl.Series([0, 2])}
468468
${"cast-Int16"} | ${pl.Series("", [1, 1, 2]).cast(pl.Int16)} | ${pl.Series("", [1, 1, 2], pl.Int16)}

‎polars/dataframe.ts

+26-12
Original file line numberDiff line numberDiff line change
@@ -1361,24 +1361,38 @@ export interface DataFrame
13611361
/**
13621362
* Sort the DataFrame by column.
13631363
* ___
1364-
* @param by - By which columns to sort. Only accepts string.
1364+
* @param by - Column(s) to sort by. Accepts expression input, including selectors. Strings are parsed as column names.
1365+
* @deprecated *since 0.16.0* @use descending
13651366
* @param reverse - Reverse/descending sort.
1367+
* @param descending - Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans.
1368+
* @param nullsLast - Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control.
1369+
* @param maintainOrder - Whether the order should be maintained if elements are equal.
13661370
*/
13671371
sort(
13681372
by: ColumnsOrExpr,
13691373
descending?: boolean,
1370-
nulls_last?: boolean,
1371-
maintain_order?: boolean,
1374+
nullsLast?: boolean,
1375+
maintainOrder?: boolean,
13721376
): DataFrame;
1377+
sort({
1378+
by,
1379+
reverse, // deprecated
1380+
maintainOrder,
1381+
}: {
1382+
by: ColumnsOrExpr;
1383+
reverse?: boolean; // deprecated
1384+
nullsLast?: boolean;
1385+
maintainOrder?: boolean;
1386+
}): DataFrame;
13731387
sort({
13741388
by,
13751389
descending,
1376-
maintain_order,
1390+
maintainOrder,
13771391
}: {
13781392
by: ColumnsOrExpr;
13791393
descending?: boolean;
1380-
nulls_last?: boolean;
1381-
maintain_order?: boolean;
1394+
nullsLast?: boolean;
1395+
maintainOrder?: boolean;
13821396
}): DataFrame;
13831397
/**
13841398
* Aggregate the columns of this DataFrame to their standard deviation value.
@@ -2360,22 +2374,22 @@ export const _DataFrame = (_df: any): DataFrame => {
23602374
}
23612375
return wrap("slice", opts.offset, opts.length);
23622376
},
2363-
sort(arg, descending = false, nulls_last = false, maintain_order = false) {
2377+
sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
23642378
if (arg?.by !== undefined) {
23652379
return this.sort(
23662380
arg.by,
2367-
arg.descending,
2368-
arg.nulls_last,
2369-
arg.maintain_order,
2381+
arg.descending ?? arg.reverse ?? false,
2382+
arg.nullsLast,
2383+
arg.maintainOrder,
23702384
);
23712385
}
23722386
if (Array.isArray(arg) || Expr.isExpr(arg)) {
23732387
return _DataFrame(_df)
23742388
.lazy()
2375-
.sort(arg, descending, nulls_last, maintain_order)
2389+
.sort(arg, descending, nullsLast, maintainOrder)
23762390
.collectSync({ noOptimization: true });
23772391
}
2378-
return wrap("sort", arg, descending, nulls_last, maintain_order);
2392+
return wrap("sort", arg, descending, nullsLast, maintainOrder);
23792393
},
23802394
std() {
23812395
return this.lazy().std().collectSync();

‎polars/lazy/dataframe.ts

+9-9
Original file line numberDiff line numberDiff line change
@@ -420,14 +420,14 @@ export interface LazyDataFrame extends Serialize, GroupByOps<LazyGroupBy> {
420420
sort(
421421
by: ColumnsOrExpr,
422422
descending?: ValueOrArray<boolean>,
423-
nulls_last?: boolean,
424-
maintain_order?: boolean,
423+
nullsLast?: boolean,
424+
maintainOrder?: boolean,
425425
): LazyDataFrame;
426426
sort(opts: {
427427
by: ColumnsOrExpr;
428428
descending?: ValueOrArray<boolean>;
429-
nulls_last?: boolean;
430-
maintain_order?: boolean;
429+
nullsLast?: boolean;
430+
maintainOrder?: boolean;
431431
}): LazyDataFrame;
432432
/**
433433
* @see {@link DataFrame.std}
@@ -1026,20 +1026,20 @@ export const _LazyDataFrame = (_ldf: any): LazyDataFrame => {
10261026
}
10271027
return _LazyDataFrame(_ldf.slice(opt, len));
10281028
},
1029-
sort(arg, descending = false, nulls_last = false, maintain_order = false) {
1029+
sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
10301030
if (arg?.by !== undefined) {
10311031
return this.sort(
10321032
arg.by,
10331033
arg.descending,
1034-
arg.nulls_last,
1035-
arg.maintain_order,
1034+
arg.nullsLast,
1035+
arg.maintainOrder,
10361036
);
10371037
}
10381038
if (typeof arg === "string") {
1039-
return wrap("sort", arg, descending, nulls_last, maintain_order);
1039+
return wrap("sort", arg, descending, nullsLast, maintainOrder);
10401040
}
10411041
const by = selectionToExprList(arg, false);
1042-
return wrap("sortByExprs", by, descending, nulls_last, maintain_order);
1042+
return wrap("sortByExprs", by, descending, nullsLast, maintainOrder);
10431043
},
10441044
std() {
10451045
return _LazyDataFrame(_ldf.std());

0 commit comments

Comments
 (0)