Datagrunt 5.4.6: Clean Excel read_options Passthrough Without Spurious Deprecation Warnings
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
- Removed Spurious
read_optionsDeprecationWarning— Dropped theDeprecationWarningchecks inExcelReader.__init__,ExcelReader.to_dataframe,ExcelReaderEngine.__init__, andExcelReaderEngine.to_dataframethat previously warned wheneverread_options={...}was passed. - Corrected
ExcelReaderEngine.get_sampleDocstring — Updated the docstring to direct callers needing row-limited full reads toto_dataframe(read_options={"n_rows": ...})rather than the invalid bareto_dataframe(n_rows=...). - Expanded Zero-Warning Regression Suite — Added a shared
preamble_xlsxpytest fixture and regression tests acrossExcelReader,ExcelWriter, andExcelReaderEngineverifying that constructorread_options, per-callread_options, and merged top-level Polars keyword arguments emit zeroDeprecationWarnings.
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"], orschema_overrides={...}are passed directly as keyword arguments. - Engine-specific calamine/fastexcel options such as
header_row,skip_rows, andn_rowsmust be nested insidepl.read_excel’sread_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, orsheet_nameas read options raises aValueError—always select worksheets viasheet=. - Sample sizing vs. full reads:
get_sample(n_rows=...)consumesn_rowslocally to slice the returned sample (default20). To cap rows during the underlyingpl.read_excel()read onto_dataframe(), passto_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 thepreamble_xlsxfixture (3 preamble rows, headers at row index 3, and 3 data rows).tests/excel_api_tests/test_excelreader.py: Replaced the oldpytest.warns(DeprecationWarning, ...)test with zero-warning assertions covering constructorread_options, per-callread_options, and constructor + per-call merging acrossget_sample(),to_dataframe(),to_arrow_table(),to_dicts(), andquery_data().tests/excel_api_tests/test_excelwriter.py: Added zero-warning tests for per-callread_options, constructorread_options, and merged top-levelcolumnsoptions onwrite_parquet()andwrite_csv().tests/core_tests/excel_io_tests/test_excel_engines.py: Wrapped existingread_optionstests withDeprecationWarningerror checks and addedtest_constructor_and_per_call_read_options_merge_without_warnings.
Upgrading
Upgrade to Datagrunt 5.4.6 using uv:
uv pip install --upgrade datagruntOr 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.