mag-parse

One parse() for every document. PDFs go to mag-pdf; everything else goes to mag-file-handler.

from mag_parse import parse

r = parse("invoice.pdf")                      # quality="fast" (default)
r = parse("report.pdf", quality="accurate")   # table structure
r = parse("deck.pptx")                        # quality does not apply
r = parse(pdf_bytes, filename="report.pdf")   # bytes work too

r.markdown        # always populated
r.text            # always populated
r.format          # "pdf" | "docx" | "xlsx" | "eml" | ...
r.engine          # which engine actually ran
r.ok, r.error, r.warnings

The facade itself has zero required dependencies. Both engines are extras, and that is not tidiness — see Install.

Routing

Decided by magic bytes, never the extension. A .docx renamed to .pdf does not reach the PDF engine, and a PDF with no extension does.

parse(file, quality=...)
        │
   sniff %PDF
        │
   ┌────┴─────┐
 PDF        not PDF
   │            │
mag-pdf   mag-file-handler
   │            │
   └────┬───────┘
        ▼
    one Result

quality is a PDF-only knob

For every other format quality is accepted and ignored, so a caller never has to branch on file type. Result.quality is "" there — the knob did not default, it does not exist.

"accurate" selects mag-pdf's profile="tables", leaving table_mode at its default. Those are two different fast/accurate axes: the profile picks the pipeline, table_mode picks TableFormer's weights. The heavier weights measured 27.6 s against 16.1 s for one additional table row, so they are not what "accurate" buys — the table pipeline is.

Markdown, and how honest it is

Both .markdown and .text are always populated, on every path including failure. They are not equally structured, and structured_markdown says which you got:

A docx table currently arrives as tab-separated fragments rather than a pipe table. That is mag-file-handler's plain-text output passed through verbatim, and the warning says so rather than letting it pass as structured markdown. Teaching the engines real markdown per format is the planned follow-up; the API does not change when it lands.

Errors

A bad document is a Result, never an exception — check .ok / .error. Only two things raise, and both are the caller's to fix:

Result.status is "ok", "empty" or "error". empty is a failure — an extraction that returns nothing while reporting success is the silent failure both engines guard against, and the facade does not launder it.

Install

pip install 'mag-parse[pdf]'        # PDFs; one dependency, Tesseract bundled
pip install 'mag-parse[office]'     # docx, xlsx, pptx, eml, html, md, txt, csv
pip install 'mag-parse[all]'        # both of the above
pip install 'mag-parse[tables]'     # adds quality="accurate" (~2 GB: torch)

The engines are extras rather than dependencies because extractous (under mag-file-handler) publishes no Linux ARM64 wheel and declares requires-python <3.14, while liteparse (under mag-pdf) has neither limit. Making the office side required would impose both constraints on PDF-only users:

Python 3.10+. Apache-2.0.