unpdf

Python bindings for unpdf - High-performance PDF content extraction to Markdown, text, and JSON.

Installation

pip install unpdf-markdown

The distribution is unpdf-markdown; the import name is unpdf.

Quick Start

import unpdf

# Convert PDF to Markdown
markdown = unpdf.to_markdown("document.pdf")
print(markdown)

# Convert PDF to plain text
text = unpdf.to_text("document.pdf")
print(text)

# Convert PDF to JSON
json_data = unpdf.to_json("document.pdf", pretty=True)
print(json_data)

# Get document information
info = unpdf.get_info("document.pdf")
print(info)

# Get page count
pages = unpdf.get_page_count("document.pdf")
print(f"Total pages: {pages}")

# Check if file is a valid PDF
is_valid = unpdf.is_pdf("document.pdf")
print(f"Is valid PDF: {is_valid}")

Input: path or bytes

Every function takes its PDF as PdfSource — a path (str, or any os.PathLike such as pathlib.Path) or the PDF's own bytes. Types are unambiguous: str is always a path, bytes is always content, and bytes go through the native in-memory parser rather than a temporary file.

from pathlib import Path
import unpdf

unpdf.to_markdown("document.pdf")
unpdf.to_markdown(Path("document.pdf"))
unpdf.to_markdown(pdf_bytes)

API Reference

Every function below also accepts an optional options: dict keyword argument — see Parsing options.

to_markdown(source: PdfSource, options: dict | None = None, render_options: dict | None = None) -> str

Convert a PDF file to Markdown format. render_options is a dict of rendering settings; every key is optional and an absent one keeps the default:

A key outside this table, or a value the library cannot honour, raises UnpdfError with kind == ErrorKind.INVALID_ARGUMENT; a page the document does not have, with ErrorKind.PAGE_OUT_OF_RANGE.

import unpdf

markdown = unpdf.to_markdown(
    "document.pdf",
    render_options={"include_frontmatter": True, "page_markers": "comment"},
)

to_text(source: PdfSource, options: dict | None = None) -> str

Convert a PDF file to plain text.

to_json(source: PdfSource, pretty: bool = False, options: dict | None = None) -> str

Convert a PDF file to JSON format.

get_info(source: PdfSource, options: dict | None = None) -> dict

Get document metadata. Keys: section_count (the page count), resource_count, plus title / author only when the document sets them.

get_page_count(source: PdfSource, options: dict | None = None) -> int

Get the number of pages in a PDF file.

is_pdf(source: PdfSource, options: dict | None = None) -> bool

Check if a file is a valid PDF.

version() -> str

Get the version of the native library.

get_extraction_quality(source: PdfSource, options: dict | None = None) -> dict

Document-level extraction diagnostics: char_count, word_count, replacement_char_count, encrypted, is_scan_pdf, suppressed_ocr_pages, suppressed_text_runs, undecodable_content_streams, pages_incomplete, declared_page_count, unresolved_page_nodes, skipped_object_count, unsupported_image_count, ai_fallback_count. See "Incomplete extraction" below.

get_page_stats(source: PdfSource, page_number: int, options: dict | None = None) -> dict

Per-page content-stream operator counts (1-indexed): page, text_op_count, image_op_count, form_op_count, ocr_text_suppressed, suppressed_text_runs, undecodable_content_streams. Text and images a page paints through Form XObjects count as the page's own; form_op_count counts the form paints. The last two are this page's share of the document-level counts of the same name.

unreadable_fonts says which fonts the suppressed_text_runs came from: a list of {"name", "reason", "runs"}, one per font and reason in order of first loss ([] when nothing was discarded). name is the font's /BaseFont, or its resource name when it has none. reason is "composite_unresolved" (a Type0/CID font whose codes map to no text) or "binary_density" (a simple font whose decode was binary noise); treat any other value as a generic "unreadable". The runs sum to suppressed_text_runs.

How well the page was read: rotation (its /Rotate), image_coverage (share of the page painted by images, 0–1 — a full-page scan is near 1, a logo a few hundredths), rotated_text_runs, ruled_grids / ruled_tables (ruling-line grids drawn vs. tables built from them), reading_regions, column_count and ambiguous_layout_regions (regions read across although their text looked like two columns — where the reading order guessed).

get_tables(source: PdfSource, tsv: bool = False, options: dict | None = None) -> list[dict]

Every table as CSV (RFC 4180), or tab-separated with tsv=True, in reading order: {"page", "index", "text"} — the page, the table's place among that page's tables (from 1), and the text. A merged cell's text is in its top-left position and the positions it covers are empty, so every record has the same number of fields: pandas.read_csv(io.StringIO(t["text"])) reads one. Document.get_tables(tsv=False) does the same on an open document.

get_resource_ids(source: PdfSource, options: dict | None = None) -> list[str]

get_resource_info(source: PdfSource, resource_id: str, options: dict | None = None) -> dict

get_resource_data(source: PdfSource, resource_id: str, options: dict | None = None) -> bytes

List and retrieve extracted embedded resources (images). Resource info carries page — the page the resource was collected from (1-based); read it from there rather than from the id, whose format is not part of the contract. See Embedded resources — these only return anything once extract_resources is enabled via options.

Parsing options

Every function accepts options: dict | None = None. Every key is optional; an absent key keeps unpdf's own default:

info = unpdf.get_info("document.pdf", options={"extract_resources": True})
print(info["resource_count"])

Rendering pages

Document keeps a parsed PDF open, so pages can be rendered — and their statistics read — without parsing it again for every call. The page rendered is the page text extraction reads.

import unpdf

with unpdf.Document("report.pdf") as doc:
    stats = doc.get_page_stats(3)
    if stats["image_coverage"] > 0.9:
        page = doc.render_page(3, dpi=150)          # region="crop" (default) or "media"
        open("page3.png", "wb").write(page.png)
        print(page.width, page.height, page.gaps)   # gaps: what could not be painted
        print(page.substituted_text_runs)           # text in a stand-in for a font not embedded

unpdf.render_page(source, page_number, dpi=150, region="crop") renders one page in one call (parsing the document for it).

Embedded resources

options = {"extract_resources": True, "min_image_dimension": 0}
data = open("document.pdf", "rb").read()

for resource_id in unpdf.get_resource_ids(data, options=options):
    info = unpdf.get_resource_info(data, resource_id, options=options)
    image_bytes = unpdf.get_resource_data(data, resource_id, options=options)
    # ...

Each call above re-parses the document — options must be passed identically to every call in the sequence, since Python has no persistent document handle the way the C#/Rust APIs do.

Detecting scanned (image-only) PDFs

Empty output can mean a scanned document, a genuinely blank page, or a parse failure. The introspection surface tells them apart:

import unpdf

if unpdf.get_extraction_quality("scan.pdf")["is_scan_pdf"]:
    print("Scanned document - OCR required")

stats = unpdf.get_page_stats("scan.pdf", 1)
if stats["text_op_count"] == 0 and stats["image_op_count"] > 0:
    print("Page 1 is image-only (scanned)")
elif stats["text_op_count"] == 0:
    print("Page 1 is genuinely blank")

Note: a searchable scan (page image plus an invisible OCR text layer) reports text_op_count > 0 — combine the check with ocr_text_suppressed, which flags pages whose unreadable OCR layer was dropped.

Incomplete extraction

A damaged PDF does not always fail. When the cross-reference table survives but the objects it points at do not, the parser returns the pages it could read — a success over an incomplete page set. Check before indexing or archiving, because a page that silently never arrived is indistinguishable from a page that never existed:

quality = unpdf.get_extraction_quality("document.pdf")
if quality["pages_incomplete"]:
    print(f"incomplete - document declares {quality['declared_page_count']} page(s)")

Also note that get_info()["resource_count"] counts the extracted-resource inventory, which is empty unless options={"extract_resources": True} (see Parsing options) — it is not a count of images on the page. Use get_page_stats for scan detection.

Handling failures

UnpdfError carries a kind so you can branch on the reason a call failed instead of matching on message text:

from unpdf import to_text, ErrorKind, UnpdfError

try:
    text = to_text("document.pdf")
except UnpdfError as e:
    if e.kind == ErrorKind.ENCRYPTED:
        print("Password required")
    elif e.kind in (ErrorKind.CORRUPTED, ErrorKind.PDF_PARSE):
        print("The file is damaged")
    else:
        print(f"Extraction failed ({e.kind.name}): {e}")

UnpdfError subclasses RuntimeError, so existing except RuntimeError handlers keep working. ErrorKind values are part of the native ABI: new reasons take new numbers and existing ones are never renumbered, so treat an unrecognised value as a generic failure.

Native library

The package ships the native library for your platform. To load another build of it — one you compiled from the Rust crate, say — set UNPDF_LIB_PATH to that file. A path that names no file is an error: importing raises OSError naming the path, rather than quietly loading the packaged library instead.

License

MIT License