Excel Worksheets & Options

ExcelReader and ExcelWriter share a common per-sheet model. See the Readers and Writers reference for full signatures.

Selecting Worksheets

A workbook can contain many worksheets (tabs). The .sheets property lists them in workbook order, and every conversion method accepts an optional sheet argument — a name (str) or a zero-based position (int) — defaulting to the first sheet.

reader = ExcelReader('workbook.xlsx')

reader.sheets                          # ['People', 'Products', ...]
reader.to_dataframe()                  # first sheet
reader.to_dataframe(sheet='Products')  # by name
reader.to_dicts(sheet=1)               # by position

An invalid sheet name or out-of-range index raises a ValueError listing the available sheets.

Exporting Every Sheet

By default ExcelWriter operates on the first sheet (or the sheet you pass). Set all_sheets=True to export every sheet at once: single-table formats write one file per sheet (named <stem>_<sheet>.<ext>), while write_excel produces a single multi-tab workbook.

writer = ExcelWriter('workbook.xlsx')
writer.write_csv('out.csv')                           # first sheet
writer.write_parquet('out.parquet', sheet='Products') # a named sheet

writer.write_csv('out.csv', all_sheets=True)     # out_People.csv, out_Products.csv, ...
writer.write_excel('all.xlsx', all_sheets=True)  # one workbook, one tab per sheet

Passing both an explicit sheet= and all_sheets=True raises a ValueError.

Polars Read-Option Passthrough

Because reading is Polars-only, you can pass any Polars read_excel option straight through as a keyword argument — set on the constructor (applied to every read) or per call (merged over the constructor’s, per-call wins).

# Treat the first row as data rather than a header
reader.to_dataframe(has_header=False)

# Skip the first two rows and read at most 100
reader.to_dataframe(skip_rows=2, n_rows=100)

Note

The read-option mechanism is identical across Datagrunt’s CSV, Excel, and Parquet readers: you always pass options as flat keyword arguments directly to the constructor or to to_dataframe(), and Datagrunt forwards them directly to the underlying Polars function (pl.read_csv, pl.read_excel, or pl.read_parquet). Passing a read_options dictionary (e.g., read_options={"n_rows": 1}) is deprecated and will be removed in a future release. Pass the options as flat keyword arguments directly instead.

Formula Injection Safety

Cell values are written verbatim — Datagrunt preserves data, it does not sanitize it. For spreadsheet-interpreted formats, a value beginning with =, +, -, or @ is treated as a formula when the file is opened in Excel / LibreOffice / Google Sheets (CSV/formula injection, CWE-1236). If your source data is untrusted and the output may be opened in a spreadsheet application, sanitize at the application layer. This applies to write_csv and write_excel on CSVWriter, ExcelWriter, and ParquetWriter alike.

Handling Messy CSVParquet Options