feat: introduce (experimental) plugin system

.github/workflows/pytest.yml

@@ -84,6 +84,8 @@ jobs:
           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
       - name: show-deps
         run: uv pip freeze
       - name: Run pytest

.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
@@ -50,6 +51,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Set  # noqa: PYI025
+    from importlib.metadata import EntryPoints
     from types import ModuleType
 
     import pandas as pd
@@ -72,7 +74,12 @@
         CompliantSeriesT,
         NativeSeriesT_co,
     )
-    from narwhals._compliant.typing import EvalNames, NativeDataFrameT, NativeLazyFrameT
+    from narwhals._compliant.typing import (
+        CompliantNamespaceAny,
+        EvalNames,
+        NativeDataFrameT,
+        NativeLazyFrameT,
+    )
     from narwhals._namespace import (
         Namespace,
         _NativeArrow,
@@ -2062,6 +2069,37 @@ def deep_getattr(obj: Any, name_1: str, *nested: str) -> Any:
     return deep_attrgetter(name_1, *nested)(obj)
 
 
+@cache
+def discover_entrypoints() -> EntryPoints:
+    import sys
+    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)
+
+
+# @mp: should the protocol be defined in namespace?
+class Plugin2(Protocol):
+    NATIVE_PACKAGE: LiteralString
+
+    def __narwhals_namespace__(self, version: Version) -> CompliantNamespaceAny: ...
+
+
+@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: Plugin2) -> bool:
+    pkg = plugin.NATIVE_PACKAGE
+    return sys.modules.get(pkg) is not None and _might_be(type(native_object), pkg)
+
+
 class Compliant(
     _StoresNative[NativeT_co], _StoresImplementation, Protocol[NativeT_co]
 ): ...

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

@@ -12,7 +12,16 @@
     is_native_polars,
     is_native_spark_like,
 )
-from narwhals._utils import Implementation, Version, has_native_namespace
+from narwhals._utils import (
+    Implementation,
+    Version,
+    _is_native_plugin,
+    discover_entrypoints,
+    has_native_namespace,
+    is_compliant_dataframe,
+    is_compliant_lazyframe,
+    is_compliant_series,
+)
 from narwhals.dependencies import (
     get_dask_expr,
     get_numpy,
@@ -314,23 +323,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 +401,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 +565,21 @@ def _from_native_impl(  # noqa: C901, PLR0911, PLR0912, PLR0915
             raise TypeError(msg)
         return Version.V1.dataframe(InterchangeFrame(native_object), level="interchange")
 
+    for entry_point in discover_entrypoints():
+        plugin = entry_point.load()
+        if _is_native_plugin(native_object, plugin):
+            compliant_namespace = plugin.__narwhals_namespace__(version=version)
+            compliant_object = compliant_namespace.from_native(native_object)
+            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,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from narwhals.utils import Version
+    from tests.test_plugin.test_plugin.dataframe import DictFrame as 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)
+
+
+NATIVE_PACKAGE = "builtins"

tests/test_plugin/test_plugin/dataframe.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+from narwhals._utils import (
+    Implementation,
+    ValidateBackendVersion,
+    Version,
+    not_implemented,
+)
+from narwhals.typing import CompliantLazyFrame
+
+DictFrame: TypeAlias = dict[str, list[Any]]
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals import LazyFrame  # noqa: F401
+
+
+class DictLazyFrame(
+    CompliantLazyFrame[Any, "DictFrame", "LazyFrame[DictFrame]"],  # type: ignore[type-var]
+    ValidateBackendVersion,
+):
+    _implementation = Implementation.UNKNOWN
+
+    def __init__(self, native_dataframe: DictFrame, *, version: Version) -> None:
+        self._native_frame: DictFrame = native_dataframe
+        self._version = version
+
+    def __narwhals_lazyframe__(self) -> Self:
+        return self
+
+    def _with_version(self, version: Version) -> Self:
+        return self.__class__(self._native_frame, version=version)
+
+    @property
+    def columns(self) -> list[str]:
+        return list(self._native_frame.keys())
+
+    # Dunders
+    __narwhals_namespace__ = not_implemented()
+    __native_namespace__ = not_implemented()
+
+    # Properties
+    schema = not_implemented()  # type: ignore[assignment]
+
+    # Static
+    _is_native = not_implemented()  # type: ignore[assignment]
+
+    # Helpers
+    _iter_columns = not_implemented()
+
+    # Functions
+    aggregate = not_implemented()
+    collect = not_implemented()
+    collect_schema = not_implemented()
+    drop = not_implemented()
+    drop_nulls = not_implemented()
+    explode = not_implemented()
+    filter = not_implemented()
+    from_native = not_implemented()
+    group_by = not_implemented()
+    head = not_implemented()
+    join = not_implemented()
+    join_asof = not_implemented()
+    rename = not_implemented()
+    select = not_implemented()
+    simple_select = not_implemented()
+    sink_parquet = not_implemented()
+    sort = not_implemented()
+    tail = not_implemented()
+    to_narwhals = not_implemented()
+    unique = not_implemented()
+    unpivot = not_implemented()
+    with_columns = not_implemented()
+    with_row_index = not_implemented()