narwhals-map 0.1.0__tar.gz

narwhals_map-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: narwhals-map
+Version: 0.1.0
+Summary: Add your description here
+Author: danielgafni
+Author-email: danielgafni <danielgafni16@gmail.com>
+Requires-Dist: ibis-framework>=12.0.0 ; extra == 'ibis'
+Requires-Dist: polars>=1.39.3 ; extra == 'polars'
+Requires-Dist: polars-map>=0.2.0 ; extra == 'polars'
+Requires-Dist: pyarrow>=23.0.1 ; extra == 'pyarrow'
+Requires-Python: >=3.10
+Provides-Extra: ibis
+Provides-Extra: polars
+Provides-Extra: pyarrow
+Description-Content-Type: text/markdown
+
+# narwhals-map
+
+An experimental Narwhals plugin adding `Map` datatype.
+
+> [!TIP]
+> See [`narwhals-dev/narwhals#3525`](https://github.com/narwhals-dev/narwhals/issues/3525) issue for more info.
+
+`Map` is natively supported across all backends except for Polars.
+
+Supported Narwhals backends:
+  - Arrow
+  - Ibis
+  - Polars (via [`polars-map`](https://github.com/hafaio/polars-map))
+
+Currently monkey-patches Narwhals to expose a new `nw.col.map` namespace.
+
+## Usage
+
+```python
+import narwhals as nw
+import narwhals_map  # registers the Map dtype and .map namespace
+
+df = nw.from_native(native_df)  # use polars_map.Map for Polars-backed frames
+result = df.select(nw.col("map_col").map.get("key1"))
+```
+
+## Known Limitations
+
+- **`.to_arrow()` on Polars-backed frames**: Polars (via `polars-map`) stores maps as `List(Struct({key, value}))` internally. Calling `.to_arrow()` on a Polars-backed Narwhals frame produces `list<struct<key, value>>` columns instead of Arrow `map` types. PyArrow and Ibis backends are unaffected.

narwhals_map-0.1.0/README.md

@@ -0,0 +1,29 @@
+# narwhals-map
+
+An experimental Narwhals plugin adding `Map` datatype.
+
+> [!TIP]
+> See [`narwhals-dev/narwhals#3525`](https://github.com/narwhals-dev/narwhals/issues/3525) issue for more info.
+
+`Map` is natively supported across all backends except for Polars.
+
+Supported Narwhals backends:
+  - Arrow
+  - Ibis
+  - Polars (via [`polars-map`](https://github.com/hafaio/polars-map))
+
+Currently monkey-patches Narwhals to expose a new `nw.col.map` namespace.
+
+## Usage
+
+```python
+import narwhals as nw
+import narwhals_map  # registers the Map dtype and .map namespace
+
+df = nw.from_native(native_df)  # use polars_map.Map for Polars-backed frames
+result = df.select(nw.col("map_col").map.get("key1"))
+```
+
+## Known Limitations
+
+- **`.to_arrow()` on Polars-backed frames**: Polars (via `polars-map`) stores maps as `List(Struct({key, value}))` internally. Calling `.to_arrow()` on a Polars-backed Narwhals frame produces `list<struct<key, value>>` columns instead of Arrow `map` types. PyArrow and Ibis backends are unaffected.

narwhals_map-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "narwhals-map"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "danielgafni", email = "danielgafni16@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+]
+
+[project.optional-dependencies]
+pyarrow = [
+    "pyarrow>=23.0.1",
+]
+polars = [
+    "polars>=1.39.3",
+    "polars-map>=0.2.0",
+]
+ibis = [
+    "ibis-framework>=12.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    # narwhals has to depend on us I guess?
+    # so we can't depend on it
+    "narwhals>=2.18.1",
+    "prek>=0.3.8",
+    "pyrefly>=0.59.1",
+    "pytest>=9.0.2",
+    "pytest-cases>=3.10.1",
+    "ruff>=0.15.9",
+    "ibis-framework[duckdb]>=12.0.0",
+]

narwhals_map-0.1.0/src/narwhals_map/__init__.py

@@ -0,0 +1,5 @@
+import narwhals_map._narwhals_patch  # noqa: F401 - applies monkey-patches at import time
+from narwhals_map._dtype import Map
+from narwhals_map._version import __version__
+
+__all__ = ["Map", "__version__"]

narwhals_map-0.1.0/src/narwhals_map/_arrow/expr_map.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+from narwhals._compliant.expr import EagerExprNamespace
+
+
+class ArrowExprMapNamespace(EagerExprNamespace):  # type: ignore[type-arg]
+    def get(self, key: Any) -> Any:
+        compliant = self._compliant_expr
+
+        def inner(df):  # type: ignore[no-untyped-def]
+            return [series.map.get(key=key) for series in compliant(df)]  # type: ignore[attr-defined]
+
+        return compliant._from_callable(
+            inner,
+            evaluate_output_names=compliant._evaluate_output_names,
+            alias_output_names=compliant._alias_output_names,
+            context=compliant,
+        )

narwhals_map-0.1.0/src/narwhals_map/_arrow/series_map.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING, Any
+
+import pyarrow.compute as pc
+from narwhals._arrow.utils import ArrowSeriesNamespace
+
+from narwhals_map._compliant.namespace import MapNamespace
+
+if TYPE_CHECKING:
+    from narwhals._arrow.series import ArrowSeries
+
+
+class ArrowSeriesMapNamespace(ArrowSeriesNamespace, MapNamespace["ArrowSeries"]):
+    def get(self, key: Any) -> "ArrowSeries":
+        return self.with_native(pc.map_lookup(self.native, key, "first")).alias(str(key))  # pyrefly: ignore [missing-attribute]

narwhals_map-0.1.0/src/narwhals_map/_compliant/namespace.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeVar
+
+from narwhals._utils import CompliantT_co, _StoresCompliant
+
+if TYPE_CHECKING:
+    from narwhals._compliant.typing import Accessor
+
+T = TypeVar("T")
+
+
+class MapNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar["Accessor"] = "map"  # type: ignore[assignment]
+
+    def get(self, key: Any) -> CompliantT_co: ...

narwhals_map-0.1.0/src/narwhals_map/_dtype.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+
+from narwhals.dtypes import DType, DTypeClass, NestedType
+
+if TYPE_CHECKING:
+    from narwhals.typing import IntoDType
+
+
+class Map(NestedType):
+    """Map composite type.
+
+    Arguments:
+        key: The key data type of the map. Must be hashable.
+        value: The value data type of the map.
+
+    Examples:
+       >>> import pyarrow as pa
+       >>> import narwhals as nw
+       >>> s_native = pa.map_(pa.string(), pa.int64())
+       ...     [[("key1", 1), ("key2", 2)]]
+       ... )
+       >>> nw.from_native(s_native, series_only=True).dtype
+       Map(String, Int64)
+    """
+
+    __slots__ = (
+        "key",
+        "value",
+    )
+    key: IntoDType
+    value: IntoDType
+    """The key and value data types of the map."""
+
+    def __init__(self, key: IntoDType, value: IntoDType) -> None:
+        self.key = key
+        self.value = value
+
+    def __eq__(self, other: DType | type[DType]) -> bool:  # type: ignore[override]
+        """Check if this Map is equivalent to another DType.
+
+        Examples:
+            >>> import narwhals as nw
+            >>> nw.Map(nw.Int64, nw.Int64) == nw.Map(nw.Int64, nw.Int64)
+            True
+            >>> nw.Map(nw.Int64, nw.Int64) == nw.Map(nw.Int64, nw.Boolean)
+            False
+
+            If a parent type is not specific about its inner type, we infer it as equal
+
+            >>> nw.Map(nw.Int64, nw.Int64) == nw.Map
+            True
+        """
+        if type(other) is DTypeClass and issubclass(other, self.__class__):
+            return True
+        if isinstance(other, self.__class__):
+            return (self.key, self.value) == (other.key, other.value)
+        return False
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, (self.key, self.value)))
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        return f"{class_name}({self.key}, {self.value})"
+
+    def to_schema(self) -> OrderedDict[str, IntoDType]:
+        """Return Map dtype as a schema dict."""
+        return OrderedDict({"key": self.key, "value": self.value})

narwhals_map-0.1.0/src/narwhals_map/_ibis/expr_map.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from narwhals._compliant import LazyExprNamespace
+
+from narwhals_map._compliant.namespace import MapNamespace
+
+if TYPE_CHECKING:
+    from narwhals._ibis.expr import IbisExpr
+
+
+class IbisExprMapNamespace(LazyExprNamespace["IbisExpr"], MapNamespace["IbisExpr"]):
+    def get(self, key: Any) -> IbisExpr:
+        return self.compliant._with_callable(lambda expr: expr.get(key).name(str(key)))

narwhals_map-0.1.0/src/narwhals_map/_narwhals_patch.py

@@ -0,0 +1,105 @@
+"""Monkey-patch narwhals internals to add Map dtype and .map namespace support."""
+
+from narwhals.expr import Expr
+from narwhals.series import Series
+
+from narwhals_map._dtype import Map
+from narwhals_map.expr_map import ExprMapNamespace
+from narwhals_map.series_map import SeriesMapNamespace
+
+# --- Public API namespace patches (always available) ---
+
+Expr.map = property(lambda self: ExprMapNamespace(self))  # type: ignore[attr-defined]
+Series.map = property(lambda self: SeriesMapNamespace(self))  # type: ignore[attr-defined]
+
+# --- PyArrow backend (optional) ---
+
+try:
+    import pyarrow as pa
+    from narwhals._arrow import utils as _arrow_utils
+    from narwhals._arrow.series import ArrowSeries
+    from narwhals._compliant.expr import EagerExpr
+
+    from narwhals_map._arrow.expr_map import ArrowExprMapNamespace
+    from narwhals_map._arrow.series_map import ArrowSeriesMapNamespace
+
+    ArrowSeries.map = property(lambda self: ArrowSeriesMapNamespace(self))  # type: ignore[attr-defined]
+    EagerExpr.map = property(lambda self: ArrowExprMapNamespace(self))  # type: ignore[attr-defined]
+
+    _orig_arrow_native_to_narwhals_dtype = _arrow_utils.native_to_narwhals_dtype
+
+    def _patched_arrow_native_to_narwhals_dtype(dtype, version):  # type: ignore[no-untyped-def]
+        if isinstance(dtype, pa.MapType):
+            return Map(
+                _patched_arrow_native_to_narwhals_dtype(dtype.key_type, version),
+                _patched_arrow_native_to_narwhals_dtype(dtype.item_type, version),
+            )
+        return _orig_arrow_native_to_narwhals_dtype(dtype, version)
+
+    _arrow_utils.native_to_narwhals_dtype = _patched_arrow_native_to_narwhals_dtype  # type: ignore[assignment]
+
+    _orig_arrow_narwhals_to_native_dtype = _arrow_utils.narwhals_to_native_dtype
+
+    def _patched_arrow_narwhals_to_native_dtype(dtype, version):  # type: ignore[no-untyped-def]
+        if isinstance(dtype, Map):
+            return pa.map_(
+                _orig_arrow_narwhals_to_native_dtype(dtype.key, version),
+                _orig_arrow_narwhals_to_native_dtype(dtype.value, version),
+            )
+        return _orig_arrow_narwhals_to_native_dtype(dtype, version)
+
+    _arrow_utils.narwhals_to_native_dtype = _patched_arrow_narwhals_to_native_dtype  # type: ignore[assignment]
+except ImportError:
+    pass
+
+# --- Polars backend (optional) ---
+
+try:
+    import polars_map as _polars_map
+    from narwhals._polars import utils as _polars_utils
+    from narwhals._polars.expr import PolarsExpr
+    from narwhals._polars.series import PolarsSeries
+
+    from narwhals_map._polars.expr_map import PolarsExprMapNamespace
+    from narwhals_map._polars.series_map import PolarsSeriesMapNamespace
+
+    PolarsExpr.map = property(lambda self: PolarsExprMapNamespace(self))  # type: ignore[attr-defined]
+    PolarsSeries.map = property(lambda self: PolarsSeriesMapNamespace(self))  # type: ignore[attr-defined]
+
+    _orig_polars_native_to_narwhals_dtype = _polars_utils.native_to_narwhals_dtype
+
+    def _patched_polars_native_to_narwhals_dtype(dtype, version):  # type: ignore[no-untyped-def]
+        if isinstance(dtype, _polars_map.Map):
+            return Map(
+                _patched_polars_native_to_narwhals_dtype(dtype.key, version),
+                _patched_polars_native_to_narwhals_dtype(dtype.value, version),
+            )
+        return _orig_polars_native_to_narwhals_dtype(dtype, version)
+
+    _polars_utils.native_to_narwhals_dtype = _patched_polars_native_to_narwhals_dtype  # type: ignore[assignment]
+except ImportError:
+    pass
+
+# --- Ibis backend (optional) ---
+
+try:
+    from narwhals._ibis import utils as _ibis_utils
+    from narwhals._ibis.expr import IbisExpr
+
+    from narwhals_map._ibis.expr_map import IbisExprMapNamespace
+
+    IbisExpr.map = property(lambda self: IbisExprMapNamespace(self))  # type: ignore[attr-defined]
+
+    _orig_ibis_native_to_narwhals_dtype = _ibis_utils.native_to_narwhals_dtype
+
+    def _patched_ibis_native_to_narwhals_dtype(ibis_dtype, version):  # type: ignore[no-untyped-def]
+        if ibis_dtype.is_map():
+            return Map(
+                _patched_ibis_native_to_narwhals_dtype(ibis_dtype.key_type, version),
+                _patched_ibis_native_to_narwhals_dtype(ibis_dtype.value_type, version),
+            )
+        return _orig_ibis_native_to_narwhals_dtype(ibis_dtype, version)
+
+    _ibis_utils.native_to_narwhals_dtype = _patched_ibis_native_to_narwhals_dtype  # type: ignore[assignment]
+except ImportError:
+    pass

narwhals_map-0.1.0/src/narwhals_map/_polars/expr_map.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING, Any
+
+import polars_map  # noqa: F401 - registers .map on pl.Expr
+from narwhals._polars.expr import PolarsExprNamespace
+
+from narwhals_map._compliant.namespace import MapNamespace
+
+if TYPE_CHECKING:
+    from narwhals._polars.expr import PolarsExpr
+
+
+class PolarsExprMapNamespace(PolarsExprNamespace, MapNamespace["PolarsExpr"]):
+    def get(self, key: Any) -> "PolarsExpr":
+        return self.compliant._with_native(self.native.map.get(key))  # pyrefly: ignore [missing-attribute]

narwhals_map-0.1.0/src/narwhals_map/_polars/series_map.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING, Any
+
+from narwhals._polars.series import PolarsSeriesNamespace
+
+from narwhals_map._compliant.namespace import MapNamespace
+
+if TYPE_CHECKING:
+    from narwhals._polars.series import PolarsSeries
+
+
+class PolarsSeriesMapNamespace(PolarsSeriesNamespace, MapNamespace["PolarsSeries"]):
+    def get(self, key: Any) -> "PolarsSeries":
+        ns = self.__narwhals_namespace__()
+        return self.to_frame().select(ns.col(self.name).map.get(key)).get_column(str(key))

narwhals_map-0.1.0/src/narwhals_map/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

narwhals_map-0.1.0/src/narwhals_map/expr_map.py

@@ -0,0 +1,18 @@
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from narwhals._expression_parsing import ExprKind, ExprNode
+
+if TYPE_CHECKING:
+    from narwhals.expr import Expr
+
+ExprT = TypeVar("ExprT", bound="Expr")
+
+
+class ExprMapNamespace(Generic[ExprT]):
+    def __init__(self, expr: ExprT) -> None:
+        self._expr = expr
+
+    def get(self, key: Any) -> ExprT:
+        return self._expr._append_node(ExprNode(ExprKind.ELEMENTWISE, "map.get", key=key))._append_node(
+            ExprNode(ExprKind.ELEMENTWISE, "alias", name=str(key))
+        )

narwhals_map-0.1.0/src/narwhals_map/series_map.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from narwhals.series import Series
+
+SeriesT = TypeVar("SeriesT", bound="Series")
+
+
+class SeriesMapNamespace(Generic[SeriesT]):
+    def __init__(self, series: SeriesT) -> None:
+        self._narwhals_series = series
+
+    def get(self, key: Any) -> SeriesT:
+        return self._narwhals_series._with_compliant(self._narwhals_series._compliant_series.map.get(key))  # pyrefly: ignore [missing-attribute]