1---
2name: pdf
3description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
4license: Proprietary. LICENSE.txt has complete terms
5---
6 
7# PDF Processing Guide
8 
9## Overview
10 
11This 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.
12 
13## Quick Start
14 
15```python
16from pypdf import PdfReader, PdfWriter
17 
18# Read a PDF
19reader = PdfReader("document.pdf")
20print(f"Pages: {len(reader.pages)}")
21 
22# Extract text
23text = ""
24for page in reader.pages:
25    text += page.extract_text()
26```
27 
28## Python Libraries
29 
30### pypdf - Basic Operations
31 
32#### Merge PDFs
33```python
34from pypdf import PdfWriter, PdfReader
35 
36writer = PdfWriter()
37for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
38    reader = PdfReader(pdf_file)
39    for page in reader.pages:
40        writer.add_page(page)
41 
42with open("merged.pdf", "wb") as output:
43    writer.write(output)
44```
45 
46#### Split PDF
47```python
48reader = PdfReader("input.pdf")
49for i, page in enumerate(reader.pages):
50    writer = PdfWriter()
51    writer.add_page(page)
52    with open(f"page_{i+1}.pdf", "wb") as output:
53        writer.write(output)
54```
55 
56#### Extract Metadata
57```python
58reader = PdfReader("document.pdf")
59meta = reader.metadata
60print(f"Title: {meta.title}")
61print(f"Author: {meta.author}")
62print(f"Subject: {meta.subject}")
63print(f"Creator: {meta.creator}")
64```
65 
66#### Rotate Pages
67```python
68reader = PdfReader("input.pdf")
69writer = PdfWriter()
70 
71page = reader.pages[0]
72page.rotate(90)  # Rotate 90 degrees clockwise
73writer.add_page(page)
74 
75with open("rotated.pdf", "wb") as output:
76    writer.write(output)
77```
78 
79### pdfplumber - Text and Table Extraction
80 
81#### Extract Text with Layout
82```python
83import pdfplumber
84 
85with pdfplumber.open("document.pdf") as pdf:
86    for page in pdf.pages:
87        text = page.extract_text()
88        print(text)
89```
90 
91#### Extract Tables
92```python
93with pdfplumber.open("document.pdf") as pdf:
94    for i, page in enumerate(pdf.pages):
95        tables = page.extract_tables()
96        for j, table in enumerate(tables):
97            print(f"Table {j+1} on page {i+1}:")
98            for row in table:
99                print(row)
100```
101 
102#### Advanced Table Extraction
103```python
104import pandas as pd
105 
106with pdfplumber.open("document.pdf") as pdf:
107    all_tables = []
108    for page in pdf.pages:
109        tables = page.extract_tables()
110        for table in tables:
111            if table:  # Check if table is not empty
112                df = pd.DataFrame(table[1:], columns=table[0])
113                all_tables.append(df)
114 
115# Combine all tables
116if all_tables:
117    combined_df = pd.concat(all_tables, ignore_index=True)
118    combined_df.to_excel("extracted_tables.xlsx", index=False)
119```
120 
121### reportlab - Create PDFs
122 
123#### Basic PDF Creation
124```python
125from reportlab.lib.pagesizes import letter
126from reportlab.pdfgen import canvas
127 
128c = canvas.Canvas("hello.pdf", pagesize=letter)
129width, height = letter
130 
131# Add text
132c.drawString(100, height - 100, "Hello World!")
133c.drawString(100, height - 120, "This is a PDF created with reportlab")
134 
135# Add a line
136c.line(100, height - 140, 400, height - 140)
137 
138# Save
139c.save()
140```
141 
142#### Create PDF with Multiple Pages
143```python
144from reportlab.lib.pagesizes import letter
145from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
146from reportlab.lib.styles import getSampleStyleSheet
147 
148doc = SimpleDocTemplate("report.pdf", pagesize=letter)
149styles = getSampleStyleSheet()
150story = []
151 
152# Add content
153title = Paragraph("Report Title", styles['Title'])
154story.append(title)
155story.append(Spacer(1, 12))
156 
157body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
158story.append(body)
159story.append(PageBreak())
160 
161# Page 2
162story.append(Paragraph("Page 2", styles['Heading1']))
163story.append(Paragraph("Content for page 2", styles['Normal']))
164 
165# Build PDF
166doc.build(story)
167```
168 
169#### Subscripts and Superscripts
170 
171**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉, ⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes.
172 
173Instead, use ReportLab's XML markup tags in Paragraph objects:
174```python
175from reportlab.platypus import Paragraph
176from reportlab.lib.styles import getSampleStyleSheet
177 
178styles = getSampleStyleSheet()
179 
180# Subscripts: use <sub> tag
181chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])
182 
183# Superscripts: use <super> tag
184squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])
185```
186 
187For canvas-drawn text (not Paragraph objects), manually adjust font the size and position rather than using Unicode subscripts/superscripts.
188 
189## Command-Line Tools
190 
191### pdftotext (poppler-utils)
192```bash
193# Extract text
194pdftotext input.pdf output.txt
195 
196# Extract text preserving layout
197pdftotext -layout input.pdf output.txt
198 
199# Extract specific pages
200pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
201```
202 
203### qpdf
204```bash
205# Merge PDFs
206qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
207 
208# Split pages
209qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
210qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
211 
212# Rotate pages
213qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees
214 
215# Remove password
216qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
217```
218 
219### pdftk (if available)
220```bash
221# Merge
222pdftk file1.pdf file2.pdf cat output merged.pdf
223 
224# Split
225pdftk input.pdf burst
226 
227# Rotate
228pdftk input.pdf rotate 1east output rotated.pdf
229```
230 
231## Common Tasks
232 
233### Extract Text from Scanned PDFs
234```python
235# Requires: pip install pytesseract pdf2image
236import pytesseract
237from pdf2image import convert_from_path
238 
239# Convert PDF to images
240images = convert_from_path('scanned.pdf')
241 
242# OCR each page
243text = ""
244for i, image in enumerate(images):
245    text += f"Page {i+1}:\n"
246    text += pytesseract.image_to_string(image)
247    text += "\n\n"
248 
249print(text)
250```
251 
252### Add Watermark
253```python
254from pypdf import PdfReader, PdfWriter
255 
256# Create watermark (or load existing)
257watermark = PdfReader("watermark.pdf").pages[0]
258 
259# Apply to all pages
260reader = PdfReader("document.pdf")
261writer = PdfWriter()
262 
263for page in reader.pages:
264    page.merge_page(watermark)
265    writer.add_page(page)
266 
267with open("watermarked.pdf", "wb") as output:
268    writer.write(output)
269```
270 
271### Extract Images
272```bash
273# Using pdfimages (poppler-utils)
274pdfimages -j input.pdf output_prefix
275 
276# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
277```
278 
279### Password Protection
280```python
281from pypdf import PdfReader, PdfWriter
282 
283reader = PdfReader("input.pdf")
284writer = PdfWriter()
285 
286for page in reader.pages:
287    writer.add_page(page)
288 
289# Add password
290writer.encrypt("userpassword", "ownerpassword")
291 
292with open("encrypted.pdf", "wb") as output:
293    writer.write(output)
294```
295 
296## Quick Reference
297 
298| Task | Best Tool | Command/Code |
299|------|-----------|--------------|
300| Merge PDFs | pypdf | `writer.add_page(page)` |
301| Split PDFs | pypdf | One page per file |
302| Extract text | pdfplumber | `page.extract_text()` |
303| Extract tables | pdfplumber | `page.extract_tables()` |
304| Create PDFs | reportlab | Canvas or Platypus |
305| Command line merge | qpdf | `qpdf --empty --pages ...` |
306| OCR scanned PDFs | pytesseract | Convert to image first |
307| Fill PDF forms | pdf-lib or pypdf (see FORMS.md) | See FORMS.md |
308 
309## Next Steps
310 
311- For advanced pypdfium2 usage, see REFERENCE.md
312- For JavaScript libraries (pdf-lib), see REFERENCE.md
313- If you need to fill out a PDF form, follow the instructions in FORMS.md
314- For troubleshooting guides, see REFERENCE.md
315