refactor: Deduplicate most Into* typing

`v1` is different for the frame cases #3016 (comment)

Author: dangotbanned

narwhals/_native.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Collection, Iterable, Sized
-from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar, Union, cast
 
 from narwhals.dependencies import (
     get_cudf,
@@ -30,6 +30,14 @@
     _Guard: TypeAlias = "Callable[[Any], TypeIs[T]]"
 
 __all__ = [
+    "IntoDataFrame",
+    "IntoDataFrameT",
+    "IntoFrame",
+    "IntoFrameT",
+    "IntoLazyFrame",
+    "IntoLazyFrameT",
+    "IntoSeries",
+    "IntoSeriesT",
     "NativeAny",
     "NativeArrow",
     "NativeCuDF",
@@ -169,6 +177,94 @@ def dropDuplicatesWithinWatermark(self, *arg: Any, **kwargs: Any) -> Any: ...  #
 NativeUnknown: TypeAlias = "NativeDataFrame | NativeSeries | NativeLazyFrame"
 NativeAny: TypeAlias = "NativeKnown | NativeUnknown"
 
+IntoDataFrame: TypeAlias = NativeDataFrame
+"""Anything which can be converted to a Narwhals DataFrame.
+
+Use this if your function accepts a narwhalifiable object but doesn't care about its backend.
+
+Examples:
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoDataFrame
+    >>> def agnostic_shape(df_native: IntoDataFrame) -> tuple[int, int]:
+    ...     df = nw.from_native(df_native, eager_only=True)
+    ...     return df.shape
+"""
+
+IntoLazyFrame: TypeAlias = Union[NativeLazyFrame, NativeIbis]
+
+IntoFrame: TypeAlias = Union[IntoDataFrame, IntoLazyFrame]
+"""Anything which can be converted to a Narwhals DataFrame or LazyFrame.
+
+Use this if your function can accept an object which can be converted to either
+`nw.DataFrame` or `nw.LazyFrame` and it doesn't care about its backend.
+
+Examples:
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoFrame
+    >>> def agnostic_columns(df_native: IntoFrame) -> list[str]:
+    ...     df = nw.from_native(df_native)
+    ...     return df.collect_schema().names()
+"""
+
+IntoSeries: TypeAlias = NativeSeries
+"""Anything which can be converted to a Narwhals Series.
+
+Use this if your function can accept an object which can be converted to `nw.Series`
+and it doesn't care about its backend.
+
+Examples:
+    >>> from typing import Any
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoSeries
+    >>> def agnostic_to_list(s_native: IntoSeries) -> list[Any]:
+    ...     s = nw.from_native(s_native)
+    ...     return s.to_list()
+"""
+
+IntoFrameT = TypeVar("IntoFrameT", bound=IntoFrame)
+"""TypeVar bound to object convertible to Narwhals DataFrame or Narwhals LazyFrame.
+
+Use this if your function accepts an object which is convertible to `nw.DataFrame`
+or `nw.LazyFrame` and returns an object of the same type.
+
+Examples:
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoFrameT
+    >>> def agnostic_func(df_native: IntoFrameT) -> IntoFrameT:
+    ...     df = nw.from_native(df_native)
+    ...     return df.with_columns(c=nw.col("a") + 1).to_native()
+"""
+
+IntoDataFrameT = TypeVar("IntoDataFrameT", bound=IntoDataFrame)
+"""TypeVar bound to object convertible to Narwhals DataFrame.
+
+Use this if your function accepts an object which can be converted to `nw.DataFrame`
+and returns an object of the same class.
+
+Examples:
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoDataFrameT
+    >>> def agnostic_func(df_native: IntoDataFrameT) -> IntoDataFrameT:
+    ...     df = nw.from_native(df_native, eager_only=True)
+    ...     return df.with_columns(c=df["a"] + 1).to_native()
+"""
+
+IntoLazyFrameT = TypeVar("IntoLazyFrameT", bound=IntoLazyFrame)
+
+IntoSeriesT = TypeVar("IntoSeriesT", bound=IntoSeries)
+"""TypeVar bound to object convertible to Narwhals Series.
+
+Use this if your function accepts an object which can be converted to `nw.Series`
+and returns an object of the same class.
+
+Examples:
+    >>> import narwhals as nw
+    >>> from narwhals.typing import IntoSeriesT
+    >>> def agnostic_abs(s_native: IntoSeriesT) -> IntoSeriesT:
+    ...     s = nw.from_native(s_native, series_only=True)
+    ...     return s.abs().to_native()
+"""
+
 
 def is_native_polars(obj: Any) -> TypeIs[NativePolars]:
     return (pl := get_polars()) is not None and isinstance(

narwhals/stable/v1/typing.py

@@ -2,10 +2,12 @@
 
 from typing import TYPE_CHECKING, Any, Protocol, TypeVar, Union
 
+from narwhals._native import IntoSeries, IntoSeriesT
+
 if TYPE_CHECKING:
     from typing_extensions import TypeAlias
 
-    from narwhals._native import NativeDataFrame, NativeLazyFrame, NativeSeries
+    from narwhals._native import NativeDataFrame, NativeLazyFrame
     from narwhals.stable.v1 import DataFrame, Expr, LazyFrame, Series
 
     class DataFrameLike(Protocol):
@@ -22,7 +24,6 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
 `nw.Expr`, e.g. `df.select('a')`.
 """
 
-
 IntoDataFrame: TypeAlias = Union["NativeDataFrame", "DataFrameLike"]
 """Anything which can be converted to a Narwhals DataFrame.
 
@@ -37,7 +38,6 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
 """
 
 IntoLazyFrame: TypeAlias = "NativeLazyFrame"
-
 IntoFrame: TypeAlias = Union["IntoDataFrame", "IntoLazyFrame"]
 """Anything which can be converted to a Narwhals DataFrame or LazyFrame.
 
@@ -66,21 +66,6 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
     ...     return df.columns
 """
 
-IntoSeries: TypeAlias = "NativeSeries"
-"""Anything which can be converted to a Narwhals Series.
-
-Use this if your function can accept an object which can be converted to `nw.Series`
-and it doesn't care about its backend.
-
-Examples:
-    >>> from typing import Any
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoSeries
-    >>> def agnostic_to_list(s_native: IntoSeries) -> list[Any]:
-    ...     s = nw.from_native(s_native)
-    ...     return s.to_list()
-"""
-
 IntoFrameT = TypeVar("IntoFrameT", bound="IntoFrame")
 """TypeVar bound to object convertible to Narwhals DataFrame or Narwhals LazyFrame.
 
@@ -110,7 +95,6 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
 """
 
 IntoLazyFrameT = TypeVar("IntoLazyFrameT", bound="IntoLazyFrame")
-
 FrameT = TypeVar("FrameT", "DataFrame[Any]", "LazyFrame[Any]")
 """TypeVar bound to Narwhals DataFrame or Narwhals LazyFrame.
 
@@ -139,20 +123,6 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
     ...     return df.with_columns(c=df["a"] + 1)
 """
 
-IntoSeriesT = TypeVar("IntoSeriesT", bound="IntoSeries")
-"""TypeVar bound to object convertible to Narwhals Series.
-
-Use this if your function accepts an object  which can be converted to `nw.Series`
-and returns an object of the same class.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoSeriesT
-    >>> def agnostic_abs(s_native: IntoSeriesT) -> IntoSeriesT:
-    ...     s = nw.from_native(s_native, series_only=True)
-    ...     return s.abs().to_native()
-"""
-
 
 __all__ = [
     "DataFrameT",

narwhals/stable/v2/typing.py

@@ -2,10 +2,20 @@
 
 from typing import TYPE_CHECKING, Any, TypeVar, Union
 
+from narwhals._native import (
+    IntoDataFrame,
+    IntoDataFrameT,
+    IntoFrame,
+    IntoFrameT,
+    IntoLazyFrame,
+    IntoLazyFrameT,
+    IntoSeries,
+    IntoSeriesT,
+)
+
 if TYPE_CHECKING:
     from typing_extensions import TypeAlias
 
-    from narwhals._native import NativeDataFrame, NativeLazyFrame, NativeSeries
     from narwhals.stable.v2 import DataFrame, Expr, LazyFrame, Series
 
 
@@ -19,35 +29,6 @@
 `nw.Expr`, e.g. `df.select('a')`.
 """
 
-IntoDataFrame: TypeAlias = "NativeDataFrame"
-"""Anything which can be converted to a Narwhals DataFrame.
-
-Use this if your function accepts a narwhalifiable object but doesn't care about its backend.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoDataFrame
-    >>> def agnostic_shape(df_native: IntoDataFrame) -> tuple[int, int]:
-    ...     df = nw.from_native(df_native, eager_only=True)
-    ...     return df.shape
-"""
-
-IntoLazyFrame: TypeAlias = "NativeLazyFrame"
-
-IntoFrame: TypeAlias = Union["IntoDataFrame", "IntoLazyFrame"]
-"""Anything which can be converted to a Narwhals DataFrame or LazyFrame.
-
-Use this if your function can accept an object which can be converted to either
-`nw.DataFrame` or `nw.LazyFrame` and it doesn't care about its backend.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoFrame
-    >>> def agnostic_columns(df_native: IntoFrame) -> list[str]:
-    ...     df = nw.from_native(df_native)
-    ...     return df.collect_schema().names()
-"""
-
 Frame: TypeAlias = Union["DataFrame[Any]", "LazyFrame[Any]"]
 """Narwhals DataFrame or Narwhals LazyFrame.
 
@@ -62,49 +43,6 @@
     ...     return df.columns
 """
 
-IntoSeries: TypeAlias = "NativeSeries"
-"""Anything which can be converted to a Narwhals Series.
-
-Use this if your function can accept an object which can be converted to `nw.Series`
-and it doesn't care about its backend.
-
-Examples:
-    >>> from typing import Any
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoSeries
-    >>> def agnostic_to_list(s_native: IntoSeries) -> list[Any]:
-    ...     s = nw.from_native(s_native)
-    ...     return s.to_list()
-"""
-
-IntoFrameT = TypeVar("IntoFrameT", bound="IntoFrame")
-"""TypeVar bound to object convertible to Narwhals DataFrame or Narwhals LazyFrame.
-
-Use this if your function accepts an object which is convertible to `nw.DataFrame`
-or `nw.LazyFrame` and returns an object of the same type.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoFrameT
-    >>> def agnostic_func(df_native: IntoFrameT) -> IntoFrameT:
-    ...     df = nw.from_native(df_native)
-    ...     return df.with_columns(c=nw.col("a") + 1).to_native()
-"""
-
-IntoDataFrameT = TypeVar("IntoDataFrameT", bound="IntoDataFrame")
-"""TypeVar bound to object convertible to Narwhals DataFrame.
-
-Use this if your function accepts an object which can be converted to `nw.DataFrame`
-and returns an object of the same class.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoDataFrameT
-    >>> def agnostic_func(df_native: IntoDataFrameT) -> IntoDataFrameT:
-    ...     df = nw.from_native(df_native, eager_only=True)
-    ...     return df.with_columns(c=df["a"] + 1).to_native()
-"""
-
 FrameT = TypeVar("FrameT", "DataFrame[Any]", "LazyFrame[Any]")
 """TypeVar bound to Narwhals DataFrame or Narwhals LazyFrame.
 
@@ -133,20 +71,6 @@
     ...     return df.with_columns(c=df["a"] + 1)
 """
 
-IntoSeriesT = TypeVar("IntoSeriesT", bound="IntoSeries")
-"""TypeVar bound to object convertible to Narwhals Series.
-
-Use this if your function accepts an object  which can be converted to `nw.Series`
-and returns an object of the same class.
-
-Examples:
-    >>> import narwhals as nw
-    >>> from narwhals.typing import IntoSeriesT
-    >>> def agnostic_abs(s_native: IntoSeriesT) -> IntoSeriesT:
-    ...     s = nw.from_native(s_native, series_only=True)
-    ...     return s.abs().to_native()
-"""
-
 
 __all__ = [
     "DataFrameT",
@@ -157,6 +81,8 @@
     "IntoExpr",
     "IntoFrame",
     "IntoFrameT",
+    "IntoLazyFrame",
+    "IntoLazyFrameT",
     "IntoSeries",
     "IntoSeriesT",
 ]