pdf

Files (11)

• SKILL.md
• forms.md
• reference.md
• check_bounding_boxes.py · scripts/
• check_fillable_fields.py · scripts/
• convert_pdf_to_images.py · scripts/
• create_validation_image.py · scripts/
• extract_form_field_info.py · scripts/
• extract_form_structure.py · scripts/
• fill_fillable_fields.py · scripts/
• fill_pdf_form_with_annotations.py · scripts/

SKILL.md (first lines)

# Working with PDFs

Task-oriented recipes for PDF work, built around three Python libraries (`pypdf`, `pdfplumber`, `reportlab`) and the poppler-utils / qpdf command-line suites.

Companion documents in this directory — open them when the task calls for it:

- `forms.md` — required reading before filling out any PDF form
- `reference.md` — deeper material: pypdfium2 rendering, JavaScript libraries (pdf-lib, pdfjs-dist), advanced qpdf/poppler flags, performance tuning, and troubleshooting

## Choosing a Tool

| Goal | Reach for |
|------|-----------|
| Pull out plain text | `pdfplumber` or `pdftotext` |
| Pull out tables | `pdfplumber` (`extract_tables`) |
| Combine documents | `pypdf` or `qpdf` |
| Break a document apart | `pypdf` (one writer per output) |
| Produce a new PDF | `reportlab` (Canvas for absolute layout, Platypus for flowing documents) |
| Grab embedded images | `pdfimages` |
| Render pages as pictures | `pdftoppm` / `pdf2image` |
| OCR a scanned document | `pytesseract` + `pdf2image` |
| Fill out a form | see `forms.md` |

## Getting Content Out of a PDF

### Text

```python
import pdfplumber

with pdfplumber.open("report.pdf") as doc:
    full_text = "\n".join(pg.extract_text() or "" for pg in doc.pages)
```

From the shell, `pdftotext` is quickest; `-layout` keeps the visual column structure and `-f`/`-l` bound the page range:

```bash
pdftotext -layout report.pdf report.txt
pdftotext -f 2 -l 4 report.pdf middle_pages.txt
```

### Tables

`pdfplumber` returns each table as a list of rows; feed them straight into pandas when you need to reshape or export:

```python
import pandas as pd
import pdfplumber

frames = []
with pdfplumber.open("report.pdf") as doc:
    for pg in doc.pages:
        for tbl in pg.extract_tables():
            if tbl:
                frames.append(pd.DataFrame(tbl[1:], columns=tbl[0]))

if frames:
    pd.concat(frames, ignore_index=True).to_excel("tables.xlsx", index=False)
```

### Document Metadata

```python
from pypdf import PdfReader

info = PdfReader("report.pdf").metadata
for key in ("title", "author", "subject", "creator"):
    print(key, "=", getattr(info, key))
```

### Embedded Images vs. Page Renders

These are different operations — pick the right one:

- `pdfimages -all report.pdf img/fig` copies the *original bitmap objects* embedded in the file, untouched by page layout.
- `pdftoppm -png -r 300 report.pdf pages/pg` *rasterizes* whole pages — text, vectors, and annotations included — producing what is effectively a screenshot of each page.

A rendered page is never a substitute for an extracted image, and vice versa.

### Scanned Documents (OCR)

Scanned PDFs contain pictures of text, so extraction tools return nothing useful. Rasterize first, then OCR each page:

```python
# pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

pages = convert_from_path("scan.pdf")
recognized = [pytesseract.image_to_string(img) for img in pages]
print("\n\n".join(recognized))
```

## Reorganizing Pages

### Combine Documents

```python
from pypdf import PdfWriter

writer = PdfWriter()
for path in ["intro.pdf", "body.pdf", "appendix.pdf"]:
    writer.append(path)

with open("combined.pdf", "wb") as out:
    writer.write(out)
```

Or from the shell:

```bash
qpdf --empty --pages intro.pdf body.pdf appendix.pdf -- combined.pdf
```

### Split into Pieces

```python
from pypdf import PdfReader, PdfWriter

From Matrixx0070/xclaw, MIT.

More from Matrixx0070/xclaw