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 — deprecated alias

!!! warning "Deprecated" PolarsFrame is deprecated and will be removed in a future release. Use Annotated[pl.DataFrame, Schema] directly (above) instead — PolarsFrame[Schema] has always just been an alias for exactly that, with no real runtime subclass behind it (polars DataFrames are Rust objects that can't be meaningfully subclassed). Under strict type checking, PolarsFrame[Schema] is declared as a nominal pl.DataFrame subclass so it gets full autocomplete — but that means assigning the plain pl.DataFrame it actually always is at runtime looks like a Liskov substitution violation to a type checker. Annotated[...] doesn't have this problem, since it's transparent to both mypy and the runtime.

PolarsFrame[Schema] was a spelling alias for Annotated[pl.DataFrame, Schema]:

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


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


# Deprecated -- emits a DeprecationWarning; prefer Annotated[pl.DataFrame, Schema]
df: PolarsFrame[EventSchema] = pl.read_csv("events.csv")

PolarsFrame.read_csv(source, schema=Schema) / .read_parquet(...) / .read_json(...) / .read_excel(...) are pass-throughs to the corresponding pl.read_* function — schema is accepted for static checking only and is never validated or attached to the result at runtime.

---

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)

Methods:

__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

    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
    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

    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
    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

    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
    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

    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
    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

    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
    return pl.read_parquet(source, **kwargs)