fix(typing): Overhaul @overloads in nw.from_native

narwhals/_native.py

@@ -190,15 +190,21 @@ def columns(self) -> Any: ...
     def join(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
-class NativeDataFrame(Sized, NativeFrame, Protocol): ...
+class NativeDataFrame(Sized, NativeFrame, Protocol):
+    def drop(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
 class NativeLazyFrame(NativeFrame, Protocol):
     def explain(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
+# Needs to have something `NativeDataFrame` doesn't?
 class NativeSeries(Sized, Iterable[Any], Protocol):
     def filter(self, *args: Any, **kwargs: Any) -> Any: ...
+    # `pd.DataFrame` has this - the others don't
+    def value_counts(self, *args: Any, **kwargs: Any) -> Any: ...
+    # `pl.DataFrame` has this - the others don't
+    def unique(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
 class _BasePandasLike(Sized, Protocol):

narwhals/_translate.py

@@ -1,8 +1,8 @@
-"""[Protocols] defining conversion methods between representations.
+"""[Protocols] defining conversion methods between representations, and related [structural] typing.
 
-These come in 3 flavors and are [generic] to promote reuse.
+The protocols come in 3 flavors and are [generic] to promote reuse.
 
-The following examples use the placeholder types `Narwhal` and `Other`:
+These examples use the placeholder types `Narwhal` and `Other`:
 - `Narwhal`: some class written in `narwhals`.
 - `Other`: any other class, could be native, compliant, or a builtin.
 
@@ -53,6 +53,7 @@ class OtherConvertible(
 
 [Protocols]: https://typing.python.org/en/latest/spec/protocol.html
 [generic]: https://typing.python.org/en/latest/spec/generics.html
+[structural]: https://typing.python.org/en/latest/spec/glossary.html#term-structural
 [upstream signature]: https://numpy.org/doc/stable/user/basics.interoperability.html#the-array-method
 [positional-only]: https://peps.python.org/pep-0570/
 [moist]: https://mypy.readthedocs.io/en/stable/generics.html#variance-of-generic-types
@@ -63,13 +64,13 @@ class OtherConvertible(
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
-from typing import TYPE_CHECKING, Any, Protocol
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypedDict
 
 from narwhals._typing_compat import TypeVar
 
 if TYPE_CHECKING:
     import pyarrow as pa
-    from typing_extensions import Self, TypeAlias, TypeIs
+    from typing_extensions import Required, Self, TypeAlias, TypeIs
 
 
 class ArrowStreamExportable(Protocol):
@@ -184,3 +185,116 @@ class ToNarwhals(Protocol[ToNarwhalsT_co]):
     def to_narwhals(self) -> ToNarwhalsT_co:
         """Convert into public representation."""
         ...
+
+
+class _ExcludeSeries(TypedDict, total=False):
+    eager_only: bool
+    series_only: Literal[False]
+    allow_series: Literal[False] | None
+
+
+class ExcludeSeries(_ExcludeSeries, total=False):
+    pass_through: bool
+
+
+class _AllowSeries(TypedDict, total=False):
+    eager_only: bool
+    series_only: Literal[False]
+    allow_series: Required[Literal[True]]
+
+
+class AllowSeries(_AllowSeries, total=False):
+    pass_through: bool
+
+
+class _OnlySeries(TypedDict, total=False):
+    eager_only: bool
+    series_only: Required[Literal[True]]
+    allow_series: bool | None
+
+
+class OnlySeries(_OnlySeries, total=False):
+    pass_through: bool
+
+
+class _OnlyEager(TypedDict, total=False):
+    eager_only: Required[Literal[True]]
+    series_only: bool
+    allow_series: bool | None
+
+
+class OnlyEager(_OnlyEager, total=False):
+    pass_through: bool
+
+
+class _AllowLazy(TypedDict, total=False):
+    eager_only: Literal[False]
+    series_only: Literal[False]
+    allow_series: bool | None
+
+
+class AllowLazy(_AllowLazy, total=False):
+    pass_through: bool
+
+
+class _AllowAny(TypedDict, total=False):
+    eager_only: Literal[False]
+    series_only: Literal[False]
+    allow_series: Required[Literal[True]]
+
+
+class AllowAny(_AllowAny, total=False):
+    pass_through: bool
+
+
+class _Unknown(TypedDict, total=False):
+    eager_only: bool
+    series_only: bool
+    allow_series: bool | None
+
+
+class PassThroughUnknown(_Unknown, total=False):
+    pass_through: Required[Literal[True]]
+
+
+class PassThroughUnknownV1(_Unknown, total=False):
+    pass_through: Required[Literal[True]]
+    eager_or_interchange_only: bool
+
+
+class StrictUnknownV1(_Unknown, total=False):
+    strict: Required[Literal[False]]
+    eager_or_interchange_only: bool
+
+
+# NOTE: Define everything *without* `pass_through`
+# inherit to add that and then independently for v1 for `strict`
+# which also needs `eager_or_interchange_only`
+class V1(TypedDict, total=False):
+    # mutually exclusive and both include `None` here? :sad:
+    # - Ok
+    #   - None, None
+    #   - bool, None
+    #   - None, bool
+    # - Bad
+    #   - bool, bool
+    strict: bool | None  # None
+    pass_through: bool | None  # None
+
+    # these guys are mutually exclusive *only* when both are `True`
+    # - Ok
+    #   - False, False
+    #   - True, False
+    #   - False, True
+    # - Bad
+    #   - True, True
+    #   - bool, bool
+    #   - True, bool
+    #   - bool, True
+    eager_only: bool  # False
+    # no lazyframe
+    eager_or_interchange_only: bool  # False
+
+    # same as others
+    series_only: bool  # False
+    allow_series: bool | None  # None

narwhals/stable/v1/__init__.py

@@ -65,9 +65,13 @@
     from collections.abc import Iterable, Mapping, Sequence
     from types import ModuleType
 
-    from typing_extensions import ParamSpec, Self
+    from typing_extensions import ParamSpec, Self, Unpack
 
-    from narwhals._translate import IntoArrowTable
+    from narwhals._translate import (
+        IntoArrowTable,
+        PassThroughUnknownV1 as PassThroughUnknown,
+        StrictUnknownV1 as StrictUnknown,
+    )
     from narwhals._typing import (
         Arrow,
         Backend,
@@ -552,18 +556,6 @@ def from_native(
 ) -> DataFrame[IntoDataFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    strict: Literal[False],
-    eager_only: Literal[False] = ...,
-    eager_or_interchange_only: Literal[True],
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT,
@@ -576,18 +568,6 @@ def from_native(
 ) -> DataFrame[IntoDataFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    strict: Literal[False],
-    eager_only: Literal[True],
-    eager_or_interchange_only: Literal[False] = ...,
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT | IntoLazyFrameT | IntoSeriesT,
@@ -636,18 +616,6 @@ def from_native(
 ) -> LazyFrame[IntoLazyFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    strict: Literal[False],
-    eager_only: Literal[False] = ...,
-    eager_or_interchange_only: Literal[False] = ...,
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT,
@@ -756,18 +724,6 @@ def from_native(
 ) -> DataFrame[IntoDataFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    pass_through: Literal[True],
-    eager_only: Literal[False] = ...,
-    eager_or_interchange_only: Literal[True],
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT,
@@ -780,18 +736,6 @@ def from_native(
 ) -> DataFrame[IntoDataFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    pass_through: Literal[True],
-    eager_only: Literal[True],
-    eager_or_interchange_only: Literal[False] = ...,
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT | IntoLazyFrameT | IntoSeriesT,
@@ -828,18 +772,6 @@ def from_native(
 ) -> DataFrame[IntoDataFrameT] | LazyFrame[IntoLazyFrameT]: ...
 
 
-@overload
-def from_native(
-    native_object: T,
-    *,
-    pass_through: Literal[True],
-    eager_only: Literal[False] = ...,
-    eager_or_interchange_only: Literal[False] = ...,
-    series_only: Literal[False] = ...,
-    allow_series: None = ...,
-) -> T: ...
-
-
 @overload
 def from_native(
     native_object: IntoDataFrameT,
@@ -912,6 +844,12 @@ def from_native(
 ) -> LazyFrame[IntoLazyFrameT]: ...
 
 
+@overload
+def from_native(native_object: T, **kwds: Unpack[PassThroughUnknown]) -> T: ...
+@overload
+def from_native(native_object: T, **kwds: Unpack[StrictUnknown]) -> T: ...
+
+
 # All params passed in as variables
 @overload
 def from_native(

narwhals/stable/v1/typing.py

@@ -7,7 +7,7 @@
 if TYPE_CHECKING:
     from typing_extensions import TypeAlias
 
-    from narwhals._native import NativeDataFrame, NativeLazyFrame
+    from narwhals._native import NativeDataFrame, NativeDuckDB, NativeLazyFrame
     from narwhals.stable.v1 import DataFrame, Expr, LazyFrame, Series
 
     class DataFrameLike(Protocol):
@@ -24,7 +24,7 @@ def __dataframe__(self, *args: Any, **kwargs: Any) -> Any: ...
 `nw.Expr`, e.g. `df.select('a')`.
 """
 
-IntoDataFrame: TypeAlias = Union["NativeDataFrame", "DataFrameLike"]
+IntoDataFrame: TypeAlias = Union["NativeDataFrame", "DataFrameLike", "NativeDuckDB"]
 """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.