feat(DRAFT): Adds (Expr|Series).first()

docs/api-reference/expr.md

@@ -23,6 +23,7 @@
         - ewm_mean
         - fill_null
         - filter
+        - first
         - gather_every
         - head
         - clip

docs/api-reference/series.md

@@ -28,6 +28,7 @@
         - ewm_mean
         - fill_null
         - filter
+        - first
         - gather_every
         - head
         - hist

narwhals/_arrow/series.py

@@ -315,6 +315,10 @@ def filter(self, predicate: ArrowSeries | list[bool | None]) -> Self:
             other_native = predicate
         return self._with_native(self.native.filter(other_native))
 
+    def first(self, *, _return_py_scalar: bool = True) -> Any:
+        result = self.native[0] if len(self.native) else None
+        return maybe_extract_py_scalar(result, _return_py_scalar)
+
     def mean(self, *, _return_py_scalar: bool = True) -> float:
         return maybe_extract_py_scalar(pc.mean(self.native), _return_py_scalar)
 

narwhals/_compliant/expr.py

@@ -160,6 +160,7 @@ def cum_max(self, *, reverse: bool) -> Self: ...
     def cum_prod(self, *, reverse: bool) -> Self: ...
     def is_in(self, other: Any) -> Self: ...
     def sort(self, *, descending: bool, nulls_last: bool) -> Self: ...
+    def first(self) -> Self: ...
     def rank(self, method: RankMethod, *, descending: bool) -> Self: ...
     def replace_strict(
         self,
@@ -851,6 +852,9 @@ def func(df: EagerDataFrameT) -> Sequence[EagerSeriesT]:
             context=self,
         )
 
+    def first(self) -> Self:
+        return self._reuse_series("first", returns_scalar=True)
+
     @property
     def cat(self) -> EagerExprCatNamespace[Self]:
         return EagerExprCatNamespace(self)

narwhals/_compliant/series.py

@@ -177,6 +177,7 @@ def fill_null(
         limit: int | None,
     ) -> Self: ...
     def filter(self, predicate: Any) -> Self: ...
+    def first(self) -> Any: ...
     def gather_every(self, n: int, offset: int) -> Self: ...
     @unstable
     def hist(

narwhals/_dask/expr.py

@@ -663,6 +663,12 @@ def is_finite(self) -> Self:
 
         return self._with_callable(da.isfinite, "is_finite")
 
+    def first(self) -> Self:
+        def fn(_input: dx.Series) -> dx.Series:
+            return _input[0].to_series()
+
+        return self._with_callable(fn, "first")
+
     @property
     def str(self) -> DaskExprStringNamespace:
         return DaskExprStringNamespace(self)

narwhals/_duckdb/expr.py

@@ -408,6 +408,12 @@ def _clip_both(
             _clip_both, lower_bound=lower_bound, upper_bound=upper_bound
         )
 
+    def first(self) -> Self:
+        def fn(_input: duckdb.Expression) -> duckdb.Expression:
+            return FunctionExpression("first", _input)
+
+        return self._with_callable(fn)
+
     def sum(self) -> Self:
         return self._with_callable(lambda _input: FunctionExpression("sum", _input))
 

narwhals/_pandas_like/series.py

@@ -381,6 +381,9 @@ def filter(self, predicate: Any) -> PandasLikeSeries:
             other_native = predicate
         return self._with_native(self.native.loc[other_native]).alias(self.name)
 
+    def first(self) -> Any:
+        return self.native.iloc[0] if len(self.native) else None
+
     def __eq__(self, other: object) -> PandasLikeSeries:  # type: ignore[override]
         ser, other = align_and_extract_native(self, other)
         return self._with_native(ser == other).alias(self.name)

narwhals/_polars/expr.py

@@ -281,6 +281,7 @@ def struct(self) -> PolarsExprStructNamespace:
     diff: Method[Self]
     drop_nulls: Method[Self]
     fill_null: Method[Self]
+    first: Method[Self]
     gather_every: Method[Self]
     head: Method[Self]
     is_finite: Method[Self]

narwhals/_polars/series.py

@@ -611,6 +611,13 @@ def hist(  # noqa: C901, PLR0912
     def to_polars(self) -> pl.Series:
         return self.native
 
+    def first(self) -> Any:
+        if self._backend_version >= (1, 10):
+            return self.native.first()
+        elif len(self):  # pragma: no cover
+            return self.native.item(0)
+        return None  # pragma: no cover
+
     @property
     def dt(self) -> PolarsSeriesDateTimeNamespace:
         return PolarsSeriesDateTimeNamespace(self)

narwhals/_spark_like/expr.py

@@ -560,6 +560,14 @@ def _clip_both(
             _clip_both, lower_bound=lower_bound, upper_bound=upper_bound
         )
 
+    def first(self) -> Self:
+        def fn(inputs: WindowInputs) -> Column:
+            return self._F.first(inputs.expr, ignorenulls=False).over(
+                self.partition_by(inputs).orderBy(*self._sort(inputs))
+            )
+
+        return self._with_window_function(fn)
+
     def is_finite(self) -> Self:
         def _is_finite(_input: Column) -> Column:
             # A value is finite if it's not NaN, and not infinite, while NULLs should be

narwhals/expr.py

@@ -1965,6 +1965,16 @@ def clip(
             ),
         )
 
+    def first(self) -> Self:
+        """Get the first value.
+
+        Returns:
+            A new expression.
+        """
+        return self._with_orderable_aggregation(
+            lambda plx: self._to_compliant_expr(plx).first()
+        )
+
     def mode(self) -> Self:
         r"""Compute the most occurring value(s).
 

narwhals/series.py

@@ -801,6 +801,25 @@ def clip(
             )
         )
 
+    def first(self) -> Any:
+        """Get the first element of the Series.
+
+        Returns:
+            A scalar value or `None` if the Series is empty.
+
+        Examples:
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>>
+            >>> s_native = pl.Series([1, 2, 3])
+            >>> s_nw = nw.from_native(s_native, series_only=True)
+            >>> s_nw.first()
+            1
+            >>> s_nw.filter(s_nw > 5).first() is None
+            True
+        """
+        return self._compliant_series.first()
+
     def is_in(self, other: Any) -> Self:
         """Check if the elements of this Series are in the other sequence.
 

tests/expr_and_series/first_test.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Mapping
+from typing import Sequence
+
+import pytest
+
+import narwhals as nw
+from tests.utils import assert_equal_data
+
+if TYPE_CHECKING:
+    from narwhals.typing import PythonLiteral
+    from tests.utils import ConstructorEager
+
+data = {
+    "a": [8, 2, 1, None],
+    "b": [58, 5, 6, 12],
+    "c": [2.5, 1.0, 3.0, 0.9],
+    "d": [2, 1, 4, 3],
+}
+
+
+@pytest.mark.parametrize(("col", "expected"), [("a", 8), ("b", 58), ("c", 2.5)])
+def test_first_series(
+    constructor_eager: ConstructorEager, col: str, expected: PythonLiteral
+) -> None:
+    series = nw.from_native(constructor_eager(data), eager_only=True)[col]
+    result = series.first()
+    assert_equal_data({col: [result]}, {col: [expected]})
+
+
+def test_first_series_empty(constructor_eager: ConstructorEager) -> None:
+    series = nw.from_native(constructor_eager(data), eager_only=True)["a"]
+    series = series.filter(series > 50)
+    result = series.first()
+    assert result is None
+
+
+@pytest.mark.parametrize(("col", "expected"), [("a", 8), ("b", 58), ("c", 2.5)])
+def test_first_expr_eager(
+    constructor_eager: ConstructorEager, col: str, expected: PythonLiteral
+) -> None:
+    df = nw.from_native(constructor_eager(data))
+    expr = nw.col(col).first()
+    result = df.select(expr)
+    assert_equal_data(result, {col: [expected]})
+
+
+@pytest.mark.parametrize(
+    "expected",
+    [{"a": [8], "c": [2.5]}, {"d": [2], "b": [58]}, {"c": [2.5], "a": [8], "d": [2]}],
+)
+def test_first_expr_eager_expand(
+    constructor_eager: ConstructorEager, expected: Mapping[str, Sequence[PythonLiteral]]
+) -> None:
+    df = nw.from_native(constructor_eager(data))
+    expr = nw.col(expected).first()
+    result = df.select(expr)
+    assert_equal_data(result, expected)
+
+
+def test_first_expr_eager_expand_sort(constructor_eager: ConstructorEager) -> None:
+    df = nw.from_native(constructor_eager(data))
+    expr = nw.col("d", "a", "b", "c").first()
+    result = df.sort("d").select(expr)
+    expected = {"d": [1], "a": [2], "b": [5], "c": [1.0]}
+    assert_equal_data(result, expected)