fix: Force Unix style path for image URI fix

[clach04]

Ensure image URI uses Unix style path for compatibility.

Resolves docling-project/docling#3617

[github-actions]

✅ DCO Check Passed

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

[mergify]

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)(?:\(.+\))?(!)?:

[cau-git]

@clach04 Thanks for this contribution. Can you please ensure the CI tests pass, by running
uv run pre-commit run --all-files
?

[clach04]

Can you please ensure the CI tests pass, by running
uv run pre-commit run --all-files

Thank you @cau-git for this hint 🙏

Good news / bad news. This helped id formatting issue, which is resolved :-)

bad news: Out of box, the headrev MyPytests failed (related to missing huggingface_hub module). I'm not likely to have time to dig into this but it looks like some dependency rules are quite 100% with the toml/prek config. But it worked well enough to catch the formatting issue :-)

Is it possible to have the mergebot make the recommendation you did (by hand) for future PR reviews? It's super useful for people like myself who are super new and do not know all the project best practices.

[ceberam]

@clach04 Thanks for supporting Docling and suggesting this PR.

Unfortunately, I don't think this is the right approach. The field uri of ImageRef class is typed as Union[AnyUrl, Path]. This PR changed the assignment to Path(...).as_posix() which returns a str, incompatible with the declared type. This is why the code checks fail.

An alternative approach could be to change the uri annotation to Union[AnyUrl, PurePosixPath] and add a pydantic field validator that converts any plain Path input into PurePosixPath. However, this change would not be backwards compatible and could impact existing client applications (e.g., isinstance(..., Path) breakage).

A safer choice is to keep Union[AnyUrl, Path] and fix the two serializer call sites (markdown, HTML), to call .as_posix() when rendering a Path uri, so the output always uses forward slashes, as proposed by #663

But in general .as_posix() would still have several limitations:

1. AnyUrl doesn't have it. The uri field is Union[AnyUrl, Path] and the REFERENCED mode branch does not pre-filter by type, so calling .as_posix() on an AnyUrl would raise AttributeError at runtime.
2. It doesn't percent-encode anything. as_posix() only replaces \ with / on Windows paths. It leaves spaces, parentheses, #, ? and all other Markdown-breaking characters completely untouched. A path like img (1).png or /home/a b/img.png would still break the Markdown inline link.
3. It doesn't handle absolute Windows paths or UNC shares specially. PureWindowsPath("C:/…").as_posix() returns "C:/…" and urlsplit would then parse C as a URL scheme. PureWindowsPath("//server/…").as_posix() returns "//server/…", which looks like a scheme-relative URL. Neither gets the file:// prefix it needs to be unambiguous.

I think that the PR #698 goes more in the right direction by defining a custom _escape_uri_path to address several edge cases. It should just need to be extended to the HTML serializer.

I would then suggest that we close this PR and we follow up with #698 to resolve docling-project/docling#3617