Datagrunt 4.4.0: Consistent Native Polars Integration

We are excited to announce the release of Datagrunt 4.4.0! This release focuses on API consistency and developer convenience by unifying how native configuration options are passed to the underlying Polars engines.

Consistent Native Polars Passthrough

Datagrunt utilizes Polars under the hood for high-performance DataFrame operations. Previously, configuring reader-specific details (like skipping rows or controlling headers) varied across readers. For example, ExcelReader required options to be wrapped in a read_options dictionary, whereas ParquetReader accepted flat keyword arguments.

With Datagrunt 4.4.0, all reader classes consistently support direct flat keyword argument passthrough (**kwargs) inside .to_dataframe(). This allows seamless access to the full, native Polars reader parameters without restrictions.

Examples in Action

Here is how you can use the unified flat keyword argument interface across different formats:

# 1. Reading a CSV with native Polars options
from datagrunt import CSVReader

reader = CSVReader("myfile.csv")
# Pass n_rows and has_header directly to pl.read_csv
df_csv = reader.to_dataframe(n_rows=2, has_header=False)

# 2. Reading an Excel sheet with native options
from datagrunt import ExcelReader

reader = ExcelReader("myfile.xlsx")
# Pass calamine engine options directly to pl.read_excel
df_excel = reader.to_dataframe(skip_rows=2, n_rows=100)

# 3. Reading a Parquet file with native options
from datagrunt import ParquetReader

reader = ParquetReader("myfile.parquet")
# Pass columns and n_rows directly to pl.read_parquet
df_parquet = reader.to_dataframe(columns=["name", "city"], n_rows=2)

Deprecation of the read_options Dictionary in Excel

To enforce this cleaner, unified pattern, passing configuration options as a dictionary via the read_options parameter (e.g., to_dataframe(read_options={"skip_rows": 2})) is now deprecated.

While this legacy pattern still works to ensure backward compatibility and will not break existing code, it now triggers a DeprecationWarning and will be removed in a future major release. We recommend migrating to flat keyword arguments directly.

Under the Hood & Backward Compatibility

All modifications in this release are entirely additive. The existing signatures and options behave exactly as before, with no breaking changes introduced to the API.

Upgrade to Datagrunt 4.4.0 today:

uv pip install -U datagrunt