refactor: Add CompliantFrame protocol

narwhals/_compliant/__init__.py

@@ -2,6 +2,7 @@
 
 from narwhals._compliant.dataframe import (
     CompliantDataFrame,
+    CompliantFrame,
     CompliantLazyFrame,
     EagerDataFrame,
 )
@@ -49,7 +50,6 @@
     EagerSeriesT,
     EvalNames,
     EvalSeries,
-    IntoCompliantExpr,
     NativeFrameT_co,
     NativeSeriesT_co,
 )
@@ -60,6 +60,7 @@
     "CompliantDataFrame",
     "CompliantExpr",
     "CompliantExprT",
+    "CompliantFrame",
     "CompliantFrameT",
     "CompliantGroupBy",
     "CompliantLazyFrame",
@@ -92,7 +93,6 @@
     "EagerWhen",
     "EvalNames",
     "EvalSeries",
-    "IntoCompliantExpr",
     "LazyExpr",
     "LazyExprNamespace",
     "LazyNamespace",

narwhals/_compliant/dataframe.py

@@ -12,7 +12,6 @@
     EagerExprT,
     EagerSeriesT,
     NativeDataFrameT,
-    NativeFrameT,
     NativeLazyFrameT,
     NativeSeriesT,
 )
@@ -42,6 +41,7 @@
 if TYPE_CHECKING:
     from io import BytesIO
     from pathlib import Path
+    from types import ModuleType
 
     import pandas as pd
     import polars as pl
@@ -77,29 +77,112 @@
 
     Incomplete: TypeAlias = Any
 
-__all__ = ["CompliantDataFrame", "CompliantLazyFrame", "EagerDataFrame"]
+__all__ = ["CompliantDataFrame", "CompliantFrame", "CompliantLazyFrame", "EagerDataFrame"]
 
 T = TypeVar("T")
 
 _ToDict: TypeAlias = "dict[str, CompliantSeriesT] | dict[str, list[Any]]"  # noqa: PYI047
 
+_NativeFrameT = TypeVar("_NativeFrameT")
+
+
+class CompliantFrame(
+    _StoresNative[_NativeFrameT],
+    FromNative[_NativeFrameT],
+    ToNarwhals[ToNarwhalsT_co],
+    Protocol[CompliantExprT_contra, _NativeFrameT, ToNarwhalsT_co],
+):
+    """Common parts of `DataFrame`, `LazyFrame`."""
+
+    _native_frame: _NativeFrameT
+    _implementation: Implementation
+    _version: Version
+
+    def __native_namespace__(self) -> ModuleType: ...
+    def __narwhals_namespace__(self) -> Any: ...
+    def _with_version(self, version: Version) -> Self: ...
+    @classmethod
+    def from_native(cls, data: _NativeFrameT, /, *, context: _LimitedContext) -> Self: ...
+    @property
+    def columns(self) -> Sequence[str]: ...
+    @property
+    def native(self) -> _NativeFrameT:
+        return self._native_frame
+
+    @property
+    def schema(self) -> Mapping[str, DType]: ...
+    def aggregate(self, *exprs: CompliantExprT_contra) -> Self:
+        """`select` where all args are aggregations or literals.
+
+        (so, no broadcasting is necessary).
+        """
+        ...
+
+    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: ...
+    def explode(self, columns: Sequence[str]) -> Self: ...
+    def filter(self, predicate: CompliantExprT_contra | Incomplete) -> Self: ...
+    def group_by(
+        self,
+        keys: Sequence[str] | Sequence[CompliantExprT_contra],
+        *,
+        drop_null_keys: bool,
+    ) -> CompliantGroupBy[Self, CompliantExprT_contra]: ...
+    def head(self, n: int) -> Self: ...
+    def join(
+        self,
+        other: Self,
+        *,
+        how: JoinStrategy,
+        left_on: Sequence[str] | None,
+        right_on: Sequence[str] | None,
+        suffix: str,
+    ) -> Self: ...
+    def join_asof(
+        self,
+        other: Self,
+        *,
+        left_on: str,
+        right_on: str,
+        by_left: Sequence[str] | None,
+        by_right: Sequence[str] | None,
+        strategy: AsofJoinStrategy,
+        suffix: str,
+    ) -> Self: ...
+    def rename(self, mapping: Mapping[str, str]) -> Self: ...
+    def select(self, *exprs: CompliantExprT_contra) -> Self: ...
+    def simple_select(self, *column_names: str) -> Self:
+        """`select` where all args are column names."""
+        ...
+
+    def sort(
+        self, *by: str, descending: bool | Sequence[bool], nulls_last: bool
+    ) -> Self: ...
+    def tail(self, n: int) -> Self: ...
+    def unique(
+        self, subset: Sequence[str] | None, *, keep: LazyUniqueKeepStrategy
+    ) -> Self: ...
+    def unpivot(
+        self,
+        on: Sequence[str] | None,
+        index: Sequence[str] | None,
+        variable_name: str,
+        value_name: str,
+    ) -> Self: ...
+    def with_columns(self, *exprs: CompliantExprT_contra) -> Self: ...
+    def with_row_index(self, name: str, order_by: Sequence[str]) -> Self: ...
+
 
 class CompliantDataFrame(
     NumpyConvertible["_2DArray", "_2DArray"],
     DictConvertible["_ToDict[CompliantSeriesT]", Mapping[str, Any]],
     ArrowConvertible["pa.Table", "IntoArrowTable"],
-    _StoresNative[NativeFrameT],
-    FromNative[NativeFrameT],
-    ToNarwhals[ToNarwhalsT_co],
     Sized,
-    Protocol[CompliantSeriesT, CompliantExprT_contra, NativeFrameT, ToNarwhalsT_co],
+    CompliantFrame[CompliantExprT_contra, NativeDataFrameT, ToNarwhalsT_co],
+    Protocol[CompliantSeriesT, CompliantExprT_contra, NativeDataFrameT, ToNarwhalsT_co],
 ):
-    _native_frame: NativeFrameT
-    _implementation: Implementation
-    _version: Version
-
     def __narwhals_dataframe__(self) -> Self: ...
-    def __narwhals_namespace__(self) -> Any: ...
     @classmethod
     def from_arrow(cls, data: IntoArrowTable, /, *, context: _LimitedContext) -> Self: ...
     @classmethod
@@ -112,8 +195,6 @@ def from_dict(
         schema: IntoSchema | None,
     ) -> Self: ...
     @classmethod
-    def from_native(cls, data: NativeFrameT, /, *, context: _LimitedContext) -> Self: ...
-    @classmethod
     def from_numpy(
         cls,
         data: _2DArray,
@@ -122,7 +203,6 @@ def from_numpy(
         context: _LimitedContext,
         schema: IntoSchema | Sequence[str] | None,
     ) -> Self: ...
-
     def __array__(self, dtype: Any, *, copy: bool | None) -> _2DArray: ...
     def __getitem__(
         self,
@@ -131,37 +211,14 @@ def __getitem__(
             MultiColSelector[CompliantSeriesT],
         ],
     ) -> Self: ...
-    def simple_select(self, *column_names: str) -> Self:
-        """`select` where all args are column names."""
-        ...
-
     def aggregate(self, *exprs: CompliantExprT_contra) -> Self:
-        """`select` where all args are aggregations or literals.
-
-        (so, no broadcasting is necessary).
-        """
         # NOTE: Ignore is to avoid an intermittent false positive
         return self.select(*exprs)  # pyright: ignore[reportArgumentType]
 
-    def _with_version(self, version: Version) -> Self: ...
-
-    @property
-    def native(self) -> NativeFrameT:
-        return self._native_frame
-
-    @property
-    def columns(self) -> Sequence[str]: ...
-    @property
-    def schema(self) -> Mapping[str, DType]: ...
     @property
     def shape(self) -> tuple[int, int]: ...
     def clone(self) -> Self: ...
-    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: ...
     def estimated_size(self, unit: SizeUnit) -> int | float: ...
-    def explode(self, columns: Sequence[str]) -> Self: ...
-    def filter(self, predicate: CompliantExprT_contra | Incomplete) -> Self: ...
     def gather_every(self, n: int, offset: int) -> Self: ...
     def get_column(self, name: str) -> CompliantSeriesT: ...
     def group_by(
@@ -170,33 +227,12 @@ def group_by(
         *,
         drop_null_keys: bool,
     ) -> DataFrameGroupBy[Self, Any]: ...
-    def head(self, n: int) -> Self: ...
     def item(self, row: int | None, column: int | str | None) -> Any: ...
     def iter_columns(self) -> Iterator[CompliantSeriesT]: ...
     def iter_rows(
         self, *, named: bool, buffer_size: int
     ) -> Iterator[tuple[Any, ...]] | Iterator[Mapping[str, Any]]: ...
     def is_unique(self) -> CompliantSeriesT: ...
-    def join(
-        self,
-        other: Self,
-        *,
-        how: JoinStrategy,
-        left_on: Sequence[str] | None,
-        right_on: Sequence[str] | None,
-        suffix: str,
-    ) -> Self: ...
-    def join_asof(
-        self,
-        other: Self,
-        *,
-        left_on: str,
-        right_on: str,
-        by_left: Sequence[str] | None,
-        by_right: Sequence[str] | None,
-        strategy: AsofJoinStrategy,
-        suffix: str,
-    ) -> Self: ...
     def lazy(
         self, backend: _LazyAllowedImpl | None, *, session: SparkSession | None
     ) -> CompliantLazyFrameAny: ...
@@ -210,7 +246,6 @@ def pivot(
         sort_columns: bool,
         separator: str,
     ) -> Self: ...
-    def rename(self, mapping: Mapping[str, str]) -> Self: ...
     def row(self, index: int) -> tuple[Any, ...]: ...
     def rows(
         self, *, named: bool
@@ -223,11 +258,6 @@ def sample(
         with_replacement: bool,
         seed: int | None,
     ) -> Self: ...
-    def select(self, *exprs: CompliantExprT_contra) -> Self: ...
-    def sort(
-        self, *by: str, descending: bool | Sequence[bool], nulls_last: bool
-    ) -> Self: ...
-    def tail(self, n: int) -> Self: ...
     def to_arrow(self) -> pa.Table: ...
     def to_pandas(self) -> pd.DataFrame: ...
     def to_polars(self) -> pl.DataFrame: ...
@@ -245,14 +275,6 @@ def unique(
         keep: UniqueKeepStrategy,
         maintain_order: bool | None = None,
     ) -> Self: ...
-    def unpivot(
-        self,
-        on: Sequence[str] | None,
-        index: Sequence[str] | None,
-        variable_name: str,
-        value_name: str,
-    ) -> Self: ...
-    def with_columns(self, *exprs: CompliantExprT_contra) -> Self: ...
     def with_row_index(self, name: str, order_by: Sequence[str] | None) -> Self: ...
     @overload
     def write_csv(self, file: None) -> str: ...
@@ -263,98 +285,15 @@ def write_parquet(self, file: str | Path | BytesIO) -> None: ...
 
 
 class CompliantLazyFrame(
-    _StoresNative[NativeLazyFrameT],
-    FromNative[NativeLazyFrameT],
-    ToNarwhals[ToNarwhalsT_co],
+    CompliantFrame[CompliantExprT_contra, NativeLazyFrameT, ToNarwhalsT_co],
     Protocol[CompliantExprT_contra, NativeLazyFrameT, ToNarwhalsT_co],
 ):
-    _native_frame: NativeLazyFrameT
-    _implementation: Implementation
-    _version: Version
-
     def __narwhals_lazyframe__(self) -> Self: ...
-    def __narwhals_namespace__(self) -> Any: ...
-
-    @classmethod
-    def from_native(
-        cls, data: NativeLazyFrameT, /, *, context: _LimitedContext
-    ) -> Self: ...
-
-    def simple_select(self, *column_names: str) -> Self:
-        """`select` where all args are column names."""
-        ...
-
-    def aggregate(self, *exprs: CompliantExprT_contra) -> Self:
-        """`select` where all args are aggregations or literals.
-
-        (so, no broadcasting is necessary).
-        """
-        ...
-
-    def _with_version(self, version: Version) -> Self: ...
-
-    @property
-    def native(self) -> NativeLazyFrameT:
-        return self._native_frame
-
-    @property
-    def columns(self) -> Sequence[str]: ...
-    @property
-    def schema(self) -> Mapping[str, DType]: ...
     def _iter_columns(self) -> Iterator[Any]: ...
     def collect(
         self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny: ...
-    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: ...
-    def explode(self, columns: Sequence[str]) -> Self: ...
-    def filter(self, predicate: CompliantExprT_contra | Incomplete) -> Self: ...
-    def group_by(
-        self,
-        keys: Sequence[str] | Sequence[CompliantExprT_contra],
-        *,
-        drop_null_keys: bool,
-    ) -> CompliantGroupBy[Self, CompliantExprT_contra]: ...
-    def head(self, n: int) -> Self: ...
-    def join(
-        self,
-        other: Self,
-        *,
-        how: JoinStrategy,
-        left_on: Sequence[str] | None,
-        right_on: Sequence[str] | None,
-        suffix: str,
-    ) -> Self: ...
-    def join_asof(
-        self,
-        other: Self,
-        *,
-        left_on: str,
-        right_on: str,
-        by_left: Sequence[str] | None,
-        by_right: Sequence[str] | None,
-        strategy: AsofJoinStrategy,
-        suffix: str,
-    ) -> Self: ...
-    def rename(self, mapping: Mapping[str, str]) -> Self: ...
-    def select(self, *exprs: CompliantExprT_contra) -> Self: ...
     def sink_parquet(self, file: str | Path | BytesIO) -> None: ...
-    def sort(
-        self, *by: str, descending: bool | Sequence[bool], nulls_last: bool
-    ) -> Self: ...
-    def unique(
-        self, subset: Sequence[str] | None, *, keep: LazyUniqueKeepStrategy
-    ) -> Self: ...
-    def unpivot(
-        self,
-        on: Sequence[str] | None,
-        index: Sequence[str] | None,
-        variable_name: str,
-        value_name: str,
-    ) -> Self: ...
-    def with_columns(self, *exprs: CompliantExprT_contra) -> Self: ...
-    def with_row_index(self, name: str, order_by: Sequence[str]) -> Self: ...
 
 
 class EagerDataFrame(