DataFrame API Compat

0.2.7 verified Fri May 01 auth: no python

A compatibility layer that enables the DataFrame Standard (PEP 764) for pandas and Polars. Version 0.2.7 supports pandas 1.5+ and Polars 0.18+, providing a unified API for common operations. Released monthly.

pip install dataframe-api-compat

Common errors

error ModuleNotFoundError: No module named 'dataframe_api_compat.pandas' ↓

cause The submodule was renamed to `pandas_standard` in version 0.2.0.

fix

Use from dataframe_api_compat.pandas_standard import PandasDataFrame or use the top-level convert_to_standard.

error 'DataFrame' object has no attribute '__convert_to_standard__' ↓

cause The private method was removed; you must use the standalone function `convert_to_standard`.

fix

Replace df.__convert_to_standard__() with from dataframe_api_compat import convert_to_standard; convert_to_standard(df).

Warnings

breaking In version 0.2.0 the namespace changed from `dataframe_api_compat.pandas` to `dataframe_api_compat.pandas_standard`. Old imports will break. ↓

fix Update imports to `dataframe_api_compat.pandas_standard` or use the top-level `convert_to_standard` function.

deprecated The method `__convert_to_standard__` on DataFrame objects is deprecated; use `convert_to_standard(df)` instead. ↓

fix Replace `df.__convert_to_standard__()` with `convert_to_standard(df)`.

gotcha The standard API does not support all pandas/Polars operations. Only column-wise operations (e.g., mean, sum, isna) are guaranteed. Index-based or row-wise operations may fail. ↓

fix Check the supported operations list in the documentation before relying on a method.

Imports

convert_to_standard

wrong

import dataframe_api_compat
pandas_df.__convert_to_standard__()

correct

from dataframe_api_compat import convert_to_standard

The old private method pattern changed; now use the standalone function.

Quickstart

Convert a pandas DataFrame to the standard DataFrame API and perform operations.

import pandas as pd
from dataframe_api_compat import convert_to_standard

df_pd = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
df_std = convert_to_standard(df_pd)
print(type(df_std))  # <class 'dataframe_api_compat.pandas_standard.PandasDataFrame'>
print(df_std.a.mean())  # 2.0