Skip to content

Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.

fix(pdf): abort early on scanned PDFs with an OCR hint (#130)

Virgilio Juniorbd8a522d5afc
diff --git a/book_to_skill/parsers/pdf.py b/book_to_skill/parsers/pdf.py
index 37bfd35..ca8cecd 100644
--- a/book_to_skill/parsers/pdf.py
+++ b/book_to_skill/parsers/pdf.py
@@ -64,6 +64,25 @@ def extract_with_pdftotext(pdf_path: str) -> str | None:
return None
+def looks_image_only(pdf_path: str, pages: int = 5) -> bool:
+ """True when the first `pages` pages yield no extractable text — the signature
+ of a scanned/image-only PDF. Cheap pre-flight so a scan fails in a second
+ instead of after the whole extraction chain has run. Best-effort: without
+ pdftotext it reports False and the normal chain (plus the final empty-text
+ guard) still applies."""
+ if not shutil.which("pdftotext"):
+ return False
+ try:
+ result = subprocess.run(
+ ["pdftotext", "-f", "1", "-l", str(pages), os.path.abspath(pdf_path), "-"],
+ capture_output=True, text=True, timeout=30,
+ encoding="utf-8", errors="replace",
+ )
+ return result.returncode == 0 and not result.stdout.strip()
+ except Exception:
+ return False
+
+
def extract_with_pypdf(pdf_path: str) -> str | None:
try:
import pypdf
diff --git a/book_to_skill/utils.py b/book_to_skill/utils.py
index 0534656..834d275 100644
--- a/book_to_skill/utils.py
+++ b/book_to_skill/utils.py
@@ -38,6 +38,7 @@ from book_to_skill.parsers.pdf import (
extract_with_pdftotext,
extract_with_pypdf,
extract_with_pdfminer,
+ looks_image_only,
count_pages,
)
from book_to_skill.parsers.epub import (
@@ -533,10 +534,17 @@ def extract_single_file(input_path: Path, extraction_mode: str, install_mode: st
pages_label = "spine_items"
elif ext == ".pdf":
print(f"Extracting PDF: {input_str}")
+ if looks_image_only(input_str):
+ raise ExtractionError(
+ f"{input_path.name} looks like a scanned (image-only) PDF: its first pages "
+ "contain no extractable text, only images.\n"
+ "Run OCR on it first, then retry:\n"
+ " ocrmypdf input.pdf output.pdf"
+ )
if extraction_mode == "technical":
print("Mode: technical — using Docling (layout-aware)...", end=" ", flush=True)
text = extract_with_docling(input_str)
- if text:
+ if text and text.strip():
method = "docling"
print("OK")
else:
@@ -547,22 +555,22 @@ def extract_single_file(input_path: Path, extraction_mode: str, install_mode: st
print("Mode: text — using pdftotext...")
print("Trying pdftotext...", end=" ", flush=True)
text = extract_with_pdftotext(input_str)
-
- if text:
+
+ if text and text.strip():
method = "pdftotext"
print("OK")
else:
print("not available")
print("Trying pypdf...", end=" ", flush=True)
text = extract_with_pypdf(input_str)
- if text:
+ if text and text.strip():
method = "pypdf"
print("OK")
else:
print("not available")
print("Trying pdfminer.six...", end=" ", flush=True)
text = extract_with_pdfminer(input_str)
- if text:
+ if text and text.strip():
method = "pdfminer"
print("OK")
else:
diff --git a/tests/test_book_to_skill.py b/tests/test_book_to_skill.py
index 8b27c65..248e72d 100644
--- a/tests/test_book_to_skill.py
+++ b/tests/test_book_to_skill.py
@@ -1506,6 +1506,56 @@ class TestPdftotextEncoding:
assert captured.get("errors") == "replace"
+class TestLooksImageOnly:
+ """Scanned PDFs are caught by probing the first pages, before the chain runs."""
+
+ def _probe(self, monkeypatch, stdout, *, has_pdftotext=True):
+ captured = {}
+
+ class _Result:
+ returncode = 0
+
+ _Result.stdout = stdout
+ monkeypatch.setattr(
+ pdf_parser.shutil, "which",
+ lambda name: "/usr/bin/pdftotext" if has_pdftotext else None,
+ )
+
+ def fake_run(cmd, **kwargs):
+ captured["cmd"] = cmd
+ return _Result()
+
+ monkeypatch.setattr(pdf_parser.subprocess, "run", fake_run)
+ return captured
+
+ def test_no_text_in_first_pages_is_image_only(self, monkeypatch):
+ captured = self._probe(monkeypatch, "\n\f\n \f")
+ assert pdf_parser.looks_image_only("scan.pdf") is True
+ # Only the first pages are probed, not the whole book.
+ assert "-l" in captured["cmd"] and captured["cmd"][captured["cmd"].index("-l") + 1] == "5"
+
+ def test_text_in_first_pages_is_not_image_only(self, monkeypatch):
+ self._probe(monkeypatch, "Chapter 1\nOnce upon a time")
+ assert pdf_parser.looks_image_only("book.pdf") is False
+
+ def test_without_pdftotext_probe_is_skipped(self, monkeypatch):
+ self._probe(monkeypatch, "", has_pdftotext=False)
+ assert pdf_parser.looks_image_only("scan.pdf") is False
+
+ def test_extraction_fails_early_with_ocr_hint(self, monkeypatch, tmp_path):
+ from book_to_skill import utils
+
+ pdf = tmp_path / "scan.pdf"
+ pdf.write_bytes(b"%PDF-1.4\n")
+ monkeypatch.setattr(utils, "looks_image_only", lambda path: True)
+
+ with pytest.raises(ExtractionError) as exc:
+ utils.extract_single_file(pdf, "text", "no")
+
+ assert "scanned" in str(exc.value)
+ assert "ocrmypdf" in str(exc.value)
+
+
class TestPdftotextCleanup:
"""clean_pdftotext strips repeated headers/footers/page numbers and dehyphenates."""