pavise.polars

Polars backend for type-parameterized DataFrame with Protocol-based schema validation.

class pavise.polars.DataFrame(data, *args, strict=False, **kwargs)

Bases: DataFrame, Generic[SchemaT_co]

Type-parameterized DataFrame with runtime validation for Polars.

Usage:

# Static type checking only
def process(df: DataFrame[UserSchema]) -> DataFrame[UserSchema]:
    return df

# Runtime validation
validated = DataFrame[UserSchema](raw_df)

The type parameter is covariant, allowing structural subtyping. DataFrame[ChildSchema] is compatible with DataFrame[ParentSchema] when ChildSchema has all columns of ParentSchema.

Parameters:

• data (Any)

• args (Any)

• strict (bool)

• kwargs (Any)

classmethod __class_getitem__(schema)

Create a new DataFrame class with schema validation.

Parameters:

schema (type)

__init__(data, *args, strict=False, **kwargs)

Initialize DataFrame with optional schema validation.

Parameters:

• data (Any) – Data to create DataFrame from (pl.DataFrame or dict/list)

• *args (Any) – Additional arguments passed to pl.DataFrame

• strict (bool) – If True, raise error on extra columns not in schema

• **kwargs (Any) – Additional keyword arguments passed to pl.DataFrame

Raises:

• ValueError – If required column is missing

• TypeError – If column has wrong type

classmethod make_empty()

Create an empty DataFrame with columns from the schema.

Returns:

Empty DataFrame with correct column types

Return type:

DataFrame

class pavise.polars.LazyFrame(data, strict=False)

Bases: LazyFrame, Generic[SchemaT_co]

Type-parameterized LazyFrame with runtime schema validation for Polars.

Schema validation happens at construction time using collect_schema(). Value-based validators (Range, Unique, etc.) are only checked on collect().

Parameters:

• data (LazyFrame)

• strict (bool)

classmethod __class_getitem__(schema)

Create a new LazyFrame class with schema validation.

Parameters:

schema (type)

static __new__(cls, data, strict=False)

Create LazyFrame instance by copying internal state from source.

Parameters:

• data (LazyFrame)

• strict (bool)

__init__(_data, strict=False)

Initialize LazyFrame with schema validation.

Parameters:

• data – Polars LazyFrame to wrap

• strict (bool) – If True, raise error on extra columns not in schema

• _data (LazyFrame)

collect()

Collect LazyFrame into DataFrame with full validation.

Returns:

DataFrame[Schema] with all validators applied

Return type:

TypedDataFrame

classmethod make_empty()

Create an empty LazyFrame with columns from the schema.

Returns:

Empty LazyFrame with correct column types

Return type:

LazyFrame