Crate spectre_pdf

Expand description

spectre_pdf — Native Rust PDF extraction engine.

Read-only PDF parsing + extraction. Every surface — the persistent Document handle and the free functions — runs on the in-repo spectre_parse lazy parser. No C dependencies. Full PDF Standard Security Handler decryption (RC4 40/128-bit + AES-128/256 R=5/R=6). Works as a pure Rust library or as a Python extension when built with the python feature (the Python package is published as spectre-rs).

§Quickstart (Rust)

use std::fs;
let bytes = fs::read("document.pdf").unwrap();
let text = spectre_pdf::extract_text(&bytes).unwrap();
let pages = spectre_pdf::extract_pages(&bytes).unwrap();
let meta = spectre_pdf::extract_metadata(&bytes).unwrap();
let tables = spectre_pdf::extract_tables(&bytes, None).unwrap();
let score = spectre_pdf::score_text(&text); // 0.0 garbage .. 1.0 clean

§Quickstart (Python, requires `--features python`)

maturin develop --release --features python

import spectre_rs
text = spectre_rs.extract_text(open("document.pdf", "rb").read())
pages = spectre_rs.extract_pages(open("document.pdf", "rb").read())

Re-exports§

pub use search::SearchHit;
pub use search::SearchOptions;

Modules§

geom: Shared geometry types used by the positional-extraction surfaces. PDF user space: points (1/72“), origin bottom-left. f32 throughout — enough precision for any page-sized coordinate (max ~14400 pt).
search: Text search returning bounding boxes.

Structs§

Annotation: One annotation. subtype is the raw PDF subtype string (Link, Highlight, FreeText, Stamp, Widget, Ink, …) — unnormalized so downstream filters can match the exact set they care about.
DecodedImage: One image’s decoded byte buffer.
Document: A parsed PDF document. Open once, query many times.
DocumentInfo
FormField: Re-export of spectre_parse::FormField for tests/internal callers. One AcroForm field returned by Document::get_form_fields. Dot-separated partial names per PDF spec §12.7.4.2 — a nested field “address” → “street” → “city” lands as address.street.city.
ImageInfo: Image XObject inventory entry. We deliberately do not return the decoded image — that would pull in JBIG2/JPEG2000/Flate/DCTDecode (large C deps). The metadata is enough to drive routing (“is this page a scan we should OCR?”).
Link: One hyperlink. External URI actions populate uri; intra-document GoTo actions populate target_page (1-indexed).
PageInfo
PositionedPage: Per-page positioned spans plus a re-assembled plain-text string.
TextBlock: Cluster of TextSpans grouped by spatial proximity.
TextLine
TextSpan: One positioned text fragment emitted by a single text-showing operator (Tj / TJ / ' / ").
TocEntry: One entry in the document outline. level is 1-indexed depth; page is the 1-indexed target page, or None for unresolvable destinations (usually external GoToR).
Widget: One AcroForm field. name is the fully qualified, dot-separated path from the field tree root. value is the current field value as a PDF text string; for choice fields with multi-select, comma-joined.
Word: Whitespace-delimited token with its own bbox. Bbox is built by proportioning the containing span’s bbox by character count.

Enums§

ExtractError: Errors emitted by spectre_pdf extraction functions.
FormFieldType: AcroForm field types (PDF spec §12.7.4 /FT).
ImageContainer: Output container for Document::image_bytes.

Constants§

MAX_OUTPUT_BYTES: Maximum byte length of the concatenated output produced by extract_text. Refuses pathological documents whose extracted text would exhaust available memory.
MAX_PAGES: Maximum number of pages a single extraction call will process. Crafted PDFs can claim millions of pages; we refuse before doing the work.
MAX_TABLES: Maximum number of tables extract_tables will return per call. The detector occasionally over-segments on noisy input; this cap keeps the returned Vec<Vec<Vec<String>>> bounded.

Functions§

extract_annotations: Extract annotations (read-only).
extract_blocks: Extract text blocks (paragraph-sized clusters) with bounding boxes.
extract_document_info: Document-level summary: page count, PDF version, encryption + linearization flags, xref size, trailer ID. Cheap; doesn’t decode any content streams.
extract_images: Inventory of embedded images (size, colorspace, filter chain) — equivalent. Image bytes are not decoded; the inventory itself covers routing and observability.
extract_links: Extract hyperlinks. Pass page to filter to one page (1-indexed).
extract_metadata: PDF /Info dictionary plus page count and PDF version. Keys: pages, pdf_version, optionally title, author, subject, keywords, creator, producer, creation_date, mod_date.
extract_page_info: Per-page geometry: mediabox, cropbox, rotation, width, height, rolled into one cheap walk over the page tree.
extract_pages: Extract text per page, in document order. Image-only pages return empty strings so indices line up. Per-page extraction failures surface as ExtractError::PageExtractFailed. Refuses documents claiming more than MAX_PAGES.
extract_pages_lenient: Best-effort variant: pages that fail to extract (commonly CID fonts missing /ToUnicode) return empty strings rather than erroring the whole document. Document-level errors still surface.
extract_tables: Whitespace-column table extraction tuned for borderless tables. page is 1-indexed matching the other extract_* functions; None scans every page.
extract_text: Extract all text from PDF bytes as a single string.
extract_text_lenient: Best-effort variant of extract_text: failing pages are silently dropped (no error, no placeholder). Output size limit still enforced.
extract_text_positioned: Extract text per page with bounding boxes. Returns one PositionedPage per page in document order; each carries a re-assembled plain-text string and the underlying TextSpans with PDF user-space rects. Pass page (1-indexed) for one page only.
extract_toc: Extract the document outline (bookmarks / TOC). Returns an empty Vec for outline-less PDFs.
extract_words: Extract words with bounding boxes. Each word carries (block_no, line_no, word_no) so callers can reconstruct paragraph structure cheaply.
score_batch: Score a batch of texts in parallel via rayon.
score_text: Text-quality score: 0.0 (binary noise) to 1.0 (clean prose). Useful for filtering pages where extraction returned a CID dump.
search: Search for a string and return one rect per match. Case-insensitive and flexible-whitespace by default; see SearchOptions.

Crate spectre_pdf

Crate spectre_pdf Copy item path

§Quickstart (Rust)

§Quickstart (Python, requires --features python)

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Crate spectre_pdf

§Quickstart (Python, requires `--features python`)