Merge remote-tracking branch 'upstream/main' into more-dedup-1

dangotbanned · dangotbanned · commit 3da91c4d13d6 · 2025-03-01T18:42:50.000Z
diff --git a/docs/backcompat.md b/docs/backcompat.md
@@ -113,6 +113,8 @@ before making any change.
 
 The following are differences between the main Narwhals namespace and `narwhals.stable.v1`:
 
+- Since Narwhals 1.29.0, `LazyFrame.gather_every` has been deprecated from the main namespace.
+
 - Since Narwhals 1.24.1, an empty or all-null object-dtype pandas Series is inferred to
   be of dtype `String`. Previously, it would have been inferred as `Object`.
 
diff --git a/narwhals/_arrow/dataframe.py b/narwhals/_arrow/dataframe.py
@@ -469,7 +469,7 @@ def drop(self: Self, columns: list[str], strict: bool) -> Self:  # noqa: FBT001
             self._native_frame.drop(to_drop), validate_column_names=False
         )
 
-    def drop_nulls(self: Self, subset: list[str] | None) -> ArrowDataFrame:
+    def drop_nulls(self: ArrowDataFrame, subset: list[str] | None) -> ArrowDataFrame:
         if subset is None:
             return self._from_native_frame(
                 self._native_frame.drop_null(), validate_column_names=False
@@ -745,7 +745,7 @@ def is_unique(self: Self) -> ArrowSeries:
         )
 
     def unique(
-        self: Self,
+        self: ArrowDataFrame,
         subset: list[str] | None,
         *,
         keep: Literal["any", "first", "last", "none"],
diff --git a/narwhals/_dask/dataframe.py b/narwhals/_dask/dataframe.py
@@ -29,7 +29,6 @@
     from narwhals._dask.expr import DaskExpr
     from narwhals._dask.group_by import DaskLazyGroupBy
     from narwhals._dask.namespace import DaskNamespace
-    from narwhals._polars.dataframe import PolarsDataFrame
     from narwhals.dtypes import DType
     from narwhals.utils import Version
 
@@ -90,7 +89,7 @@ def collect(
         self: Self,
         backend: Implementation | None,
         **kwargs: Any,
-    ) -> CompliantDataFrame[Any] | PolarsDataFrame:
+    ) -> CompliantDataFrame[Any]:
         import pandas as pd
 
         result = self._native_frame.compute(**kwargs)
diff --git a/narwhals/_duckdb/dataframe.py b/narwhals/_duckdb/dataframe.py
@@ -35,7 +35,6 @@
     from narwhals._duckdb.group_by import DuckDBGroupBy
     from narwhals._duckdb.namespace import DuckDBNamespace
     from narwhals._duckdb.series import DuckDBInterchangeSeries
-    from narwhals._polars.dataframe import PolarsDataFrame
     from narwhals.dtypes import DType
 
 from narwhals.typing import CompliantLazyFrame
@@ -90,7 +89,7 @@ def collect(
         self: Self,
         backend: ModuleType | Implementation | str | None,
         **kwargs: Any,
-    ) -> CompliantDataFrame[Any] | PolarsDataFrame:
+    ) -> CompliantDataFrame[Any]:
         if backend is None or backend is Implementation.PYARROW:
             import pyarrow as pa  # ignore-banned-import
 
diff --git a/narwhals/_pandas_like/dataframe.py b/narwhals/_pandas_like/dataframe.py
@@ -48,7 +48,6 @@
     from narwhals._pandas_like.expr import PandasLikeExpr
     from narwhals._pandas_like.group_by import PandasLikeGroupBy
     from narwhals._pandas_like.namespace import PandasLikeNamespace
-    from narwhals._polars.dataframe import PolarsDataFrame
     from narwhals.dtypes import DType
     from narwhals.typing import SizeUnit
     from narwhals.typing import _1DArray
@@ -397,7 +396,9 @@ def simple_select(self: Self, *column_names: str) -> Self:
             validate_column_names=False,
         )
 
-    def aggregate(self: Self, *exprs: PandasLikeExpr) -> PandasLikeDataFrame:
+    def aggregate(
+        self: PandasLikeDataFrame, *exprs: PandasLikeExpr
+    ) -> PandasLikeDataFrame:
         return self.select(*exprs)
 
     def select(self: PandasLikeDataFrame, *exprs: PandasLikeExpr) -> PandasLikeDataFrame:
@@ -415,7 +416,9 @@ def select(self: PandasLikeDataFrame, *exprs: PandasLikeExpr) -> PandasLikeDataF
         )
         return self._from_native_frame(df, validate_column_names=True)
 
-    def drop_nulls(self: Self, subset: list[str] | None) -> PandasLikeDataFrame:
+    def drop_nulls(
+        self: PandasLikeDataFrame, subset: list[str] | None
+    ) -> PandasLikeDataFrame:
         if subset is None:
             return self._from_native_frame(
                 self._native_frame.dropna(axis=0), validate_column_names=False
@@ -533,7 +536,7 @@ def collect(
         self: Self,
         backend: Implementation | None,
         **kwargs: Any,
-    ) -> CompliantDataFrame[Any] | PolarsDataFrame:
+    ) -> CompliantDataFrame[Any]:
         if backend is None:
             return PandasLikeDataFrame(
                 self._native_frame,
diff --git a/narwhals/_polars/dataframe.py b/narwhals/_polars/dataframe.py
@@ -474,7 +474,7 @@ def collect(
         self: Self,
         backend: Implementation | None,
         **kwargs: Any,
-    ) -> PolarsDataFrame | CompliantDataFrame[Any]:
+    ) -> CompliantDataFrame[Any]:
         try:
             result = self._native_frame.collect(**kwargs)
         except Exception as e:  # noqa: BLE001
diff --git a/narwhals/_polars/series.py b/narwhals/_polars/series.py
@@ -115,6 +115,9 @@ def dtype(self: Self) -> DType:
             self._native_series.dtype, self._version, self._backend_version
         )
 
+    def alias(self, name: str) -> Self:
+        return self._from_native_object(self._native_series.alias(name))
+
     @overload
     def __getitem__(self: Self, item: int) -> Any: ...
 
diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
@@ -34,6 +34,7 @@
 from narwhals.utils import flatten
 from narwhals.utils import generate_repr
 from narwhals.utils import is_sequence_but_not_str
+from narwhals.utils import issue_deprecation_warning
 from narwhals.utils import parse_version
 
 if TYPE_CHECKING:
@@ -201,21 +202,22 @@ def filter(
             and isinstance(predicates[0], list)
             and all(isinstance(x, bool) for x in predicates[0])
         ):
+            from narwhals.functions import col
+
             flat_predicates = flatten(predicates)
             check_expressions_preserve_length(*flat_predicates, function_name="filter")
-            compliant_predicates, _kinds = self._flatten_and_extract(*flat_predicates)
             plx = self.__narwhals_namespace__()
+            compliant_predicates, _kinds = self._flatten_and_extract(*flat_predicates)
+            compliant_constraints = (
+                (col(name) == v)._to_compliant_expr(plx)
+                for name, v in constraints.items()
+            )
             predicate = plx.all_horizontal(
-                *chain(
-                    compliant_predicates,
-                    (plx.col(name) == v for name, v in constraints.items()),
-                )
+                *chain(compliant_predicates, compliant_constraints)
             )
         else:
             predicate = predicates[0]
-        return self._from_compliant_dataframe(
-            self._compliant_frame.filter(predicate),
-        )
+        return self._from_compliant_dataframe(self._compliant_frame.filter(predicate))
 
     def sort(
         self: Self,
@@ -3140,13 +3142,25 @@ def lazy(self: Self) -> Self:
     def gather_every(self: Self, n: int, offset: int = 0) -> Self:
         r"""Take every nth row in the DataFrame and return as a new DataFrame.
 
+        !!! warning
+            `LazyFrame.gather_every` is deprecated and will be removed in a future version.
+            Note: this will remain available in `narwhals.stable.v1`.
+            See [stable api](../backcompat.md/) for more information.
+
         Arguments:
             n: Gather every *n*-th row.
             offset: Starting index.
 
         Returns:
             The LazyFrame containing only the selected rows.
         """
+        msg = (
+            "`LazyFrame.gather_every` is deprecated and will be removed in a future version.\n\n"
+            "Note: this will remain available in `narwhals.stable.v1`.\n"
+            "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
+        )
+        issue_deprecation_warning(msg, _version="1.29.0")
+
         return super().gather_every(n=n, offset=offset)
 
     def unpivot(
diff --git a/narwhals/expr.py b/narwhals/expr.py
@@ -1096,7 +1096,7 @@ def sort(self: Self, *, descending: bool = False, nulls_last: bool = False) -> S
             "Note: this will remain available in `narwhals.stable.v1`.\n"
             "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
         )
-        issue_deprecation_warning(msg, _version="1.22.0")
+        issue_deprecation_warning(msg, _version="1.23.0")
         return self.__class__(
             lambda plx: self._to_compliant_expr(plx).sort(
                 descending=descending, nulls_last=nulls_last
@@ -1485,7 +1485,7 @@ def sample(
             "Note: this will remain available in `narwhals.stable.v1`.\n"
             "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
         )
-        issue_deprecation_warning(msg, _version="1.22.0")
+        issue_deprecation_warning(msg, _version="1.23.0")
         return self.__class__(
             lambda plx: self._to_compliant_expr(plx).sample(
                 n, fraction=fraction, with_replacement=with_replacement, seed=seed
@@ -1753,7 +1753,7 @@ def head(self: Self, n: int = 10) -> Self:
             "Note: this will remain available in `narwhals.stable.v1`.\n"
             "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
         )
-        issue_deprecation_warning(msg, _version="1.22.0")
+        issue_deprecation_warning(msg, _version="1.23.0")
         return self.__class__(
             lambda plx: self._to_compliant_expr(plx).head(n),
             self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
@@ -1781,7 +1781,7 @@ def tail(self: Self, n: int = 10) -> Self:
             "Note: this will remain available in `narwhals.stable.v1`.\n"
             "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
         )
-        issue_deprecation_warning(msg, _version="1.22.0")
+        issue_deprecation_warning(msg, _version="1.23.0")
         return self.__class__(
             lambda plx: self._to_compliant_expr(plx).tail(n),
             self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
@@ -1876,7 +1876,7 @@ def gather_every(self: Self, n: int, offset: int = 0) -> Self:
             "Note: this will remain available in `narwhals.stable.v1`.\n"
             "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
         )
-        issue_deprecation_warning(msg, _version="1.22.0")
+        issue_deprecation_warning(msg, _version="1.23.0")
         return self.__class__(
             lambda plx: self._to_compliant_expr(plx).gather_every(n=n, offset=offset),
             self._metadata.with_kind_and_extra_open_window(ExprKind.FILTRATION),
diff --git a/narwhals/stable/v1/__init__.py b/narwhals/stable/v1/__init__.py
@@ -348,6 +348,20 @@ def tail(self, n: int = 5) -> Self:  # pragma: no cover
         """
         return super().tail(n)
 
+    def gather_every(self: Self, n: int, offset: int = 0) -> Self:
+        r"""Take every nth row in the DataFrame and return as a new DataFrame.
+
+        Arguments:
+            n: Gather every *n*-th row.
+            offset: Starting index.
+
+        Returns:
+            The LazyFrame containing only the selected rows.
+        """
+        return self._from_compliant_dataframe(
+            self._compliant_frame.gather_every(n=n, offset=offset)
+        )
+
 
 class Series(NwSeries[IntoSeriesT]):
     """Narwhals Series, backed by a native series.
diff --git a/narwhals/typing.py b/narwhals/typing.py
@@ -3,7 +3,6 @@
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Callable
-from typing import Generic
 from typing import Literal
 from typing import Protocol
 from typing import Sequence
@@ -69,7 +68,7 @@ def alias(self, name: str) -> Self: ...
 )
 
 
-class CompliantDataFrame(Generic[CompliantSeriesT_co], Protocol):
+class CompliantDataFrame(Protocol[CompliantSeriesT_co]):
     def __narwhals_dataframe__(self) -> Self: ...
     def __narwhals_namespace__(self) -> Any: ...
     def simple_select(
@@ -142,7 +141,7 @@ def broadcast(
     ) -> Self: ...
 
 
-class CompliantNamespace(Protocol, Generic[CompliantFrameT, CompliantSeriesT_co]):
+class CompliantNamespace(Protocol[CompliantFrameT, CompliantSeriesT_co]):
     def col(
         self, *column_names: str
     ) -> CompliantExpr[CompliantFrameT, CompliantSeriesT_co]: ...
diff --git a/narwhals/utils.py b/narwhals/utils.py
@@ -1362,7 +1362,7 @@ def _hasattr_static(obj: Any, attr: str) -> bool:
 
 
 def is_compliant_dataframe(
-    obj: Any | CompliantDataFrame[CompliantSeriesT_co],
+    obj: CompliantDataFrame[CompliantSeriesT_co] | Any,
 ) -> TypeIs[CompliantDataFrame[CompliantSeriesT_co]]:
     return _hasattr_static(obj, "__narwhals_dataframe__")
 
diff --git a/tests/expr_and_series/arg_true_test.py b/tests/expr_and_series/arg_true_test.py
@@ -14,7 +14,9 @@ def test_arg_true(constructor_eager: ConstructorEager) -> None:
     expected = {"a": [1, 2]}
     assert_equal_data(result, expected)
 
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(nw.col("a").is_null().arg_true())
 
 
diff --git a/tests/expr_and_series/gather_every_test.py b/tests/expr_and_series/gather_every_test.py
@@ -22,7 +22,9 @@ def test_gather_every_expr(
 
     assert_equal_data(result, expected)
 
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(nw_main.col("a").gather_every(n=n, offset=offset))
 
 
diff --git a/tests/expr_and_series/head_test.py b/tests/expr_and_series/head_test.py
@@ -19,7 +19,9 @@ def test_head(
     expected = {"a": [1, 2]}
     assert_equal_data(result, expected)
 
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(nw_main.col("a").head(5))
 
 
diff --git a/tests/expr_and_series/sample_test.py b/tests/expr_and_series/sample_test.py
@@ -21,7 +21,9 @@ def test_expr_sample(constructor_eager: ConstructorEager) -> None:
     expected_series = (2,)
     assert result_series == expected_series
 
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(nw_main.col("a").sample(n=2))
 
 
diff --git a/tests/expr_and_series/sort_test.py b/tests/expr_and_series/sort_test.py
@@ -30,7 +30,9 @@ def test_sort_expr(
         nw.col("b").sort(descending=descending, nulls_last=nulls_last),
     )
     assert_equal_data(result, expected)
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(
             "a",
             nw_main.col("b").sort(descending=descending, nulls_last=nulls_last),
diff --git a/tests/expr_and_series/tail_test.py b/tests/expr_and_series/tail_test.py
@@ -19,7 +19,9 @@ def test_tail(
     expected = {"a": [2, 3]}
     assert_equal_data(result, expected)
 
-    with pytest.deprecated_call():
+    with pytest.deprecated_call(
+        match="is deprecated and will be removed in a future version"
+    ):
         df.select(nw_main.col("a").tail(5))
 
 
diff --git a/tests/frame/filter_test.py b/tests/frame/filter_test.py
@@ -54,3 +54,17 @@ def test_filter_raise_on_shape_mismatch(constructor: Constructor) -> None:
     df = nw.from_native(constructor(data))
     with pytest.raises((LengthChangingExprError, ShapeError)):
         df.filter(nw.col("b").unique() > 2).lazy().collect()
+
+
+def test_filter_with_constrains(constructor: Constructor) -> None:
+    data = {"a": [1, 3, 2], "b": [4, 4, 6]}
+    df = nw.from_native(constructor(data))
+    result_scalar = df.filter(a=3)
+    expected_scalar = {"a": [3], "b": [4]}
+
+    assert_equal_data(result_scalar, expected_scalar)
+
+    result_expr = df.filter(a=nw.col("b") // 3)
+    expected_expr = {"a": [1, 2], "b": [4, 6]}
+
+    assert_equal_data(result_expr, expected_expr)
diff --git a/tests/frame/gather_every_test.py b/tests/frame/gather_every_test.py
diff --git a/tests/stable_api_test.py b/tests/stable_api_test.py

Original file line number	Diff line number	Diff line change
`@@ -115,6 +115,9 @@ def dtype(self: Self) -> DType:`
`115`	`115`	`self._native_series.dtype, self._version, self._backend_version`
`116`	`116`	`)`
`117`	`117`
	`118`	`+ def alias(self, name: str) -> Self:`
	`119`	`+ return self._from_native_object(self._native_series.alias(name))`
	`120`	`+`
`118`	`121`	`@overload`
`119`	`122`	`def __getitem__(self: Self, item: int) -> Any: ...`
`120`	`123`