feat: add DataFrame.equals and Series.equals

docs/api-reference/dataframe.md

@@ -11,6 +11,7 @@
         - columns
         - drop
         - drop_nulls
+        - equals
         - estimated_size
         - explode
         - filter

docs/api-reference/series.md

@@ -28,6 +28,7 @@
         - diff
         - drop_nulls
         - dtype
+        - equals
         - ewm_mean
         - exp
         - fill_nan

src/narwhals/_arrow/dataframe.py

@@ -350,6 +350,21 @@ def schema(self) -> dict[str, DType]:
     def collect_schema(self) -> dict[str, DType]:
         return self.schema
 
+    def equals(self, other: Self, *, null_equal: bool) -> bool:
+        if self.shape != other.shape:
+            return False
+        if self.columns != other.columns:
+            return False
+        return all(
+            self.get_column(name).equals(
+                other.get_column(name),
+                check_dtypes=False,
+                check_names=False,
+                null_equal=null_equal,
+            )
+            for name in self.columns
+        )
+
     def estimated_size(self, unit: SizeUnit) -> int | float:
         sz = self.native.nbytes
         return scale_bytes(sz, unit)

src/narwhals/_arrow/series.py

@@ -553,6 +553,26 @@ def cast(self, dtype: IntoDType) -> Self:
     def null_count(self, *, _return_py_scalar: bool = True) -> int:
         return maybe_extract_py_scalar(self.native.null_count, _return_py_scalar)
 
+    def equals(
+        self, other: Self, *, check_dtypes: bool, check_names: bool, null_equal: bool
+    ) -> bool:
+        if check_names and self._name != other._name:
+            return False
+        if check_dtypes and self.dtype != other.dtype:
+            return False
+        if len(self) != len(other):
+            return False
+        lhs = self.native
+        rhs = other.native
+        if null_equal:
+            both_null = pc.and_(pc.is_null(lhs), pc.is_null(rhs))
+            values_equal = pc.equal(lhs, rhs)
+            result = pc.if_else(both_null, True, values_equal)
+            return bool(pc.all(result, skip_nulls=False).as_py())
+        if lhs.null_count or rhs.null_count:
+            return False
+        return bool(pc.all(pc.equal(lhs, rhs)).as_py())
+
     def head(self, n: int) -> Self:
         if n >= 0:
             return self._with_native(self.native.slice(0, n))

src/narwhals/_compliant/dataframe.py

@@ -227,6 +227,7 @@ def __getitem__(
     @property
     def shape(self) -> tuple[int, int]: ...
     def clone(self) -> Self: ...
+    def equals(self, other: Self, *, null_equal: bool) -> bool: ...
     def estimated_size(self, unit: SizeUnit) -> int | float: ...
     def gather_every(self, n: int, offset: int) -> Self: ...
     def get_column(self, name: str) -> CompliantSeriesT: ...

src/narwhals/_compliant/series.py

@@ -133,6 +133,9 @@ def arg_max(self) -> int: ...
     def arg_min(self) -> int: ...
     def arg_true(self) -> Self: ...
     def count(self) -> int: ...
+    def equals(
+        self, other: Self, *, check_dtypes: bool, check_names: bool, null_equal: bool
+    ) -> bool: ...
     def filter(self, predicate: Any) -> Self: ...
     def first(self) -> PythonLiteral: ...
     def last(self) -> PythonLiteral: ...

src/narwhals/_pandas_like/dataframe.py

@@ -465,6 +465,15 @@ def drop_nulls(self, subset: Sequence[str] | None) -> Self:
         mask = ~plx.any_horizontal(plx.col(*subset).is_null(), ignore_nulls=True)
         return self.filter(mask)
 
+    def equals(self, other: Self, *, null_equal: bool) -> bool:
+        if self.shape != other.shape:
+            return False  # not needed but can short-circuit the isna() scan below
+        if not null_equal and (
+            self.native.isna().any(axis=None) or other.native.isna().any(axis=None)
+        ):
+            return False
+        return self.native.equals(other.native)
+
     def estimated_size(self, unit: SizeUnit) -> int | float:
         sz = self.native.memory_usage(deep=True).sum()
         return scale_bytes(sz, unit=unit)

src/narwhals/_pandas_like/series.py

@@ -1219,6 +1219,25 @@ def struct(self) -> PandasLikeSeriesStructNamespace:
             raise TypeError(msg)
         return PandasLikeSeriesStructNamespace(self)
 
+    def equals(
+        self, other: Self, *, check_dtypes: bool, check_names: bool, null_equal: bool
+    ) -> bool:
+        if check_names and self._name != other._name:
+            return False
+        if check_dtypes and self.dtype != other.dtype:
+            return False
+        if not null_equal:
+            if len(self) != len(other):
+                return False  # not needed but can short-circuit the isna() checks below
+            if self.native.isna().any() or other.native.isna().any():
+                return False
+        other_native = (
+            other.native.astype(self.native.dtype)
+            if not check_dtypes and self.native.dtype != other.native.dtype
+            else other.native
+        )
+        return self.native.equals(other_native)
+
 
 class _PandasHist(EagerSeriesHist["pd.Series[Any]", "list[float]"]):
     _series: PandasLikeSeries

src/narwhals/_polars/dataframe.py

@@ -78,6 +78,7 @@
     [
         "clone",
         "drop_nulls",
+        "equals",
         "estimated_size",
         "explode",
         "filter",
@@ -108,6 +109,7 @@
 
 class PolarsBaseFrame(Generic[NativePolarsFrame]):
     drop_nulls: Method[Self]
+    equals: Method[bool]
     explode: Method[Self]
     filter: Method[Self]
     gather_every: Method[Self]

src/narwhals/_polars/series.py

@@ -92,6 +92,7 @@
         "cum_sum",
         "diff",
         "drop_nulls",
+        "equals",
         "exp",
         "fill_null",
         "fill_nan",
@@ -720,6 +721,7 @@ def struct(self) -> PolarsSeriesStructNamespace:
     cum_sum: Method[Self]
     diff: Method[Self]
     drop_nulls: Method[Self]
+    equals: Method[bool]
     exp: Method[Self]
     fill_null: Method[Self]
     fill_nan: Method[Self]

src/narwhals/dataframe.py

@@ -1295,6 +1295,9 @@ def drop_nulls(self, subset: str | list[str] | None = None) -> Self:
         """
         return super().drop_nulls(subset=subset)
 
+    def equals(self, other: Self, *, null_equal: bool = True) -> bool:
+        return self._compliant_frame.equals(other._compliant_frame, null_equal=null_equal)
+
     def with_row_index(
         self, name: str = "index", *, order_by: str | Sequence[str] | None = None
     ) -> Self:

src/narwhals/series.py

@@ -2942,3 +2942,18 @@ def list(self) -> SeriesListNamespace[Self]:
     @property
     def struct(self) -> SeriesStructNamespace[Self]:
         return SeriesStructNamespace(self)
+
+    def equals(
+        self,
+        other: Self,
+        *,
+        check_dtypes: bool = False,
+        check_names: bool = False,
+        null_equal: bool = True,
+    ) -> bool:
+        return self._compliant_series.equals(
+            other._compliant_series,
+            check_dtypes=check_dtypes,
+            check_names=check_names,
+            null_equal=null_equal,
+        )

tests/series_only/equals_test.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+import narwhals as nw
+
+if TYPE_CHECKING:
+    from tests.utils import ConstructorEager
+
+TBD = None
+_NAN_HANDLING = pytest.mark.xfail(
+    strict=True, reason="NaN/null disambiguation not yet decided"
+)
+_CROSS_TYPE = pytest.mark.xfail(
+    strict=True, reason="Inconsistent behavior across backends for incompatible types"
+)
+_DTYPE_INFERENCE = pytest.mark.xfail(
+    strict=True,
+    reason="Constructor dtype inference is backend-dependent for whole-number floats",
+)
+_CHECK_NAMES = pytest.mark.xfail(
+    strict=True,
+    reason=(
+        "Bare ChunkedArray carries no name metadata, resulting in empty names - "
+        "TBD whether check_names=True should raise for pyarrow in case of empty names"
+    ),
+)
+
+
+@pytest.mark.parametrize(
+    ("left", "right", "expected"),
+    [
+        # --- Same dtype: int ---
+        ([1, 2], [1, 2], True),
+        # --- Same dtype: float ---
+        ([1.1, 2.2], [1.1, 2.2], True),
+        # --- Value differs ---
+        ([1, 2], [1, 0], False),
+        # --- Cross-supertype: float vs int ---
+        ([1.0, 2.0], [1, 2], True),
+        ([1.1, 2.2], [1, 2], False),
+        # --- Cross-supertype: int vs string ---
+        # pandas: False, polars: False, pyarrow: raises
+        pytest.param([1, 2], ["1", "2"], TBD, marks=_CROSS_TYPE),
+    ],
+)
+def test_series_equals(
+    constructor_eager: ConstructorEager,
+    left: list,
+    right: list,
+    expected: bool | None,  # noqa: FBT001
+) -> None:
+    left_native = constructor_eager({"left": left})["left"]
+    right_native = constructor_eager({"right": right})["right"]
+    left_nw = nw.from_native(left_native, series_only=True)
+    right_nw = nw.from_native(right_native, series_only=True)
+
+    result = left_nw.equals(right_nw)
+    assert result == expected
+
+
+@pytest.mark.parametrize(
+    ("left", "right", "null_equal", "expected"),
+    [
+        # --- Null vs value ---
+        ([1, None], [1, 2], True, False),
+        ([1, None], [1, 2], False, False),
+        # --- Null vs Null ---
+        ([1, None], [1, None], True, True),
+        ([1, None], [1, None], False, False),
+        # --- NaN vs NaN ---
+        # pandas: True, polars: True, pyarrow: False
+        pytest.param(
+            [1.0, float("nan")], [1.0, float("nan")], True, TBD, marks=_NAN_HANDLING
+        ),
+        # pandas: True, polars: True, pyarrow: False
+        pytest.param(
+            [1.0, float("nan")], [1.0, float("nan")], False, TBD, marks=_NAN_HANDLING
+        ),
+        # --- NaN vs value ---
+        # pandas: False, polars: False, pyarrow: False
+        ([1.0, float("nan")], [1.0, 2.0], True, False),
+    ],
+)
+def test_series_equals_null_equal(
+    constructor_eager: ConstructorEager,
+    left: list,
+    right: list,
+    null_equal: bool,  # noqa: FBT001
+    expected: bool | None,  # noqa: FBT001
+) -> None:
+    left_native = constructor_eager({"left": left})["left"]
+    right_native = constructor_eager({"right": right})["right"]
+    left_nw = nw.from_native(left_native, series_only=True)
+    right_nw = nw.from_native(right_native, series_only=True)
+
+    result = left_nw.equals(right_nw, null_equal=null_equal)
+    assert result == expected
+
+
+@pytest.mark.parametrize(
+    ("left", "right", "check_dtypes", "expected"),
+    [
+        # --- Same values, different dtype ---
+        ([1.1, 2.2], [1, 2], False, False),
+        # --- Whole-number floats, check_dtypes=False ---
+        ([1.0, 2.0], [1, 2], False, True),
+        # --- Whole-number floats, check_dtypes=True ---
+        # pandas: False, polars: False, pyarrow: False, pandas[pyarrow]: True (infers Int64)
+        pytest.param([1.0, 2.0], [1, 2], True, TBD, marks=_DTYPE_INFERENCE),
+    ],
+)
+def test_series_equals_check_dtypes(
+    constructor_eager: ConstructorEager,
+    left: list,
+    right: list,
+    check_dtypes: bool,  # noqa: FBT001
+    expected: bool | None,  # noqa: FBT001
+) -> None:
+    left_native = constructor_eager({"a": left})["a"]
+    right_native = constructor_eager({"a": right})["a"]
+    left_nw = nw.from_native(left_native, series_only=True)
+    right_nw = nw.from_native(right_native, series_only=True)
+
+    result = left_nw.equals(right_nw, check_dtypes=check_dtypes)
+    assert result == expected
+
+
+@pytest.mark.parametrize(
+    ("left_name", "right_name", "check_names", "expected"),
+    [
+        # --- Different names ---
+        ("left", "right", False, True),
+        # pandas: False, polars: False, pyarrow: True (ChunkedArray has no name metadata)
+        pytest.param("left", "right", True, TBD, marks=_CHECK_NAMES),
+    ],
+)
+def test_series_equals_check_names(
+    constructor_eager: ConstructorEager,
+    left_name: str,
+    right_name: str,
+    check_names: bool,  # noqa: FBT001
+    expected: bool | None,  # noqa: FBT001
+) -> None:
+    data = [1, 2]
+    left_native = constructor_eager({left_name: data})[left_name]
+    right_native = constructor_eager({right_name: data})[right_name]
+    left_nw = nw.from_native(left_native, series_only=True)
+    right_nw = nw.from_native(right_native, series_only=True)
+
+    result = left_nw.equals(right_nw, check_names=check_names)
+    assert result == expected

utils/check_api_reference.py

@@ -79,6 +79,7 @@ def read_documented_members(source: str | Path) -> list[str]:
     "arg_max",
     "arg_min",
     "arg_true",
+    "equals",
     "dtype",
     "from_iterable",
     "from_numpy",