feat(typing): Make IntoBackend generic

docs/api-reference/typing.md

@@ -18,8 +18,6 @@ Narwhals comes fully statically typed. In addition to `nw.DataFrame`, `nw.Expr`,
         - IntoSeries
         - IntoSeriesT
         - IntoBackend
-        - IntoEagerBackend
-        - IntoLazyBackend
         - IntoDType
         - IntoSchema
         - SizeUnit

narwhals/_arrow/dataframe.py

@@ -44,13 +44,12 @@
     )
     from narwhals._compliant.typing import CompliantDataFrameAny, CompliantLazyFrameAny
     from narwhals._translate import IntoArrowTable
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dtypes import DType
     from narwhals.typing import (
-        EagerImplementation,
         IntoSchema,
         JoinStrategy,
-        LazyImplementation,
         SizedMultiIndexSelector,
         SizedMultiNameSelector,
         SizeUnit,
@@ -513,7 +512,7 @@ def tail(self, n: int) -> Self:
             )
         return self._with_native(df.slice(abs(n)), validate_column_names=False)
 
-    def lazy(self, backend: LazyImplementation | None = None) -> CompliantLazyFrameAny:
+    def lazy(self, backend: _LazyAllowedImpl | None = None) -> CompliantLazyFrameAny:
         if backend is None:
             return self
         if backend is Implementation.DUCKDB:
@@ -559,7 +558,7 @@ def lazy(self, backend: LazyImplementation | None = None) -> CompliantLazyFrameA
         raise AssertionError  # pragma: no cover
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if backend is Implementation.PYARROW or backend is None:
             from narwhals._arrow.dataframe import ArrowDataFrame

narwhals/_compliant/dataframe.py

@@ -49,16 +49,15 @@
     from narwhals._compliant.group_by import CompliantGroupBy, DataFrameGroupBy
     from narwhals._compliant.namespace import EagerNamespace
     from narwhals._translate import IntoArrowTable
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import Implementation, _LimitedContext
     from narwhals.dataframe import DataFrame
     from narwhals.dtypes import DType
     from narwhals.exceptions import ColumnNotFoundError
     from narwhals.typing import (
         AsofJoinStrategy,
-        EagerImplementation,
         IntoSchema,
         JoinStrategy,
-        LazyImplementation,
         LazyUniqueKeepStrategy,
         MultiColSelector,
         MultiIndexSelector,
@@ -155,7 +154,7 @@ def schema(self) -> Mapping[str, DType]: ...
     def shape(self) -> tuple[int, int]: ...
     def clone(self) -> Self: ...
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny: ...
     def collect_schema(self) -> Mapping[str, DType]: ...
     def drop(self, columns: Sequence[str], *, strict: bool) -> Self: ...
@@ -198,7 +197,7 @@ def join_asof(
         strategy: AsofJoinStrategy,
         suffix: str,
     ) -> Self: ...
-    def lazy(self, backend: LazyImplementation | None) -> CompliantLazyFrameAny: ...
+    def lazy(self, backend: _LazyAllowedImpl | None) -> CompliantLazyFrameAny: ...
     def pivot(
         self,
         on: Sequence[str],
@@ -300,7 +299,7 @@ def columns(self) -> Sequence[str]: ...
     def schema(self) -> Mapping[str, DType]: ...
     def _iter_columns(self) -> Iterator[Any]: ...
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny: ...
     def collect_schema(self) -> Mapping[str, DType]: ...
     def drop(self, columns: Sequence[str], *, strict: bool) -> Self: ...

narwhals/_dask/dataframe.py

@@ -33,16 +33,12 @@
     from narwhals._dask.expr import DaskExpr
     from narwhals._dask.group_by import DaskLazyGroupBy
     from narwhals._dask.namespace import DaskNamespace
+    from narwhals._typing import _EagerAllowedImpl
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dataframe import LazyFrame
     from narwhals.dtypes import DType
     from narwhals.exceptions import ColumnNotFoundError
-    from narwhals.typing import (
-        AsofJoinStrategy,
-        EagerImplementation,
-        JoinStrategy,
-        LazyUniqueKeepStrategy,
-    )
+    from narwhals.typing import AsofJoinStrategy, JoinStrategy, LazyUniqueKeepStrategy
 
 Incomplete: TypeAlias = "Any"
 """Using `_pandas_like` utils with `_dask`.
@@ -116,7 +112,7 @@ def with_columns(self, *exprs: DaskExpr) -> Self:
         return self._with_native(self.native.assign(**dict(new_series)))
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         result = self.native.compute(**kwargs)
 

narwhals/_duckdb/dataframe.py

@@ -47,17 +47,12 @@
     from narwhals._duckdb.group_by import DuckDBGroupBy
     from narwhals._duckdb.namespace import DuckDBNamespace
     from narwhals._duckdb.series import DuckDBInterchangeSeries
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import _LimitedContext
     from narwhals.dataframe import LazyFrame
     from narwhals.dtypes import DType
     from narwhals.stable.v1 import DataFrame as DataFrameV1
-    from narwhals.typing import (
-        AsofJoinStrategy,
-        EagerImplementation,
-        JoinStrategy,
-        LazyImplementation,
-        LazyUniqueKeepStrategy,
-    )
+    from narwhals.typing import AsofJoinStrategy, JoinStrategy, LazyUniqueKeepStrategy
 
 
 class DuckDBLazyFrame(
@@ -135,7 +130,7 @@ def _iter_columns(self) -> Iterator[Expression]:
             yield col(name)
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if backend is None or backend is Implementation.PYARROW:
             from narwhals._arrow.dataframe import ArrowDataFrame
@@ -193,7 +188,7 @@ def drop(self, columns: Sequence[str], *, strict: bool) -> Self:
         selection = (name for name in self.columns if name not in columns_to_drop)
         return self._with_native(self.native.select(*selection))
 
-    def lazy(self, backend: LazyImplementation | None = None) -> Self:
+    def lazy(self, backend: _LazyAllowedImpl | None = None) -> Self:
         # The `backend`` argument has no effect but we keep it here for
         # backwards compatibility because in `narwhals.stable.v1`
         # function `.from_native()` will return a DataFrame for DuckDB.

narwhals/_ibis/dataframe.py

@@ -33,17 +33,12 @@
     from narwhals._ibis.group_by import IbisGroupBy
     from narwhals._ibis.namespace import IbisNamespace
     from narwhals._ibis.series import IbisInterchangeSeries
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import _LimitedContext
     from narwhals.dataframe import LazyFrame
     from narwhals.dtypes import DType
     from narwhals.stable.v1 import DataFrame as DataFrameV1
-    from narwhals.typing import (
-        AsofJoinStrategy,
-        EagerImplementation,
-        JoinStrategy,
-        LazyImplementation,
-        LazyUniqueKeepStrategy,
-    )
+    from narwhals.typing import AsofJoinStrategy, JoinStrategy, LazyUniqueKeepStrategy
 
     JoinPredicates: TypeAlias = "Sequence[ir.BooleanColumn] | Sequence[str]"
 
@@ -107,7 +102,7 @@ def _iter_columns(self) -> Iterator[ir.Expr]:
             yield self.native[name]
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if backend is None or backend is Implementation.PYARROW:
             from narwhals._arrow.dataframe import ArrowDataFrame
@@ -169,7 +164,7 @@ def drop(self, columns: Sequence[str], *, strict: bool) -> Self:
         selection = (col for col in self.columns if col not in columns_to_drop)
         return self._with_native(self.native.select(*selection))
 
-    def lazy(self, backend: LazyImplementation | None = None) -> Self:
+    def lazy(self, backend: _LazyAllowedImpl | None = None) -> Self:
         # The `backend`` argument has no effect but we keep it here for
         # backwards compatibility because in `narwhals.stable.v1`
         # function `.from_native()` will return a DataFrame for Ibis.

narwhals/_namespace.py

@@ -49,34 +49,25 @@
     from narwhals._polars.namespace import PolarsNamespace
     from narwhals._spark_like.dataframe import SQLFrameDataFrame
     from narwhals._spark_like.namespace import SparkLikeNamespace
-    from narwhals.typing import (
+    from narwhals._typing import (
         Arrow,
+        Backend,
         Dask,
-        DataFrameLike,
         DuckDB,
         EagerAllowed,
         Ibis,
         IntoBackend,
-        NativeFrame,
-        NativeLazyFrame,
-        NativeSeries,
         PandasLike,
         Polars,
         SparkLike,
     )
+    from narwhals.typing import DataFrameLike, NativeFrame, NativeLazyFrame, NativeSeries
 
     T = TypeVar("T")
 
     _Guard: TypeAlias = "Callable[[Any], TypeIs[T]]"
 
     EagerAllowedNamespace: TypeAlias = "Namespace[PandasLikeNamespace] | Namespace[ArrowNamespace] | Namespace[PolarsNamespace]"
-    EagerAllowedImplementation: TypeAlias = Literal[
-        Implementation.PANDAS,
-        Implementation.CUDF,
-        Implementation.MODIN,
-        Implementation.PYARROW,
-        Implementation.POLARS,
-    ]
 
     class _BasePandasLike(Sized, Protocol):
         index: Any
@@ -214,12 +205,12 @@ def from_backend(cls, backend: EagerAllowed, /) -> EagerAllowedNamespace: ...
     @overload
     @classmethod
     def from_backend(
-        cls, backend: IntoBackend, /
+        cls, backend: IntoBackend[Backend], /
     ) -> Namespace[CompliantNamespaceAny]: ...
 
     @classmethod
     def from_backend(
-        cls: type[Namespace[Any]], backend: IntoBackend, /
+        cls: type[Namespace[Any]], backend: IntoBackend[Backend], /
     ) -> Namespace[Any]:
         """Instantiate from native namespace module, string, or Implementation.
 
@@ -333,6 +324,7 @@ def from_native_object(
     def from_native_object(
         cls: type[Namespace[Any]], native: NativeAny, /
     ) -> Namespace[Any]:
+        impl: Backend
         if is_native_polars(native):
             impl = Implementation.POLARS
         elif is_native_pandas(native):

narwhals/_pandas_like/dataframe.py

@@ -47,15 +47,14 @@
     from narwhals._pandas_like.group_by import PandasLikeGroupBy
     from narwhals._pandas_like.namespace import PandasLikeNamespace
     from narwhals._translate import IntoArrowTable
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dtypes import DType
     from narwhals.typing import (
         AsofJoinStrategy,
         DTypeBackend,
-        EagerImplementation,
         IntoSchema,
         JoinStrategy,
-        LazyImplementation,
         PivotAgg,
         SizedMultiIndexSelector,
         SizedMultiNameSelector,
@@ -492,7 +491,7 @@ def sort(self, *by: str, descending: bool | Sequence[bool], nulls_last: bool) ->
 
     # --- convert ---
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if backend is None:
             return PandasLikeDataFrame(
@@ -760,7 +759,7 @@ def unique(
         )
 
     # --- lazy-only ---
-    def lazy(self, backend: LazyImplementation | None = None) -> CompliantLazyFrameAny:
+    def lazy(self, backend: _LazyAllowedImpl | None = None) -> CompliantLazyFrameAny:
         pandas_df = self.to_pandas()
         if backend is None:
             return self

narwhals/_polars/dataframe.py

@@ -40,14 +40,13 @@
     from narwhals._polars.expr import PolarsExpr
     from narwhals._polars.group_by import PolarsGroupBy, PolarsLazyGroupBy
     from narwhals._translate import IntoArrowTable
+    from narwhals._typing import _EagerAllowedImpl, _LazyAllowedImpl
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dataframe import DataFrame, LazyFrame
     from narwhals.dtypes import DType
     from narwhals.typing import (
-        EagerImplementation,
         IntoSchema,
         JoinStrategy,
-        LazyImplementation,
         MultiColSelector,
         MultiIndexSelector,
         PivotAgg,
@@ -442,7 +441,7 @@ def iter_columns(self) -> Iterator[PolarsSeries]:
         for series in self.native.iter_columns():
             yield PolarsSeries.from_native(series, context=self)
 
-    def lazy(self, backend: LazyImplementation | None = None) -> CompliantLazyFrameAny:
+    def lazy(self, backend: _LazyAllowedImpl | None = None) -> CompliantLazyFrameAny:
         if backend is None or backend is Implementation.POLARS:
             return PolarsLazyFrame.from_native(self.native.lazy(), context=self)
         if backend is Implementation.DUCKDB:
@@ -589,7 +588,7 @@ def collect_schema(self) -> dict[str, DType]:
             raise catch_polars_exception(e) from None
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         try:
             result = self.native.collect(**kwargs)

narwhals/_spark_like/dataframe.py

@@ -41,10 +41,11 @@
     from narwhals._spark_like.expr import SparkLikeExpr
     from narwhals._spark_like.group_by import SparkLikeLazyGroupBy
     from narwhals._spark_like.namespace import SparkLikeNamespace
+    from narwhals._typing import _EagerAllowedImpl
     from narwhals._utils import Version, _LimitedContext
     from narwhals.dataframe import LazyFrame
     from narwhals.dtypes import DType
-    from narwhals.typing import EagerImplementation, JoinStrategy, LazyUniqueKeepStrategy
+    from narwhals.typing import JoinStrategy, LazyUniqueKeepStrategy
 
     SQLFrameDataFrame = BaseDataFrame[Any, Any, Any, Any, Any]
 
@@ -198,7 +199,7 @@ def columns(self) -> list[str]:
         return self._cached_columns
 
     def _collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if backend is Implementation.PANDAS:
             from narwhals._pandas_like.dataframe import PandasLikeDataFrame
@@ -236,7 +237,7 @@ def _collect(
         raise ValueError(msg)  # pragma: no cover
 
     def collect(
-        self, backend: EagerImplementation | None, **kwargs: Any
+        self, backend: _EagerAllowedImpl | None, **kwargs: Any
     ) -> CompliantDataFrameAny:
         if self._implementation.is_pyspark_connect():
             try: