diff --git a/docs/api-reference/narwhals.md b/docs/api-reference/narwhals.md index 103aeb042..b8ec2d793 100644 --- a/docs/api-reference/narwhals.md +++ b/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 diff --git a/narwhals/__init__.py b/narwhals/__init__.py index 3708c3e88..e00300f73 100644 --- a/narwhals/__init__.py +++ b/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", diff --git a/narwhals/functions.py b/narwhals/functions.py index 1369e4ba6..98ec5fc44 100644 --- a/narwhals/functions.py +++ b/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) diff --git a/narwhals/stable/v1/__init__.py b/narwhals/stable/v1/__init__.py index 71a2d3296..05249cd1e 100644 --- a/narwhals/stable/v1/__init__.py +++ b/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", ] diff --git a/tests/from_pycapsule_test.py b/tests/from_pycapsule_test.py index bdf4a15e3..7ab8f1fe8 100644 --- a/tests/from_pycapsule_test.py +++ b/tests/from_pycapsule_test.py @@ -11,20 +11,20 @@ @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) @@ -32,14 +32,14 @@ def test_from_pycapsule_to_polars(monkeypatch: pytest.MonkeyPatch) -> None: @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]