polars

Recommended: Annotated type annotation

For most use cases, annotate with Annotated[pl.DataFrame, MySchema] and use native polars expressions. The checker validates both subscript access and pl.col() references at lint time:

from typing import Annotated
import polars as pl
from typedframes import BaseSchema, Column

class EventSchema(BaseSchema):
    event_id  = Column(type=int)
    user_id   = Column(type=int)
    timestamp = Column(type=str)

df: Annotated[pl.DataFrame, EventSchema] = pl.read_csv("events.csv")

# Native polars — both forms validated by checker
print(df.select(pl.col("event_id")))             # ✓ pl.col() validated
print(df.filter(pl.col("timestamp").is_not_null()))  # ✓ pl.col() in filter
print(df.select(pl.col("typo")))                  # ✗ unknown-column — 'typo' not in EventSchema

# Descriptor access — refactor-safe polars expressions
df.select(EventSchema.event_id.col, EventSchema.user_id.col)
df.filter(EventSchema.user_id.col > 100)

PolarsFrame — runtime enhancement

PolarsFrame is a polars DataFrame wrapper that adds descriptor dispatch. Use it when you want df[Schema.column] subscript syntax without .col:

from typedframes.polars import PolarsFrame
from typedframes import BaseSchema, Column

class EventSchema(BaseSchema):
    event_id = Column(type=int)

df = PolarsFrame.from_schema(pl.read_csv("events.csv"), EventSchema)
df[EventSchema.event_id]  # descriptor dispatch — returns the column series

!!! note Prefer Annotated[pl.DataFrame, Schema] for new code. The checker validates pl.col() references directly, so descriptor dispatch is optional.

---

typedframes.polars.PolarsFrame

Bases: Generic[SchemaT]

Type marker for schema-annotated polars DataFrames.

This is a type-only construct - at runtime, PolarsFrame[Schema] returns Annotated[pl.DataFrame, Schema], meaning the actual value is a plain pl.DataFrame with full polars functionality.

The typedframes checker parses the Annotated metadata to validate column access statically.

Example

df: PolarsFrame[UserSchema] = pl.read_csv("users.csv")

This is equivalent to:

df: Annotated[pl.DataFrame, UserSchema] = pl.read_csv("users.csv")

Full polars autocomplete and all methods work

result = df.filter(pl.col("user_id") > 10).select("email")

Schema-based column access (for building expressions)

df.filter(UserSchema.user_id.col > 10)

Functions

__class_getitem__(schema)

Create an Annotated type combining pl.DataFrame with schema metadata.

Parameters:

Name	Type	Description	Default
schema	type[SchemaT]	A BaseSchema subclass defining the DataFrame structure.	required

Returns:

Type	Description
Any	Annotated[pl.DataFrame, schema] for type checking.

Source code in src/typedframes/polars.py

def __class_getitem__(cls, schema: type[SchemaT]) -> Any:
    """
    Create an Annotated type combining pl.DataFrame with schema metadata.

    Args:
        schema: A BaseSchema subclass defining the DataFrame structure.

    Returns:
        Annotated[pl.DataFrame, schema] for type checking.

    """
    import polars as pl

    return Annotated[pl.DataFrame, schema]

read_csv(source, schema, **kwargs) classmethod

Read a CSV file into a polars DataFrame.

The schema parameter is for typing and static checking only — it is not validated or attached to the DataFrame at runtime. This method is a pass-through to pl.read_csv.

Parameters:

Name	Type	Description	Default
source	Any	File path or buffer to read from.	required
schema	type[SchemaT]	Schema class describing the expected DataFrame structure. Used for static analysis only; ignored at runtime.	required
**kwargs	Any	Additional arguments passed to pl.read_csv.	{}

Returns:

Type	Description
Any	A plain polars DataFrame. Annotate the result as PolarsFrame[Schema].

Source code in src/typedframes/polars.py

@classmethod
def read_csv(cls, source: Any, schema: type[SchemaT], **kwargs: Any) -> Any:  # noqa: ARG003
    """
    Read a CSV file into a polars DataFrame.

    The schema parameter is for typing and static checking only — it is not
    validated or attached to the DataFrame at runtime. This method is a
    pass-through to ``pl.read_csv``.

    Args:
        source: File path or buffer to read from.
        schema: Schema class describing the expected DataFrame structure.
            Used for static analysis only; ignored at runtime.
        **kwargs: Additional arguments passed to ``pl.read_csv``.

    Returns:
        A plain polars DataFrame. Annotate the result as ``PolarsFrame[Schema]``.

    """
    import polars as pl

    return pl.read_csv(source, **kwargs)

read_excel(source, schema, **kwargs) classmethod

Read an Excel file into a polars DataFrame.

The schema parameter is for typing and static checking only — it is not validated or attached to the DataFrame at runtime. This method is a pass-through to pl.read_excel.

Parameters:

Name	Type	Description	Default
source	Any	File path or buffer to read from.	required
schema	type[SchemaT]	Schema class describing the expected DataFrame structure. Used for static analysis only; ignored at runtime.	required
**kwargs	Any	Additional arguments passed to pl.read_excel.	{}

Returns:

Type	Description
Any	A plain polars DataFrame. Annotate the result as PolarsFrame[Schema].

Source code in src/typedframes/polars.py

@classmethod
def read_excel(cls, source: Any, schema: type[SchemaT], **kwargs: Any) -> Any:  # noqa: ARG003
    """
    Read an Excel file into a polars DataFrame.

    The schema parameter is for typing and static checking only — it is not
    validated or attached to the DataFrame at runtime. This method is a
    pass-through to ``pl.read_excel``.

    Args:
        source: File path or buffer to read from.
        schema: Schema class describing the expected DataFrame structure.
            Used for static analysis only; ignored at runtime.
        **kwargs: Additional arguments passed to ``pl.read_excel``.

    Returns:
        A plain polars DataFrame. Annotate the result as ``PolarsFrame[Schema]``.

    """
    import polars as pl

    return pl.read_excel(source, **kwargs)

read_json(source, schema, **kwargs) classmethod

Read a JSON file into a polars DataFrame.

The schema parameter is for typing and static checking only — it is not validated or attached to the DataFrame at runtime. This method is a pass-through to pl.read_json.

Parameters:

Name	Type	Description	Default
source	Any	File path or buffer to read from.	required
schema	type[SchemaT]	Schema class describing the expected DataFrame structure. Used for static analysis only; ignored at runtime.	required
**kwargs	Any	Additional arguments passed to pl.read_json.	{}

Returns:

Type	Description
Any	A plain polars DataFrame. Annotate the result as PolarsFrame[Schema].

Source code in src/typedframes/polars.py

@classmethod
def read_json(cls, source: Any, schema: type[SchemaT], **kwargs: Any) -> Any:  # noqa: ARG003
    """
    Read a JSON file into a polars DataFrame.

    The schema parameter is for typing and static checking only — it is not
    validated or attached to the DataFrame at runtime. This method is a
    pass-through to ``pl.read_json``.

    Args:
        source: File path or buffer to read from.
        schema: Schema class describing the expected DataFrame structure.
            Used for static analysis only; ignored at runtime.
        **kwargs: Additional arguments passed to ``pl.read_json``.

    Returns:
        A plain polars DataFrame. Annotate the result as ``PolarsFrame[Schema]``.

    """
    import polars as pl

    return pl.read_json(source, **kwargs)

read_parquet(source, schema, **kwargs) classmethod

Read a Parquet file into a polars DataFrame.

The schema parameter is for typing and static checking only — it is not validated or attached to the DataFrame at runtime. This method is a pass-through to pl.read_parquet.

Parameters:

Name	Type	Description	Default
source	Any	File path or buffer to read from.	required
schema	type[SchemaT]	Schema class describing the expected DataFrame structure. Used for static analysis only; ignored at runtime.	required
**kwargs	Any	Additional arguments passed to pl.read_parquet.	{}

Returns:

Type	Description
Any	A plain polars DataFrame. Annotate the result as PolarsFrame[Schema].

Source code in src/typedframes/polars.py

@classmethod
def read_parquet(cls, source: Any, schema: type[SchemaT], **kwargs: Any) -> Any:  # noqa: ARG003
    """
    Read a Parquet file into a polars DataFrame.

    The schema parameter is for typing and static checking only — it is not
    validated or attached to the DataFrame at runtime. This method is a
    pass-through to ``pl.read_parquet``.

    Args:
        source: File path or buffer to read from.
        schema: Schema class describing the expected DataFrame structure.
            Used for static analysis only; ignored at runtime.
        **kwargs: Additional arguments passed to ``pl.read_parquet``.

    Returns:
        A plain polars DataFrame. Annotate the result as ``PolarsFrame[Schema]``.

    """
    import polars as pl

    return pl.read_parquet(source, **kwargs)