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,23 @@
+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,
+        ).alias(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

@@ -643,3 +643,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
@@ -131,6 +132,8 @@ def _from_call(
         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')`)
         """
@@ -484,6 +487,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,25 @@
+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",
+        ).alias(name)

narwhals/_expression_parsing.py

@@ -217,9 +217,12 @@ 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__()
+
     return plx._create_expr_from_callable(  # type: ignore[return-value]
         lambda df: [
             getattr(getattr(series, series_namespace), attr)(**kwargs)

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,23 @@
+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,
+        ).alias(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:

narwhals/_pandas_like/series_struct.py

@@ -0,0 +1,21 @@
+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:
+        if not hasattr(series._native_series, "struct"):
+            msg = "Series must be of PyArrow Struct type to support struct namespace."
+            raise TypeError(msg)
+        self._compliant_series = series
+
+    def field(self: Self, name: str) -> PandasLikeSeries:
+        return self._compliant_series._from_native_series(
+            self._compliant_series._native_series.struct.field(name).rename(name)
+        )

narwhals/_polars/expr.py

@@ -320,6 +320,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:
@@ -405,3 +409,19 @@ def func(*args: Any, **kwargs: Any) -> PolarsExpr:
             )
 
         return func
+
+
+class PolarsExprStructNamespace:
+    def __init__(self: Self, expr: PolarsExpr) -> None:
+        self._expr = expr
+
+    def __getattr__(
+        self: Self, attr: str
+    ) -> Callable[[Any], PolarsExpr]:  # pragma: no cover
+        def func(*args: Any, **kwargs: Any) -> PolarsExpr:
+            args, kwargs = extract_args_kwargs(args, kwargs)  # type: ignore[assignment]
+            return self._expr._from_native_expr(
+                getattr(self._expr._native_expr.struct, attr)(*args, **kwargs)
+            )
+
+        return func

narwhals/_polars/series.py

@@ -580,6 +580,10 @@ def cat(self: Self) -> PolarsSeriesCatNamespace:
     def list(self: Self) -> PolarsSeriesListNamespace:
         return PolarsSeriesListNamespace(self)
 
+    @property
+    def struct(self: Self) -> PolarsSeriesStructNamespace:
+        return PolarsSeriesStructNamespace(self)
+
 
 class PolarsSeriesDateTimeNamespace:
     def __init__(self: Self, series: PolarsSeries) -> None:
@@ -650,3 +654,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, name: str) -> PolarsSeries:
+        native_series = self._series._native_series
+        native_result = native_series.struct.field(name)
+
+        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
@@ -591,6 +592,10 @@ def dt(self: Self) -> SparkLikeExprDateTimeNamespace:
     def list(self: Self) -> SparkLikeExprListNamespace:
         return SparkLikeExprListNamespace(self)
 
+    @property
+    def struct(self: Self) -> SparkLikeExprStructNamespace:
+        return SparkLikeExprStructNamespace(self)
+
     arg_min = not_implemented()
     arg_max = not_implemented()
     arg_true = not_implemented()