Datagrunt Documentation

This documentation provides comprehensive guidance for installing, using, and understanding Datagrunt - a Python library designed to simplify the way you work with CSV, Excel, Parquet, and PDF files.

Installation

Datagrunt 5.0+ requires Python 3.11 or newer (4.x supported Python 3.10). We recommend using uv as the default package manager.

To install Datagrunt using uv:

uv pip install datagrunt

Optional PDF & Rationalization Support

PDF parsing ships as an optional extra. Install basic PDF support with the pdf extra:

uv pip install "datagrunt[pdf]"

For schema-driven PDF extraction (rationalize()), install the [pdf,rationalize] extras:

uv pip install "datagrunt[pdf,rationalize]"

The pdf extra installs pypdfium2 (PDFium) and Pillow. The rationalize extra adds pydantic (schema validation) and httpx (provider communication). import datagrunt, the Key marker, load_bundle(), load_corpus(), CorpusManifest, CorpusEntry, CorpusFailure, prepare_batch(), ingest_batch(), BatchPlan, and BatchItem work without any extra installed.

OCR of scanned pages additionally requires the Tesseract program, with its English (eng) and orientation (osd) data:

• macOS: brew install tesseract
• Debian/Ubuntu: apt-get install tesseract-ocr
• Windows: install via the UB-Mannheim build (winget install UB-Mannheim.TesseractOCR, choco install tesseract, or scoop install tesseract), then add its install directory to PATH

Datagrunt runs the tesseract it finds in an absolute directory on your PATH, never one in the working directory; there is no Python wrapper to install. Digital PDFs — text, tables, and embedded images — work without Tesseract: it is only needed for pages read by OCR. See Scanned pages and OCR.

Quick Start

Datagrunt makes reading and writing CSV, Excel, Parquet, and PDF files incredibly simple. Here is a 2-minute guide showing how to use the primary classes.

Reading Files

from pathlib import Path
from datagrunt import CSVReader, ExcelReader, ParquetReader, PDFReader

# 1. Read CSV (supports 'polars', 'duckdb', and 'pyarrow' engines)
reader_csv = CSVReader("data.csv", engine="polars")
df_csv = reader_csv.to_dataframe()

# 2. Read Excel worksheets (powered by Polars + calamine)
reader_excel = ExcelReader("data.xlsx")
df_excel = reader_excel.to_dataframe(sheet="Sheet1")  # Sheet name or index

# 3. Read Parquet (powered by Polars)
reader_parquet = ParquetReader("data.parquet")
df_parquet = reader_parquet.to_dataframe()

# 4. Read PDF (requires PDF support)
reader_pdf = PDFReader("data.pdf")
df_pdf = reader_pdf.to_dataframe()  # One row per element: headings, paragraphs, tables, ...
markdown_pdf = reader_pdf.to_markdown()

Writing & Converting Files

from datagrunt import CSVWriter, ExcelWriter, ParquetWriter, PDFWriter

# 1. Export CSV data to other formats (CSV, Excel, JSON, Parquet)
writer_csv = CSVWriter("data.csv")
writer_csv.write_parquet("data.parquet")

# 2. Export Excel workbook sheets
writer_excel = ExcelWriter("data.xlsx")
writer_excel.write_csv("sheet.csv", sheet="Sheet1")

# 3. Export/Compress Parquet data
writer_parquet = ParquetWriter("data.parquet")
writer_parquet.write_excel("data.xlsx")

# 4. Write PDF results, extract images, and render pages —
#    the PDF is extracted once, and every write reuses it
writer_pdf = PDFWriter("data.pdf")
writer_pdf.write_json("output.json")
writer_pdf.write_markdown("report.md")
writer_pdf.extract_images("extracted_images")
writer_pdf.render_pages_as_images("page_images", dpi=300)

# 5. Write all of the above as one checked directory that PDFReader loads back
writer_pdf.write_bundle("report_bundle")

Every CSV, Excel, and Parquet reader can also run SQL directly against your file via DuckDB — see Querying with DuckDB.

Next Steps

• API Reference — Every class, constructor signature, and method in one place.
• Guides — Task-oriented walkthroughs: engine selection, messy CSV handling, Excel worksheets, Parquet options, PDF parsing, DuckDB queries, and concurrency.
• Studio Reference — Datagrunt Studio, the web workbench built on this library: setup, importing, querying, cleansing, AI PDF extraction, and exporting.