feat: Add Series.from_iterable

docs/api-reference/series.md

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

narwhals/_arrow/series.py

@@ -15,6 +15,7 @@
     chunked_array,
     extract_native,
     floordiv_compat,
+    is_array_or_scalar,
     lit,
     narwhals_to_native_dtype,
     native_to_narwhals_dtype,
@@ -156,10 +157,15 @@ def from_iterable(
         dtype: IntoDType | None = None,
     ) -> Self:
         version = context._version
-        dtype_pa = narwhals_to_native_dtype(dtype, version) if dtype else None
-        return cls.from_native(
-            chunked_array([data], dtype_pa), name=name, context=context
-        )
+        if dtype is not None:
+            dtype_pa: pa.DataType | None = narwhals_to_native_dtype(dtype, version)
+            if is_array_or_scalar(data):
+                data = data.cast(dtype_pa)
+                dtype_pa = None
+            native = data if cls._is_native(data) else chunked_array([data], dtype_pa)
+        else:
+            native = chunked_array([data])
+        return cls.from_native(native, context=context, name=name)
 
     def _from_scalar(self, value: Any) -> Self:
         if hasattr(value, "as_py"):

narwhals/_arrow/utils.py

@@ -80,14 +80,19 @@ def extract_py_scalar(value: Any, /) -> Any:
     return maybe_extract_py_scalar(value, return_py_scalar=True)
 
 
+def is_array_or_scalar(obj: Any) -> TypeIs[ArrayOrScalar]:
+    """Return True for any base `pyarrow` container."""
+    return isinstance(obj, (pa.ChunkedArray, pa.Array, pa.Scalar))
+
+
 def chunked_array(
     arr: ArrayOrScalar | list[Iterable[Any]], dtype: pa.DataType | None = None, /
 ) -> ChunkedArrayAny:
     if isinstance(arr, pa.ChunkedArray):
         return arr
     if isinstance(arr, list):
         return pa.chunked_array(arr, dtype)
-    return pa.chunked_array([arr], arr.type)
+    return pa.chunked_array([arr], dtype)
 
 
 def nulls_like(n: int, series: ArrowSeries) -> ArrayAny:

narwhals/_polars/series.py

@@ -6,6 +6,8 @@
 
 from narwhals._polars.utils import (
     BACKEND_VERSION,
+    SERIES_ACCEPTS_PD_INDEX,
+    SERIES_RESPECTS_DTYPE,
     PolarsAnyNamespace,
     PolarsCatNamespace,
     PolarsDateTimeNamespace,
@@ -19,7 +21,7 @@
     native_to_narwhals_dtype,
 )
 from narwhals._utils import Implementation, requires
-from narwhals.dependencies import is_numpy_array_1d
+from narwhals.dependencies import is_numpy_array_1d, is_pandas_index
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Mapping, Sequence
@@ -48,6 +50,7 @@
     T = TypeVar("T")
     IncludeBreakpoint: TypeAlias = Literal[False, True]
 
+Incomplete: TypeAlias = Any
 
 # Series methods where PolarsSeries just defers to Polars.Series directly.
 INHERITED_METHODS = frozenset(
@@ -180,9 +183,15 @@ def from_iterable(
     ) -> Self:
         version = context._version
         dtype_pl = narwhals_to_native_dtype(dtype, version) if dtype else None
-        # NOTE: `Iterable` is fine, annotation is overly narrow
-        # https://github.com/pola-rs/polars/blob/82d57a4ee41f87c11ca1b1af15488459727efdd7/py-polars/polars/series/series.py#L332-L333
-        native = pl.Series(name=name, values=cast("Sequence[Any]", data), dtype=dtype_pl)
+        values: Incomplete = data
+        if SERIES_RESPECTS_DTYPE:
+            native = pl.Series(name, values, dtype=dtype_pl)
+        else:  # pragma: no cover
+            if (not SERIES_ACCEPTS_PD_INDEX) and is_pandas_index(values):
+                values = values.to_series()
+            native = pl.Series(name, values)
+            if dtype_pl:
+                native = native.cast(dtype_pl)
         return cls.from_native(native, context=context)
 
     @staticmethod
@@ -565,8 +574,6 @@ def _bins_from_bin_count(self, bin_count: int) -> pl.Series:  # pragma: no cover
         returns bins that range from -inf to +inf and has bin_count + 1 bins.
           for compat: convert `bin_count=` call to `bins=`
         """
-        from typing import cast
-
         lower = cast("float", self.native.min())
         upper = cast("float", self.native.max())
 

narwhals/_polars/utils.py

@@ -2,7 +2,7 @@
 
 import abc
 from functools import lru_cache
-from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeVar, overload
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Protocol, TypeVar, overload
 
 import polars as pl
 
@@ -49,6 +49,15 @@
 BACKEND_VERSION = Implementation.POLARS._backend_version()
 """Static backend version for `polars`."""
 
+SERIES_RESPECTS_DTYPE: Final[bool] = BACKEND_VERSION >= (0, 20, 26)
+"""`pl.Series(dtype=...)` fixed in https://github.com/pola-rs/polars/pull/15962
+
+Includes `SERIES_ACCEPTS_PD_INDEX`.
+"""
+
+SERIES_ACCEPTS_PD_INDEX: Final[bool] = BACKEND_VERSION >= (0, 20, 7)
+"""`pl.Series(values: pd.Index)` fixed in https://github.com/pola-rs/polars/pull/14087"""
+
 
 @overload
 def extract_native(obj: _StoresNative[NativeT]) -> NativeT: ...

narwhals/series.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import math
-from collections.abc import Iterator, Mapping, Sequence
+from collections.abc import Iterable, Iterator, Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, Literal, overload
 
 from narwhals._utils import (
@@ -13,9 +13,10 @@
     is_compliant_series,
     is_eager_allowed,
     is_index_selector,
+    qualified_type_name,
     supports_arrow_c_stream,
 )
-from narwhals.dependencies import is_numpy_array_1d, is_numpy_scalar
+from narwhals.dependencies import is_numpy_array, is_numpy_array_1d, is_numpy_scalar
 from narwhals.dtypes import _validate_dtype, _validate_into_dtype
 from narwhals.exceptions import ComputeError, InvalidOperationError
 from narwhals.series_cat import SeriesCatNamespace
@@ -157,6 +158,71 @@ def from_numpy(
         )
         raise ValueError(msg)
 
+    @classmethod
+    def from_iterable(
+        cls,
+        name: str,
+        values: Iterable[Any],
+        dtype: IntoDType | None = None,
+        *,
+        backend: ModuleType | Implementation | str,
+    ) -> Series[Any]:
+        """Construct a Series from an iterable.
+
+        Arguments:
+            name: Name of resulting Series.
+            values: One-dimensional data represented as an iterable.
+            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 pandas as pd
+            >>> import narwhals as nw
+            >>>
+            >>> values = [4, 1, 3, 2]
+            >>> nw.Series.from_iterable("a", values, dtype=nw.UInt32, backend="pandas")
+            ┌──────────────────────┐
+            |   Narwhals Series    |
+            |----------------------|
+            |0    4                |
+            |1    1                |
+            |2    3                |
+            |3    2                |
+            |Name: a, dtype: uint32|
+            └──────────────────────┘
+        """
+        if is_numpy_array(values):
+            return cls.from_numpy(name, values, dtype, backend=backend)
+        if dtype:
+            _validate_into_dtype(dtype)
+        if not isinstance(values, Iterable):
+            msg = f"Expected values to be an iterable, got: {qualified_type_name(values)!r}."
+            raise TypeError(msg)
+        implementation = Implementation.from_backend(backend)
+        if is_eager_allowed(implementation):
+            ns = cls._version.namespace.from_backend(implementation).compliant
+            compliant = ns._series.from_iterable(
+                values, context=ns, name=name, dtype=dtype
+            )
+            return cls(compliant, level="full")
+        msg = (
+            f"{implementation} support in Narwhals is lazy-only, but `Series.from_iterable` 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_iterable('a', [1,2,3], backend='pyarrow').to_frame().lazy('{implementation}')"
+        )
+        raise ValueError(msg)
+
     @property
     def implementation(self) -> Implementation:
         """Return implementation of native Series.

narwhals/stable/v1/__init__.py

@@ -311,6 +311,18 @@ def from_numpy(
         result = super().from_numpy(name, values, dtype, backend=backend)
         return cast("Series[Any]", result)
 
+    @classmethod
+    def from_iterable(
+        cls,
+        name: str,
+        values: Iterable[Any],
+        dtype: IntoDType | None = None,
+        *,
+        backend: ModuleType | Implementation | str,
+    ) -> Series[Any]:
+        result = super().from_iterable(name, values, dtype, backend=backend)
+        return cast("Series[Any]", result)
+
     @property
     def _dataframe(self) -> type[DataFrame[Any]]:
         return DataFrame

narwhals/stable/v2/__init__.py

@@ -189,6 +189,8 @@ def collect(
 
 
 class Series(NwSeries[IntoSeriesT]):
+    _version = Version.V2
+
     @inherit_doc(NwSeries)
     def __init__(
         self, series: Any, *, level: Literal["full", "lazy", "interchange"]
@@ -203,6 +205,20 @@ def __init__(
     def _dataframe(self) -> type[DataFrame[Any]]:
         return DataFrame
 
+    # TODO @dangotbanned: Fix `from_numpy` override missing in `v2` in another PR
+
+    @classmethod
+    def from_iterable(
+        cls,
+        name: str,
+        values: Iterable[Any],
+        dtype: IntoDType | None = None,
+        *,
+        backend: ModuleType | Implementation | str,
+    ) -> Series[Any]:
+        result = super().from_iterable(name, values, dtype, backend=backend)
+        return cast("Series[Any]", result)
+
     def to_frame(self) -> DataFrame[Any]:
         return _stableify(super().to_frame())
 

tests/conftest.py

@@ -327,3 +327,9 @@ def pytest_generate_tests(metafunc: pytest.Metafunc) -> None:
 @pytest.fixture(params=TEST_EAGER_BACKENDS)
 def eager_backend(request: pytest.FixtureRequest) -> EagerAllowed:
     return request.param  # type: ignore[no-any-return]
+
+
+@pytest.fixture(params=[el for el in TEST_EAGER_BACKENDS if not isinstance(el, str)])
+def eager_implementation(request: pytest.FixtureRequest) -> EagerAllowed:
+    """Use if a test is heavily parametric, skips `str` backend."""
+    return request.param  # type: ignore[no-any-return]