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,52 @@
+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 narwhals._compliant.typing import CompliantSeriesT_co
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals.dtypes import DType
+
+__all__ = ["CompliantDataFrame", "CompliantLazyFrame"]
+
+
+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]: ...

narwhals/_compliant/expr.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Callable
+from typing import Literal
+from typing import Protocol
+from typing import Sequence
+
+from narwhals._compliant.typing import CompliantDataFrameT
+from narwhals._compliant.typing import CompliantFrameT
+from narwhals._compliant.typing import CompliantLazyFrameT
+from narwhals._compliant.typing import CompliantSeriesOrNativeExprT_co
+from narwhals._compliant.typing import CompliantSeriesT_co
+from narwhals._compliant.typing import NativeExprT_co
+from narwhals.utils import deprecated
+from narwhals.utils import not_implemented
+from narwhals.utils import unstable
+
+if not TYPE_CHECKING:  # pragma: no cover
+    if sys.version_info >= (3, 9):
+        from typing import Protocol as Protocol38
+    else:
+        from typing import Generic as Protocol38
+else:  # pragma: no cover
+    # TODO @dangotbanned: Remove after dropping `3.8` (#2084)
+    # - https://github.com/narwhals-dev/narwhals/pull/2064#discussion_r1965921386
+    from typing import Protocol as Protocol38
+
+if TYPE_CHECKING:
+    from typing import Mapping
+
+    from typing_extensions import Self
+
+    from narwhals._compliant.namespace import CompliantNamespace
+    from narwhals._compliant.series import CompliantSeries
+    from narwhals._expression_parsing import ExprKind
+    from narwhals.dtypes import DType
+    from narwhals.utils import Implementation
+    from narwhals.utils import Version
+
+__all__ = ["CompliantExpr"]
+
+
+# NOTE: Only common methods for lazy expr-like objects
+class NativeExpr(Protocol):
+    def between(self, *args: Any, **kwds: Any) -> Any: ...
+    def isin(self, *args: Any, **kwds: Any) -> Any: ...
+
+
+class CompliantExpr(Protocol38[CompliantFrameT, CompliantSeriesOrNativeExprT_co]):
+    _implementation: Implementation
+    _backend_version: tuple[int, ...]
+    _version: Version
+    _evaluate_output_names: Callable[[CompliantFrameT], Sequence[str]]
+    _alias_output_names: Callable[[Sequence[str]], Sequence[str]] | None
+    _depth: int
+    _function_name: str
+
+    def __call__(
+        self, df: CompliantFrameT
+    ) -> Sequence[CompliantSeriesOrNativeExprT_co]: ...
+    def __narwhals_expr__(self) -> None: ...
+    def __narwhals_namespace__(
+        self,
+    ) -> CompliantNamespace[CompliantFrameT, CompliantSeriesOrNativeExprT_co]: ...
+    def is_null(self) -> Self: ...
+    def abs(self) -> Self: ...
+    def all(self) -> Self: ...
+    def any(self) -> Self: ...
+    def alias(self, name: str) -> Self: ...
+    def cast(self, dtype: DType | type[DType]) -> Self: ...
+    def count(self) -> Self: ...
+    def min(self) -> Self: ...
+    def max(self) -> Self: ...
+    def arg_min(self) -> Self: ...
+    def arg_max(self) -> Self: ...
+    def arg_true(self) -> Self: ...
+    def mean(self) -> Self: ...
+    def sum(self) -> Self: ...
+    def median(self) -> Self: ...
+    def skew(self) -> Self: ...
+    def std(self, *, ddof: int) -> Self: ...
+    def var(self, *, ddof: int) -> Self: ...
+    def n_unique(self) -> Self: ...
+    def null_count(self) -> Self: ...
+    def drop_nulls(self) -> Self: ...
+    def fill_null(
+        self,
+        value: Any | None,
+        strategy: Literal["forward", "backward"] | None,
+        limit: int | None,
+    ) -> Self: ...
+    def diff(self) -> Self: ...
+    def unique(self) -> Self: ...
+    def len(self) -> Self: ...
+    def round(self, decimals: int) -> Self: ...
+    def mode(self) -> Self: ...
+    def head(self, n: int) -> Self: ...
+    def tail(self, n: int) -> Self: ...
+    def shift(self, n: int) -> Self: ...
+    def is_finite(self) -> Self: ...
+    def is_nan(self) -> Self: ...
+    def is_unique(self) -> Self: ...
+    def is_first_distinct(self) -> Self: ...
+    def is_last_distinct(self) -> Self: ...
+    def cum_sum(self, *, reverse: bool) -> Self: ...
+    def cum_count(self, *, reverse: bool) -> Self: ...
+    def cum_min(self, *, reverse: bool) -> Self: ...
+    def cum_max(self, *, reverse: bool) -> Self: ...
+    def cum_prod(self, *, reverse: bool) -> Self: ...
+    def is_in(self, other: Any) -> Self: ...
+    def sort(self, *, descending: bool, nulls_last: bool) -> Self: ...
+    def rank(
+        self,
+        method: Literal["average", "min", "max", "dense", "ordinal"],
+        *,
+        descending: bool,
+    ) -> Self: ...
+    def replace_strict(
+        self,
+        old: Sequence[Any] | Mapping[Any, Any],
+        new: Sequence[Any],
+        *,
+        return_dtype: DType | type[DType] | None,
+    ) -> Self: ...
+    def over(self: Self, keys: Sequence[str], kind: ExprKind) -> Self: ...
+    def sample(
+        self,
+        n: int | None,
+        *,
+        fraction: float | None,
+        with_replacement: bool,
+        seed: int | None,
+    ) -> Self: ...
+    def quantile(
+        self,
+        quantile: float,
+        interpolation: Literal["nearest", "higher", "lower", "midpoint", "linear"],
+    ) -> Self: ...
+    def map_batches(
+        self,
+        function: Callable[[CompliantSeries], CompliantExpr[Any, Any]],
+        return_dtype: DType | type[DType] | None,
+    ) -> Self: ...
+
+    @property
+    def str(self) -> Any: ...
+    @property
+    def name(self) -> Any: ...
+    @property
+    def dt(self) -> Any: ...
+    @property
+    def cat(self) -> Any: ...
+    @property
+    def list(self) -> Any: ...
+
+    @unstable
+    def ewm_mean(
+        self,
+        *,
+        com: float | None,
+        span: float | None,
+        half_life: float | None,
+        alpha: float | None,
+        adjust: bool,
+        min_samples: int,
+        ignore_nulls: bool,
+    ) -> Self: ...
+
+    @unstable
+    def rolling_sum(
+        self,
+        window_size: int,
+        *,
+        min_samples: int | None,
+        center: bool,
+    ) -> Self: ...
+
+    @unstable
+    def rolling_mean(
+        self,
+        window_size: int,
+        *,
+        min_samples: int | None,
+        center: bool,
+    ) -> Self: ...
+
+    @unstable
+    def rolling_var(
+        self,
+        window_size: int,
+        *,
+        min_samples: int | None,
+        center: bool,
+        ddof: int,
+    ) -> Self: ...
+
+    @unstable
+    def rolling_std(
+        self,
+        window_size: int,
+        *,
+        min_samples: int | None,
+        center: bool,
+        ddof: int,
+    ) -> Self: ...
+
+    @deprecated("Since `1.22.0`")
+    def gather_every(self, n: int, offset: int) -> Self: ...
+    def __and__(self, other: Any) -> Self: ...
+    def __or__(self, other: Any) -> Self: ...
+    def __add__(self, other: Any) -> Self: ...
+    def __sub__(self, other: Any) -> Self: ...
+    def __mul__(self, other: Any) -> Self: ...
+    def __floordiv__(self, other: Any) -> Self: ...
+    def __truediv__(self, other: Any) -> Self: ...
+    def __mod__(self, other: Any) -> Self: ...
+    def __pow__(self, other: Any) -> Self: ...
+    def __gt__(self, other: Any) -> Self: ...
+    def __ge__(self, other: Any) -> Self: ...
+    def __lt__(self, other: Any) -> Self: ...
+    def __le__(self, other: Any) -> Self: ...
+    def __invert__(self) -> Self: ...
+    def broadcast(
+        self, kind: Literal[ExprKind.AGGREGATION, ExprKind.LITERAL]
+    ) -> Self: ...
+
+
+class EagerExpr(
+    CompliantExpr[CompliantDataFrameT, CompliantSeriesT_co],
+    Protocol38[CompliantDataFrameT, CompliantSeriesT_co],
+): ...
+
+
+# NOTE: See (https://github.com/narwhals-dev/narwhals/issues/2044#issuecomment-2674262833)
+class LazyExpr(
+    CompliantExpr[CompliantLazyFrameT, NativeExprT_co],
+    Protocol38[CompliantLazyFrameT, NativeExprT_co],
+):
+    arg_min: not_implemented = not_implemented()
+    arg_max: not_implemented = not_implemented()
+    arg_true: not_implemented = not_implemented()
+    head: not_implemented = not_implemented()
+    tail: not_implemented = not_implemented()
+    mode: not_implemented = not_implemented()
+    sort: not_implemented = not_implemented()
+    rank: not_implemented = not_implemented()
+    sample: not_implemented = not_implemented()
+    map_batches: not_implemented = not_implemented()
+    ewm_mean: not_implemented = not_implemented()
+    rolling_sum: not_implemented = not_implemented()
+    rolling_mean: not_implemented = not_implemented()
+    rolling_var: not_implemented = not_implemented()
+    rolling_std: not_implemented = not_implemented()
+    gather_every: not_implemented = not_implemented()
+    replace_strict: not_implemented = not_implemented()
+    cat: not_implemented = not_implemented()  # pyright: ignore[reportAssignmentType]