pdfmonkey 1.0.0

One-call PDF table extraction returning clean lists of dicts, with heuristic detection, multi-page merging, and confidence scoring.

pdfmonkey

One-call PDF table extraction that returns clean Python data instead of jumbled text. pdfplumber handles ruled tables; a position-based heuristic reconstructs borderless ones; multi-page tables are stitched back together; every table comes with a confidence score.

import pdfmonkey

tables = pdfmonkey.extract_tables("report.pdf")
tables[0].to_dicts()
# [{'Name': 'Alice', 'Age': '30', 'City': 'London'},
#  {'Name': 'Bob',   'Age': '25', 'City': 'Paris'}]

Why

Existing tools (pdfplumber, PyMuPDF, pdfminer) produce output where columns bleed, rows split, headers detach, and multi-page tables fragment. Closing that gap takes 100–200 lines of heuristic glue every time. pdfmonkey is that glue, packaged: raw PDF in, clean list[dict] out.

Install

pip install pdfmonkey            # core (pdfplumber only)
pip install pdfmonkey[enrich]    # + enrich=True column types & text cleaning
pip install pdfmonkey[pandas]    # + Table.to_dataframe()
pip install pdfmonkey[dev]       # + test toolchain

The enrich extra pulls in the monkey ecosystem (cleanmonkey, datemonkey, typemonkey). The core install does not require them: enrich=True records a diagnostic and leaves column_types empty when they are absent, and text extraction attempts cleanmonkey only via a guarded import before falling back to a built-in cleaner.

Requires Python 3.11+.

Library API

import pdfmonkey

# Headline one-call API -> list[Table]
tables = pdfmonkey.extract_tables(
    "report.pdf",
    pages="1-3,5",        # None/"all", "3", "2-5", "1,3,5-7"
    merge=True,           # stitch tables continued across pages (matching headers)
    merge_headerless=False,  # also stitch a headerless continuation (looser; opt-in)
    enrich=False,         # annotate Table.column_types via the monkey ecosystem
    min_confidence=0.0,   # drop tables scoring below this
)

# Rich result with diagnostics -> ExtractionResult
result = pdfmonkey.extract("report.pdf")
result.strategy_used      # 'pdfplumber' | 'heuristic' | 'mixed' | 'none'
result.tables             # list[Table]

# Clean text, paragraph-preserving -> str
text = pdfmonkey.extract_text("report.pdf", pages="1")

Each Table converts to whatever shape you need:

table.to_dicts()       # list[dict]      (dsvmonkey input, pgmonkey CSV import)
table.to_lists()       # list[list[str]] (header row first)
table.to_csv()         # str
table.to_json()        # str
table.to_dataframe()   # pandas.DataFrame (needs the [pandas] extra)

CLI

pdfmonkey extract report.pdf                 # CSV to stdout
pdfmonkey extract report.pdf -f json -p 1-3  # JSON, pages 1–3
pdfmonkey extract report.pdf --text          # clean text instead of tables
pdfmonkey inspect report.pdf                 # shape/confidence/strategy, no data dump

inspect is the "should I trust this extraction?" command — it reports each table's pages, shape, confidence, detecting strategy, and diagnostics without printing the data.

Ecosystem

Built to interoperate with the monkey toolkit: to_dicts() feeds dsvmonkey, to_csv() imports via pgmonkey, two tables compare with diffmonkey. With enrich=True, cleanmonkey normalises cells and datemonkey/typemonkey populate Table.column_types.

Scope

In scope: table detection, extraction, multi-page merging, structural analysis, text extraction. Out of scope: PDF creation/editing, form filling, image extraction, OCR, merging/splitting files.

Design tradeoffs

See LIMITATIONS.md for deliberate design tradeoffs (e.g. missing-vs-empty cells, header detection, conservative multi-page merge) before filing what looks like a bug.

Using with AI assistants

SKILL.md is an LLM-consumable guide (decision tree, worked examples, anti-patterns) so assistants reach for pdfmonkey instead of hand-rolling pdfplumber glue.

Changelog

Release history is in CHANGELOG.md.

License

MIT — see LICENSE.