Readers

CSVReader, ExcelReader, ParquetReader, and PDFReader all accept a string path or pathlib.Path, and share a common set of conversion methods (to_dataframe(), to_arrow_table(), to_dicts(), get_sample()). Every return value is a standard, open object — Polars DataFrame, PyArrow Table, or plain dicts — so nothing locks you in; see Polars to Pandas. Each reader also supports use as a context manager (with ... as reader:) for early, deterministic release of its DuckDB connection — this is optional; cleanup happens automatically when the reader goes out of scope either way.

CSVReader 

CSVReader(filepath, engine="polars", lenient=False, normalize_columns=False)
Parameter Type Default Description
filepath str | Path required Path to the CSV file.
engine str "polars" "polars", "duckdb", or "pyarrow". See CSV Engines.
lenient bool False Gracefully handle ragged rows instead of raising. See Handling Messy CSV.
normalize_columns bool False Normalize column names at construction. See Column Name Normalization.

Properties & Methods

Member Description
db_table Attribute: the auto-generated DuckDB table name for query_data.
get_sample(n_rows=None) Returns a sample (default 20 rows; n_rows must be a positive integer), streamed from the top of the file.
to_dataframe(**kwargs) Converts the file to a Polars DataFrame. kwargs tunes how the CSV is parsed: any Polars read_csv option — e.g. to_dataframe(n_rows=100) to read at most 100 rows, or null_values=["NA"] to treat NA as null. Polars engine only; the duckdb and pyarrow engines parse the file themselves and ignore these keywords.
to_arrow_table() Converts the file to a PyArrow Table.
to_dicts() Converts the file to a list of dictionaries.
query_data(sql_query) Runs a SQL query via DuckDB against the file — write it against db_table. Repeated calls reuse the imported table. See Querying with DuckDB.

An unrecognized engine, a directory path, or a missing path all raise immediately at construction (ValueError / FileNotFoundError). See Fail-Fast Input Validation and Legacy Mac OS Carriage Returns for engine-specific caveats.

ExcelReader 

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

Reads the full Excel family (.xlsx, .xlsm, .xlsb, .xls, template variants) via a single canonical engine — Polars + calamine (fastexcel) — so there is no engine argument.

Parameter Type Default Description
filepath str | Path required Path to the Excel workbook.
normalize_columns bool False Normalize column names at construction. See Column Name Normalization.
**read_options — — How to read the workbook: any Polars read_excel keyword, e.g. has_header=False, skip_rows=2, n_rows=100. Applied to every read.

Properties & Methods

Member Description
sheets Property: worksheet names in workbook order.
db_table Property: the auto-generated DuckDB table name for query_data.
get_sample(sheet=None,
           n_rows=None,
           **read_options)		 Returns a sample of the selected sheet (default 20 rows; n_rows must be a positive integer). Sheet · read options.
to_dataframe(sheet=None,
             **read_options)		 Converts the selected sheet to a Polars DataFrame. Sheet · read options.
to_arrow_table(sheet=None,
               **read_options)		 Converts the selected sheet to a PyArrow Table. Sheet · read options.
to_dicts(sheet=None,
         **read_options)		 Converts the selected sheet to a list of dictionaries. Sheet · read options.
query_data(sql_query,
           sheet=None,
           **read_options)		 Runs a SQL query via DuckDB against the selected sheet, registered under db_table. Sheet · read options.

The sheet parameter

sheet selects which worksheet to operate on — a name (str) or zero-based position (int), defaulting to the first sheet. See Selecting Worksheets.

The **read_options parameter

**read_options controls how the sheet is read: any Polars read_excel keyword — e.g. to_dataframe(has_header=False) to treat the first row as data, or to_dataframe(skip_rows=2, n_rows=100) to skip a preamble and cap the rows. Options set on the constructor apply to every read; per-call options are merged over them and win. See Polars Read-Option Passthrough.

ParquetReader 

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

Reads a single-table Parquet file — no sheet dimension, no engine argument. Reading is powered by a single canonical engine, Polars (pl.read_parquet).

Parameter Type Default Description
filepath str | Path required Path to the Parquet file.
normalize_columns bool False Normalize column names at construction. See Column Name Normalization.
**read_options — — How to read the file: any Polars read_parquet keyword, e.g. columns=['name', 'city'], n_rows=100. Applied to every read.

Properties & Methods

Member Description
db_table Property: the auto-generated DuckDB table name for query_data.
get_sample(n_rows=None,
           **read_options)		 Returns a sample as a Polars DataFrame (default 20 rows; n_rows must be a positive integer). Read options.
to_dataframe(**read_options) Converts the file to a Polars DataFrame. Read options.
to_arrow_table(**read_options) Converts the file to a PyArrow Table. Read options.
to_dicts(**read_options) Converts the file to a list of dictionaries. Read options.
query_data(sql_query,
           **read_options)		 Runs a SQL query via DuckDB, registered under db_table. Read options.

The **read_options parameter

**read_options controls how the file is read: any Polars read_parquet keyword — e.g. to_dataframe(columns=['name', 'city']) to read only those columns, or to_dataframe(n_rows=100) to cap the rows. Options set on the constructor apply to every read; per-call options are merged over them and win. See Polars Read-Option Passthrough.

A non-Parquet path or missing path raises (ValueError / FileNotFoundError) at construction. Empty/blank files return empty results rather than raising.

PDFReader 

PDFReader(
    source,
    *,
    password=None,
    workers=1,
    ocr="auto",
    dpi=200,
    vision_dpi=300,
    max_render_pixels=16_000_000,
    min_image_dimension=40,
    strict=False,
)

Requires the pdf extra. Reads a PDF into a typed document: headings, paragraphs, key-value pairs, tables, lists, and figures, in reading order. The arguments are checked at construction; the PDF is read on first use, then cached for the reader’s life. PDFReader never writes to the filesystem. See PDF Parsing for the document model, OCR, hidden text, and errors.

Parameter Type Default Description
source str | os.PathLike | Mapping required A PDF path, a bundle directory or its manifest.json, or a dict of the document JSON PDFWriter.write_json writes. A missing path raises FileNotFoundError; a path that is not a PDF or a valid bundle raises ValueError.
password str | None None Keyword-only. An encrypted PDF’s password. Without the right one, reading raises PDFEncryptedError.
workers int 1 Keyword-only. Processes to extract pages with (at least 1). See Concurrency & Environments.
ocr str "auto" Keyword-only. "auto", "always" (every page to OCR), or "never". See Scanned pages and OCR.
dpi int 200 Keyword-only. The DPI of page images (at least 36).
vision_dpi int 300 Keyword-only. The DPI of pages read by OCR (at least dpi).
max_render_pixels int 16_000_000 Keyword-only. Caps the pixels of every render (at least 262,144): a very large page renders at a lower DPI.
min_image_dimension int 40 Keyword-only. Embedded images narrower or shorter than this many pixels are not figures (at least 1). See Filtering Small Embedded Images.
strict bool False Keyword-only. Raise PDFCorruptError on a bad page instead of recording it as an error page. See Page status.

An out-of-range option raises ValueError; a wrong type raises TypeError.

Properties & Methods

Member Description
document Property: the whole extraction as a PDFDocument. See The document model.
pages, headings, paragraphs, key_values, tables, lists, figures, page_images, sections, header_context Properties: the document’s collections, as tuples in document (or page) order.
metadata Property: a DocumentMetadata — doc_id, source_name, sha256, page_count, title, author.
to_dataframe() Returns the element rows as a Polars DataFrame, one row per element in document order; each call returns your own copy.
to_arrow_table() Returns the element rows as a PyArrow Table of a fixed schema.
to_dicts() Returns the element rows as a list of dicts.
get_sample(n_rows=20) Returns the first n_rows element rows (all of them if there are fewer) as a Polars DataFrame; n_rows must be a positive integer.
to_markdown(*, include_hidden=False) Returns the document as Markdown. Hidden elements are left out unless include_hidden=True, which keeps each behind its <!-- hidden: ... --> marker.
db_table Property: the element rows’ table name for query_data (tbl_ and the doc_id, with each character outside A–Z, a–z, 0–9, and _ replaced by _).
query_data(sql) Runs SQL via DuckDB against the element rows, registered under db_table, on the reader’s own in-memory connection. Returns the rows with .pl(), .pa(), and .dicts(). DuckDB installs no extension on its own. See Querying with SQL.
close() / with Optional: releases the DuckDB connection early. The reader stays usable; cleanup is automatic either way.

A failed read is not cached: the next call tries again. Encrypted PDFs raise PDFEncryptedError (also a ValueError) and unreadable ones PDFCorruptError (also a RuntimeError), on first use. A bad page is recorded and the rest of the document still extracts — see Page status and error isolation.

Writers