Skip to content

yggdrasil.polars.cast

cast

register_converter 

register_converter(from_hint: Any, to_hint: Any) -> Callable[[F], F]

Decorator to register a converter from from_hint -> to_hint.

This preserves the original function object (and its type signature), while registering it as a runtime Converter.

Wildcard registrations

If from_hint is typing.Any or object, the converter is stored in _any_registry[to_hint] and is eligible for any source value type.

Expected converter behavior

func(value, options) -> converted_value

where options may be None.

any_to_polars_dataframe 

any_to_polars_dataframe(
    obj: Any, options: Optional[CastOptions] = None
) -> pl.DataFrame

Convert any supported object to a pl.DataFrame, then cast to the target schema.

Dispatch order is by isinstance against the well-known engine classes first (polars, pyarrow), then by type(obj).__module__ for the rarer engines that we can't isinstance against without importing them (pandas, pyspark). The module-prefix check is cheap — type(obj).__module__ is a single attribute read, no inspect.unwrap walk.

Supported input types:

  • pl.DataFrame — passed through to :func:cast_polars_dataframe.
  • pl.LazyFrame — collect() first, then cast.
  • pa.Table / pa.RecordBatch / pa.RecordBatchReader / pa.dataset.Scanner — routed through pl.from_arrow (zero-copy where possible).
  • pandas.DataFrame — routed through pl.from_pandas.
  • pyspark.sql.DataFrame — materialised via Spark's toArrow() and loaded with pl.from_arrow.
  • None — an empty frame with the target schema (if any).
  • Everything else (dicts, sequences of dicts, dataclasses, …) — constructed directly via pl.DataFrame(obj).

polars_dataframe_to_arrow_table 

polars_dataframe_to_arrow_table(
    df: Union[DataFrame, LazyFrame], options: Optional[CastOptions] = None
) -> pa.Table

Convert a Polars frame to a pa.Table, then cast to the target schema.

pl.LazyFrame inputs are materialised via collect() first. The polars→arrow bridge runs with compat_level=newest() so string / binary / list columns surface as Arrow view types (string_view / binary_view / list_view) which Polars produces zero-copy — a ~6× speedup over the legacy to_arrow() default (large_string / large_binary / large_list) on the hot name-heavy shape. The downstream :func:cast_arrow_tabular pass casts view types to whatever the target schema demands (typically string / binary), which Arrow's compute kernels handle cheaply via the view layout.