feat: Added struct namespace with field method.

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

@@ -14,6 +14,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
@@ -639,3 +640,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,24 @@
+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:
+        return reuse_series_namespace_implementation(
+            self._compliant_expr,
+            "struct",
+            "field",
+            name=name,
+            evaluate_output_names=lambda _col: [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
@@ -1213,3 +1214,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/_dask/expr.py

@@ -156,6 +156,8 @@ def _from_call(
         call: Callable[..., dx.Series],
         expr_name: str,
         call_kwargs: dict[str, Any] | None = None,
+        evaluate_output_names: Callable[[DaskLazyFrame], Sequence[str]] | None = None,
+        alias_output_names: Callable[[Sequence[str]], Sequence[str]] | None = None,
         **expressifiable_args: Self | Any,
     ) -> Self:
         def func(df: DaskLazyFrame) -> list[dx.Series]:
@@ -170,12 +172,18 @@ def func(df: DaskLazyFrame) -> list[dx.Series]:
                 native_results.append(result_native)
             return native_results
 
+        if evaluate_output_names is None:
+            evaluate_output_names = self._evaluate_output_names
+
+        if alias_output_names is None:
+            alias_output_names = self._alias_output_names
+
         return self.__class__(
             func,
             depth=self._depth + 1,
             function_name=f"{self._function_name}->{expr_name}",
-            evaluate_output_names=self._evaluate_output_names,
-            alias_output_names=self._alias_output_names,
+            evaluate_output_names=evaluate_output_names,
+            alias_output_names=alias_output_names,
             backend_version=self._backend_version,
             version=self._version,
             call_kwargs=call_kwargs,
@@ -643,3 +651,4 @@ def name(self: Self) -> DaskExprNameNamespace:
 
     cat = not_implemented()  # pyright: ignore[reportAssignmentType]
     list = not_implemented()  # pyright: ignore[reportAssignmentType]
+    struct = not_implemented()  # pyright: ignore[reportAssignmentType]

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
@@ -124,13 +125,17 @@ def _from_call(
         self: Self,
         call: Callable[..., duckdb.Expression],
         expr_name: str,
+        evaluate_output_names: Callable[[DuckDBLazyFrame], Sequence[str]] | None = None,
+        alias_output_names: Callable[[Sequence[str]], Sequence[str]] | None = None,
         **expressifiable_args: Self | Any,
     ) -> Self:
         """Create expression from callable.
 
         Arguments:
             call: Callable from compliant DataFrame to native Expression
             expr_name: Expression name
+            evaluate_output_names: Output names function.
+            alias_output_names: Alias Output names function.
             expressifiable_args: arguments pass to expression which should be parsed
                 as expressions (e.g. in `nw.col('a').is_between('b', 'c')`)
         """
@@ -146,11 +151,17 @@ def func(df: DuckDBLazyFrame) -> list[duckdb.Expression]:
                 for native_series in native_series_list
             ]
 
+        if evaluate_output_names is None:
+            evaluate_output_names = self._evaluate_output_names
+
+        if alias_output_names is None:
+            alias_output_names = self._alias_output_names
+
         return self.__class__(
             func,
             function_name=f"{self._function_name}->{expr_name}",
-            evaluate_output_names=self._evaluate_output_names,
-            alias_output_names=self._alias_output_names,
+            evaluate_output_names=evaluate_output_names,
+            alias_output_names=alias_output_names,
             backend_version=self._backend_version,
             version=self._version,
         )
@@ -484,6 +495,10 @@ def name(self: Self) -> DuckDBExprNameNamespace:
     def list(self: Self) -> DuckDBExprListNamespace:
         return DuckDBExprListNamespace(self)
 
+    @property
+    def struct(self: Self) -> DuckDBExprStructNamespace:
+        return DuckDBExprStructNamespace(self)
+
     arg_min = not_implemented()
     arg_max = not_implemented()
     arg_true = not_implemented()

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:
+        return self._compliant_expr._from_call(
+            lambda _input: FunctionExpression("struct_extract", _input, lit(name)).alias(
+                name
+            ),
+            "field",
+            evaluate_output_names=lambda _col: [name],
+        )

narwhals/_expression_parsing.py

@@ -25,7 +25,9 @@
     from typing_extensions import Never
     from typing_extensions import TypeIs
 
+    from narwhals._arrow.dataframe import ArrowDataFrame
     from narwhals._arrow.expr import ArrowExpr
+    from narwhals._pandas_like.dataframe import PandasLikeDataFrame
     from narwhals._pandas_like.expr import PandasLikeExpr
     from narwhals.expr import Expr
     from narwhals.typing import CompliantDataFrame
@@ -206,6 +208,10 @@ def reuse_series_namespace_implementation(
     expr: ArrowExprT | PandasLikeExprT,
     series_namespace: str,
     attr: str,
+    evaluate_output_names: Callable[[ArrowDataFrame], Sequence[str]]
+    | Callable[[PandasLikeDataFrame], Sequence[str]]
+    | None = None,
+    alias_output_names: Callable[[Sequence[str]], Sequence[str]] | None = None,
     **kwargs: Any,
 ) -> ArrowExprT | PandasLikeExprT:
     """Reuse Series implementation for expression.
@@ -217,18 +223,27 @@ def reuse_series_namespace_implementation(
         expr: expression object.
         series_namespace: The Series namespace (e.g. `dt`, `cat`, `str`, `list`, `name`)
         attr: name of method.
+        evaluate_output_names: Output names function.
+        alias_output_names: Alias output names function.
         kwargs: keyword arguments to pass to function.
     """
     plx = expr.__narwhals_namespace__()
+
+    if evaluate_output_names is None:
+        evaluate_output_names = expr._evaluate_output_names
+
+    if alias_output_names is None:
+        alias_output_names = expr._alias_output_names
+
     return plx._create_expr_from_callable(  # type: ignore[return-value]
         lambda df: [
             getattr(getattr(series, series_namespace), attr)(**kwargs)
             for series in expr(df)  # type: ignore[arg-type]
         ],
         depth=expr._depth + 1,
         function_name=f"{expr._function_name}->{series_namespace}.{attr}",
-        evaluate_output_names=expr._evaluate_output_names,  # type: ignore[arg-type]
-        alias_output_names=expr._alias_output_names,
+        evaluate_output_names=evaluate_output_names,  # type: ignore[arg-type]
+        alias_output_names=alias_output_names,
     )
 
 

narwhals/_pandas_like/expr.py

@@ -17,6 +17,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.dependencies import get_numpy
@@ -742,3 +743,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,24 @@
+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:
+        return reuse_series_namespace_implementation(
+            self._compliant_expr,
+            "struct",
+            "field",
+            name=name,
+            evaluate_output_names=lambda _col: [name],
+        )

narwhals/_pandas_like/series.py

@@ -15,6 +15,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
@@ -1131,3 +1132,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_list.py

@@ -16,6 +16,9 @@
 
 class PandasLikeSeriesListNamespace:
     def __init__(self: Self, series: PandasLikeSeries) -> None:
+        if not hasattr(series._native_series, "list"):
+            msg = "Series must be of PyArrow List type to support struct namespace."
+            raise TypeError(msg)
         self._compliant_series = series
 
     def len(self: Self) -> PandasLikeSeries: