feat: Add Series.from_numpy (#2893)

Author: dangotbanned

docs/api-reference/series.md

@@ -29,6 +29,7 @@
         - exp
         - fill_null
         - filter
+        - from_numpy
         - gather_every
         - head
         - hist

narwhals/dtypes.py

@@ -7,12 +7,17 @@
 from itertools import starmap
 from typing import TYPE_CHECKING
 
-from narwhals._utils import _DeferredIterable, isinstance_or_issubclass
+from narwhals._utils import (
+    _DeferredIterable,
+    isinstance_or_issubclass,
+    qualified_type_name,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
+    from typing import Any
 
-    from typing_extensions import Self
+    from typing_extensions import Self, TypeIs
 
     from narwhals.typing import IntoDType, TimeUnit
 
@@ -26,6 +31,34 @@ def _validate_dtype(dtype: DType | type[DType]) -> None:
         raise TypeError(msg)
 
 
+def _is_into_dtype(obj: Any) -> TypeIs[IntoDType]:
+    return isinstance(obj, DType) or (
+        isinstance(obj, type)
+        and issubclass(obj, DType)
+        and not issubclass(obj, NestedType)
+    )
+
+
+def _is_nested_type(obj: Any) -> TypeIs[type[NestedType]]:
+    return isinstance(obj, type) and issubclass(obj, NestedType)
+
+
+def _validate_into_dtype(dtype: Any) -> None:
+    if not _is_into_dtype(dtype):
+        if _is_nested_type(dtype):
+            name = f"nw.{dtype.__name__}"
+            msg = (
+                f"{name!r} is not valid in this context.\n\n"
+                f"Hint: instead of:\n\n"
+                f"    {name}\n\n"
+                "use:\n\n"
+                f"    {name}(...)"
+            )
+        else:
+            msg = f"Expected Narwhals dtype, got: {qualified_type_name(dtype)!r}."
+        raise TypeError(msg)
+
+
 class DType:
     def __repr__(self) -> str:  # pragma: no cover
         return self.__class__.__qualname__

narwhals/series.py

@@ -2,19 +2,21 @@
 
 import math
 from collections.abc import Iterator, Mapping, Sequence
-from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, overload
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, Literal, overload
 
 from narwhals._utils import (
     Implementation,
+    Version,
     _validate_rolling_arguments,
     ensure_type,
     generate_repr,
     is_compliant_series,
+    is_eager_allowed,
     is_index_selector,
     supports_arrow_c_stream,
 )
-from narwhals.dependencies import is_numpy_scalar
-from narwhals.dtypes import _validate_dtype
+from narwhals.dependencies import is_numpy_array_1d, is_numpy_scalar
+from narwhals.dtypes import _validate_dtype, _validate_into_dtype
 from narwhals.exceptions import ComputeError
 from narwhals.series_cat import SeriesCatNamespace
 from narwhals.series_dt import SeriesDateTimeNamespace
@@ -70,6 +72,8 @@ class Series(Generic[IntoSeriesT]):
             ```
     """
 
+    _version: ClassVar[Version] = Version.MAIN
+
     @property
     def _dataframe(self) -> type[DataFrame[Any]]:
         from narwhals.dataframe import DataFrame
@@ -88,6 +92,74 @@ def __init__(
             msg = f"Expected Polars Series or an object which implements `__narwhals_series__`, got: {type(series)}."
             raise AssertionError(msg)
 
+    @classmethod
+    def from_numpy(
+        cls,
+        name: str,
+        values: _1DArray,
+        dtype: IntoDType | None = None,
+        *,
+        backend: ModuleType | Implementation | str,
+    ) -> Series[Any]:
+        """Construct a Series from a NumPy ndarray.
+
+        Arguments:
+            name: Name of resulting Series.
+            values: One-dimensional data represented as a NumPy ndarray.
+            dtype: (Narwhals) dtype. If not provided, the native library
+                may auto-infer it from `values`.
+            backend: specifies which eager backend instantiate to.
+
+                `backend` can be specified in various ways
+
+                - As `Implementation.<BACKEND>` with `BACKEND` being `PANDAS`, `PYARROW`,
+                    `POLARS`, `MODIN` or `CUDF`.
+                - As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`.
+                - Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`.
+
+        Returns:
+            A new Series
+
+        Examples:
+            >>> import numpy as np
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>>
+            >>> arr = np.arange(5, 10)
+            >>> nw.Series.from_numpy("arr", arr, dtype=nw.Int8, backend="polars")
+            ┌──────────────────┐
+            | Narwhals Series  |
+            |------------------|
+            |shape: (5,)       |
+            |Series: 'arr' [i8]|
+            |[                 |
+            |        5         |
+            |        6         |
+            |        7         |
+            |        8         |
+            |        9         |
+            |]                 |
+            └──────────────────┘
+        """
+        if not is_numpy_array_1d(values):
+            msg = "`from_numpy` only accepts 1D numpy arrays"
+            raise ValueError(msg)
+        if dtype:
+            _validate_into_dtype(dtype)
+        implementation = Implementation.from_backend(backend)
+        if is_eager_allowed(implementation):
+            ns = cls._version.namespace.from_backend(implementation).compliant
+            compliant = ns.from_numpy(values).alias(name)
+            if dtype:
+                return cls(compliant.cast(dtype), level="full")
+            return cls(compliant, level="full")
+        msg = (
+            f"{implementation} support in Narwhals is lazy-only, but `Series.from_numpy` is an eager-only function.\n\n"
+            "Hint: you may want to use an eager backend and then call `.lazy`, e.g.:\n\n"
+            f"    nw.Series.from_numpy(arr, backend='pyarrow').to_frame().lazy('{implementation}')"
+        )
+        raise ValueError(msg)
+
     @property
     def implementation(self) -> Implementation:
         """Return implementation of native Series.

narwhals/stable/v1/__init__.py

@@ -287,6 +287,8 @@ def with_row_index(
 
 
 class Series(NwSeries[IntoSeriesT]):
+    _version = Version.V1
+
     @inherit_doc(NwSeries)
     def __init__(
         self, series: Any, *, level: Literal["full", "lazy", "interchange"]
@@ -297,6 +299,18 @@ def __init__(
     # We need to override any method which don't return Self so that type
     # annotations are correct.
 
+    @classmethod
+    def from_numpy(
+        cls,
+        name: str,
+        values: _1DArray,
+        dtype: IntoDType | None = None,
+        *,
+        backend: ModuleType | Implementation | str,
+    ) -> Series[Any]:
+        result = super().from_numpy(name, values, dtype, backend=backend)
+        return cast("Series[Any]", result)
+
     @property
     def _dataframe(self) -> type[DataFrame[Any]]:
         return DataFrame

tests/series_only/from_numpy_test.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+import pytest
+
+pytest.importorskip("numpy")
+import numpy as np
+
+import narwhals as nw
+from tests.utils import assert_equal_data
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from narwhals._namespace import EagerAllowed
+    from narwhals.dtypes import NestedType
+    from narwhals.typing import IntoDType, _1DArray
+
+
+arr: _1DArray = cast("_1DArray", np.array([5, 2, 0, 1]))
+NAME = "a"
+
+
+def assert_equal_series(
+    result: nw.Series[Any], expected: Sequence[Any], name: str
+) -> None:
+    assert_equal_data(result.to_frame(), {name: expected})
+
+
+def test_series_from_numpy(eager_backend: EagerAllowed) -> None:
+    expected = [5, 2, 0, 1]
+    result = nw.Series.from_numpy(NAME, arr, backend=eager_backend)
+    assert isinstance(result, nw.Series)
+    assert_equal_series(result, expected, NAME)
+
+
+@pytest.mark.parametrize(
+    ("dtype", "expected"),
+    [
+        (nw.Int16, [5, 2, 0, 1]),
+        (nw.Int32(), [5, 2, 0, 1]),
+        (nw.Float64, [5.0, 2.0, 0.0, 1.0]),
+        (nw.Float32(), [5.0, 2.0, 0.0, 1.0]),
+    ],
+    ids=str,
+)
+def test_series_from_numpy_dtype(
+    eager_backend: EagerAllowed, dtype: IntoDType, expected: Sequence[Any]
+) -> None:
+    result = nw.Series.from_numpy(NAME, arr, backend=eager_backend, dtype=dtype)
+    assert result.dtype == dtype
+    assert_equal_series(result, expected, NAME)
+
+
+@pytest.mark.parametrize(
+    ("bad_dtype", "message"),
+    [
+        (nw.List, r"nw.List.+not.+valid.+hint"),
+        (nw.Struct, r"nw.Struct.+not.+valid.+hint"),
+        (nw.Array, r"nw.Array.+not.+valid.+hint"),
+        (np.floating, r"expected.+narwhals.+dtype.+floating"),
+        (list[int], r"expected.+narwhals.+dtype.+(types.GenericAlias|list)"),
+    ],
+    ids=str,
+)
+def test_series_from_numpy_not_init_dtype(
+    eager_backend: EagerAllowed, bad_dtype: type[NestedType] | object, message: str
+) -> None:
+    with pytest.raises(TypeError, match=re.compile(message, re.IGNORECASE | re.DOTALL)):
+        nw.Series.from_numpy(NAME, arr, bad_dtype, backend=eager_backend)  # type: ignore[arg-type]
+
+
+def test_series_from_numpy_not_eager() -> None:
+    pytest.importorskip("ibis")
+    with pytest.raises(ValueError, match="lazy-only"):
+        nw.Series.from_numpy(NAME, arr, backend="ibis")
+
+
+def test_series_from_numpy_not_1d(eager_backend: EagerAllowed) -> None:
+    with pytest.raises(ValueError, match="`from_numpy` only accepts 1D numpy arrays"):
+        nw.Series.from_numpy(NAME, np.array([[0], [2]]), backend=eager_backend)  # pyright: ignore[reportArgumentType]

tests/v1_test.py

@@ -40,11 +40,13 @@
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from typing_extensions import assert_type
 
     from narwhals._namespace import EagerAllowed
     from narwhals.stable.v1.typing import IntoDataFrameT
-    from narwhals.typing import _2DArray
+    from narwhals.typing import IntoDType, _1DArray, _2DArray
     from tests.utils import Constructor, ConstructorEager
 
 
@@ -615,7 +617,8 @@ def test_series_recursive_v1() -> None:
 
     pl_series = pl.Series(name="test", values=[1, 2, 3])
     nw_series = nw_v1.from_native(pl_series, series_only=True)
-    with pytest.raises(AttributeError):
+    # NOTE: (#2629) combined with passing in `nw_v1.Series` (w/ a `_version`) into itself changes the error
+    with pytest.raises(AssertionError):
         nw_v1.Series(nw_series, level="full")
 
     nw_series_early_return = nw_v1.from_native(nw_series, series_only=True)
@@ -1022,3 +1025,27 @@ def test_dataframe_from_numpy(eager_backend: EagerAllowed) -> None:
         assert isinstance(result_schema, nw_v1.Schema)
 
     assert isinstance(result_schema, nw.Schema)
+
+
+@pytest.mark.parametrize(
+    ("dtype", "expected"),
+    [
+        (None, [5, 2, 0, 1]),
+        (nw_v1.Int64, [5, 2, 0, 1]),
+        (nw_v1.Int16(), [5, 2, 0, 1]),
+        (nw_v1.Float64, [5.0, 2.0, 0.0, 1.0]),
+        (nw_v1.Float32(), [5.0, 2.0, 0.0, 1.0]),
+    ],
+    ids=str,
+)
+def test_series_from_numpy(
+    eager_backend: EagerAllowed, dtype: IntoDType | None, expected: Sequence[Any]
+) -> None:
+    arr: _1DArray = cast("_1DArray", np.array([5, 2, 0, 1]))
+    name = "abc"
+    result = nw_v1.Series.from_numpy(name, arr, backend=eager_backend, dtype=dtype)
+    assert result._version is Version.V1
+    assert isinstance(result, nw_v1.Series)
+    if dtype:
+        assert result.dtype == dtype
+    assert_equal_data(result.to_frame(), {name: expected})

utils/check_api_reference.py

@@ -66,6 +66,7 @@ def read_documented_members(source: str | Path) -> list[str]:
     "arg_min",
     "arg_true",
     "dtype",
+    "from_numpy",
     "gather_every",
     "implementation",
     "is_empty",