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: resolve OPF-relative hrefs in EPUB zipfile fallback (#11) (#12)
Marcello Mendofbc46c8a04da
diff --git a/scripts/extractor/parsers/epub.py b/scripts/extractor/parsers/epub.pyindex a9cc87a..681108c 100644--- a/scripts/extractor/parsers/epub.py+++ b/scripts/extractor/parsers/epub.py@@ -1,3 +1,4 @@+import posixpathimport reimport zipfilefrom extractor.parsers.html import _HTMLTextExtractor@@ -21,17 +22,45 @@ def extract_with_ebooklib(epub_path: str) -> str | None:return None+def _find_opf_path(zf: zipfile.ZipFile) -> str | None:+ """Locate the OPF package document inside an EPUB archive.++ First tries ``META-INF/container.xml`` (the spec-defined entry point),+ then falls back to scanning the archive for any ``.opf`` file.+ """+ # Spec-defined: read container.xml for the rootfile path+ try:+ container = zf.read("META-INF/container.xml").decode("utf-8", errors="replace")+ match = re.search(r'full-path=["\']([^"\']+\.opf)["\']', container)+ if match:+ return match.group(1)+ except (KeyError, Exception):+ pass++ # Fallback: glob for any .opf file+ opf_files = [n for n in zf.namelist() if n.endswith(".opf")]+ return opf_files[0] if opf_files else None++def extract_with_zipfile(epub_path: str) -> str | None:"""stdlib-only EPUB extractor: unzip → parse HTML files."""try:with zipfile.ZipFile(epub_path) as zf:names = zf.namelist()++ # Locate OPF and determine its directory for resolving relative hrefs+ opf_path = _find_opf_path(zf)+ opf_dir = posixpath.dirname(opf_path) if opf_path else ""+# Read OPF spine to get reading order, fall back to sorted xhtml filesspine_order: list[str] = []- opf_files = [n for n in names if n.endswith(".opf")]- if opf_files:- opf_text = zf.read(opf_files[0]).decode("utf-8", errors="replace")- spine_order = re.findall(r'href=["\']([^"\']+\.(?:xhtml|html))["\']', opf_text)+ if opf_path:+ opf_text = zf.read(opf_path).decode("utf-8", errors="replace")+ raw_hrefs = re.findall(r'href=["\']([^"\']+\.(?:xhtml|html))["\']', opf_text)+ # Resolve hrefs relative to the OPF directory+ for href in raw_hrefs:+ resolved = posixpath.normpath(posixpath.join(opf_dir, href)) if opf_dir else href+ spine_order.append(resolved)html_files = spine_order or sorted(n for n in names if n.endswith((".html", ".xhtml"))@@ -57,10 +86,11 @@ def count_epub_chapters(epub_path: str) -> int:"""Count spine items (approximate chapter count) without dependencies."""try:with zipfile.ZipFile(epub_path) as zf:- opf_files = [n for n in zf.namelist() if n.endswith(".opf")]- if not opf_files:+ opf_path = _find_opf_path(zf)+ if not opf_path:return 0- opf_text = zf.read(opf_files[0]).decode("utf-8", errors="replace")+ opf_text = zf.read(opf_path).decode("utf-8", errors="replace")return len(re.findall(r'<itemref\b', opf_text))except Exception:return 0+diff --git a/tests/test_extractor.py b/tests/test_extractor.pyindex c08fcc2..e7e455a 100644--- a/tests/test_extractor.py+++ b/tests/test_extractor.py@@ -115,6 +115,57 @@ def _make_unsupported_file(path: Path) -> Path:return path+def _make_oebps_epub(path: Path) -> Path:+ """Create an EPUB with OPF inside OEBPS/ (like LibreOffice/Calibre output).++ This is the layout that triggers the OPF-relative href bug:+ the OPF lists ``href="sections/ch1.xhtml"`` but the actual zip entry+ is ``OEBPS/sections/ch1.xhtml``.+ """+ with zipfile.ZipFile(path, "w") as zf:+ zf.writestr("mimetype", "application/epub+zip")+ zf.writestr(+ "META-INF/container.xml",+ textwrap.dedent("""\+ <?xml version="1.0"?>+ <container xmlns="urn:oasis:names:tc:opendocument:xmlns:container"+ version="1.0">+ <rootfiles>+ <rootfile full-path="OEBPS/content.opf"+ media-type="application/oebps-package+xml"/>+ </rootfiles>+ </container>+ """),+ )+ zf.writestr(+ "OEBPS/content.opf",+ textwrap.dedent("""\+ <?xml version="1.0"?>+ <package xmlns="http://www.idpf.org/2007/opf" version="3.0">+ <metadata/>+ <manifest>+ <item id="ch1" href="sections/ch1.xhtml" media-type="application/xhtml+xml"/>+ <item id="ch2" href="sections/ch2.xhtml" media-type="application/xhtml+xml"/>+ </manifest>+ <spine>+ <itemref idref="ch1"/>+ <itemref idref="ch2"/>+ </spine>+ </package>+ """),+ )+ zf.writestr(+ "OEBPS/sections/ch1.xhtml",+ "<html><body><p>Chapter one from OEBPS.</p></body></html>",+ )+ zf.writestr(+ "OEBPS/sections/ch2.xhtml",+ "<html><body><p>Chapter two from OEBPS.</p></body></html>",+ )+ return path+++# ═══════════════════════════════════════════════════════════════════════════# FIX #1 — EPUB extraction no longer does tuple-unpack# ═══════════════════════════════════════════════════════════════════════════@@ -160,6 +211,65 @@ class TestEpubExtractionFix:assert result["text"] # some text was extracted+# ═══════════════════════════════════════════════════════════════════════════+# BUG #11 — EPUB OPF-relative href resolution+# ═══════════════════════════════════════════════════════════════════════════++class TestEpubOpfRelativePaths:+ """Verify that EPUBs with OPF in a subdirectory (OEBPS/) are extracted."""++ def test_zipfile_fallback_resolves_oebps_paths(self, tmp_path):+ """The core bug: hrefs in OPF are relative to OPF dir, not archive root."""+ from extractor.parsers.epub import extract_with_zipfile++ epub_path = _make_oebps_epub(tmp_path / "oebps.epub")+ text = extract_with_zipfile(str(epub_path))++ assert text is not None, "extract_with_zipfile returned None for OEBPS EPUB"+ assert "Chapter one from OEBPS" in text+ assert "Chapter two from OEBPS" in text++ def test_full_extraction_with_oebps_epub(self, tmp_path):+ """End-to-end: extract_single_file should succeed with OEBPS layout."""+ epub_path = _make_oebps_epub(tmp_path / "test_oebps.epub")++ with mock.patch("extractor.utils.prepare_dependencies"):+ result = extract_single_file(epub_path, "text", "no")++ assert result["format"] == "epub"+ assert result["extraction_method"] in ("ebooklib", "zipfile")+ assert "Chapter one from OEBPS" in result["text"]+ assert "Chapter two from OEBPS" in result["text"]++ def test_container_xml_locates_opf(self, tmp_path):+ """_find_opf_path should prefer META-INF/container.xml over globbing."""+ from extractor.parsers.epub import _find_opf_path++ epub_path = _make_oebps_epub(tmp_path / "container.epub")+ with zipfile.ZipFile(epub_path) as zf:+ opf_path = _find_opf_path(zf)++ assert opf_path == "OEBPS/content.opf"++ def test_count_chapters_with_oebps(self, tmp_path):+ """count_epub_chapters should work with OPF in subdirectory."""+ from extractor.parsers.epub import count_epub_chapters++ epub_path = _make_oebps_epub(tmp_path / "chapters.epub")+ count = count_epub_chapters(str(epub_path))+ assert count == 2++ def test_root_level_opf_still_works(self, tmp_path):+ """Regression check: root-level OPF (no subdirectory) should still work."""+ from extractor.parsers.epub import extract_with_zipfile++ epub_path = _make_minimal_epub(tmp_path / "root_opf.epub")+ text = extract_with_zipfile(str(epub_path))++ assert text is not None+ assert "EPUB chapter one content" in text++# ═══════════════════════════════════════════════════════════════════════════# FIX #2 — Batch resilience (ExtractionError instead of sys.exit)# ═══════════════════════════════════════════════════════════════════════════