Writers

CSVWriter, ExcelWriter, ParquetWriter, and PDFWriter read a source file and export it to other formats. All accept a string path or pathlib.Path. Values are written verbatim — Datagrunt does not sanitize output; see Formula Injection Safety for spreadsheet-format caveats.

CSVWriter 

CSVWriter(filepath, engine="duckdb", lenient=False, normalize_columns=False)
Parameter Type Default Description
filepath str | Path required Path to the source CSV file.
engine str "duckdb" "duckdb", "polars", or "pyarrow". See CSV Engines.
lenient bool False Gracefully handle ragged rows before export. See Handling Messy CSV.
normalize_columns bool False Write with normalized column names. See Column Name Normalization.

Methods

Method Description
write_csv(out_filename=None) Writes to a CSV file.
write_excel(out_filename=None) Writes to an Excel file.
write_json(out_filename=None) Writes to a JSON file.
write_json_newline_delimited(out_filename=None) Writes to newline-delimited JSON.
write_parquet(out_filename=None) Writes to a Parquet file.

ExcelWriter 

ExcelWriter(filepath, normalize_columns=False, **read_options)

Mirrors ExcelReader’s constructor (same parameters — see ExcelReader) and shares the same per-sheet model. Every method below accepts sheet=None (name or zero-based position; defaults to the first sheet) and all_sheets=False. Passing both sheet and all_sheets=True raises ValueError. See Selecting Worksheets.

Methods

Method Description
write_csv(out_filename=None,
          sheet=None,
          all_sheets=False,
          **read_options)		 Writes the selected sheet, or one file per sheet. Read options.
write_excel(out_filename=None,
            sheet=None,
            all_sheets=False,
            **read_options)		 Writes the selected sheet, or every sheet into one multi-tab workbook. Read options.
write_json(out_filename=None,
           sheet=None,
           all_sheets=False,
           **read_options)		 Writes the selected sheet(s) to JSON. Read options.
write_json_newline_delimited(
    out_filename=None,
    sheet=None,
    all_sheets=False,
    **read_options)		 Writes the selected sheet(s) to newline-delimited JSON. Read options.
write_parquet(out_filename=None,
              sheet=None,
              all_sheets=False,
              **read_options)		 Writes the selected sheet(s) to Parquet. Read options.

The **read_options parameter

**read_options controls how the source workbook is read before export (the writer reads the sheet, then writes it out): any Polars read_excel keyword — e.g. write_csv('out.csv', has_header=False) to treat the first row as data, or skip_rows=2 to skip a preamble. Constructor options apply to every export; per-call options are merged over them and win. See Polars Read-Option Passthrough.

All methods honor the constructor’s normalize_columns setting.

ParquetWriter 

ParquetWriter(filepath, normalize_columns=False, **read_options)

Mirrors ParquetReader’s constructor (same parameters — see ParquetReader); **read_options on the constructor controls how the source Parquet is read before export. Empty/blank source files produce a single empty (0-byte) output file rather than raising.

Methods

Method Description
write_csv(out_filename=None,
          **write_options)		 Writes to a CSV file. Write options.
write_excel(out_filename=None,
            **write_options)		 Writes to an Excel file. Write options.
write_json(out_filename=None,
           **write_options)		 Writes to a JSON file. Write options.
write_json_newline_delimited(
    out_filename=None,
    **write_options)		 Writes to newline-delimited JSON. Write options.
write_parquet(out_filename=None,
              **write_options)		 Re-encodes to Parquet. Write options · Parquet Options guide.

The **write_options parameter

**write_options controls how the output file is written: any keyword accepted by the matching Polars writer — write_csv (e.g. separator=';'), write_excel (e.g. autofit=True), write_parquet (e.g. compression='zstd'), and so on. For example: write_parquet('recompressed.parquet', compression='zstd').

All methods honor the constructor’s normalize_columns setting.

PDFWriter 

PDFWriter(filepath, engine="pdfium", workers=1, native=False, *, min_image_dimension=40)

Requires the pdf extra. filepath may also be a pre-parsed .json file or an in-memory document dict — useful for generating Markdown/JSON/JSONL without re-parsing the PDF.

Parameter Type Default Description
filepath str | Path | dict required PDF path, .json path, or a pre-parsed document dict.
engine str "pdfium" "pdfium" or "pymupdf". See Choosing a PDF Engine.
workers int 1 PDFium-only: per-page process-pool concurrency, used by render_pages_as_images. See Concurrency & Environments.
native bool False PDFium-only: lean schema (no table detection).
min_image_dimension int 40 Keyword-only. Minimum pixel size for kept embedded images. See Filtering Small Embedded Images.

Properties & Methods

Member Description
total_pages Property: number of pages in the source PDF (or pages in a pre-parsed document).
write_json(export_filename=None,
           image_output_dir=None,
           dedupe_images=True,
           drop_layout_tables=False)		 Writes the unified document JSON (defaults to output.json); returns the written path.
write_json_newline_delimited(
    export_filename=None,
    image_output_dir=None,
    dedupe_images=True,
    drop_layout_tables=False)		 Writes one flattened element per line as JSONL (defaults to output.jsonl).
write_markdown(export_filename=None,
               image_output_dir=None,
               dedupe_images=True,
               drop_layout_tables=False)		 Writes a Markdown rendering (defaults to output.md); instant when constructed from pre-parsed JSON/dict.
extract_images(output_dir=None,
               dedupe=True)		 Writes embedded image files (defaults to output_images), page/image-numbered and zero-padded.
render_pages_as_images(
    output_dir=None,
    dpi=300,
    image_format="png")		 Rasterizes each whole page to an image file (defaults to page_images). Honors workers on PDFium. Requires the source PDF — raises ValueError on a writer constructed from a pre-parsed dict/JSON.

The parse is cached per writer, so mixed calls (write_json() then write_markdown()) never re-parse the PDF. An explicitly empty/whitespace filename raises ValueError (pass None for the default); image_format must be png, jpg, or jpeg. See PDF Parsing for the output schemas, OCR fallback, image deduplication, and drop_layout_tables.

Readers