feat(python): expose to_struct to series list namespace (#5298)

py-polars/docs/source/reference/series.rst

@@ -332,6 +332,7 @@ The following methods are available under the `Series.arr` attribute.
     ListNameSpace.sort
     ListNameSpace.sum
     ListNameSpace.tail
+    ListNameSpace.to_struct
     ListNameSpace.unique
 
 Categories

py-polars/polars/internals/series/list.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 from datetime import date, datetime
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Callable
 
 import polars.internals as pli
 from polars.internals.series.utils import expr_dispatch
 
 if TYPE_CHECKING:
-    from polars.internals.type_aliases import NullBehavior
+    from polars.internals.type_aliases import NullBehavior, ToStructStrategy
     from polars.polars import PySeries
 
 
@@ -268,6 +268,48 @@ def tail(self, n: int = 5) -> pli.Series:
 
         """
 
+    def to_struct(
+        self,
+        n_field_strategy: ToStructStrategy = "first_non_null",
+        name_generator: Callable[[int], str] | None = None,
+    ) -> pli.Series:
+        """
+        Convert the series of type ``List`` to a series of type ``Struct``.
+
+        Parameters
+        ----------
+        n_field_strategy : {'first_non_null', 'max_width'}
+            Strategy to determine the number of fields of the struct.
+        name_generator
+            A custom function that can be used to generate the field names.
+            Default field names are `field_0, field_1 .. field_n`
+
+        Examples
+        --------
+        >>> df = pl.DataFrame({"a": [[1, 2, 3], [1, 2]]})
+        >>> df.select([pl.col("a").arr.to_struct()])
+        shape: (2, 1)
+        ┌────────────┐
+        │ a          │
+        │ ---        │
+        │ struct[3]  │
+        ╞════════════╡
+        │ {1,2,3}    │
+        ├╌╌╌╌╌╌╌╌╌╌╌╌┤
+        │ {1,2,null} │
+        └────────────┘
+        >>> df.select(
+        ...     [
+        ...         pl.col("a").arr.to_struct(
+        ...             name_generator=lambda idx: f"col_name_{idx}"
+        ...         )
+        ...     ]
+        ... ).to_series().to_list()
+        [{'col_name_0': 1, 'col_name_1': 2, 'col_name_2': 3},
+        {'col_name_0': 1, 'col_name_1': 2, 'col_name_2': None}]
+
+        """
+
     def eval(self, expr: pli.Expr, parallel: bool = False) -> pli.Series:
         """
         Run any polars expression against the lists' elements.