feat: introduce (experimental) plugin system

.github/workflows/pytest.yml

@@ -84,6 +84,9 @@ jobs:
           cache-suffix: pytest-full-coverage-${{ matrix.python-version }}
           cache-dependency-glob: "pyproject.toml"
       - name: install-reqs
+        run: uv pip install -e ".[dask, modin, ibis]" --group core-tests --group extra --system
+      - name: install-test-plugin
+        run: uv pip install -e tests/test_plugin --system
         # TODO(FBruzzesi): Unpin duckdb version once ibis makes a new release
         run: uv pip install -e ".[dask, modin, ibis]" --group core-tests --group extra "duckdb<1.4" --system
       - name: show-deps

.pre-commit-config.yaml

@@ -94,7 +94,10 @@ repos:
   rev: v6.0.0
   hooks:
   -   id: name-tests-test
-      exclude: ^tests/utils\.py
+      exclude: |
+        (?x)
+          ^(tests/utils\.py)
+          |^(tests/test_plugin/)
   -   id: no-commit-to-branch
   -   id: end-of-file-fixer
       exclude: .svg$

narwhals/_utils.py

@@ -2,6 +2,7 @@
 
 import os
 import re
+import sys
 from collections.abc import Collection, Container, Iterable, Iterator, Mapping, Sequence
 from datetime import timezone
 from enum import Enum, auto

narwhals/plugins.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import sys
+from functools import cache
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+from narwhals._compliant import CompliantNamespace
+from narwhals._typing_compat import TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from importlib.metadata import EntryPoints
+
+    from typing_extensions import LiteralString, TypeAlias
+
+    from narwhals._compliant.typing import (
+        CompliantDataFrameAny,
+        CompliantFrameAny,
+        CompliantLazyFrameAny,
+        CompliantSeriesAny,
+    )
+    from narwhals.utils import Version
+
+
+__all__ = ["Plugin", "from_native"]
+
+CompliantAny: TypeAlias = (
+    "CompliantDataFrameAny | CompliantLazyFrameAny | CompliantSeriesAny"
+)
+"""A statically-unknown, Compliant object originating from a plugin."""
+
+FrameT = TypeVar(
+    "FrameT",
+    bound="CompliantFrameAny",
+    default="CompliantDataFrameAny | CompliantLazyFrameAny",
+)
+FromNativeR_co = TypeVar(
+    "FromNativeR_co", bound=CompliantAny, covariant=True, default=CompliantAny
+)
+
+
+@cache
+def _discover_entrypoints() -> EntryPoints:
+    from importlib.metadata import entry_points as eps
+
+    group = "narwhals.plugins"
+    if sys.version_info < (3, 10):
+        return cast("EntryPoints", eps().get(group, ()))
+    return eps(group=group)
+
+
+class PluginNamespace(CompliantNamespace[FrameT, Any], Protocol[FrameT, FromNativeR_co]):
+    def from_native(self, data: Any, /) -> FromNativeR_co: ...
+
+
+class Plugin(Protocol[FrameT, FromNativeR_co]):
+    NATIVE_PACKAGE: LiteralString
+
+    def __narwhals_namespace__(
+        self, version: Version
+    ) -> PluginNamespace[FrameT, FromNativeR_co]: ...
+    def is_native(self, native_object: object, /) -> bool: ...
+
+
+@cache
+def _might_be(cls: type, type_: str) -> bool:
+    try:
+        return any(type_ in o.__module__.split(".") for o in cls.mro())
+    except TypeError:
+        return False
+
+
+def _is_native_plugin(native_object: Any, plugin: Plugin) -> bool:
+    pkg = plugin.NATIVE_PACKAGE
+    return (
+        sys.modules.get(pkg) is not None
+        and _might_be(type(native_object), pkg)  # type: ignore[arg-type]
+        and plugin.is_native(native_object)
+    )
+
+
+def _iter_from_native(native_object: Any, version: Version) -> Iterator[CompliantAny]:
+    for entry_point in _discover_entrypoints():
+        plugin: Plugin = entry_point.load()
+        if _is_native_plugin(native_object, plugin):
+            compliant_namespace = plugin.__narwhals_namespace__(version=version)
+            yield compliant_namespace.from_native(native_object)
+
+
+def from_native(native_object: Any, version: Version) -> CompliantAny | None:
+    """Attempt to convert `native_object` to a Compliant object, using any available plugin(s).
+
+    Arguments:
+        native_object: Raw object from user.
+        version: Narwhals API version.
+
+    Returns:
+        If the following conditions are met
+            - at least 1 plugin is installed
+            - at least 1 installed plugin supports `type(native_object)`
+
+        Then for the **first matching plugin**, the result of the call below.
+        This *should* be an object accepted by a Narwhals Dataframe, Lazyframe, or Series:
+
+            plugin: Plugin
+            plugin.__narwhals_namespace__(version).from_native(native_object)
+
+        In all other cases, `None` is returned instead.
+    """
+    return next(_iter_from_native(native_object, version), None)

narwhals/stable/v2/__init__.py

@@ -554,6 +554,7 @@ def from_native(  # noqa: D417
         eager_only=eager_only,
         series_only=series_only,
         allow_series=allow_series,
+        eager_or_interchange_only=False,
         version=Version.V2,
     )
 

narwhals/translate.py

@@ -5,14 +5,22 @@
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar, overload
 
+from narwhals import plugins
 from narwhals._constants import EPOCH, MS_PER_SECOND
 from narwhals._namespace import (
     is_native_arrow,
     is_native_pandas_like,
     is_native_polars,
     is_native_spark_like,
 )
-from narwhals._utils import Implementation, Version, has_native_namespace
+from narwhals._utils import (
+    Implementation,
+    Version,
+    has_native_namespace,
+    is_compliant_dataframe,
+    is_compliant_lazyframe,
+    is_compliant_series,
+)
 from narwhals.dependencies import (
     get_dask_expr,
     get_numpy,
@@ -314,23 +322,65 @@ def from_native(  # noqa: D417
     )
 
 
+def _translate_if_compliant(  # noqa: C901,PLR0911
+    compliant_object: Any,
+    *,
+    pass_through: bool = False,
+    eager_only: bool = False,
+    # Interchange-level was removed after v1
+    eager_or_interchange_only: bool,
+    series_only: bool,
+    allow_series: bool | None,
+    version: Version,
+) -> Any:
+    if is_compliant_dataframe(compliant_object):
+        if series_only:
+            if not pass_through:
+                msg = "Cannot only use `series_only` with dataframe"
+                raise TypeError(msg)
+            return compliant_object
+        return version.dataframe(
+            compliant_object.__narwhals_dataframe__()._with_version(version), level="full"
+        )
+    if is_compliant_lazyframe(compliant_object):
+        if series_only:
+            if not pass_through:
+                msg = "Cannot only use `series_only` with lazyframe"
+                raise TypeError(msg)
+            return compliant_object
+        if eager_only or eager_or_interchange_only:
+            if not pass_through:
+                msg = "Cannot only use `eager_only` or `eager_or_interchange_only` with lazyframe"
+                raise TypeError(msg)
+            return compliant_object
+        return version.lazyframe(
+            compliant_object.__narwhals_lazyframe__()._with_version(version), level="full"
+        )
+    if is_compliant_series(compliant_object):
+        if not allow_series:
+            if not pass_through:
+                msg = "Please set `allow_series=True` or `series_only=True`"
+                raise TypeError(msg)
+            return compliant_object
+        return version.series(
+            compliant_object.__narwhals_series__()._with_version(version), level="full"
+        )
+    # Object wasn't compliant, can't translate here.
+    return None
+
+
 def _from_native_impl(  # noqa: C901, PLR0911, PLR0912, PLR0915
     native_object: Any,
     *,
     pass_through: bool = False,
     eager_only: bool = False,
     # Interchange-level was removed after v1
-    eager_or_interchange_only: bool = False,
-    series_only: bool = False,
-    allow_series: bool | None = None,
+    eager_or_interchange_only: bool,
+    series_only: bool,
+    allow_series: bool | None,
     version: Version,
 ) -> Any:
     from narwhals._interchange.dataframe import supports_dataframe_interchange
-    from narwhals._utils import (
-        is_compliant_dataframe,
-        is_compliant_lazyframe,
-        is_compliant_series,
-    )
     from narwhals.dataframe import DataFrame, LazyFrame
     from narwhals.series import Series
 
@@ -350,38 +400,18 @@ def _from_native_impl(  # noqa: C901, PLR0911, PLR0912, PLR0915
         raise ValueError(msg)
 
     # Extensions
-    if is_compliant_dataframe(native_object):
-        if series_only:
-            if not pass_through:
-                msg = "Cannot only use `series_only` with dataframe"
-                raise TypeError(msg)
-            return native_object
-        return version.dataframe(
-            native_object.__narwhals_dataframe__()._with_version(version), level="full"
-        )
-    if is_compliant_lazyframe(native_object):
-        if series_only:
-            if not pass_through:
-                msg = "Cannot only use `series_only` with lazyframe"
-                raise TypeError(msg)
-            return native_object
-        if eager_only or eager_or_interchange_only:
-            if not pass_through:
-                msg = "Cannot only use `eager_only` or `eager_or_interchange_only` with lazyframe"
-                raise TypeError(msg)
-            return native_object
-        return version.lazyframe(
-            native_object.__narwhals_lazyframe__()._with_version(version), level="full"
-        )
-    if is_compliant_series(native_object):
-        if not allow_series:
-            if not pass_through:
-                msg = "Please set `allow_series=True` or `series_only=True`"
-                raise TypeError(msg)
-            return native_object
-        return version.series(
-            native_object.__narwhals_series__()._with_version(version), level="full"
+    if (
+        translated := _translate_if_compliant(
+            native_object,
+            pass_through=pass_through,
+            eager_only=eager_only,
+            eager_or_interchange_only=eager_or_interchange_only,
+            series_only=series_only,
+            allow_series=allow_series,
+            version=version,
         )
+    ) is not None:
+        return translated
 
     # Polars
     if is_native_polars(native_object):
@@ -534,6 +564,18 @@ def _from_native_impl(  # noqa: C901, PLR0911, PLR0912, PLR0915
             raise TypeError(msg)
         return Version.V1.dataframe(InterchangeFrame(native_object), level="interchange")
 
+    compliant_object = plugins.from_native(native_object, version)
+    if compliant_object is not None:
+        return _translate_if_compliant(
+            compliant_object,
+            pass_through=pass_through,
+            eager_only=eager_only,
+            eager_or_interchange_only=eager_or_interchange_only,
+            series_only=series_only,
+            allow_series=allow_series,
+            version=version,
+        )
+
     if not pass_through:
         msg = f"Expected pandas-like dataframe, Polars dataframe, or Polars lazyframe, got: {type(native_object)}"
         raise TypeError(msg)

tests/plugins_test.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+import narwhals as nw
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="3.10+ required for entrypoints")
+def test_plugin() -> None:
+    pytest.importorskip("test_plugin")
+    df_native = {"a": [1, 1, 2], "b": [4, 5, 6]}
+    lf = nw.from_native(df_native)  # type: ignore[call-overload]
+    assert isinstance(lf, nw.LazyFrame)
+    assert lf.columns == ["a", "b"]

tests/test_plugin/pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "test_plugin"
+version = "0.1.0"
+
+[project.entry-points.'narwhals.plugins']
+test-plugin = 'test_plugin'

tests/test_plugin/test_plugin/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeIs
+
+    from narwhals.utils import Version
+    from tests.test_plugin.test_plugin.dataframe import DictFrame
+    from tests.test_plugin.test_plugin.namespace import DictNamespace
+
+
+def __narwhals_namespace__(version: Version) -> DictNamespace:  # noqa: N807
+    from tests.test_plugin.test_plugin.namespace import DictNamespace
+
+    return DictNamespace(version=version)
+
+
+def is_native(native_object: object) -> TypeIs[DictFrame]:
+    return isinstance(native_object, dict)
+
+
+NATIVE_PACKAGE = "builtins"