Skip to content

fix(epub): resolve single-quoted and percent-escaped image sources - #4602

Merged
PeterStaar-IBM merged 2 commits into
docling-project:mainfrom
CyberRik:fix/epub-image-src
Oct 7, 2026
Merged

PeterStaar-IBM merged 2 commits into
docling-project:mainfrom
CyberRik:fix/epub-image-src

Conversation

@CyberRik

@CyberRik CyberRik commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

When fetch_images=True, the EPUB backend rewrites each image src to a path relative to the extraction directory. Two kinds of src were missed:

  • Single quotes. The pattern only matched src="...". A src='../Images/map.png' stays relative to the merged document at the archive root, resolves outside the extraction directory, and the conversion fails with Path traversal blocked.
  • Percent-escapes. A src is a URL, while the archive stores the literal file name. src="../Images/cover%20art.png" points to cover%20art.png, which does not exist, so the image is lost. Manifest hrefs are already decoded the same way (fix(epub): decode percent-escaped manifest hrefs #4199).

Changes in _fix_image_paths:

  • match src in either quote style;
  • decode percent-escapes with unquote;
  • join and normalize with posixpath, as archive paths are POSIX paths. This also avoids backslashes in the rewritten src on Windows.

The new test builds an EPUB with both cases and checks that both pictures carry image data. It fails on main.

Checklist:

  • Documentation has been updated, if necessary.
  • Examples have been added, if necessary.
  • Tests have been added, if necessary.

@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

✅ DCO Check Passed

Thanks @CyberRik, all your commits are properly signed off. 🎉

@mergify

mergify Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

  • title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

@ceberam ceberam added bug Something isn't working xml issue related to supported schema-specific XML formats labels Oct 6, 2026
@codecov

codecov Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@ceberam ceberam left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @CyberRik , the fix is correct, minimal, and well-tested.
Please, check a couple of minor suggestions.

Comment thread docling/backend/epub_backend.py Resolved
Comment thread docling/backend/epub_backend.py Resolved

@dolfim-ibm dolfim-ibm left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. Two follow-ups:

  • strip the query/fragment before unquote (decode only urlsplit(src).path), so map.png?v=1 resolves and an escaped %3F is not taken as a query;
  • a path that fails the base-directory check raises ValueError and fails the whole document. Such a path can now also arrive through %2e%2e%2f or %2F…. This is shared with main for plain ../ paths; dropping only that picture, with a warning, would be friendlier.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working xml issue related to supported schema-specific XML formats

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants