feat: Added struct namespace with field method. (#2146)

osoucy · web-flow · commit ea213c48cf1e · 2025-03-09T21:35:09.000Z
diff --git a/docs/api-reference/expr_struct.md b/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
diff --git a/docs/api-reference/index.md b/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)
diff --git a/docs/api-reference/series_struct.md b/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
diff --git a/mkdocs.yml b/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
diff --git a/narwhals/_arrow/expr.py b/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
@@ -635,3 +636,7 @@ def name(self: Self) -> ArrowExprNameNamespace:
     @property
     def list(self: Self) -> ArrowExprListNamespace:
         return ArrowExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> ArrowExprStructNamespace:
+        return ArrowExprStructNamespace(self)
diff --git a/narwhals/_arrow/expr_struct.py b/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)
diff --git a/narwhals/_arrow/series.py b/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)
diff --git a/narwhals/_arrow/series_struct.py b/narwhals/_arrow/series_struct.py
@@ -0,0 +1,20 @@
+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:
+        return self._compliant_series._from_native_series(
+            pc.struct_field(self._compliant_series._native_series, name),
+        ).alias(name)
diff --git a/narwhals/_dask/expr.py b/narwhals/_dask/expr.py
@@ -652,3 +652,4 @@ def name(self: Self) -> DaskExprNameNamespace:
 
     cat = not_implemented()  # pyright: ignore[reportAssignmentType]
     list = not_implemented()  # pyright: ignore[reportAssignmentType]
+    struct = not_implemented()  # pyright: ignore[reportAssignmentType]
diff --git a/narwhals/_duckdb/expr.py b/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
@@ -484,6 +485,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()
diff --git a/narwhals/_duckdb/expr_struct.py b/narwhals/_duckdb/expr_struct.py
@@ -0,0 +1,23 @@
+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)),
+            "field",
+        ).alias(name)
diff --git a/narwhals/_expression_parsing.py b/narwhals/_expression_parsing.py
@@ -220,6 +220,7 @@ def reuse_series_namespace_implementation(
         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)
diff --git a/narwhals/_pandas_like/expr.py b/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
@@ -753,3 +754,7 @@ def name(self: Self) -> PandasLikeExprNameNamespace:
     @property
     def list(self: Self) -> PandasLikeExprListNamespace:
         return PandasLikeExprListNamespace(self)
+
+    @property
+    def struct(self: Self) -> PandasLikeExprStructNamespace:
+        return PandasLikeExprStructNamespace(self)
diff --git a/narwhals/_pandas_like/expr_struct.py b/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)
diff --git a/narwhals/_pandas_like/series.py b/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)
diff --git a/narwhals/_pandas_like/series_list.py b/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 list namespace."
+            raise TypeError(msg)
         self._compliant_series = series
 
     def len(self: Self) -> PandasLikeSeries:
diff --git a/narwhals/_pandas_like/series_struct.py b/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)
+        ).alias(name)
diff --git a/narwhals/_polars/expr.py b/narwhals/_polars/expr.py
@@ -316,6 +316,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:
@@ -401,3 +405,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
diff --git a/narwhals/_polars/series.py b/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,19 @@ def func(*args: Any, **kwargs: Any) -> Any:
             )
 
         return func
+
+
+class PolarsSeriesStructNamespace:
+    def __init__(self: Self, series: PolarsSeries) -> None:
+        self._compliant_series = series
+
+    def __getattr__(self: Self, attr: str) -> Any:
+        def func(*args: Any, **kwargs: Any) -> Any:
+            args, kwargs = extract_args_kwargs(args, kwargs)  # type: ignore[assignment]
+            return self._compliant_series._from_native_series(
+                getattr(self._compliant_series._native_series.struct, attr)(
+                    *args, **kwargs
+                )
+            )
+
+        return func
diff --git a/narwhals/_spark_like/expr.py b/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
@@ -617,6 +618,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()
diff --git a/narwhals/_spark_like/expr_struct.py b/narwhals/_spark_like/expr_struct.py
@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyspark.sql import Column
+    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:
+        def func(_input: Column) -> Column:
+            return _input.getField(name)
+
+        return self._compliant_expr._from_call(func, "field").alias(name)
diff --git a/narwhals/expr.py b/narwhals/expr.py
diff --git a/narwhals/expr_struct.py b/narwhals/expr_struct.py
diff --git a/narwhals/series.py b/narwhals/series.py
diff --git a/narwhals/series_struct.py b/narwhals/series_struct.py
diff --git a/narwhals/typing.py b/narwhals/typing.py
diff --git a/tests/expr_and_series/list/len_test.py b/tests/expr_and_series/list/len_test.py
diff --git a/tests/expr_and_series/struct_/__init__.py b/tests/expr_and_series/struct_/__init__.py
diff --git a/tests/expr_and_series/struct_/field_test.py b/tests/expr_and_series/struct_/field_test.py
diff --git a/utils/check_api_reference.py b/utils/check_api_reference.py
diff --git a/utils/generate_backend_completeness.py b/utils/generate_backend_completeness.py

Original file line number	Diff line number	Diff line change
`@@ -652,3 +652,4 @@ def name(self: Self) -> DaskExprNameNamespace:`
`652`	`652`
`653`	`653`	`cat = not_implemented() # pyright: ignore[reportAssignmentType]`
`654`	`654`	`list = not_implemented() # pyright: ignore[reportAssignmentType]`
	`655`	`+ struct = not_implemented() # pyright: ignore[reportAssignmentType]`