correct procotol signature and name, use from_arrow instead of from_p…

…ycapsule

docs/api-reference/narwhals.md

@@ -14,7 +14,7 @@ Here are the top-level functions available in Narwhals.
         - concat_str
         - from_dict
         - from_native
-        - from_pycapsule
+        - from_arrow
         - get_level
         - get_native_namespace
         - is_ordered_categorical

narwhals/__init__.py

@@ -44,8 +44,8 @@
 from narwhals.expr import sum_horizontal
 from narwhals.expr import when
 from narwhals.functions import concat
+from narwhals.functions import from_arrow
 from narwhals.functions import from_dict
-from narwhals.functions import from_pycapsule
 from narwhals.functions import get_level
 from narwhals.functions import new_series
 from narwhals.functions import show_versions
@@ -69,7 +69,7 @@
     "selectors",
     "concat",
     "from_dict",
-    "from_pycapsule",
+    "from_arrow",
     "get_level",
     "new_series",
     "to_native",

narwhals/functions.py

@@ -31,8 +31,10 @@
     from narwhals.series import Series
     from narwhals.typing import DTypes
 
-    class SupportsPyCapsule(Protocol):
-        def __arrow_c_stream__(self) -> Any: ...
+    class ArrowStreamExportable(Protocol):
+        def __arrow_c_stream__(
+            self, requested_schema: object | None = None
+        ) -> object: ...
 
 
 def concat(
@@ -411,8 +413,8 @@ def _from_dict_impl(
     return from_native(native_frame, eager_only=True)
 
 
-def from_pycapsule(
-    native_frame: SupportsPyCapsule, *, native_namespace: ModuleType
+def from_arrow(
+    native_frame: ArrowStreamExportable, *, native_namespace: ModuleType
 ) -> DataFrame[Any]:
     """
     Construct a DataFrame from an object which supports the PyCapsule Interface.
@@ -433,7 +435,7 @@ def from_pycapsule(
 
         >>> @nw.narwhalify
         ... def func(df):
-        ...     return nw.from_pycapsule(df, native_namespace=pa)
+        ...     return nw.from_arrow(df, native_namespace=pa)
 
         Let's see what happens when passing pandas / Polars input:
 
@@ -472,10 +474,10 @@ def from_pycapsule(
         try:
             import pyarrow as pa  # ignore-banned-import
         except ModuleNotFoundError as exc:  # pragma: no cover
-            msg = f"PyArrow>=14.0.0 is required for `from_pycapsule` for object of type {native_namespace}"
+            msg = f"PyArrow>=14.0.0 is required for `from_arrow` for object of type {native_namespace}"
             raise ModuleNotFoundError(msg) from exc
         if parse_version(pa.__version__) < (14, 0):  # pragma: no cover
-            msg = f"PyArrow>=14.0.0 is required for `from_pycapsule` for object of type {native_namespace}"
+            msg = f"PyArrow>=14.0.0 is required for `from_arrow` for object of type {native_namespace}"
             raise ModuleNotFoundError(msg) from None
 
         tbl = pa.table(native_frame)

narwhals/stable/v1/__init__.py

@@ -21,7 +21,7 @@
 from narwhals.expr import when as nw_when
 from narwhals.functions import _from_dict_impl
 from narwhals.functions import _new_series_impl
-from narwhals.functions import from_pycapsule as nw_from_pycapsule
+from narwhals.functions import from_arrow as nw_from_arrow
 from narwhals.functions import show_versions
 from narwhals.schema import Schema as NwSchema
 from narwhals.series import Series as NwSeries
@@ -65,7 +65,7 @@
     from typing_extensions import Self
 
     from narwhals.dtypes import DType
-    from narwhals.functions import SupportsPyCapsule
+    from narwhals.functions import ArrowStreamExportable
     from narwhals.typing import IntoExpr
 
 T = TypeVar("T")
@@ -2183,8 +2183,8 @@ def new_series(
     )
 
 
-def from_pycapsule(
-    native_frame: SupportsPyCapsule, *, native_namespace: ModuleType
+def from_arrow(
+    native_frame: ArrowStreamExportable, *, native_namespace: ModuleType
 ) -> DataFrame[Any]:
     """
     Construct a DataFrame from an object which supports the PyCapsule Interface.
@@ -2205,7 +2205,7 @@ def from_pycapsule(
 
         >>> @nw.narwhalify
         ... def func(df):
-        ...     return nw.from_pycapsule(df, native_namespace=pa)
+        ...     return nw.from_arrow(df, native_namespace=pa)
 
         Let's see what happens when passing pandas / Polars input:
 
@@ -2225,7 +2225,7 @@ def from_pycapsule(
         b: [[4,5,6]]
     """
     return _stableify(  # type: ignore[no-any-return]
-        nw_from_pycapsule(native_frame, native_namespace=native_namespace)
+        nw_from_arrow(native_frame, native_namespace=native_namespace)
     )
 
 
@@ -2352,6 +2352,6 @@ def from_dict(
     "show_versions",
     "Schema",
     "from_dict",
-    "from_pycapsule",
+    "from_arrow",
     "new_series",
 ]

tests/from_pycapsule_test.py

@@ -11,35 +11,35 @@
 
 
 @pytest.mark.xfail(parse_version(pa.__version__) < (14,), reason="too old")
-def test_from_pycapsule_to_arrow() -> None:
+def test_from_arrow_to_arrow() -> None:
     df = nw.from_native(pl.DataFrame({"ab": [1, 2, 3], "ba": [4, 5, 6]}), eager_only=True)
-    result = nw.from_pycapsule(df, native_namespace=pa)
+    result = nw.from_arrow(df, native_namespace=pa)
     assert isinstance(result.to_native(), pa.Table)
     expected = {"ab": [1, 2, 3], "ba": [4, 5, 6]}
     compare_dicts(result, expected)
 
 
 @pytest.mark.xfail(parse_version(pa.__version__) < (14,), reason="too old")
-def test_from_pycapsule_to_polars(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_from_arrow_to_polars(monkeypatch: pytest.MonkeyPatch) -> None:
     tbl = pa.table({"ab": [1, 2, 3], "ba": [4, 5, 6]})
     monkeypatch.delitem(sys.modules, "pandas")
     df = nw.from_native(tbl, eager_only=True)
-    result = nw.from_pycapsule(df, native_namespace=pl)
+    result = nw.from_arrow(df, native_namespace=pl)
     assert isinstance(result.to_native(), pl.DataFrame)
     expected = {"ab": [1, 2, 3], "ba": [4, 5, 6]}
     compare_dicts(result, expected)
     assert "pandas" not in sys.modules
 
 
 @pytest.mark.xfail(parse_version(pa.__version__) < (14,), reason="too old")
-def test_from_pycapsule_to_pandas() -> None:
+def test_from_arrow_to_pandas() -> None:
     df = nw.from_native(pa.table({"ab": [1, 2, 3], "ba": [4, 5, 6]}), eager_only=True)
-    result = nw.from_pycapsule(df, native_namespace=pd)
+    result = nw.from_arrow(df, native_namespace=pd)
     assert isinstance(result.to_native(), pd.DataFrame)
     expected = {"ab": [1, 2, 3], "ba": [4, 5, 6]}
     compare_dicts(result, expected)
 
 
-def test_from_pycapsule_invalid() -> None:
+def test_from_arrow_invalid() -> None:
     with pytest.raises(TypeError, match="PyCapsule"):
-        nw.from_pycapsule({"a": [1]}, native_namespace=pa)  # type: ignore[arg-type]
+        nw.from_arrow({"a": [1]}, native_namespace=pa)  # type: ignore[arg-type]