PDF

# PDF

Work with PDF documents for extraction, creation, merging, splitting, annotation,
and form filling. PDFs are the most common business document format — and the
most variable in quality.

## Keywords
pdf, portable document format, scanned pdf, ocr, form fill, merge pdf, split pdf,
annotate, watermark, redact, sign, signature, fillable form, extract text,
extract tables, page rotation, password protection, encryption, decrypt,
attachments, bookmarks, table of contents

## Core Truth

There are three kinds of PDFs and they need three different approaches:
1. **Text-native PDFs** — generated from Word/HTML, text is selectable. Use pdfplumber.
2. **Image-only PDFs** — scanned documents, text is pixels. Need OCR (tesseract).
3. **Hybrid PDFs** — text layer over scanned image. Quality varies wildly.

Identify the type first. Running text extraction on an image-only PDF returns
empty strings and the user thinks you broke. Always inspect before extracting.

---

## 1. When To Use

- Extracting text, tables, or data from PDFs
- Creating a new PDF from content
- Merging multiple PDFs into one
- Splitting one PDF into many
- Filling a fillable form
- Adding watermarks or page numbers
- OCR on scanned documents
- Annotating with highlights or comments

## 2. Choosing the Right Library

| Task | Library | Notes |
|------|---------|-------|
| Read text-native | pdfplumber | Best for tables and structured text |
| Read scanned | pytesseract + pdf2image | Requires tesseract binary |
| Create from scratch | reportlab | Programmatic, code-heavy |
| Create from HTML | weasyprint | Better visual quality |
| Merge/split | pypdf | Lightweight, reliable |
| Fill forms | pypdf or pdfrw | pypdf for AcroForms, pdfrw for legacy |
| Annotate | PyMuPDF (fitz) | Most powerful, slightly heavier |

Default to PyMuPDF when uncertain — it covers ~80% of operations.

## 3. Detecting PDF Type

```python
import pdfplumber
with pdfplumber.open(path) as pdf:
    text = pdf.pages[0].extract_text() or ""
    if len(text.strip()) < 50:
        # Probably image-only — need OCR
```

A page with < 50 characters of extracted text is almost always image-only. Switch
to OCR. Don't waste 10 pages of extraction before realizing.

## 4. OCR Workflow

1. Convert PDF pages to images (`pdf2image.convert_from_path`)
2. Run tesseract on each image (`pytesseract.image_to_string`)
3. Reassemble into structured text
4. Warn the user — OCR is never perfect. Quote accuracy is 95-98% for clean
   scans, 70-85% for poor scans.

## 5. Form Filling

Two form types exist:
- **AcroForm** — text fields, checkboxes, dropdowns. Use `pypdf`.
- **XFA** — dynamic forms (LiveCycle). Very few libraries handle these. Often
  the right answer is "convert to a flat PDF and add text overlays."

Always preserve the original form structure if the user might re-fill it later.

## 6. Tables

Table extraction is the hardest PDF task. Strategies:
- pdfplumber's `extract_tables()` works for ruled tables
- For unruled tables, use `find_tables()` with custom settings
- For complex layouts, consider tabula-py (requires Java)
- For scanned tables, OCR + manual reconstruction

Don't promise perfect table extraction. Validate the output.

## 7. Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Empty text | Image-only PDF | Use OCR |
| Garbled text | Embedded fonts not mapped | Try alternate library; sometimes unfixable |
| Form fields missing after fill | Need to flatten or update_field_appearances | Set NeedAppearances flag |
| Merged PDF huge | Inherited fonts not deduplicated | Use `compress_content_streams()` |
| Rotation lost | PDF /Rotate not preserved | Read and reapply rotation |

## 8. Key Questions Before Starting

- What kind of PDF — native, scanned, or hybrid?
- Read-only or modify?
- Does the user need to preserve the original?
- Is there a form, and is it AcroForm or XFA?
- What's the OCR language (default English may not fit)?

## References
- `references/pdf-extraction.md` — Strategies per content type
- `references/pdf-creation.md` — Templates and design patterns
- `scripts/detect-pdf-type.py` — One-liner detection helper