yggdrasil.data.types.nested.struct_polars

struct_polars

Polars cast helpers for :class:StructType targets.

The polars implementation is expression-first — series and tabular casts both lower to a tree of :class:pl.Expr operations, which lets the cast fuse into the LazyFrame plan when the source is lazy.

Three source shapes lower to expressions:

• :func:cast_polars_struct_expr — struct → struct (per-child rebuild via pl.struct(...), null preserved with pl.when(is_null)).
• :func:cast_polars_map_expr — list-of-key/value structs → struct, one list.eval(when key == name) lookup per target child.
• :func:cast_polars_list_expr — list → struct by positional index via list.get(i, null_on_oob=True).

Series wrappers (:func:cast_polars_struct_series, :func:cast_polars_list_series) build a single-column DataFrame and .select(expr).to_series() — same lowering, eager driver.

:func:cast_polars_tabular rebuilds a DataFrame/LazyFrame against the merged schema with one expression per target column.