Datagrunt Documentation

PyPI Version Python Versions License

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

We recommend using uv as the default package manager.

To install Datagrunt using uv:

uv pip install datagrunt

Optional PDF Support

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

uv pip install "datagrunt[pdf]"

OCR of scanned (image-only) pages additionally requires the Tesseract system binary:

  • 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)

Native-text PDFs, tables, and embedded images work without Tesseract — it is only needed for OCR of scanned pages.

The pdf extra installs both PDF engines: PDFium (via pypdfium2, the default — permissively licensed under BSD-3 / Apache-2.0) and PyMuPDF (AGPL-3.0 / commercial), along with pdfplumber for table extraction. PDFium is the default because it is permissively licensed and fast; both engines emit the same unified output, so they are interchangeable. See Choosing a PDF Engine.

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")
doc_dict = reader_pdf.to_dicts()  # Flattens page layout, tables, and images

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 parser results, extract images, and render pages
writer_pdf = PDFWriter("data.pdf")
writer_pdf.write_json("output.json", image_output_dir="extracted_images")
writer_pdf.extract_images(output_dir="extracted_images")
writer_pdf.render_pages_as_images(output_dir="page_images", dpi=300, image_format="png")

# 5. Generate Markdown from the pre-parsed JSON — executes instantly,
#    without double-parsing the PDF
writer_from_json = PDFWriter("output.json")
writer_from_json.write_markdown("report.md")

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.