Datagrunt 5.4.6: Clean Excel read_options Passthrough Without Spurious Deprecation Warnings

November 21, 2026by Martin Graham

Datagrunt 5.4.6 is now available! This patch release fixes an erroneous DeprecationWarning when passing Polars’ read_options={...} dictionary to Datagrunt’s Excel APIs (PR #513, #290), updates stale docstring guidance, and expands regression coverage across ExcelReader, ExcelWriter, and ExcelReaderEngine.


Key Highlights in Datagrunt 5.4.6

  1. Removed Spurious read_options DeprecationWarning — Dropped the DeprecationWarning checks in ExcelReader.__init__, ExcelReader.to_dataframe, ExcelReaderEngine.__init__, and ExcelReaderEngine.to_dataframe that previously warned whenever read_options={...} was passed.
  2. Corrected ExcelReaderEngine.get_sample Docstring — Updated the docstring to direct callers needing row-limited full reads to to_dataframe(read_options={"n_rows": ...}) rather than the invalid bare to_dataframe(n_rows=...).
  3. Expanded Zero-Warning Regression Suite — Added a shared preamble_xlsx pytest fixture and regression tests across ExcelReader, ExcelWriter, and ExcelReaderEngine verifying that constructor read_options, per-call read_options, and merged top-level Polars keyword arguments emit zero DeprecationWarnings.

Why read_options={...} Is Required for Excel

In Datagrunt, ExcelReader, ExcelWriter, and ExcelReaderEngine forward **read_options verbatim to Polars’ pl.read_excel(). Unlike pl.read_csv and pl.read_parquet—which expose all options as top-level keyword parameters—Polars’ read_excel splits its configuration:

  • Top-level Polars keywords such as has_header=False, columns=["name", "city"], or schema_overrides={...} are passed directly as keyword arguments.
  • Engine-specific calamine/fastexcel options such as header_row, skip_rows, and n_rows must be nested inside pl.read_excel’s read_options={...} dictionary parameter.

Previously, ExcelReader and ExcelReaderEngine checked if "read_options" in read_options: in __init__ and to_dataframe and emitted a DeprecationWarning advising callers to pass those options as flat keyword arguments instead. Because pl.read_excel requires read_options={...} for header_row, skip_rows, and n_rows, users reading workbooks with preamble rows or row caps hit an unavoidable warning on the only valid call pattern. Datagrunt 5.4.6 removes those warning blocks completely.


Using ExcelReader and ExcelWriter with read_options

You can configure read_options={...} on the constructor as a workbook-wide default, pass it per call, or combine constructor engine options with per-call top-level Polars options—with zero DeprecationWarnings:

import warnings
from datagrunt import ExcelReader, ExcelWriter

with warnings.catch_warnings():
    warnings.simplefilter("error", DeprecationWarning)

    # Skip a 3-row report preamble by setting header_row=3 at construction
    with ExcelReader("quarterly_report.xlsx", read_options={"header_row": 3}) as reader:
        # Inherits constructor read_options across every read method
        sample = reader.get_sample(n_rows=2)
        df = reader.to_dataframe()
        table = reader.to_arrow_table()
        rows = reader.to_dicts()
        count = reader.query_data(f"SELECT count(*) FROM {reader.db_table}").fetchall()[0][0]

        # Merge constructor read_options with a per-call top-level Polars kwarg
        df_subset = reader.to_dataframe(columns=["name", "city"])

        # Per-call read_options overrides constructor read_options
        df_first_row = reader.to_dataframe(read_options={"header_row": 3, "n_rows": 1})

    # Export preamble-adjusted sheets cleanly with ExcelWriter
    writer = ExcelWriter("quarterly_report.xlsx", read_options={"header_row": 3})
    writer.write_parquet("report.parquet")
    writer.write_csv("report_names.csv", columns=["name", "city"])

The same passthrough and merging behavior applies when using ExcelReaderEngine directly from datagrunt.core (or datagrunt.core.excel_io):

from datagrunt.core import ExcelReaderEngine

engine = ExcelReaderEngine("quarterly_report.xlsx", read_options={"header_row": 3})
df = engine.to_dataframe(columns=["name", "city"])

Two guardrails remain unchanged:

  • Reserved sheet/source keys: Passing source, sheet_id, or sheet_name as read options raises a ValueError—always select worksheets via sheet=.
  • Sample sizing vs. full reads: get_sample(n_rows=...) consumes n_rows locally to slice the returned sample (default 20). To cap rows during the underlying pl.read_excel() read on to_dataframe(), pass to_dataframe(read_options={"n_rows": ...}).

Regression Coverage

Datagrunt 5.4.6 adds and updates tests across the Excel unit and API test suites under warnings.simplefilter("error", DeprecationWarning):

  • tests/conftest.py: Added the preamble_xlsx fixture (3 preamble rows, headers at row index 3, and 3 data rows).
  • tests/excel_api_tests/test_excelreader.py: Replaced the old pytest.warns(DeprecationWarning, ...) test with zero-warning assertions covering constructor read_options, per-call read_options, and constructor + per-call merging across get_sample(), to_dataframe(), to_arrow_table(), to_dicts(), and query_data().
  • tests/excel_api_tests/test_excelwriter.py: Added zero-warning tests for per-call read_options, constructor read_options, and merged top-level columns options on write_parquet() and write_csv().
  • tests/core_tests/excel_io_tests/test_excel_engines.py: Wrapped existing read_options tests with DeprecationWarning error checks and added test_constructor_and_per_call_read_options_merge_without_warnings.

Upgrading

Upgrade to Datagrunt 5.4.6 using uv:

uv pip install --upgrade datagrunt

Or with PDF and rationalization extras:

uv pip install --upgrade "datagrunt[pdf,rationalize]"

For full option details, see the Excel Worksheets & Options, Readers Reference, and Writers Reference documentation.