README.md

pdf-parser Python bindings

Python bindings for the Zig pdf-parser library. The package is named pdf-parser, while the import path remains zpdf for compatibility with the inherited API.

The current development package is 0.4.0.dev0, the Python packaging spelling of the native parser's 0.4.0-dev build. Adaptive output uses schema 0.20.0; its version is independent of the package version. This is a capable pre-1.0 parser; a development build is not a tagged release.

Install

Published wheels are platform-specific. From a source checkout, build a wheel from the current Zig shared library with:

python3 -m pip install build
python3 -m build --wheel python

Repository imports prefer an explicit PDF_PARSER_LIB (or legacy ZPDF_LIB), then the current zig-out/lib build, and finally a library bundled in an installed wheel. An explicit override must name an existing file.

Usage

from zpdf import Document

with Document("paper.pdf") as doc:
    print(doc.page_count)

    # Extract all text (reading order)
    text = doc.extract_all()

    # Extract single page
    page_text = doc.extract_page(0)

    # Extract as markdown
    md = doc.extract_all_markdown()

    # Get text with bounding boxes
    spans = doc.extract_bounds(0)
    for span in spans:
        print(f"{span.text} at ({span.x0}, {span.y0})")

From bytes

with open("doc.pdf", "rb") as f:
    data = f.read()

with Document(data) as doc:
    text = doc.extract_all()

Benchmark

Build the native library in fast mode, then use the repository benchmark harness for current timings:

zig build -Doptimize=fast --summary all
.venv/bin/python benchmark/eval/compare.py \
  --pdf-parser-adaptive \
  --tools pdf-parser,pymupdf,pypdfium2,pdfplumber \
  --ensure-releasefast \
  --manifest benchmark/eval/corpus/manifest.tsv

Avoid copying old prose timing tables into reports. Use generated scorecards and profiler JSONL from the corpus and machine you are evaluating.

License

MIT for new implementation work. The inherited native base came from Lulzx/zpdf under CC0-1.0; see the repository NOTICE.md.