Skip to content

Commit 4517baa

Browse files
MarcoGorelliMarcoGorelli
authored
chore: rename changes_length to filtration (#2094)
1 parent eaaffa4 commit 4517baa

File tree

6 files changed

+34
-34
lines changed

6 files changed

+34
-34
lines changed

‎narwhals/_expression_parsing.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -331,8 +331,8 @@ class ExprKind(Enum):
331331
332332
Commutative composition rules are:
333333
- LITERAL vs LITERAL -> LITERAL
334-
- CHANGES_LENGTH vs (LITERAL | AGGREGATION) -> CHANGES_LENGTH
335-
- CHANGES_LENGTH vs (CHANGES_LENGTH | TRANSFORM | WINDOW) -> raise
334+
- FILTRATION vs (LITERAL | AGGREGATION) -> FILTRATION
335+
- FILTRATION vs (FILTRATION | TRANSFORM | WINDOW) -> raise
336336
- (TRANSFORM | WINDOW) vs (LITERAL | AGGREGATION) -> TRANSFORM
337337
- AGGREGATION vs (LITERAL | AGGREGATION) -> AGGREGATION
338338
"""
@@ -358,7 +358,7 @@ class ExprKind(Enum):
358358
- `nw.col('a').cum_sum().mean()`
359359
"""
360360

361-
CHANGES_LENGTH = auto()
361+
FILTRATION = auto()
362362
"""e.g. `nw.col('a').drop_nulls()`"""
363363

364364
def preserves_length(self) -> bool:
@@ -367,8 +367,8 @@ def preserves_length(self) -> bool:
367367
def is_window(self) -> bool:
368368
return self is ExprKind.WINDOW
369369

370-
def is_changes_length(self) -> bool:
371-
return self is ExprKind.CHANGES_LENGTH
370+
def is_filtration(self) -> bool:
371+
return self is ExprKind.FILTRATION
372372

373373
def is_scalar_like(self) -> bool:
374374
return is_scalar_like(self)
@@ -420,7 +420,7 @@ def selector() -> ExprMetadata:
420420
def combine_metadata(*args: IntoExpr | object | None, str_as_lit: bool) -> ExprMetadata:
421421
# Combine metadata from `args`.
422422

423-
n_changes_length = 0
423+
n_filtrations = 0
424424
has_transforms_or_windows = False
425425
has_aggregations = False
426426
has_literals = False
@@ -437,8 +437,8 @@ def combine_metadata(*args: IntoExpr | object | None, str_as_lit: bool) -> ExprM
437437
has_aggregations = True
438438
elif kind is ExprKind.LITERAL:
439439
has_literals = True
440-
elif kind is ExprKind.CHANGES_LENGTH:
441-
n_changes_length += 1
440+
elif kind is ExprKind.FILTRATION:
441+
n_filtrations += 1
442442
elif kind.preserves_length():
443443
has_transforms_or_windows = True
444444
else: # pragma: no cover
@@ -448,17 +448,17 @@ def combine_metadata(*args: IntoExpr | object | None, str_as_lit: bool) -> ExprM
448448
has_literals
449449
and not has_aggregations
450450
and not has_transforms_or_windows
451-
and not n_changes_length
451+
and not n_filtrations
452452
):
453453
result_kind = ExprKind.LITERAL
454-
elif n_changes_length > 1:
454+
elif n_filtrations > 1:
455455
msg = "Length-changing expressions can only be used in isolation, or followed by an aggregation"
456456
raise LengthChangingExprError(msg)
457-
elif n_changes_length and has_transforms_or_windows:
457+
elif n_filtrations and has_transforms_or_windows:
458458
msg = "Cannot combine length-changing expressions with length-preserving ones or aggregations"
459459
raise ShapeError(msg)
460-
elif n_changes_length:
461-
result_kind = ExprKind.CHANGES_LENGTH
460+
elif n_filtrations:
461+
result_kind = ExprKind.FILTRATION
462462
elif has_transforms_or_windows:
463463
result_kind = ExprKind.TRANSFORM
464464
else:

‎narwhals/dataframe.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2212,7 +2212,7 @@ def _extract_compliant(self: Self, arg: Any) -> Any:
22122212
" `over` and they will be supported."
22132213
)
22142214
raise OrderDependentExprError(msg)
2215-
if arg._metadata.kind.is_changes_length():
2215+
if arg._metadata.kind.is_filtration():
22162216
msg = (
22172217
"Length-changing expressions are not supported for use in LazyFrame, unless\n"
22182218
"followed by an aggregation.\n\n"

‎narwhals/expr.py‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -649,7 +649,7 @@ def map_batches(
649649
function=function, return_dtype=return_dtype
650650
),
651651
# safest assumptions
652-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
652+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
653653
)
654654

655655
def skew(self: Self) -> Self:
@@ -869,7 +869,7 @@ def unique(self: Self) -> Self:
869869
"""
870870
return self.__class__(
871871
lambda plx: self._to_compliant_expr(plx).unique(),
872-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
872+
self._metadata.with_kind(ExprKind.FILTRATION),
873873
)
874874

875875
def abs(self: Self) -> Self:
@@ -1233,7 +1233,7 @@ def filter(self: Self, *predicates: Any) -> Self:
12331233
str_as_lit=False,
12341234
),
12351235
combine_metadata(self, *flat_predicates, str_as_lit=False).with_kind(
1236-
ExprKind.CHANGES_LENGTH
1236+
ExprKind.FILTRATION
12371237
),
12381238
)
12391239

@@ -1321,7 +1321,7 @@ def arg_true(self: Self) -> Self:
13211321
issue_deprecation_warning(msg, _version="1.23.0")
13221322
return self.__class__(
13231323
lambda plx: self._to_compliant_expr(plx).arg_true(),
1324-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1324+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
13251325
)
13261326

13271327
def fill_null(
@@ -1449,7 +1449,7 @@ def drop_nulls(self: Self) -> Self:
14491449
"""
14501450
return self.__class__(
14511451
lambda plx: self._to_compliant_expr(plx).drop_nulls(),
1452-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
1452+
self._metadata.with_kind(ExprKind.FILTRATION),
14531453
)
14541454

14551455
def sample(
@@ -1490,7 +1490,7 @@ def sample(
14901490
lambda plx: self._to_compliant_expr(plx).sample(
14911491
n, fraction=fraction, with_replacement=with_replacement, seed=seed
14921492
),
1493-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
1493+
self._metadata.with_kind(ExprKind.FILTRATION),
14941494
)
14951495

14961496
def over(
@@ -1535,7 +1535,7 @@ def over(
15351535
|2 4 y 4|
15361536
└────────────────────────────┘
15371537
"""
1538-
if self._metadata.kind.is_changes_length():
1538+
if self._metadata.kind.is_filtration():
15391539
msg = "`.over()` can not be used for expressions which change length."
15401540
raise LengthChangingExprError(msg)
15411541
kind = ExprKind.TRANSFORM
@@ -1754,7 +1754,7 @@ def head(self: Self, n: int = 10) -> Self:
17541754
issue_deprecation_warning(msg, _version="1.22.0")
17551755
return self.__class__(
17561756
lambda plx: self._to_compliant_expr(plx).head(n),
1757-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1757+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
17581758
)
17591759

17601760
def tail(self: Self, n: int = 10) -> Self:
@@ -1782,7 +1782,7 @@ def tail(self: Self, n: int = 10) -> Self:
17821782
issue_deprecation_warning(msg, _version="1.22.0")
17831783
return self.__class__(
17841784
lambda plx: self._to_compliant_expr(plx).tail(n),
1785-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1785+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
17861786
)
17871787

17881788
def round(self: Self, decimals: int = 0) -> Self:
@@ -1877,7 +1877,7 @@ def gather_every(self: Self, n: int, offset: int = 0) -> Self:
18771877
issue_deprecation_warning(msg, _version="1.22.0")
18781878
return self.__class__(
18791879
lambda plx: self._to_compliant_expr(plx).gather_every(n=n, offset=offset),
1880-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1880+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
18811881
)
18821882

18831883
# need to allow numeric typing
@@ -1949,7 +1949,7 @@ def mode(self: Self) -> Self:
19491949
"""
19501950
return self.__class__(
19511951
lambda plx: self._to_compliant_expr(plx).mode(),
1952-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
1952+
self._metadata.with_kind(ExprKind.FILTRATION),
19531953
)
19541954

19551955
def is_finite(self: Self) -> Self:

‎narwhals/expr_cat.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,5 +65,5 @@ def get_categories(self: Self) -> ExprT:
6565
"""
6666
return self._expr.__class__(
6767
lambda plx: self._expr._to_compliant_expr(plx).cat.get_categories(),
68-
self._expr._metadata.with_kind(ExprKind.CHANGES_LENGTH),
68+
self._expr._metadata.with_kind(ExprKind.FILTRATION),
6969
)

‎narwhals/stable/v1/__init__.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ def _extract_compliant(self: Self, arg: Any) -> Any:
268268
msg = "Mixing Series with LazyFrame is not supported."
269269
raise TypeError(msg)
270270
if isinstance(arg, Expr):
271-
# After stable.v1, we raise if arg._is_order_dependent or arg._changes_length
271+
# After stable.v1, we raise for order-dependent exprs or filtrations
272272
return arg._to_compliant_expr(self.__narwhals_namespace__())
273273
if isinstance(arg, str):
274274
plx = self.__narwhals_namespace__()
@@ -968,7 +968,7 @@ def head(self: Self, n: int = 10) -> Self:
968968
"""
969969
return self.__class__(
970970
lambda plx: self._to_compliant_expr(plx).head(n),
971-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
971+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
972972
)
973973

974974
def tail(self: Self, n: int = 10) -> Self:
@@ -982,7 +982,7 @@ def tail(self: Self, n: int = 10) -> Self:
982982
"""
983983
return self.__class__(
984984
lambda plx: self._to_compliant_expr(plx).tail(n),
985-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
985+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
986986
)
987987

988988
def gather_every(self: Self, n: int, offset: int = 0) -> Self:
@@ -997,7 +997,7 @@ def gather_every(self: Self, n: int, offset: int = 0) -> Self:
997997
"""
998998
return self.__class__(
999999
lambda plx: self._to_compliant_expr(plx).gather_every(n=n, offset=offset),
1000-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1000+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
10011001
)
10021002

10031003
def unique(self: Self, *, maintain_order: bool | None = None) -> Self:
@@ -1019,7 +1019,7 @@ def unique(self: Self, *, maintain_order: bool | None = None) -> Self:
10191019
warn(message=msg, category=UserWarning, stacklevel=find_stacklevel())
10201020
return self.__class__(
10211021
lambda plx: self._to_compliant_expr(plx).unique(),
1022-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
1022+
self._metadata.with_kind(ExprKind.FILTRATION),
10231023
)
10241024

10251025
def sort(self: Self, *, descending: bool = False, nulls_last: bool = False) -> Self:
@@ -1047,7 +1047,7 @@ def arg_true(self: Self) -> Self:
10471047
"""
10481048
return self.__class__(
10491049
lambda plx: self._to_compliant_expr(plx).arg_true(),
1050-
self._metadata.with_kind_and_extra_open_window(ExprKind.CHANGES_LENGTH),
1050+
self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
10511051
)
10521052

10531053
def sample(
@@ -1081,7 +1081,7 @@ def sample(
10811081
lambda plx: self._to_compliant_expr(plx).sample(
10821082
n, fraction=fraction, with_replacement=with_replacement, seed=seed
10831083
),
1084-
self._metadata.with_kind(ExprKind.CHANGES_LENGTH),
1084+
self._metadata.with_kind(ExprKind.FILTRATION),
10851085
)
10861086

10871087

‎tests/frame/select_test.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ def test_alias_invalid(constructor: Constructor) -> None:
143143
df.lazy().select(nw.all().alias("c")).collect()
144144

145145

146-
def test_changes_length_vs_aggregation(constructor_eager: ConstructorEager) -> None:
146+
def test_filtration_vs_aggregation(constructor_eager: ConstructorEager) -> None:
147147
df = nw.from_native(constructor_eager({"a": [1, None, 3]}))
148148
result = df.select(nw.col("a").drop_nulls(), b=nw.col("a").mean())
149149
expected: dict[str, Any] = {"a": [1, 3], "b": [2.0, 2.0]}

0 commit comments

Comments
 (0)