chore: Add CompliantDataFrame.native (#2249)

* chore: Add `CompliantDataFrame.native` -> `NativeFrame`

Related:
- #2232
- #2230
- #2130

* chore: Coverage for `PolarsDataFrame.native`

* refactor: remove already imported imports

* chore: Coverage for `ArrowDataFrame.native`

* chore: Cov for `PandasLikeDataFrame.native`

* refactor: Clean up `ArrowDataFrame`

* unbreak `ArrowDataFrame.with_columns`

and write an essay

Author: dangotbanned

narwhals/_arrow/dataframe.py

@@ -23,6 +23,7 @@
 from narwhals._compliant.typing import EagerDataFrameT
 from narwhals._compliant.typing import EagerSeriesT
 from narwhals._compliant.typing import IntoCompliantExpr
+from narwhals._compliant.typing import NativeFrameT_co
 
 __all__ = [
     "CompliantDataFrame",
@@ -48,4 +49,5 @@
     "IntoCompliantExpr",
     "LazyExpr",
     "LazySelectorNamespace",
+    "NativeFrameT_co",
 ]

narwhals/_compliant/__init__.py

@@ -44,7 +44,13 @@
 T = TypeVar("T")
 
 
-class CompliantDataFrame(Sized, Protocol[CompliantSeriesT, CompliantExprT_contra]):
+class CompliantDataFrame(
+    _StoresNative[NativeFrameT_co],
+    Sized,
+    Protocol[CompliantSeriesT, CompliantExprT_contra, NativeFrameT_co],
+):
+    _native_frame: Any
+
     def __narwhals_dataframe__(self) -> Self: ...
     def __narwhals_namespace__(self) -> Any: ...
     def __array__(self, dtype: Any, *, copy: bool | None) -> _2DArray: ...
@@ -60,6 +66,10 @@ def aggregate(self, *exprs: CompliantExprT_contra) -> Self:
         """
         return self.select(*exprs)
 
+    @property
+    def native(self) -> NativeFrameT_co:
+        return self._native_frame  # type: ignore[no-any-return]
+
     @property
     def columns(self) -> Sequence[str]: ...
     @property
@@ -69,7 +79,7 @@ def shape(self) -> tuple[int, int]: ...
     def clone(self) -> Self: ...
     def collect(
         self, backend: Implementation | None, **kwargs: Any
-    ) -> CompliantDataFrame[Any, Any]: ...
+    ) -> CompliantDataFrame[Any, Any, Any]: ...
     def collect_schema(self) -> Mapping[str, DType]: ...
     def drop(self, columns: Sequence[str], *, strict: bool) -> Self: ...
     def drop_nulls(self, subset: Sequence[str] | None) -> Self: ...
@@ -195,7 +205,7 @@ def schema(self) -> Mapping[str, DType]: ...
     def _iter_columns(self) -> Iterator[Any]: ...
     def collect(
         self, backend: Implementation | None, **kwargs: Any
-    ) -> CompliantDataFrame[Any, Any]: ...
+    ) -> CompliantDataFrame[Any, Any, Any]: ...
     def collect_schema(self) -> Mapping[str, DType]: ...
     def drop(self, columns: Sequence[str], *, strict: bool) -> Self: ...
     def drop_nulls(self, subset: Sequence[str] | None) -> Self: ...
@@ -252,7 +262,7 @@ def with_row_index(self, name: str) -> Self: ...
 
 
 class EagerDataFrame(
-    CompliantDataFrame[EagerSeriesT, EagerExprT_contra],
+    CompliantDataFrame[EagerSeriesT, EagerExprT_contra, NativeFrameT_co],
     CompliantLazyFrame[EagerExprT_contra, NativeFrameT_co],
     Protocol[EagerSeriesT, EagerExprT_contra, NativeFrameT_co],
 ):

narwhals/_compliant/dataframe.py

@@ -66,9 +66,9 @@
 SeriesT = TypeVar("SeriesT", bound="CompliantSeries")
 ExprT = TypeVar("ExprT", bound="NativeExpr")
 FrameT = TypeVar(
-    "FrameT", bound="CompliantDataFrame[Any, Any] | CompliantLazyFrame[Any, Any]"
+    "FrameT", bound="CompliantDataFrame[Any, Any, Any] | CompliantLazyFrame[Any, Any]"
 )
-DataFrameT = TypeVar("DataFrameT", bound="CompliantDataFrame[Any, Any]")
+DataFrameT = TypeVar("DataFrameT", bound="CompliantDataFrame[Any, Any, Any]")
 LazyFrameT = TypeVar("LazyFrameT", bound="CompliantLazyFrame[Any, Any]")
 SelectorOrExpr: TypeAlias = (
     "CompliantSelector[FrameT, SeriesOrExprT] | CompliantExpr[FrameT, SeriesOrExprT]"
@@ -311,7 +311,7 @@ def __repr__(self: Self) -> str:  # pragma: no cover
 
 
 def _eval_lhs_rhs(
-    df: CompliantDataFrame[Any, Any] | CompliantLazyFrame[Any, Any],
+    df: CompliantDataFrame[Any, Any, Any] | CompliantLazyFrame[Any, Any],
     lhs: CompliantExpr[Any, Any],
     rhs: CompliantExpr[Any, Any],
 ) -> tuple[Sequence[str], Sequence[str]]:

narwhals/_compliant/selectors.py

@@ -28,6 +28,7 @@
     "CompliantLazyFrameT",
     "CompliantSeriesT",
     "IntoCompliantExpr",
+    "NativeFrameT_co",
 ]
 NativeExprT_co = TypeVar("NativeExprT_co", bound="NativeExpr", covariant=True)
 CompliantSeriesT = TypeVar("CompliantSeriesT", bound="CompliantSeries")
@@ -36,12 +37,14 @@
     bound="CompliantSeries | NativeExpr",
     covariant=True,
 )
-
 NativeFrameT_co = TypeVar("NativeFrameT_co", bound="NativeFrame", covariant=True)
 CompliantFrameT = TypeVar(
-    "CompliantFrameT", bound="CompliantDataFrame[Any, Any] | CompliantLazyFrame[Any, Any]"
+    "CompliantFrameT",
+    bound="CompliantDataFrame[Any, Any, Any] | CompliantLazyFrame[Any, Any]",
+)
+CompliantDataFrameT = TypeVar(
+    "CompliantDataFrameT", bound="CompliantDataFrame[Any, Any, Any]"
 )
-CompliantDataFrameT = TypeVar("CompliantDataFrameT", bound="CompliantDataFrame[Any, Any]")
 CompliantLazyFrameT = TypeVar("CompliantLazyFrameT", bound="CompliantLazyFrame[Any, Any]")
 IntoCompliantExpr: TypeAlias = "CompliantExpr[CompliantFrameT, CompliantSeriesOrNativeExprT_co] | CompliantSeriesOrNativeExprT_co"
 CompliantExprT = TypeVar("CompliantExprT", bound="CompliantExpr[Any, Any]")

narwhals/_compliant/typing.py

@@ -95,7 +95,7 @@ def collect(
         self: Self,
         backend: Implementation | None,
         **kwargs: Any,
-    ) -> CompliantDataFrame[Any, Any]:
+    ) -> CompliantDataFrame[Any, Any, Any]:
         result = self._native_frame.compute(**kwargs)
 
         if backend is None or backend is Implementation.PANDAS:

narwhals/_dask/dataframe.py

@@ -94,7 +94,7 @@ def collect(
         self: Self,
         backend: ModuleType | Implementation | str | None,
         **kwargs: Any,
-    ) -> CompliantDataFrame[Any, Any]:
+    ) -> CompliantDataFrame[Any, Any, Any]:
         if backend is None or backend is Implementation.PYARROW:
             import pyarrow as pa  # ignore-banned-import
 

narwhals/_duckdb/dataframe.py

@@ -109,7 +109,7 @@ def extract_compliant(
 
 def evaluate_output_names_and_aliases(
     expr: CompliantExpr[Any, Any],
-    df: CompliantDataFrame[Any, Any] | CompliantLazyFrame[Any, Any],
+    df: CompliantDataFrame[Any, Any, Any] | CompliantLazyFrame[Any, Any],
     exclude: Sequence[str],
 ) -> tuple[Sequence[str], Sequence[str]]:
     output_names = expr._evaluate_output_names(df)