pdf-official

# PDF skill An Apache-2.0 toolkit for reading, composing, transforming, and filling PDF files. Written from scratch on top of permissively-licensed open-source libraries (pypdf, pdfplumber, pypdfium2, reportlab, pdf-lib, qpdf) so this can be embedded in commercial projects without special agreement. ## Route the task Pick the sub-guide by the *verb* of the request. | Task | Path | Read | |------|------|------| | Pull text / tables / metadata / images out of an existing PDF | Extract | [`extract.md`](extract.md) | | Combine, carve, rotate, crop, watermark, encrypt, or shrink | Transform | [`transform.md`](transform.md) | | Build a PDF that doesn't exist yet (report, invoice, certificate) | Compose | [`compose.md`](compose.md) | | Fill a form (AcroForm or scanned) | Interactive | [`interactive.md`](interactive.md) | | Scanned / image-only PDF (no selectable text) | Extract → *OCR* | [`extract.md`](extract.md) §5 | If a task mixes several of these, follow the order: **probe → plan → extract or compose → validate.** Every path starts with a probe. `scripts/survey.py` returns page count, whether the file is encrypted, whether it has an AcroForm, and whether page 1 looks like a scan. ## First install > **Bundled runtime:** when the `MIMO_PYTHON` environment variable is set, skip the installs below — run every command with `python3`/`uv run` replaced by `"$MIMO_PYTHON"` (pypdf/pypdfium2/reportlab/Pillow preinstalled; pip console scripts unavailable, use `"$MIMO_PYTHON" -m <module>`). A bundled qpdf is exposed as `MIMO_QPDF` (picked up automatically by the scripts here); invoke it directly as `"$MIMO_QPDF" --check file.pdf`. Python-only path (all BSD / MIT / Apache) — covers 95% of tasks: ```bash python3 -m pip install --upgrade pypdf pdfplumber pypdfium2 reportlab Pillow ``` Add these external binaries only when you actually need them: ```bash # qpdf — merge/split/encrypt/repair, Apache-2.0 brew install qpdf # macOS apt-get install -y qpdf # Debian / Ubuntu # Tesseract — OCR for scanned PDFs, Apache-2.0 brew install tesseract python3 -m pip install pytesseract pdf2image apt-get install -y tesseract-ocr # Poppler — pdftotext / pdftoppm / pdfimages, GPL-2.0 # Optional. Only install if you accept a GPL dependency at CLI level. brew install poppler apt-get install -y poppler-utils ``` Every script under `scripts/` uses argparse. Exit codes: `0` OK · `1` runtime failure · `2` bad arguments · `3` validation failure (`apply_values.py` / `overlay_text.py`; `sanity_check.py` reports findings with exit `1`). Any single script can be lifted into another project — none imports from a shared framework. ## One-command triage ```bash scripts/survey.py path/to/file.pdf --pretty ``` Sample output: ```json { "path": "/abs/path/file.pdf", "page_count": 12, "is_locked": false, "form_field_count": 34, "looks_scanned": false, "metadata": {"Title": "...", "Author": "...", "Producer": "..."} } ``` Route by the flags: - `is_locked: true` → unlock first (`qpdf --password=… --decrypt`). Almost every reader library refuses locked files. - `form_field_count > 0` → widgets path in [`interactive.md`](interactive.md) §1. - `form_field_count == 0` AND you need to fill it → overlay path in [`interactive.md`](interactive.md) §2. - `looks_scanned: true` → skip pypdf text extraction, go straight to OCR ([`extract.md`](extract.md) §5). ## Which library for which task | Task | Preferred | Reason | Fallback | |------|-----------|--------|----------| | Plain text | `pdftotext -layout` | fastest, keeps columns | `pypdf` | | Positioned text | `pdfplumber` | char-level bboxes | `pypdfium2.get_text` | | Tables | `pdfplumber` | tunable `table_settings` | pandas over manual CSV | | Page → image | `pypdfium2` | Apache/BSD, no GPL | `pdftoppm` (GPL) | | Merge / carve / rotate | `pypdf` | pure Python | `qpdf --pages` (faster on huge files) | | Encrypt / repair / linearise | `qpdf` | handles broken input | pypdf (basic encrypt only) | | Compose from scratch | `reportlab` | mature, BSD | `pdf-lib` in Node | | Fill AcroForm | `pypdf.update_page_form_field_values` | preserves widget appearances | `pdf-lib` in Node | | Overlay on non-fillable | reportlab + `pypdf.merge_page` | two-layer merge, see interactive.md | — | ## Common gotchas 1. **PDF origin is bottom-left**, image origin is top-left. Every "off by a few points" bug is one of these two systems misapplied. Coordinate conversion is in one place: [`interactive.md`](interactive.md) §2.c. 2. **`pypdf.extract_text()` returns nothing for scans.** That's not a bug — there's no text stream. Use the `looks_scanned` flag and route to OCR. 3. **Unicode subscripts / superscripts render as black rectangles in reportlab** because Helvetica/Times/Courier don't ship those glyphs. Use `<sub>` / `<super>` XML in `Paragraph`, or move the pen manually on canvas. See [`compose.md`](compose.md) §5. 4. **CJK text renders as black boxes when the font never registered.** reportlab does not consult the OS font system; a bad font name/path (思源黑体, PingFang, Noto on machines that lack it) plus a swallowed exception means a silent Helvetica fallback — and Helvetica has no CJK glyphs. Resolve fonts with the ladder in [`compose.md`](compose.md) §4 (`resolve_cjk_font()`); the terminal fallback is the built-in CID font, never Helvetica. 5. **XFA forms are not AcroForms.** If `probe_fields.py` returns `[]` on a PDF that clearly has widgets in Adobe Reader, it's XFA — flatten it in Acrobat first. 6. **`writer.encrypt(pw)` in pypdf uses RC4 by default**. For real AES-256, pass `algorithm="AES-256"`, or use `qpdf --encrypt … 256 --`. ## What's next Open the sub-guide from the routing table and work through it end to end. Each sub-guide has a Validation section at the bottom describing how to confirm the result.