feat(typing): Make Implementation less opaque

narwhals/_utils.py

@@ -96,7 +96,6 @@
         _ArrowImpl,
         _CudfImpl,
         _DaskImpl,
-        _DataFrameLazyImpl,
         _DuckDBImpl,
         _EagerAllowedImpl,
         _IbisImpl,
@@ -2139,8 +2138,9 @@ def __get__(self, instance: Narwhals[_NativeIbis], owner: Any) -> _IbisImpl: ...
     def __get__(
         self, instance: Narwhals[_NativePySpark | _NativePySparkConnect], owner: Any
     ) -> _PySparkImpl | _PySparkConnectImpl: ...
+    # NOTE: https://docs.python.org/3/howto/descriptor.html#invocation-from-a-class
     @overload
-    def __get__(self, instance: None, owner: Any) -> Self: ...
+    def __get__(self, instance: None, owner: type[Narwhals[Any]]) -> Self: ...
     @overload
     def __get__(
         self, instance: DataFrame[Any] | Series[Any], owner: Any

narwhals/dataframe.py

@@ -27,7 +27,6 @@
     Implementation,
     Version,
     _Implementation,
-    can_dataframe_lazy,
     can_lazyframe_collect,
     check_columns_exist,
     flatten,

tests/implementation_test.py

@@ -73,6 +73,41 @@ def test_implementation_new(member: str, value: str) -> None:
     assert nw.Implementation(value) is getattr(nw.Implementation, member)
 
 
+_TYPING_ONLY_TESTS = "_"
+"""Exhaustive checks for overload matching native -> implementation.
+
+## Arrange
+Each test defines a function accepting a `native` frame.
+
+Important:
+    We *must* use the concrete types and therefore the type checker *needs* the package installed.
+
+Next, wrap `native` as a `nw.{Data,Lazy}Frame`.
+
+Note:
+    If we support multiple native types, use `native` to generate `nw.{LazyFrame,Series}` as well.
+
+Finally, look-up `.implementation` on all wrapped objects.
+
+## Act
+Try passing every result (`*_impl`) to functions that *only* accept a **subset** of `Implementation`.
+
+This step *may require* a `# (type|pyright): ignore` directive, which defines the `# [... Negative]` result.
+Otherwise, results are labelled with `# [... Positive]`.
+
+If this *static* label matches *runtime* we use `# [True ...]`, otherwise `# [False ...]`.
+
+Tip:
+    `# [False Negative]`s are the most frustrating for users.
+    Always try to minimize warning on safe code.
+
+## Assert
+The action determined whether or not our typing warns on an `@overload` match.
+
+We still need to use [`assert_type`] to verify which `Implementation`(s) were returned as a result.
+
+[`assert_type`]: https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.assert_type
+"""
 if TYPE_CHECKING:
     import dask.dataframe as dd
     import duckdb
@@ -179,8 +214,9 @@ def test_sqlframe_typing(native: BaseDataFrame[Any, Any, Any, Any, Any]) -> None
 
         ldf_impl = ldf.implementation
 
+        # [True Positive]
+        any_df.lazy(ldf_impl)
         # [True Negative]
-        any_df.lazy(ldf_impl)  # pyright: ignore[reportArgumentType]
         any_ldf.collect(ldf_impl)  # pyright: ignore[reportArgumentType]
 
         assert_type(ldf.implementation, _SQLFrameImpl)
@@ -254,7 +290,9 @@ def test_bound_typing() -> None:
 
         # [True Negative]
         any_df.lazy(df_impl)  # type: ignore[arg-type]
-        any_df.lazy(ldf_impl)  # type: ignore[arg-type]
+        # [True Positive]
+        any_df.lazy(ldf_impl)
+        # [True Negative]
         any_df.lazy(ser_impl)  # type: ignore[arg-type]
         any_ldf.collect(df_impl)  # type: ignore[arg-type]
         any_ldf.collect(ldf_impl)  # type: ignore[arg-type]

utils/check_api_reference.py

@@ -5,7 +5,7 @@
 import sys
 
 # ruff: noqa: N806
-from collections import deque
+from collections import OrderedDict, deque
 from inspect import isfunction, ismethoddescriptor
 from pathlib import Path
 from types import MethodType, ModuleType
@@ -223,7 +223,11 @@ def read_documented_members(source: str | Path) -> list[str]:
 # Schema
 schema_methods = list(iter_api_reference_names(nw.Schema))
 documented = read_documented_members(DIR_API_REF / "schema.md")
-if missing := set(schema_methods).difference(documented):
+if (
+    missing := set(schema_methods)
+    .difference(documented)
+    .difference(iter_api_reference_names(OrderedDict))
+):
     print("Schema: not documented")  # noqa: T201
     print(missing)  # noqa: T201
     ret = 1