feat(typing): Make Implementation less opaque

narwhals/dataframe.py

@@ -71,8 +71,21 @@
 
     from narwhals._compliant import CompliantDataFrame, CompliantLazyFrame
     from narwhals._compliant.typing import CompliantExprAny, EagerNamespaceAny
+    from narwhals._namespace import _NativePandasLikeDataFrame
     from narwhals._translate import IntoArrowTable
-    from narwhals._typing import Dask, DuckDB, EagerAllowed, Ibis, IntoBackend, Polars
+    from narwhals._typing import (
+        Dask,
+        DuckDB,
+        EagerAllowed,
+        Ibis,
+        IntoBackend,
+        Polars,
+        _ArrowImpl,
+        _EagerAllowedImpl,
+        _PandasImpl,
+        _PandasLikeImpl,
+        _PolarsImpl,
+    )
     from narwhals.group_by import GroupBy, LazyGroupBy
     from narwhals.typing import (
         AsofJoinStrategy,
@@ -407,6 +420,36 @@ def explode(self, columns: str | Sequence[str], *more_columns: str) -> Self:
         return self._with_compliant(self._compliant_frame.explode(columns=to_explode))
 
 
+class _ImplDescriptor:
+    def __set_name__(self, owner: type[Any], name: str) -> None:
+        self.__name__: str = name
+
+    @overload
+    def __get__(self, instance: DataFrame[pl.DataFrame], owner: Any) -> _PolarsImpl: ...
+    @overload
+    def __get__(self, instance: DataFrame[pd.DataFrame], owner: Any) -> _PandasImpl: ...
+    @overload
+    def __get__(
+        self, instance: DataFrame[_NativePandasLikeDataFrame], owner: Any
+    ) -> _PandasLikeImpl: ...
+    @overload
+    def __get__(self, instance: DataFrame[pa.Table], owner: Any) -> _ArrowImpl: ...
+    @overload
+    def __get__(
+        self, instance: DataFrame[pl.DataFrame | pd.DataFrame | pa.Table], owner: Any
+    ) -> _PolarsImpl | _PandasImpl | _ArrowImpl: ...
+    @overload
+    def __get__(
+        self, instance: DataFrame[IntoDataFrame], owner: Any
+    ) -> _EagerAllowedImpl: ...
+    @overload
+    def __get__(self, instance: None, owner: Any) -> Self: ...
+    def __get__(self, instance: Any | None, owner: Any) -> Any:
+        if instance is None:
+            return self
+        return instance._compliant_frame._implementation
+
+
 class DataFrame(BaseFrame[DataFrameT]):
     """Narwhals DataFrame, backed by a native eager dataframe.
 
@@ -660,28 +703,26 @@ def from_numpy(
         )
         raise ValueError(msg)
 
-    @property
-    def implementation(self) -> Implementation:
-        """Return implementation of native frame.
-
-        This can be useful when you need to use special-casing for features outside of
-        Narwhals' scope - for example, when dealing with pandas' Period Dtype.
-
-        Examples:
-            >>> import narwhals as nw
-            >>> import pandas as pd
-            >>> df_native = pd.DataFrame({"a": [1, 2, 3]})
-            >>> df = nw.from_native(df_native)
-            >>> df.implementation
-            <Implementation.PANDAS: 'pandas'>
-            >>> df.implementation.is_pandas()
-            True
-            >>> df.implementation.is_pandas_like()
-            True
-            >>> df.implementation.is_polars()
-            False
-        """
-        return self._compliant_frame._implementation
+    implementation: _ImplDescriptor = _ImplDescriptor()
+    """Return implementation of native frame.
+
+    This can be useful when you need to use special-casing for features outside of
+    Narwhals' scope - for example, when dealing with pandas' Period Dtype.
+
+    Examples:
+        >>> import narwhals as nw
+        >>> import pandas as pd
+        >>> df_native = pd.DataFrame({"a": [1, 2, 3]})
+        >>> df = nw.from_native(df_native)
+        >>> df.implementation
+        <Implementation.PANDAS: 'pandas'>
+        >>> df.implementation.is_pandas()
+        True
+        >>> df.implementation.is_pandas_like()
+        True
+        >>> df.implementation.is_polars()
+        False
+    """
 
     def __len__(self) -> int:
         return self._compliant_frame.__len__()

tests/expr_and_series/is_close_test.py

@@ -11,7 +11,6 @@
 import pytest
 
 import narwhals as nw
-from narwhals._utils import is_eager_allowed
 from narwhals.exceptions import ComputeError, InvalidOperationError
 from tests.conftest import (
     dask_lazy_p1_constructor,
@@ -114,11 +113,8 @@ def test_is_close_series_with_series(
 ) -> None:
     df = nw.from_native(constructor_eager(data), eager_only=True)
     x, y = df["x"], df["y"]
-    backend = df.implementation
-    assert is_eager_allowed(backend)
-
     nulls = nw.new_series(
-        name="nulls", values=[None] * len(x), dtype=nw.Float64(), backend=backend
+        "nulls", [None] * len(x), nw.Float64(), backend=df.implementation
     )
     x = x.zip_with(x != NAN_PLACEHOLDER, x**0.5).zip_with(x != NULL_PLACEHOLDER, nulls)
     y = y.zip_with(y != NAN_PLACEHOLDER, y**0.5).zip_with(y != NULL_PLACEHOLDER, nulls)
@@ -141,11 +137,8 @@ def test_is_close_series_with_scalar(
 ) -> None:
     df = nw.from_native(constructor_eager(data), eager_only=True)
     y = df["y"]
-    backend = df.implementation
-    assert is_eager_allowed(backend)
-
     nulls = nw.new_series(
-        name="nulls", values=[None] * len(y), dtype=nw.Float64(), backend=backend
+        "nulls", [None] * len(y), nw.Float64(), backend=df.implementation
     )
     y = y.zip_with(y != NAN_PLACEHOLDER, y**0.5).zip_with(y != NULL_PLACEHOLDER, nulls)
     result = y.is_close(other, abs_tol=abs_tol, rel_tol=rel_tol, nans_equal=nans_equal)

utils/check_api_reference.py

@@ -6,7 +6,7 @@
 
 # ruff: noqa: N806
 from collections import deque
-from inspect import isfunction
+from inspect import isfunction, ismethoddescriptor
 from pathlib import Path
 from types import MethodType, ModuleType
 from typing import TYPE_CHECKING, Any
@@ -24,13 +24,14 @@
 
     def _is_public_method_or_property(obj: Any) -> bool:
         return (
-            isfunction(obj) or isinstance(obj, (MethodType, property))
+            isfunction(obj)
+            or (isinstance(obj, (MethodType, property)) or ismethoddescriptor(obj))
         ) and obj.__name__.startswith(LOWERCASE)
 else:
 
     def _is_public_method_or_property(obj: Any) -> bool:
         return (
-            (isfunction(obj) or isinstance(obj, MethodType))
+            (isfunction(obj) or (isinstance(obj, MethodType) or ismethoddescriptor(obj)))
             and obj.__name__.startswith(LOWERCASE)
         ) or (isinstance(obj, property) and obj.fget.__name__.startswith(LOWERCASE))