API Reference

Core

class frameright.core.FieldInfo(alias=None, ge=None, gt=None, le=None, lt=None, isin=None, regex=None, min_length=None, max_length=None, nullable=True, unique=False)[source]

Bases: object

Stores metadata for column mapping and field-level validation.

alias: Map this attribute to a differently-named DataFrame column.

ge: Value must be greater than or equal to this.

gt: Value must be strictly greater than this.

le: Value must be less than or equal to this.

lt: Value must be strictly less than this.

isin: Value must be one of these allowed values.

regex: String value must match this regex pattern.

min_length: String value must be at least this long.

max_length: String value must be at most this long.

nullable: Whether NaN/None values are allowed (default True).

unique: Whether all values must be unique (default False).

frameright.core.Field(alias=None, ge=None, gt=None, le=None, lt=None, isin=None, regex=None, min_length=None, max_length=None, nullable=True, unique=False)[source]

Helper function to define a field’s properties and constraints.

Parameters:

alias (Optional[str]) – Map this attribute to a differently-named DataFrame column.
ge (Optional[float]) – Value must be >= this threshold.
gt (Optional[float]) – Value must be > this threshold.
le (Optional[float]) – Value must be <= this threshold.
lt (Optional[float]) – Value must be < this threshold.
isin (Optional[List[Any]]) – Value must be one of these allowed values.
regex (Optional[str]) – String value must match this regex pattern.
min_length (Optional[int]) – String value must be at least this long.
max_length (Optional[int]) – String value must be at most this long.
nullable (bool) – Whether NaN/None values are allowed (default True).
unique (bool) – Whether all values must be unique (default False).

Return type:

Any

Returns:

A FieldInfo metadata object consumed by Schema during class creation.

class frameright.core.BaseSchema(df, copy=False, validate=True, validate_types=True, coerce=False, coerce_errors='raise', strict=False)[source]

Bases: object

Base class for the Object-DataFrame Mapper (ODM).

Define your DataFrame schema as a Python class with typed attributes. Schema validates column existence, runtime dtypes, and field-level constraints, while providing IDE-friendly autocomplete and type safety.

Do not instantiate BaseSchema directly. Use backend-specific Schema classes:

from frameright.pandas import Schema # For pandas from frameright.polars.eager import Schema # For polars eager from frameright.polars.lazy import Schema # For polars lazy

Example with pandas:

import pandas as pd
from frameright.pandas import Schema, Col

class Orders(Schema):
    order_id: Col[int]
    revenue: Col[float]

orders = Orders(pd.DataFrame(...))
orders.revenue  # Returns pd.Series
orders.revenue.sum()  # Use pandas methods

Example with polars:

import polars as pl
from frameright.polars.eager import Schema, Col

class Orders(Schema):
    order_id: Col[int]
    revenue: Col[float]

orders = Orders(pl.DataFrame(...))
orders.revenue  # Returns pl.Series
orders.revenue.sum()  # Use polars methods

Use fr_data to access the underlying DataFrame.

fr_validate(check_types=True, strict=False)[source]

Validate column existence, runtime dtypes, and field-level constraints.

Uses Pandera for validation, with errors translated into Schema exception types (MissingColumnError, TypeMismatchError, ConstraintViolationError).

Parameters:

check_types (bool) – If True, also validate that column dtypes match the type annotations. Defaults to True.
strict (bool) – If True, reject DataFrames with columns not defined in the schema. Defaults to False (extra columns are allowed).

Return type:

Self

Returns:

self, for method chaining.

Raises:

MissingColumnError – If a required column is not present.
TypeMismatchError – If a column’s dtype doesn’t match the annotation.
ConstraintViolationError – If a field-level constraint is violated.

property fr_data: Any

Return the underlying DataFrame.

For pandas backend, returns pd.DataFrame. For polars backend, returns pl.DataFrame or pl.LazyFrame. For narwhals backend, returns nw.DataFrame.

This property gives direct access to the DataFrame for performing operations using the backend’s native API:

# Pandas operations
df.fr_data.groupby('column').sum()

# Polars operations
df.fr_data.filter(pl.col('x') > 5)

# LazyFrame operations
lazy_df.fr_data.collect()

classmethod fr_schema_info()[source]

Return the schema definition as a list of dictionaries.

Returns:: attribute, column, type, required, nullable, unique, constraints.
Return type:: List[Dict[str, Any]]

Typing

Generic column type for Schema.

Col[T] is a generic type used for type annotations in Schema schemas.

For backend-specific imports: - from frameright.typing.pandas import Col - from frameright.typing.polars_eager import Col # Polars DataFrame (eager) - from frameright.typing.polars_lazy import Col # Polars LazyFrame (lazy) - from frameright.typing.narwhals import Col

At runtime, Col is a lightweight generic sentinel used by __init_subclass__ to detect annotated columns. At type-check time, it’s a generic type that allows IDE autocompletion and type hints.

Typing note: with pandas-stubs installed, type checkers can treat Col[T] as pd.Series[T]. Other backends are best-effort because their upstream libraries do not currently expose fully generic Series[T] / Expr[T] types.

class frameright.typing.Col[source]: Generic column type marker for Schema schemas.

Pandas-specific column types for Schema.

Use these imports when your Schema subclass wraps a pandas DataFrame:

from frameright.typing.pandas import Col

At type-check time Col[T] resolves to pd.Series[T], giving full IDE autocomplete and static analysis. At runtime Col is identical to the generic sentinel from frameright.typing (used by __init_subclass__ for schema parsing).