PDF Processing Guide

When to Use This Skill

Use this skill when working with PDF document generation or manipulation in your codebase.

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your PDF implementation
Follow the best practices outlined in this skill

Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.

Quick Start

from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()

Python Libraries

pypdf - Basic Operations

Merge PDFs

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)

Split PDF

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)

Extract Metadata

reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")

Rotate Pages

reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)

pdfplumber - Text and Table Extraction

Extract Text with Layout

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)

Extract Tables

with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)

Advanced Table Extraction

import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # Check if table is not empty
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# Combine all tables
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

reportlab - Create PDFs

Basic PDF Creation

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("hello.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()

Create PDF with Multiple Pages

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)

Command-Line Tools

pdftotext (poppler-utils)

# Extract text
pdftotext input.pdf output.txt

# Extract text preserving layout
pdftotext -layout input.pdf output.txt

# Extract specific pages
pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5

qpdf

# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Split pages
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf

# Rotate pages
qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees

# Remove password
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

pdftk (if available)

# Merge
pdftk file1.pdf file2.pdf cat output merged.pdf

# Split
pdftk input.pdf burst

# Rotate
pdftk input.pdf rotate 1east output rotated.pdf

Common Tasks

Extract Text from Scanned PDFs

# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# Convert PDF to images
images = convert_from_path('scanned.pdf')

# OCR each page
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)

Add Watermark

from pypdf import PdfReader, PdfWriter

# Create watermark (or load existing)
watermark = PdfReader("watermark.pdf").pages[0]

# Apply to all pages
reader = PdfReader("document.pdf")
writer = PdfWriter()

for page in reader.pages:
    page.merge_page(watermark)
    writer.add_page(page)

with open("watermarked.pdf", "wb") as output:
    writer.write(output)

Extract Images

# Using pdfimages (poppler-utils)
pdfimages -j input.pdf output_prefix

# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.

Password Protection

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()

for page in reader.pages:
    writer.add_page(page)

# Add password
writer.encrypt("userpassword", "ownerpassword")

with open("encrypted.pdf", "wb") as output:
    writer.write(output)

Quick Reference

Task	Best Tool	Command/Code
Merge PDFs	pypdf	`writer.add_page(page)`
Split PDFs	pypdf	One page per file
Extract text	pdfplumber	`page.extract_text()`
Extract tables	pdfplumber	`page.extract_tables()`
Create PDFs	reportlab	Canvas or Platypus
Command line merge	qpdf	`qpdf --empty --pages ...`
OCR scanned PDFs	pytesseract	Convert to image first
Fill PDF forms	pdf-lib or pypdf (see forms.md)	See forms.md

Next Steps

For advanced pypdfium2 usage, see reference.md
For JavaScript libraries (pdf-lib), see reference.md
If you need to fill out a PDF form, follow the instructions in forms.md
For troubleshooting guides, see reference.md

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: pdf

Completed:
- [x] PDF operation completed: [merge|split|extract|create|form-fill]
- [x] Output file(s) created at [path(s)]
- [x] File integrity verified (opens without errors)
- [x] Text/tables/metadata extracted successfully (if applicable)

Outputs:
- [path/to/output.pdf]
- [path/to/extracted.txt] (if text extraction)
- [path/to/tables.xlsx] (if table extraction)

Verification:
- Page count: [N] pages
- File size: [X] MB
- Integrity: Valid PDF structure

Completion Checklist

Before marking this skill as complete, verify:

Output PDF file(s) exist at expected path(s)
PDF opens without errors in PDF reader (Adobe, Preview, etc.)
For merge: All source PDFs combined in correct order
For split: Correct pages extracted to separate files
For text extraction: Text content readable and complete
For table extraction: Tables converted to structured format (CSV/Excel)
For form filling: All fields populated correctly
For creation: Content displays as intended with proper layout
File permissions and encryption applied correctly (if applicable)

Failure Indicators

This skill has FAILED if:

❌ PDF file not created at expected path
❌ PDF corrupted or cannot be opened
❌ pypdf/pdfplumber/reportlab import errors
❌ Text extraction returns empty or garbled text
❌ Table extraction fails or returns incorrect data
❌ Merge operation produces incorrect page order
❌ Form fields not populated or data lost
❌ OCR required but pytesseract not available
❌ Watermark/encryption fails to apply

When NOT to Use

Do NOT use this skill when:

Native document format is better (use DOCX/XLSX for editable documents)
Simple text file is sufficient (use .txt or markdown)
Interactive forms needed (use web forms instead of PDF forms)
Heavy editing required (PDF is not easily editable; use source format)
Real-time collaboration needed (use Google Docs/collaborative tools)

Use alternatives:

Text extraction only: Use pdftotext command-line tool
Form creation: Use PDF form design tools (Adobe Acrobat)
Web publishing: Convert to HTML for better accessibility
Data storage: Use databases instead of PDF tables

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Not checking for scanned PDFs	Text extraction fails on images	Use OCR (pytesseract) for scanned PDFs
Opening with data_only then saving	Corrupts PDF structure	Use pypdf for manipulation, not editing
Missing password handling	Fails on encrypted PDFs	Check for encryption, handle passwords
Ignoring page orientation	Rotated text not extracted	Use pdfplumber with rotation handling
Large file memory loading	Memory exhaustion	Process page-by-page for large PDFs
No table extraction validation	Returns incomplete/wrong data	Verify table structure before processing
Using reportlab for editing	Can only create, not edit	Use pypdf for editing existing PDFs
Not verifying output integrity	Delivers corrupted PDFs	Always test output file opens correctly

Principles

This skill embodies:

#1 Zero Defects - Verify PDF integrity; corrupted PDFs are unacceptable
#4 Validation - Test output files open correctly in PDF readers
#6 Clear, Understandable, Explainable - Use appropriate tool for task (pypdf/pdfplumber/reportlab)
#8 No Assumptions - Check for encryption, scanned content, rotation
#10 First Principles - Understand PDF structure (text vs images vs forms)

Reference Standards:

PDF/A for archival (long-term preservation)
PDF/X for print production
PDF/UA for accessibility (Universal Access)
Use PyPDF for manipulation, pdfplumber for extraction, reportlab for creation

When to Use This Skill​

How to Use This Skill​

Overview​

Quick Start​

Python Libraries​

pypdf - Basic Operations​

Merge PDFs​

Split PDF​

Extract Metadata​

Rotate Pages​

pdfplumber - Text and Table Extraction​

Extract Text with Layout​

Extract Tables​

Advanced Table Extraction​

reportlab - Create PDFs​

Basic PDF Creation​

Create PDF with Multiple Pages​

Command-Line Tools​

pdftotext (poppler-utils)​

qpdf​

pdftk (if available)​

Common Tasks​

Extract Text from Scanned PDFs​

Add Watermark​

Extract Images​

Password Protection​

Quick Reference​

Next Steps​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​