feat: add list.contains (#2942)

raisadz · MarcoGorelli · web-flow · commit bfd31c4def15 · 2025-08-08T16:33:33.000+01:00
---------

Co-authored-by: Marco Edward Gorelli &lt;33491632+MarcoGorelli@users.noreply.github.com&gt;
diff --git a/docs/api-reference/expr_list.md b/docs/api-reference/expr_list.md
@@ -4,6 +4,7 @@
     handler: python
     options:
       members:
+        - contains
         - len
         - unique
       show_source: false
diff --git a/docs/api-reference/series_list.md b/docs/api-reference/series_list.md
@@ -4,6 +4,7 @@
     handler: python
     options:
       members:
+        - contains
         - len
         - unique
       show_source: false
diff --git a/narwhals/_arrow/series_list.py b/narwhals/_arrow/series_list.py
@@ -17,3 +17,4 @@ def len(self) -> ArrowSeries:
         return self.with_native(pc.list_value_length(self.native).cast(pa.uint32()))
 
     unique = not_implemented()
+    contains = not_implemented()
diff --git a/narwhals/_compliant/any_namespace.py b/narwhals/_compliant/any_namespace.py
@@ -9,7 +9,7 @@
 if TYPE_CHECKING:
     from typing import Callable
 
-    from narwhals.typing import TimeUnit
+    from narwhals.typing import NonNestedLiteral, TimeUnit
 
 __all__ = [
     "CatNamespace",
@@ -54,6 +54,7 @@ def offset_by(self, by: str) -> CompliantT_co: ...
 class ListNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
     def len(self) -> CompliantT_co: ...
     def unique(self) -> CompliantT_co: ...
+    def contains(self, item: NonNestedLiteral) -> CompliantT_co: ...
 
 
 class NameNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
diff --git a/narwhals/_compliant/expr.py b/narwhals/_compliant/expr.py
@@ -1062,6 +1062,9 @@ def len(self) -> EagerExprT:
     def unique(self) -> EagerExprT:
         return self.compliant._reuse_series_namespace("list", "unique")
 
+    def contains(self, item: NonNestedLiteral) -> EagerExprT:
+        return self.compliant._reuse_series_namespace("list", "contains", item=item)
+
 
 class CompliantExprNameNamespace(  # type: ignore[misc]
     _ExprNamespace[CompliantExprT_co],
diff --git a/narwhals/_duckdb/expr_list.py b/narwhals/_duckdb/expr_list.py
@@ -10,6 +10,7 @@
     from duckdb import Expression
 
     from narwhals._duckdb.expr import DuckDBExpr
+    from narwhals.typing import NonNestedLiteral
 
 
 class DuckDBExprListNamespace(
@@ -27,3 +28,8 @@ def func(expr: Expression) -> Expression:
             ).otherwise(expr_distinct)
 
         return self.compliant._with_callable(func)
+
+    def contains(self, item: NonNestedLiteral) -> DuckDBExpr:
+        return self.compliant._with_elementwise(
+            lambda expr: F("list_contains", expr, lit(item))
+        )
diff --git a/narwhals/_ibis/expr_list.py b/narwhals/_ibis/expr_list.py
@@ -7,6 +7,7 @@
 
 if TYPE_CHECKING:
     from narwhals._ibis.expr import IbisExpr
+    from narwhals.typing import NonNestedLiteral
 
 
 class IbisExprListNamespace(LazyExprNamespace["IbisExpr"], ListNamespace["IbisExpr"]):
@@ -15,3 +16,6 @@ def len(self) -> IbisExpr:
 
     def unique(self) -> IbisExpr:
         return self.compliant._with_callable(lambda expr: expr.unique())
+
+    def contains(self, item: NonNestedLiteral) -> IbisExpr:
+        return self.compliant._with_callable(lambda expr: expr.contains(item))
diff --git a/narwhals/_pandas_like/series_list.py b/narwhals/_pandas_like/series_list.py
@@ -33,3 +33,4 @@ def len(self) -> PandasLikeSeries:
         return self.with_native(result.astype(dtype)).alias(self.native.name)
 
     unique = not_implemented()
+    contains = not_implemented()
diff --git a/narwhals/_polars/expr.py b/narwhals/_polars/expr.py
@@ -415,6 +415,15 @@ def len(self) -> PolarsExpr:
 
         return self.compliant._with_native(native_result)
 
+    def contains(self, item: Any) -> PolarsExpr:
+        if self.compliant._backend_version < (1, 28):
+            result: pl.Expr = pl.when(self.native.is_not_null()).then(
+                self.native.list.contains(item)
+            )
+        else:
+            result = self.native.list.contains(item)
+        return self.compliant._with_native(result)
+
 
 class PolarsExprStructNamespace(
     PolarsExprNamespace, PolarsStructNamespace[PolarsExpr, pl.Expr]
diff --git a/narwhals/_polars/series.py b/narwhals/_polars/series.py
@@ -36,7 +36,13 @@
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dtypes import DType
     from narwhals.series import Series
-    from narwhals.typing import Into1DArray, IntoDType, MultiIndexSelector, _1DArray
+    from narwhals.typing import (
+        Into1DArray,
+        IntoDType,
+        MultiIndexSelector,
+        NonNestedLiteral,
+        _1DArray,
+    )
 
     T = TypeVar("T")
     IncludeBreakpoint: TypeAlias = Literal[False, True]
@@ -737,6 +743,11 @@ def len(self) -> PolarsSeries:
         ns = self.__narwhals_namespace__()
         return self.to_frame().select(ns.col(name).list.len()).get_column(name)
 
+    def contains(self, item: NonNestedLiteral) -> PolarsSeries:
+        name = self.name
+        ns = self.__narwhals_namespace__()
+        return self.to_frame().select(ns.col(name).list.contains(item)).get_column(name)
+
 
 class PolarsSeriesStructNamespace(
     PolarsSeriesNamespace, PolarsStructNamespace[PolarsSeries, pl.Series]
diff --git a/narwhals/_spark_like/expr_list.py b/narwhals/_spark_like/expr_list.py
@@ -6,7 +6,10 @@
 from narwhals._compliant.any_namespace import ListNamespace
 
 if TYPE_CHECKING:
+    from sqlframe.base.column import Column
+
     from narwhals._spark_like.expr import SparkLikeExpr
+    from narwhals.typing import NonNestedLiteral
 
 
 class SparkLikeExprListNamespace(
@@ -17,3 +20,10 @@ def len(self) -> SparkLikeExpr:
 
     def unique(self) -> SparkLikeExpr:
         return self.compliant._with_elementwise(self.compliant._F.array_distinct)
+
+    def contains(self, item: NonNestedLiteral) -> SparkLikeExpr:
+        def func(expr: Column) -> Column:
+            F = self.compliant._F  # noqa: N806
+            return F.array_contains(expr, F.lit(item))
+
+        return self.compliant._with_elementwise(func)
diff --git a/narwhals/expr_list.py b/narwhals/expr_list.py
@@ -4,6 +4,7 @@
 
 if TYPE_CHECKING:
     from narwhals.expr import Expr
+    from narwhals.typing import NonNestedLiteral
 
 ExprT = TypeVar("ExprT", bound="Expr")
 
@@ -79,3 +80,37 @@ def unique(self) -> ExprT:
         return self._expr._with_elementwise(
             lambda plx: self._expr._to_compliant_expr(plx).list.unique()
         )
+
+    def contains(self, item: NonNestedLiteral) -> ExprT:
+        """Check if sublists contain the given item.
+
+        Arguments:
+            item: Item that will be checked for membership.
+
+        Returns:
+            A new expression.
+
+        Examples:
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> df_native = pl.DataFrame({"a": [[1, 2], None, []]})
+            >>> df = nw.from_native(df_native)
+            >>> df.with_columns(a_contains_1=nw.col("a").list.contains(1))
+            ┌────────────────────────────┐
+            |     Narwhals DataFrame     |
+            |----------------------------|
+            |shape: (3, 2)               |
+            |┌───────────┬──────────────┐|
+            |│ a         ┆ a_contains_1 │|
+            |│ ---       ┆ ---          │|
+            |│ list[i64] ┆ bool         │|
+            |╞═══════════╪══════════════╡|
+            |│ [1, 2]    ┆ true         │|
+            |│ null      ┆ null         │|
+            |│ []        ┆ false        │|
+            |└───────────┴──────────────┘|
+            └────────────────────────────┘
+        """
+        return self._expr._with_elementwise(
+            lambda plx: self._expr._to_compliant_expr(plx).list.contains(item)
+        )
diff --git a/narwhals/series_list.py b/narwhals/series_list.py
@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from typing import Generic
+from typing import TYPE_CHECKING, Generic
 
 from narwhals.typing import SeriesT
 
+if TYPE_CHECKING:
+    from narwhals.typing import NonNestedLiteral
+
 
 class SeriesListNamespace(Generic[SeriesT]):
     def __init__(self, series: SeriesT) -> None:
@@ -63,3 +66,30 @@ def unique(self) -> SeriesT:
         return self._narwhals_series._with_compliant(
             self._narwhals_series._compliant_series.list.unique()
         )
+
+    def contains(self, item: NonNestedLiteral) -> SeriesT:
+        """Check if sublists contain the given item.
+
+        Arguments:
+            item: Item that will be checked for membership.
+
+        Returns:
+            A new expression.
+
+        Examples:
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> s_native = pl.Series([[1, 2], None, []])
+            >>> s = nw.from_native(s_native, series_only=True)
+            >>> s.list.contains(1).to_native()  # doctest: +NORMALIZE_WHITESPACE
+            shape: (3,)
+            Series: '' [bool]
+            [
+                    true
+                    null
+                    false
+            ]
+        """
+        return self._narwhals_series._with_compliant(
+            self._narwhals_series._compliant_series.list.contains(item)
+        )
diff --git a/tests/expr_and_series/list/contains_test.py b/tests/expr_and_series/list/contains_test.py
@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+import narwhals as nw
+from tests.utils import assert_equal_data
+
+if TYPE_CHECKING:
+    from tests.utils import Constructor, ConstructorEager
+
+data = {"a": [[2, 2, 3, None, None], None, []]}
+expected = {"a": [True, None, False]}
+
+
+def test_contains_expr(request: pytest.FixtureRequest, constructor: Constructor) -> None:
+    if any(
+        backend in str(constructor)
+        for backend in ("dask", "modin", "cudf", "pyarrow", "pandas")
+    ):
+        request.applymarker(pytest.mark.xfail)
+    result = nw.from_native(constructor(data)).select(
+        nw.col("a").cast(nw.List(nw.Int32())).list.contains(2)
+    )
+    assert_equal_data(result, expected)
+
+
+def test_contains_series(
+    request: pytest.FixtureRequest, constructor_eager: ConstructorEager
+) -> None:
+    if any(
+        backend in str(constructor_eager)
+        for backend in ("modin", "cudf", "pyarrow", "pandas")
+    ):
+        request.applymarker(pytest.mark.xfail)
+    df = nw.from_native(constructor_eager(data), eager_only=True)
+    result = df["a"].cast(nw.List(nw.Int32())).list.contains(2)
+    assert_equal_data({"a": result}, expected)

Original file line number	Diff line number	Diff line change
`@@ -17,3 +17,4 @@ def len(self) -> ArrowSeries:`
`17`	`17`	`return self.with_native(pc.list_value_length(self.native).cast(pa.uint32()))`
`18`	`18`
`19`	`19`	`unique = not_implemented()`
	`20`	`+ contains = not_implemented()`
Original file line number	Diff line number	Diff line change
`@@ -33,3 +33,4 @@ def len(self) -> PandasLikeSeries:`
`33`	`33`	`return self.with_native(result.astype(dtype)).alias(self.native.name)`
`34`	`34`
`35`	`35`	`unique = not_implemented()`
	`36`	`+ contains = not_implemented()`