cloclo: Skill for Claude Code

PDF Processing Guide

Overview

This guide covers essential PDF reading operations using Python libraries and command-line tools. For advanced features (pypdfium2 rendering, pdfplumber table settings, OCR fallback, encrypted/corrupted PDF handling), see REFERENCE.md.

Reading & Inspecting PDFs

Before doing anything with a PDF, understand what you're working with.

Content inventory

Run a quick diagnostic first. For simple tasks ("summarize this document"), pdfinfo + a text sample may suffice. For anything involving figures, attachments, or extraction issues, run the full set:

# Always: page count, file size, PDF version, metadata
pdfinfo document.pdf

# Always: quick text extraction check — is this a text PDF or a scan?
pdftotext -f 1 -l 1 document.pdf - | head -20

# If figures/charts may matter:
pdfimages -list document.pdf

# If the PDF might contain embedded files (reports, portfolios):
pdfdetach -list document.pdf

# If text extraction looks garbled:
pdffonts document.pdf

This tells you:

• Page count and size — how big is the job?
• Text extractability — does pdftotext return real text, or is it empty (scanned) or garbled (broken font encoding)?
• Embedded raster images — are there photos or raster figures? (Note: vector-drawn charts from matplotlib/Excel won't appear — see "Extracting embedded images" below)
• Attachments — are there embedded spreadsheets, data files, etc.?
• Font status — are fonts embedded? If not, text extraction may produce wrong characters.

Text extraction

pypdf for basic text:

from pypdf import PdfReader

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

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

pdftotext preserving layout (better for multi-column docs):

# Layout mode preserves spatial positioning
pdftotext -layout document.pdf output.txt

# Specific page range
pdftotext -f 1 -l 5 document.pdf output.txt