Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(docreader): resolve EPUB images relative to their chapters (#3924)

Linyao Du3d01bebce3d7
diff --git a/docreader/parser/epub_parser.py b/docreader/parser/epub_parser.py
index 41961b7e1..68fdef94c 100644
--- a/docreader/parser/epub_parser.py
+++ b/docreader/parser/epub_parser.py
@@ -288,13 +288,12 @@ class EPUBParser(BaseParser):
aliases = {
original_path,
normalized,
- unquote(original_path),
- unquote(normalized),
- posixpath.basename(normalized),
}
for alias in aliases:
if alias:
image_aliases[alias] = image_path
+ # A basename fallback must not overwrite a real archive-root path.
+ image_aliases.setdefault(posixpath.basename(normalized), image_path)
@staticmethod
def _rewrite_image_sources(
@@ -306,17 +305,26 @@ class EPUBParser(BaseParser):
src = (img.get("src") or "").strip()
if not src:
continue
- normalized_src = EPUBParser._normalize_epub_path(src)
- candidates = [
- src,
- normalized_src,
- unquote(src),
- unquote(normalized_src),
- posixpath.basename(normalized_src),
- ]
+ # Only src is a URI reference. Strip its URI suffixes before decoding
+ # once; archive paths from EbookLib and ZIP already contain literal
+ # characters, including #, ? and percent-encoded-looking names.
+ raw_path = src.split("#", 1)[0].split("?", 1)[0].replace("\\", "/")
+ src_path = unquote(raw_path).replace("\\", "/")
+ normalized_src = EPUBParser._normalize_epub_path(src_path)
+ # Some EPUBs reference literal percent-looking names verbatim.
+ # Try the undecoded path after the decoded path at each location.
+ raw_normalized = EPUBParser._normalize_epub_path(raw_path)
+ candidates = [normalized_src, raw_normalized]
if base_path:
- joined = EPUBParser._normalize_epub_path(posixpath.join(base_path, src))
- candidates.extend([joined, unquote(joined)])
+ joined = EPUBParser._normalize_epub_path(
+ posixpath.join(base_path, src_path)
+ )
+ raw_joined = EPUBParser._normalize_epub_path(
+ posixpath.join(base_path, raw_path)
+ )
+ # Resolve relative to the chapter before trying ambiguous aliases.
+ candidates[:0] = [joined, raw_joined]
+ candidates.append(posixpath.basename(normalized_src))
for candidate in candidates:
if candidate in image_aliases:
img["src"] = image_aliases[candidate]
@@ -324,6 +332,6 @@ class EPUBParser(BaseParser):
@staticmethod
def _normalize_epub_path(path: str) -> str:
- path = unquote(path).split("#", 1)[0].split("?", 1)[0].replace("\\", "/")
- normalized = posixpath.normpath(path)
+ """Normalize a decoded archive path without interpreting it as a URI."""
+ normalized = posixpath.normpath(path.replace("\\", "/"))
return "" if normalized == "." else normalized.lstrip("/")
diff --git a/docreader/tests/test_epub_parser.py b/docreader/tests/test_epub_parser.py
index 4154f263c..282c55017 100644
--- a/docreader/tests/test_epub_parser.py
+++ b/docreader/tests/test_epub_parser.py
@@ -1,8 +1,15 @@
+import base64
+from html import escape
+from io import BytesIO
import os
import tempfile
import unittest
+from unittest.mock import patch
+from urllib.parse import quote
+import zipfile
from ebooklib import epub
+from PIL import Image
from docreader.parser.epub_parser import EPUBParser
from docreader.parser.registry import registry
@@ -52,7 +59,223 @@ def _minimal_epub_bytes() -> bytes:
os.unlink(path)
+def _epub_with_colliding_image_names(
+ image_src: str, *, root_image_first: bool = False
+) -> tuple[bytes, dict[str, bytes]]:
+ book = epub.EpubBook()
+ book.set_identifier("colliding-images")
+ book.set_title("Images in separate directories")
+ book.set_language("en")
+
+ image_data = {}
+ chapters = []
+ directories = (
+ ("root", "first", "second")
+ if root_image_first
+ else ("first", "second", "root")
+ )
+ for directory in directories:
+ index = ("first", "second", "root").index(directory)
+ image = BytesIO()
+ Image.new("RGB", (1, 1), (index * 100, 0, 0)).save(image, format="PNG")
+ image_data[directory] = image.getvalue()
+ book.add_item(
+ epub.EpubItem(
+ uid=f"{directory}-image",
+ file_name="pic.png" if directory == "root" else f"{directory}/pic.png",
+ media_type="image/png",
+ content=image_data[directory],
+ )
+ )
+ chapter_path = (
+ "root.xhtml" if directory == "root" else f"{directory}/chapter.xhtml"
+ )
+ chapter = epub.EpubHtml(
+ title=directory, file_name=chapter_path, lang="en"
+ )
+ src = (
+ "pic.png" if directory == "root" else image_src.format(directory=directory)
+ )
+ chapter.content = (
+ f'<html><body><h1>{directory}</h1>'
+ f'<img alt="{directory}" src="{src}">'
+ "</body></html>"
+ )
+ book.add_item(chapter)
+ chapters.append(chapter)
+ # The root-level pic.png also collides with chapter-relative references.
+ book.toc = tuple(chapters)
+ book.spine = chapters
+ book.add_item(epub.EpubNcx())
+ book.add_item(epub.EpubNav())
+ output = BytesIO()
+ epub.write_epub(output, book)
+ return output.getvalue(), image_data
+
+
+def _epub_with_literal_path_characters(
+ chapter_path: str, image_src: str, image_path: str, decoy_path: str
+) -> tuple[bytes, bytes]:
+ """URI-encode manifest hrefs while preserving literal ZIP entry names."""
+ container = (
+ '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container"'
+ ' version="1.0"><rootfiles><rootfile full-path="EPUB/package.opf"'
+ ' media-type="application/oebps-package+xml"/></rootfiles></container>'
+ )
+ package = (
+ '<package xmlns="http://www.idpf.org/2007/opf" version="3.0"'
+ ' unique-identifier="id"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
+ '<dc:identifier id="id">literal-paths</dc:identifier>'
+ '<dc:title>Literal paths</dc:title><dc:language>en</dc:language>'
+ '<meta property="dcterms:modified">2026-01-01T00:00:00Z</meta>'
+ '</metadata><manifest>'
+ f'<item id="chapter" href="{quote(chapter_path)}"'
+ ' media-type="application/xhtml+xml"/>'
+ f'<item id="expected" href="{quote(image_path)}" media-type="image/png"/>'
+ f'<item id="decoy" href="{quote(decoy_path)}" media-type="image/png"/>'
+ '<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml"'
+ ' properties="nav"/></manifest><spine><itemref idref="chapter"/>'
+ '</spine></package>'
+ )
+ chapter = (
+ '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter</title>'
+ '</head><body><h1>Chapter</h1>'
+ f'<img alt="expected" src="{escape(image_src, quote=True)}"/>'
+ '</body></html>'
+ )
+ nav = (
+ '<html xmlns="http://www.w3.org/1999/xhtml"'
+ ' xmlns:epub="http://www.idpf.org/2007/ops"><head><title>Contents</title>'
+ '</head><body><nav epub:type="toc"><ol><li>'
+ f'<a href="{quote(chapter_path)}">Chapter</a>'
+ '</li></ol></nav></body></html>'
+ )
+ expected = BytesIO()
+ decoy = BytesIO()
+ Image.new("RGB", (1, 1), "red").save(expected, format="PNG")
+ Image.new("RGB", (1, 1), "blue").save(decoy, format="PNG")
+ output = BytesIO()
+ with zipfile.ZipFile(output, "w") as archive:
+ archive.writestr("mimetype", "application/epub+zip")
+ archive.writestr("META-INF/container.xml", container)
+ archive.writestr("EPUB/package.opf", package)
+ archive.writestr(f"EPUB/{chapter_path}", chapter)
+ archive.writestr(f"EPUB/{image_path}", expected.getvalue())
+ archive.writestr(f"EPUB/{decoy_path}", decoy.getvalue())
+ archive.writestr("EPUB/nav.xhtml", nav)
+ return output.getvalue(), expected.getvalue()
+
+
class EPUBParserTest(unittest.TestCase):
+ def assert_literal_path_image_bytes(self, *, use_fallback: bool):
+ cases = (
+ ("Text#1/chapter.xhtml", "../images/pic.png",
+ "images/pic.png", "Text#1/cover.png"),
+ ("Text?1/chapter.xhtml", "../images/pic.png",
+ "images/pic.png", "Text?1/cover.png"),
+ ("Text%231/chapter.xhtml", "pic.png",
+ "Text%231/pic.png", "Text#1/pic.png"),
+ ("Text/chapter.xhtml", "../images/pic%231.png?version=1#image",
+ "images/pic#1.png", "images/pic#2.png"),
+ ("Text/chapter.xhtml", "../images/pic%3F1.png?version=1#image",
+ "images/pic?1.png", "images/pic?2.png"),
+ ("Text/chapter.xhtml", "../images/pic%25231.png",
+ "images/pic%231.png", "images/pic#1.png"),
+ ("Text/chapter.xhtml", "../images/pic%231.png",
+ "images/pic#1.png", "images/pic%231.png"),
+ # Verbatim percent-looking names must beat decoded basename aliases.
+ ("chapter.xhtml", "images/my%20pic.png",
+ "images/my%20pic.png", "my pic.png"),
+ ("Text/chapter.xhtml", "../images/my%20pic.png?version=1#image",
+ "images/my%20pic.png", "my pic.png"),
+ # A literal chapter-relative path also beats a decoded root path.
+ ("Text/chapter.xhtml", "images/my%20pic.png",
+ "Text/images/my%20pic.png", "images/my pic.png"),
+ # When both exact paths exist, URI decoding still takes precedence.
+ ("Text/chapter.xhtml", "../images/my%20pic.png",
+ "images/my pic.png", "images/my%20pic.png"),
+ # Normalize encoded separators before joining to the chapter path.
+ ("Text/chapter.xhtml", "%5Cimages/pic.png",
+ "images/pic.png", "Text/images/pic.png"),
+ )
+ for chapter_path, image_src, image_path, decoy_path in cases:
+ with self.subTest(chapter_path=chapter_path, image_src=image_src):
+ content, expected = _epub_with_literal_path_characters(
+ chapter_path, image_src, image_path, decoy_path
+ )
+ parser = EPUBParser(file_name="literal-paths.epub", file_type="epub")
+ if use_fallback:
+ with patch(
+ "docreader.parser.epub_parser.epub.read_epub",
+ side_effect=ValueError("exercise ZIP fallback"),
+ ):
+ document = parser.parse(content)
+ else:
+ with patch.object(parser, "_parse_epub_fallback") as fallback:
+ document = parser.parse(content)
+ fallback.assert_not_called()
+ self.assertEqual(len(document.images), 2)
+ image_ref = next(
+ ref for ref, encoded in document.images.items()
+ if base64.b64decode(encoded) == expected
+ )
+ self.assertIn(f"![expected]({image_ref})", document.content)
+
+ def test_literal_path_characters_are_preserved(self):
+ self.assert_literal_path_image_bytes(use_fallback=False)
+
+ def test_zip_fallback_preserves_literal_path_characters(self):
+ self.assert_literal_path_image_bytes(use_fallback=True)
+
+ def assert_chapter_image_bytes(self, document, image_data):
+ self.assertEqual(len(document.images), 3)
+ for directory, expected_data in image_data.items():
+ image_ref = next(
+ ref
+ for ref, encoded in document.images.items()
+ if base64.b64decode(encoded) == expected_data
+ )
+ self.assertIn(f"![{directory}]({image_ref})", document.content)
+
+ def test_chapter_relative_images_win_over_colliding_aliases(self):
+ for image_src in (
+ "pic.png",
+ "../{directory}/pic.png",
+ "./pic%2Epng?version=1#image",
+ ):
+ with self.subTest(image_src=image_src):
+ content, image_data = _epub_with_colliding_image_names(image_src)
+ parser = EPUBParser(file_name="colliding.epub", file_type="epub")
+ with patch.object(parser, "_parse_epub_fallback") as fallback:
+ document = parser.parse(content)
+ fallback.assert_not_called()
+ self.assert_chapter_image_bytes(document, image_data)
+
+ def test_zip_fallback_resolves_colliding_chapter_relative_images(self):
+ for root_image_first in (False, True):
+ with self.subTest(root_image_first=root_image_first):
+ content, image_data = _epub_with_colliding_image_names(
+ "pic.png", root_image_first=root_image_first
+ )
+ with patch(
+ "docreader.parser.epub_parser.epub.read_epub",
+ side_effect=ValueError("exercise ZIP fallback"),
+ ):
+ document = EPUBParser(
+ file_name="colliding.epub", file_type="epub"
+ ).parse(content)
+ self.assert_chapter_image_bytes(document, image_data)
+
+ def test_root_image_alias_is_not_overwritten_by_nested_image_basenames(self):
+ content, image_data = _epub_with_colliding_image_names(
+ "pic.png", root_image_first=True
+ )
+ parser = EPUBParser(file_name="colliding.epub", file_type="epub")
+ with patch.object(parser, "_parse_epub_fallback") as fallback:
+ document = parser.parse(content)
+ fallback.assert_not_called()
+ self.assert_chapter_image_bytes(document, image_data)
+
def test_parse_minimal_epub(self):
document = EPUBParser(
file_name="tiny.epub", file_type="epub"