refactor: adds _compliant sub-package

narwhals/_arrow/expr.py

@@ -13,14 +13,14 @@
 from narwhals._arrow.expr_name import ArrowExprNameNamespace
 from narwhals._arrow.expr_str import ArrowExprStringNamespace
 from narwhals._arrow.series import ArrowSeries
+from narwhals._compliant import CompliantExpr
 from narwhals._expression_parsing import ExprKind
 from narwhals._expression_parsing import evaluate_output_names_and_aliases
 from narwhals._expression_parsing import is_scalar_like
 from narwhals._expression_parsing import reuse_series_implementation
 from narwhals.dependencies import get_numpy
 from narwhals.dependencies import is_numpy_array
 from narwhals.exceptions import ColumnNotFoundError
-from narwhals.typing import CompliantExpr
 from narwhals.utils import Implementation
 from narwhals.utils import not_implemented
 

narwhals/_arrow/namespace.py

@@ -25,9 +25,9 @@
 from narwhals._arrow.utils import horizontal_concat
 from narwhals._arrow.utils import nulls_like
 from narwhals._arrow.utils import vertical_concat
+from narwhals._compliant import CompliantNamespace
 from narwhals._expression_parsing import combine_alias_output_names
 from narwhals._expression_parsing import combine_evaluate_output_names
-from narwhals.typing import CompliantNamespace
 from narwhals.utils import Implementation
 from narwhals.utils import exclude_column_names
 from narwhals.utils import get_column_names

narwhals/_arrow/selectors.py

@@ -3,16 +3,16 @@
 from typing import TYPE_CHECKING
 
 from narwhals._arrow.expr import ArrowExpr
-from narwhals._selectors import CompliantSelector
-from narwhals._selectors import EagerSelectorNamespace
+from narwhals._compliant import CompliantSelector
+from narwhals._compliant import EagerSelectorNamespace
 
 if TYPE_CHECKING:
     from typing_extensions import Self
 
     from narwhals._arrow.dataframe import ArrowDataFrame
     from narwhals._arrow.series import ArrowSeries
-    from narwhals._selectors import EvalNames
-    from narwhals._selectors import EvalSeries
+    from narwhals._compliant import EvalNames
+    from narwhals._compliant import EvalSeries
     from narwhals.utils import _FullContext
 
 

narwhals/_compliant/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from narwhals._compliant.dataframe import CompliantDataFrame
+from narwhals._compliant.dataframe import CompliantLazyFrame
+from narwhals._compliant.expr import CompliantExpr
+from narwhals._compliant.expr import LazyExpr
+from narwhals._compliant.namespace import CompliantNamespace
+from narwhals._compliant.selectors import CompliantSelector
+from narwhals._compliant.selectors import CompliantSelectorNamespace
+from narwhals._compliant.selectors import EagerSelectorNamespace
+from narwhals._compliant.selectors import EvalNames
+from narwhals._compliant.selectors import EvalSeries
+from narwhals._compliant.selectors import LazySelectorNamespace
+from narwhals._compliant.series import CompliantSeries
+from narwhals._compliant.typing import CompliantFrameT
+from narwhals._compliant.typing import CompliantSeriesOrNativeExprT_co
+from narwhals._compliant.typing import CompliantSeriesT_co
+from narwhals._compliant.typing import IntoCompliantExpr
+
+__all__ = [
+    "CompliantDataFrame",
+    "CompliantExpr",
+    "CompliantFrameT",
+    "CompliantLazyFrame",
+    "CompliantNamespace",
+    "CompliantSelector",
+    "CompliantSelectorNamespace",
+    "CompliantSeries",
+    "CompliantSeriesOrNativeExprT_co",
+    "CompliantSeriesT_co",
+    "EagerSelectorNamespace",
+    "EvalNames",
+    "EvalSeries",
+    "IntoCompliantExpr",
+    "LazyExpr",
+    "LazySelectorNamespace",
+]

narwhals/_compliant/dataframe.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Iterator
+from typing import Mapping
+from typing import Protocol
+from typing import Sequence
+from typing import TypeVar
+
+from narwhals._compliant.typing import CompliantSeriesT_co
+from narwhals._compliant.typing import EagerSeriesT
+from narwhals._compliant.typing import EagerSeriesT_co
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+    from typing_extensions import TypeIs
+
+    from narwhals._compliant.expr import EagerExpr
+    from narwhals.dtypes import DType
+
+__all__ = ["CompliantDataFrame", "CompliantLazyFrame"]
+
+T = TypeVar("T")
+
+
+class CompliantDataFrame(Protocol[CompliantSeriesT_co]):
+    def __narwhals_dataframe__(self) -> Self: ...
+    def __narwhals_namespace__(self) -> Any: ...
+    def simple_select(
+        self, *column_names: str
+    ) -> Self: ...  # `select` where all args are column names.
+    def aggregate(self, *exprs: Any) -> Self:  # pragma: no cover
+        ...  # `select` where all args are aggregations or literals
+        # (so, no broadcasting is necessary).
+
+    @property
+    def columns(self) -> Sequence[str]: ...
+    @property
+    def schema(self) -> Mapping[str, DType]: ...
+    def get_column(self, name: str) -> CompliantSeriesT_co: ...
+    def iter_columns(self) -> Iterator[CompliantSeriesT_co]: ...
+
+
+class CompliantLazyFrame(Protocol):
+    def __narwhals_lazyframe__(self) -> Self: ...
+    def __narwhals_namespace__(self) -> Any: ...
+    def simple_select(
+        self, *column_names: str
+    ) -> Self: ...  # `select` where all args are column names.
+    def aggregate(self, *exprs: Any) -> Self:  # pragma: no cover
+        ...  # `select` where all args are aggregations or literals
+        # (so, no broadcasting is necessary).
+
+    @property
+    def columns(self) -> Sequence[str]: ...
+    @property
+    def schema(self) -> Mapping[str, DType]: ...
+    def _iter_columns(self) -> Iterator[Any]: ...
+
+
+class EagerDataFrame(CompliantDataFrame[EagerSeriesT_co], Protocol[EagerSeriesT_co]):
+    def _maybe_evaluate_expr(
+        self, expr: EagerExpr[EagerDataFrame[EagerSeriesT_co], EagerSeriesT_co] | T, /
+    ) -> EagerSeriesT_co | T:
+        if is_eager_expr(expr):
+            result: Sequence[EagerSeriesT_co] = expr(self)
+            if len(result) > 1:
+                msg = (
+                    "Multi-output expressions (e.g. `nw.all()` or `nw.col('a', 'b')`) "
+                    "are not supported in this context"
+                )
+                raise ValueError(msg)
+            return result[0]
+        return expr
+
+
+# NOTE: DON'T CHANGE THIS EITHER
+def is_eager_expr(
+    obj: EagerExpr[Any, EagerSeriesT] | Any,
+) -> TypeIs[EagerExpr[Any, EagerSeriesT]]:
+    return hasattr(obj, "__narwhals_expr__")