Patito

0.8.6 verified Fri May 01 auth: no python

Patito is a dataframe modelling library built on top of Polars and Pydantic, providing a declarative way to define schemas, validate data, and serialize dataframes. Version 0.8.6 requires Python >= 3.9 and polars >= 1.32.0. The library is actively maintained with frequent releases.

pip install patito

Common errors

error ModuleNotFoundError: No module named 'pydantic' ↓

cause Pydantic is a required dependency but not installed automatically in all environments (e.g., when using pip with --no-deps).

fix

Run 'pip install pydantic'

error polars.exceptions.ComputeError: ... dtype mismatch ↓

cause Patito's validate() casts columns to the types defined in the model; if a column contains incompatible values (e.g., string in an int field), validation fails.

fix

Ensure data in each column can be cast to the model's field type, or use null values for missing data.

Warnings

breaking Patito 0.7.0 dropped support for polars < 1.0 and pydantic < 2.7. If you are on older versions, do not upgrade. ↓

fix Pin patito to <0.7.0 if you need polars 0.x or pydantic <2.7: pip install 'patito<0.7.0'

breaking Patito 0.8.1+ requires polars >= 1.10.0, and 0.8.5+ requires >= 1.32.0. Existing code may break due to polars API changes. ↓

fix Upgrade polars to match patito's requirement: pip install 'polars>=1.32.0'

deprecated The ConfigDict key 'allow_superfluous_columns' is deprecated in favor of 'extra' since patito 0.8.4. ↓

fix Use model_config = ConfigDict(extra='allow') instead of model_config = ConfigDict(allow_superfluous_columns=True).

gotcha When using DataFrame[MyModel] as a type hint, patito's metaclass only works correctly if the module uses from __future__ import annotations or if the hint is inside a function/class that is evaluated at runtime. Otherwise, you may get a generic DataFrame without schema enforcement. ↓

fix Add 'from __future__ import annotations' at the top of your module or use a string annotation: 'DataFrame[MyModel]'

Imports

Model
wrong
```
from patito.models import Model
```
correct
```
from patito import Model
```
Model is exported directly from the top-level package since v0.6.0
DataFrame
wrong
```
from patito.polars import DataFrame
```
correct
```
from patito import DataFrame
```
Patito's DataFrame subclass is available at top-level since v0.7.0

Quickstart

Define a Pydantic model, create a Polars DataFrame, and validate it with patito.

import polars as pl
from patito import Model, validate

class Product(Model):
    product_id: int
    name: str
    price: float = 0.0
    is_active: bool = True

# Create a valid dataframe
df = pl.DataFrame({
    "product_id": [1, 2, 3],
    "name": ["A", "B", "C"],
    "price": [10.0, 20.0, 30.0],
})

# Validate and cast
validated = Product.validate(df)
print(validated)

# Use patito's DataFrame type hint for type checking
products: DataFrame[Product] = df