Skip to content

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

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.py
index a9cc87a..681108c 100644
--- a/scripts/extractor/parsers/epub.py
+++ b/scripts/extractor/parsers/epub.py
@@ -1,3 +1,4 @@
+import posixpath
import re
import zipfile
from 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 files
spine_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.py
index 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)
# ═══════════════════════════════════════════════════════════════════════════