Skip to content

yggdrasil.data.types.nested.struct_pandas

struct_pandas

Pandas cast helpers for :class:StructType targets.

Pandas has no first-class struct type, so struct/list values flow through Arrow (or Polars) under the hood and surface as Python-object cells in the resulting Series. The public helpers in this module pick the fastest path that can complete the cast end-to-end:

  1. PyArrow round-trip. Treat the pandas Series / DataFrame as Arrow input via pa.array(..., from_pandas=True) / pa.Table. from_pandas, dispatch to the Arrow cast helpers, and surface back through Array.to_pandas() / Table.to_pandas(). No per-row Python loop, no to_pylist materialisation hop.
  2. Polars round-trip. When the Arrow path rejects the source shape (mixed-schema dicts, list-of-mixed-dtype, …), fall back to pl.from_pandas → :func:cast_polars_tabular / expression cast → to_pandas. Polars accepts a slightly different set of object-dtype inputs than Arrow.
  3. Column-by-column. Last-resort path that casts each column / child through its own engine (Arrow or Polars) and reassembles the pandas frame / object Series. This is the only path that touches row-shaped Python values, and it only runs when both vectorised paths above fail.

The arrow→polars→columnwise chain mirrors the wider repo rule "no Python for over data" — anything reachable from a real caller should land on (1) or (2). (3) stays as the documented fallback for shapes pyarrow and polars both reject.