feat: Added struct namespace with field method.

docs/api-completeness/expr_struct.md

@@ -0,0 +1,5 @@
+# Expr.str
+
+| Method       | arrow              | duckdb             | pandas-like        | polars             | spark-like         |
+|--------------|--------------------|--------------------|--------------------|--------------------|--------------------|
+| field        | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |

docs/api-completeness/series_struct.md

@@ -0,0 +1,5 @@
+# Series.str
+
+| Method       | arrow               | pandas-like        | polars             |
+|--------------|---------------------|--------------------|--------------------|
+| field        | :white_check_mark:  | :white_check_mark: | :white_check_mark: |

docs/api-reference/expr_struct.md

@@ -0,0 +1,9 @@
+# `narwhals.Expr.struct`
+
+::: narwhals.expr.ExprStructNamespace
+    handler: python
+    options:
+      members:
+        - field
+      show_source: false
+      show_bases: false

docs/api-reference/index.md

@@ -8,6 +8,7 @@
 - [narwhals.Expr.list](expr_list.md)
 - [narwhals.Expr.name](expr_name.md)
 - [narwhals.Expr.str](expr_str.md)
+- [narwhals.Expr.struct](expr_struct.md)
 - [narwhals.GroupBy](group_by.md)
 - [narwhals.LazyGroupBy](lazy_group_by.md)
 - [narwhals.LazyFrame](lazyframe.md)
@@ -17,6 +18,7 @@
 - [narwhals.Series.dt](series_dt.md)
 - [narwhals.Series.list](series_list.md)
 - [narwhals.Series.str](series_str.md)
+- [narwhals.Series.struct](series_struct.md)
 - [narwhals.dependencies](dependencies.md)
 - [narwhals.Implementation](implementation.md)
 - [narwhals.dtypes](dtypes.md)

docs/api-reference/series_struct.md

@@ -0,0 +1,9 @@
+# `narwhals.Series.struct`
+
+::: narwhals.series.SeriesStructNamespace
+    handler: python
+    options:
+      members:
+        - field
+      show_source: false
+      show_bases: false

mkdocs.yml

@@ -34,11 +34,13 @@ nav:
     - Supported Expr.list methods: api-completeness/expr_list.md
     - Supported Expr.name methods: api-completeness/expr_name.md
     - Supported Expr.str methods: api-completeness/expr_str.md
+    - Supported Expr.struct methods: api-completeness/expr_struct.md
     - Supported Series methods: api-completeness/series.md
     - Supported Series.cat methods: api-completeness/series_cat.md
     - Supported Series.dt methods: api-completeness/series_dt.md
     - Supported Series.list methods: api-completeness/series_list.md
     - Supported Series.str methods: api-completeness/series_str.md
+    - Supported Series.struct methods: api-completeness/series_struct.md
   - API Reference:
     - api-reference/index.md
     - api-reference/narwhals.md
@@ -49,6 +51,7 @@ nav:
     - api-reference/expr_list.md
     - api-reference/expr_name.md
     - api-reference/expr_str.md
+    - api-reference/expr_struct.md
     - api-reference/group_by.md
     - api-reference/lazy_group_by.md
     - api-reference/lazyframe.md
@@ -58,6 +61,7 @@ nav:
     - api-reference/series_dt.md
     - api-reference/series_list.md
     - api-reference/series_str.md
+    - api-reference/series_struct.md
     - api-reference/dependencies.md
     - api-reference/implementation.md
     - api-reference/dtypes.md

narwhals/_arrow/expr.py

@@ -11,6 +11,7 @@
 from narwhals._arrow.expr_list import ArrowExprListNamespace
 from narwhals._arrow.expr_name import ArrowExprNameNamespace
 from narwhals._arrow.expr_str import ArrowExprStringNamespace
+from narwhals._arrow.expr_struct import ArrowExprStructNamespace
 from narwhals._arrow.series import ArrowSeries
 from narwhals._expression_parsing import ExprKind
 from narwhals._expression_parsing import evaluate_output_names_and_aliases
@@ -598,3 +599,7 @@ def name(self: Self) -> ArrowExprNameNamespace:
     @property
     def list(self: Self) -> ArrowExprListNamespace:
         return ArrowExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> ArrowExprStructNamespace:
+        return ArrowExprStructNamespace(self)

narwhals/_arrow/expr_struct.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from narwhals._expression_parsing import reuse_series_namespace_implementation
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._arrow.expr import ArrowExpr
+
+
+class ArrowExprStructNamespace:
+    def __init__(self: Self, expr: ArrowExpr) -> None:
+        self._compliant_expr = expr
+
+    def field(self: Self, name: str) -> ArrowExpr:
+        self._compliant_expr._evaluate_output_names = lambda _col: [name]
+        return reuse_series_namespace_implementation(
+            self._compliant_expr, "struct", "field", name=name
+        )

narwhals/_arrow/series.py

@@ -16,6 +16,7 @@
 from narwhals._arrow.series_dt import ArrowSeriesDateTimeNamespace
 from narwhals._arrow.series_list import ArrowSeriesListNamespace
 from narwhals._arrow.series_str import ArrowSeriesStringNamespace
+from narwhals._arrow.series_struct import ArrowSeriesStructNamespace
 from narwhals._arrow.utils import cast_for_truediv
 from narwhals._arrow.utils import chunked_array
 from narwhals._arrow.utils import extract_native
@@ -1232,3 +1233,7 @@ def str(self: Self) -> ArrowSeriesStringNamespace:
     @property
     def list(self: Self) -> ArrowSeriesListNamespace:
         return ArrowSeriesListNamespace(self)
+
+    @property
+    def struct(self: Self) -> ArrowSeriesStructNamespace:
+        return ArrowSeriesStructNamespace(self)

narwhals/_arrow/series_struct.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pyarrow.compute as pc
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._arrow.series import ArrowSeries
+
+
+class ArrowSeriesStructNamespace:
+    def __init__(self: Self, series: ArrowSeries) -> None:
+        self._compliant_series: ArrowSeries = series
+
+    def field(self: Self, name: str) -> ArrowSeries:
+        self._compliant_series._name = name
+        return self._compliant_series._from_native_series(
+            pc.struct_field(self._compliant_series._native_series, name)
+        )

narwhals/_duckdb/dataframe.py

@@ -267,7 +267,7 @@ def join(
             if self._backend_version < (1, 1, 4):
                 msg = f"DuckDB>=1.1.4 is required for cross-join, found version: {self._backend_version}"
                 raise NotImplementedError(msg)
-            rel = self._native_frame.set_alias("lhs").cross(  # pragma: no cover
+            rel = self._native_frame.set_alias("lhs").cross(  # type: ignore[operator]  # pragma: no cover
                 other._native_frame.set_alias("rhs")
             )
         else:

narwhals/_duckdb/expr.py

@@ -18,6 +18,7 @@
 from narwhals._duckdb.expr_list import DuckDBExprListNamespace
 from narwhals._duckdb.expr_name import DuckDBExprNameNamespace
 from narwhals._duckdb.expr_str import DuckDBExprStringNamespace
+from narwhals._duckdb.expr_struct import DuckDBExprStructNamespace
 from narwhals._duckdb.utils import lit
 from narwhals._duckdb.utils import maybe_evaluate_expr
 from narwhals._duckdb.utils import narwhals_to_native_dtype
@@ -482,3 +483,7 @@ def name(self: Self) -> DuckDBExprNameNamespace:
     @property
     def list(self: Self) -> DuckDBExprListNamespace:
         return DuckDBExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> DuckDBExprStructNamespace:
+        return DuckDBExprStructNamespace(self)

narwhals/_duckdb/expr_struct.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from duckdb import FunctionExpression
+
+from narwhals._duckdb.utils import lit
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._duckdb.expr import DuckDBExpr
+
+
+class DuckDBExprStructNamespace:
+    def __init__(self: Self, expr: DuckDBExpr) -> None:
+        self._compliant_expr = expr
+
+    def field(self: Self, name: str) -> DuckDBExpr:
+        self._compliant_expr._evaluate_output_names = lambda _col: [name]
+        return self._compliant_expr._from_call(
+            lambda _input: FunctionExpression("struct_extract", _input, lit(name)).alias(
+                name
+            ),
+            "field",
+        )

narwhals/_pandas_like/expr.py

@@ -16,6 +16,7 @@
 from narwhals._pandas_like.expr_list import PandasLikeExprListNamespace
 from narwhals._pandas_like.expr_name import PandasLikeExprNameNamespace
 from narwhals._pandas_like.expr_str import PandasLikeExprStringNamespace
+from narwhals._pandas_like.expr_struct import PandasLikeExprStructNamespace
 from narwhals._pandas_like.group_by import AGGREGATIONS_TO_PANDAS_EQUIVALENT
 from narwhals._pandas_like.series import PandasLikeSeries
 from narwhals._pandas_like.utils import rename
@@ -710,3 +711,7 @@ def name(self: Self) -> PandasLikeExprNameNamespace:
     @property
     def list(self: Self) -> PandasLikeExprListNamespace:
         return PandasLikeExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> PandasLikeExprStructNamespace:
+        return PandasLikeExprStructNamespace(self)

narwhals/_pandas_like/expr_struct.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from narwhals._expression_parsing import reuse_series_namespace_implementation
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._pandas_like.expr import PandasLikeExpr
+
+
+class PandasLikeExprStructNamespace:
+    def __init__(self: Self, expr: PandasLikeExpr) -> None:
+        self._compliant_expr = expr
+
+    def field(self, name: str) -> PandasLikeExpr:
+        self._compliant_expr._evaluate_output_names = lambda _col: [name]
+        return reuse_series_namespace_implementation(
+            self._compliant_expr, "struct", "field", name=name
+        )

narwhals/_pandas_like/series.py

@@ -13,6 +13,7 @@
 from narwhals._pandas_like.series_dt import PandasLikeSeriesDateTimeNamespace
 from narwhals._pandas_like.series_list import PandasLikeSeriesListNamespace
 from narwhals._pandas_like.series_str import PandasLikeSeriesStringNamespace
+from narwhals._pandas_like.series_struct import PandasLikeSeriesStructNamespace
 from narwhals._pandas_like.utils import align_and_extract_native
 from narwhals._pandas_like.utils import get_dtype_backend
 from narwhals._pandas_like.utils import narwhals_to_native_dtype
@@ -1106,3 +1107,7 @@ def cat(self: Self) -> PandasLikeSeriesCatNamespace:
     @property
     def list(self: Self) -> PandasLikeSeriesListNamespace:
         return PandasLikeSeriesListNamespace(self)
+
+    @property
+    def struct(self: Self) -> PandasLikeSeriesStructNamespace:
+        return PandasLikeSeriesStructNamespace(self)

narwhals/_pandas_like/series_struct.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._pandas_like.series import PandasLikeSeries
+
+
+class PandasLikeSeriesStructNamespace:
+    def __init__(self: Self, series: PandasLikeSeries) -> None:
+        self._compliant_series = series
+
+    def field(self: Self, name: str) -> PandasLikeSeries:
+        return self._compliant_series._from_native_series(
+            self._compliant_series._native_series.apply(lambda x: x[name]).rename(name),
+        )

narwhals/_polars/expr.py

@@ -306,6 +306,10 @@ def name(self: Self) -> PolarsExprNameNamespace:
     def list(self: Self) -> PolarsExprListNamespace:
         return PolarsExprListNamespace(self)
 
+    @property
+    def struct(self: Self) -> PolarsExprStructNamespace:
+        return PolarsExprStructNamespace(self)
+
 
 class PolarsExprDateTimeNamespace:
     def __init__(self: Self, expr: PolarsExpr) -> None:
@@ -391,3 +395,14 @@ def func(*args: Any, **kwargs: Any) -> PolarsExpr:
             )
 
         return func
+
+
+class PolarsExprStructNamespace:
+    def __init__(self: Self, expr: PolarsExpr) -> None:
+        self._expr = expr
+
+    def field(self: Self, name: str) -> PolarsExpr:
+        native_expr = self._expr._native_expr
+        native_result = native_expr.struct.field(name)
+
+        return self._expr._from_native_expr(native_result)

narwhals/_polars/series.py

@@ -647,3 +647,14 @@ def func(*args: Any, **kwargs: Any) -> Any:
             )
 
         return func
+
+
+class PolarsSeriesStructNamespace:
+    def __init__(self: Self, series: PolarsSeries) -> None:
+        self._series = series
+
+    def field(self: Self, *names: str) -> PolarsSeries:
+        native_series = self._series._native_series
+        native_result = native_series.struct.field(*names)
+
+        return self._series._from_native_series(native_result)

narwhals/_spark_like/expr.py

@@ -14,6 +14,7 @@
 from narwhals._spark_like.expr_list import SparkLikeExprListNamespace
 from narwhals._spark_like.expr_name import SparkLikeExprNameNamespace
 from narwhals._spark_like.expr_str import SparkLikeExprStringNamespace
+from narwhals._spark_like.expr_struct import SparkLikeExprStructNamespace
 from narwhals._spark_like.utils import maybe_evaluate_expr
 from narwhals._spark_like.utils import narwhals_to_native_dtype
 from narwhals.dependencies import get_pyspark
@@ -526,3 +527,7 @@ def dt(self: Self) -> SparkLikeExprDateTimeNamespace:
     @property
     def list(self: Self) -> SparkLikeExprListNamespace:
         return SparkLikeExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> SparkLikeExprStructNamespace:
+        return SparkLikeExprStructNamespace(self)

narwhals/_spark_like/expr_struct.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from narwhals._spark_like.expr import SparkLikeExpr
+
+
+class SparkLikeExprStructNamespace:
+    def __init__(self: Self, expr: SparkLikeExpr) -> None:
+        self._compliant_expr = expr
+
+    def field(self: Self, name: str) -> SparkLikeExpr:
+        self._compliant_expr._evaluate_output_names = lambda _col: [name]
+        return self._compliant_expr._from_call(lambda col: col.getField(name), "field")

narwhals/expr.py

@@ -20,6 +20,7 @@
 from narwhals.expr_list import ExprListNamespace
 from narwhals.expr_name import ExprNameNamespace
 from narwhals.expr_str import ExprStringNamespace
+from narwhals.expr_struct import ExprStructNamespace
 from narwhals.translate import to_native
 from narwhals.utils import _validate_rolling_arguments
 from narwhals.utils import flatten
@@ -2467,6 +2468,10 @@ def name(self: Self) -> ExprNameNamespace[Self]:
     def list(self: Self) -> ExprListNamespace[Self]:
         return ExprListNamespace(self)
 
+    @property
+    def struct(self: Self) -> ExprStructNamespace[Self]:
+        return ExprStructNamespace(self)
+
 
 __all__ = [
     "Expr",