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.
