Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.
Python agent-skillsai-agentsbook-to-skillcontext-engineeringdocument-processingedtechknowledge-baseknowledge-managementllmpdf-to-markdownragself-studystudy-tools
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.pyindex 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 pypdfdiff --git a/book_to_skill/utils.py b/book_to_skill/utils.pyindex 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: stpages_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: stprint("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.pyindex 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."""