Metadata-Version: 2.4
Name: pdfmonkey
Version: 1.0.2
Summary: One-call PDF table extraction returning clean lists of dicts, with heuristic detection, multi-page merging, and confidence scoring.
Author-email: GoodBoy <pythonic@rexbytes.com>
License: MIT License
        
        Copyright (c) 2026 RexBytes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/rexbytes/pdfmonkey
Project-URL: Issues, https://github.com/rexbytes/pdfmonkey/issues
Keywords: pdf,table,extraction,pdfplumber,data
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pdfplumber>=0.11.6
Provides-Extra: enrich
Requires-Dist: cleanmonkey; extra == "enrich"
Requires-Dist: datemonkey; extra == "enrich"
Requires-Dist: typemonkey; extra == "enrich"
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: reportlab>=4.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: cleanmonkey; extra == "dev"
Requires-Dist: datemonkey; extra == "dev"
Requires-Dist: typemonkey; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# 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.

```python
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

```bash
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

```python
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:

```python
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

```bash
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](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](SKILL.md) is an LLM-consumable guide (decision tree, worked examples,
anti-patterns) so assistants reach for pdfmonkey instead of hand-rolling
pdfplumber glue.

## Contributing & quality

[CONTRIBUTING.md](CONTRIBUTING.md) is the project's quality contract — the
testing philosophy and the competitive multi-model review methodology pdfmonkey
is hardened with. The release decision is made explicit and measurable:
[RELEASE_READINESS.md](RELEASE_READINESS.md) defines the rubric,
`python scripts/readiness.py` computes the score, and
[REVIEW_HISTORY.md](REVIEW_HISTORY.md) records the panel trajectory. The
portable source of this methodology lives in [`review-kit/`](review-kit/).

## Changelog

Release history is in [CHANGELOG.md](CHANGELOG.md).

## License

MIT — see [LICENSE](LICENSE).
