feat: add Schema.to_(arrow|pandas|polars)

narwhals/functions.py

@@ -21,6 +21,7 @@
 from narwhals.dependencies import is_numpy_array
 from narwhals.exceptions import ShapeError
 from narwhals.expr import Expr
+from narwhals.schema import Schema
 from narwhals.translate import from_native
 from narwhals.translate import to_native
 from narwhals.utils import Implementation
@@ -43,7 +44,6 @@
     from typing_extensions import Self
 
     from narwhals.dtypes import DType
-    from narwhals.schema import Schema
     from narwhals.series import Series
     from narwhals.typing import IntoDataFrameT
     from narwhals.typing import IntoExpr
@@ -449,20 +449,14 @@ def from_dict(
     backend = validate_native_namespace_and_backend(
         backend, native_namespace, emit_deprecation_warning=True
     )
-    return _from_dict_impl(
-        data,
-        schema,
-        backend=backend,
-        version=Version.MAIN,
-    )
+    return _from_dict_impl(data, schema, backend=backend)
 
 
-def _from_dict_impl(  # noqa: PLR0915
+def _from_dict_impl(
     data: dict[str, Any],
     schema: dict[str, DType] | Schema | None = None,
     *,
     backend: ModuleType | Implementation | str | None = None,
-    version: Version,
 ) -> DataFrame[Any]:
     from narwhals.series import Series
 
@@ -494,18 +488,7 @@ def _from_dict_impl(  # noqa: PLR0915
         msg = f"Unsupported `backend` value.\nExpected one of {supported_eager_backends} or None, got: {eager_backend}."
         raise ValueError(msg)
     if eager_backend is Implementation.POLARS:
-        if schema:
-            from narwhals._polars.utils import (
-                narwhals_to_native_dtype as polars_narwhals_to_native_dtype,
-            )
-
-            schema_pl = {
-                name: polars_narwhals_to_native_dtype(dtype, version=version)
-                for name, dtype in schema.items()
-            }
-        else:
-            schema_pl = None
-
+        schema_pl = Schema(schema).to_polars() if schema else None
         native_frame = native_namespace.from_dict(data, schema=schema_pl)
     elif eager_backend in {
         Implementation.PANDAS,
@@ -535,36 +518,18 @@ def _from_dict_impl(  # noqa: PLR0915
 
         if schema:
             from narwhals._pandas_like.utils import get_dtype_backend
-            from narwhals._pandas_like.utils import (
-                narwhals_to_native_dtype as pandas_like_narwhals_to_native_dtype,
-            )
 
-            backend_version = parse_version(native_namespace.__version__)
-            schema = {
-                name: pandas_like_narwhals_to_native_dtype(
-                    dtype=schema[name],
-                    dtype_backend=get_dtype_backend(native_type, eager_backend),
-                    implementation=eager_backend,
-                    backend_version=backend_version,
-                    version=version,
+            pd_schema = Schema(schema).to_pandas(
+                dtype_backend=(
+                    get_dtype_backend(native_type, eager_backend)
+                    for native_type in native_frame.dtypes
                 )
-                for name, native_type in native_frame.dtypes.items()
-            }
-            native_frame = native_frame.astype(schema)
-
-    elif eager_backend is Implementation.PYARROW:
-        if schema:
-            from narwhals._arrow.utils import (
-                narwhals_to_native_dtype as arrow_narwhals_to_native_dtype,
             )
+            native_frame = native_frame.astype(pd_schema)
 
-            schema = native_namespace.schema(
-                [
-                    (name, arrow_narwhals_to_native_dtype(dtype, version))
-                    for name, dtype in schema.items()
-                ]
-            )
-        native_frame = native_namespace.table(data, schema=schema)
+    elif eager_backend is Implementation.PYARROW:
+        pa_schema = Schema(schema).to_arrow() if schema is not None else schema
+        native_frame = native_namespace.table(data, schema=pa_schema)
     else:  # pragma: no cover
         try:
             # implementation is UNKNOWN, Narwhals extension using this feature should

narwhals/schema.py

@@ -7,11 +7,21 @@
 from __future__ import annotations
 
 from collections import OrderedDict
+from functools import partial
 from typing import TYPE_CHECKING
 from typing import Iterable
 from typing import Mapping
 
+from narwhals.utils import Implementation
+from narwhals.utils import Version
+from narwhals.utils import parse_version
+
 if TYPE_CHECKING:
+    from typing import Any
+    from typing import ClassVar
+
+    import polars as pl
+    import pyarrow as pa
     from typing_extensions import Self
 
     from narwhals.dtypes import DType
@@ -55,6 +65,8 @@ class Schema(BaseSchema):
         2
     """
 
+    _version: ClassVar[Version] = Version.MAIN
+
     def __init__(
         self: Self,
         schema: Mapping[str, DType] | Iterable[tuple[str, DType]] | None = None,
@@ -85,3 +97,47 @@ def len(self: Self) -> int:
             Number of columns.
         """
         return len(self)
+
+    def to_arrow(self: Self) -> pa.Schema:
+        import pyarrow as pa  # ignore-banned-import
+
+        from narwhals._arrow.utils import narwhals_to_native_dtype
+
+        return pa.schema(
+            (name, narwhals_to_native_dtype(dtype, self._version))
+            for name, dtype in self.items()
+        )
+
+    def to_pandas(
+        self: Self, *, dtype_backend: str | Iterable[str] | None = None
+    ) -> dict[str, Any]:
+        import pandas as pd  # ignore-banned-import
+
+        from narwhals._pandas_like.utils import narwhals_to_native_dtype
+
+        to_native = partial(
+            narwhals_to_native_dtype,
+            implementation=Implementation.from_native_namespace(pd),
+            backend_version=parse_version(pd.__version__),
+            version=self._version,
+        )
+        if dtype_backend is None or isinstance(dtype_backend, str):
+            return {
+                name: to_native(dtype=dtype, dtype_backend=dtype_backend)
+                for name, dtype in self.items()
+            }
+        else:
+            return {
+                name: to_native(dtype=dtype, dtype_backend=backend)
+                for name, dtype, backend in zip(self.keys(), self.values(), dtype_backend)
+            }
+
+    def to_polars(self: Self) -> pl.Schema:
+        import polars as pl  # ignore-banned-import
+
+        from narwhals._polars.utils import narwhals_to_native_dtype
+
+        return pl.Schema(
+            (name, narwhals_to_native_dtype(dtype, self._version))
+            for name, dtype in self.items()
+        )

narwhals/stable/v1/__init__.py

@@ -1081,6 +1081,8 @@ class Schema(NwSchema):
             *instantiated* Narwhals data type. Accepts a mapping or an iterable of tuples.
     """
 
+    _version = Version.V1
+
 
 @overload
 def _stableify(obj: NwDataFrame[IntoFrameT]) -> DataFrame[IntoFrameT]: ...
@@ -2200,12 +2202,7 @@ def from_dict(
         backend, native_namespace, emit_deprecation_warning=False
     )
     return _stableify(  # type: ignore[no-any-return]
-        _from_dict_impl(
-            data,
-            schema,
-            backend=backend,
-            version=Version.V1,
-        )
+        _from_dict_impl(data, schema, backend=backend)
     )
 
 

tests/frame/schema_test.py

@@ -17,6 +17,8 @@
 from tests.utils import PANDAS_VERSION
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
+
     from tests.utils import Constructor
     from tests.utils import ConstructorEager
 
@@ -330,3 +332,67 @@ def test_all_nulls_pandas() -> None:
         nw.from_native(pd.Series([None] * 3, dtype="object"), series_only=True).dtype
         == nw.Object
     )
+
+
+@pytest.mark.parametrize(
+    ("dtype_backend", "expected"),
+    [
+        (
+            None,
+            {"a": "int64", "b": str, "c": "bool", "d": "float64", "e": "datetime64[us]"},
+        ),
+        (
+            "numpy",
+            {"a": "int64", "b": str, "c": "bool", "d": "float64", "e": "datetime64[us]"},
+        ),
+        (
+            "pyarrow-nullable",
+            {
+                "a": "Int64[pyarrow]",
+                "b": "string[pyarrow]",
+                "c": "boolean[pyarrow]",
+                "d": "Float64[pyarrow]",
+                "e": "timestamp[us][pyarrow]",
+            },
+        ),
+        (
+            "pandas-nullable",
+            {
+                "a": "Int64",
+                "b": "string",
+                "c": "boolean",
+                "d": "Float64",
+                "e": "datetime64[us]",
+            },
+        ),
+        (
+            [
+                "pandas-nullable",
+                "pyarrow-nullable",
+                "numpy",
+                "pyarrow-nullable",
+                "pandas-nullable",
+            ],
+            {
+                "a": "Int64",
+                "b": "string[pyarrow]",
+                "c": "bool",
+                "d": "Float64[pyarrow]",
+                "e": "datetime64[us]",
+            },
+        ),
+    ],
+)
+def test_schema_to_pandas(
+    dtype_backend: str | Iterable[str] | None, expected: dict[str, Any]
+) -> None:
+    schema = nw.Schema(
+        {
+            "a": nw.Int64(),
+            "b": nw.String(),
+            "c": nw.Boolean(),
+            "d": nw.Float64(),
+            "e": nw.Datetime("us"),
+        }
+    )
+    assert schema.to_pandas(dtype_backend=dtype_backend) == expected