extracting-pdf-tables

name	extracting-pdf-tables
description	Use when extracting tables from PDF documents — works for digital and OCR'd PDFs, multi-column layouts, and rotated tables. Triggers on requests to "pull tables out of a PDF", "extract a table from a .pdf file", or after pdfplumber/Camelot return empty results.
license	MIT

Extracting PDF Tables

Reliable table extraction from PDFs that simpler tools struggle with. Wraps pdfplumber for digital text and falls back to tabula-java plus OCR for scanned pages.

When to use

• A user wants tabular data from a PDF.
• pdfplumber returned None for page.extract_tables().
• The PDF is scanned, rotated, or uses multi-column page layouts.

Do NOT use for free-form text extraction (use a plain text extractor) or for forms with named fields (use a form-specific tool).

Workflow

1. Inspect the PDF — confirm pages with tables and whether text is selectable.
2. Run scripts/extract.py <file.pdf> --pages <range> to attempt digital extraction.
3. If output is empty for any page, re-run with --ocr to fall through to OCR.
4. Validate the output against references/expected-shape.md before returning to the user.

Quick reference

Need	Path
Run extraction	scripts/extract.py
Output shape spec	references/expected-shape.md

Example

$ scripts/extract.py invoices.pdf --pages 2-5
extracting-pdf-tables: 4 pages, 6 tables found
  invoices_p2_t0.csv  (12 rows × 5 cols)
  invoices_p3_t0.csv  (8 rows × 5 cols)
  invoices_p4_t0.csv  (15 rows × 5 cols)
  invoices_p4_t1.csv  (3 rows × 2 cols)
  ...

Output contract

CSV per table, one file per (page, table_index). Filename pattern: STEM_pPAGE_tINDEX.csv.