docling-core 2.85.0__tar.gz → 2.86.0__tar.gz

{docling_core-2.85.0 → docling_core-2.86.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.85.0
+Version: 2.86.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core/cli/view.py

@@ -69,8 +69,7 @@ def view(
         image_mode=ImageRefMode.EMBEDDED,
         split_page_view=split_view,
     )
-    with open(target_path, "w", encoding="utf-8") as f:
-        f.write(html_output)
+    target_path.write_text(html_output, encoding="utf-8")
     webbrowser.open(url=f"file://{target_path.absolute().resolve()}")
 
 

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core/types/doc/document.py

@@ -6,7 +6,6 @@ import hashlib
 import json
 import logging
 import mimetypes
-import os
 import re
 import sys
 import tempfile
@@ -15,7 +14,7 @@ import warnings
 from collections.abc import Iterable, Sequence
 from dataclasses import dataclass
 from enum import Enum
-from io import BytesIO
+from io import BytesIO, StringIO
 from pathlib import Path
 from typing import (
     Annotated,
@@ -69,6 +68,7 @@ from docling_core.types.doc.labels import (
 )
 from docling_core.types.doc.tokens import DocumentToken, TableToken
 from docling_core.types.doc.utils import (
+    is_remote_path,
     parse_otsl_table_content,
     relative_path,
     resolve_archive_path,
@@ -1074,22 +1074,23 @@ class DocumentOrigin(BaseModel):
     )
 
     _extra_mimetypes: typing.ClassVar[list[str]] = [
-        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-        "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
-        "application/vnd.openxmlformats-officedocument.presentationml.template",
-        "application/vnd.openxmlformats-officedocument.presentationml.slideshow",
+        "application/vnd.box.boxnote",
+        "application/vnd.oasis.opendocument.presentation",
+        "application/vnd.oasis.opendocument.spreadsheet",
+        "application/vnd.oasis.opendocument.text",
         "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/vnd.openxmlformats-officedocument.presentationml.slideshow",
+        "application/vnd.openxmlformats-officedocument.presentationml.template",
         "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-        "application/vnd.oasis.opendocument.text",
-        "application/vnd.oasis.opendocument.spreadsheet",
-        "application/vnd.oasis.opendocument.presentation",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
+        "audio/mp3",
+        "audio/wav",
+        "audio/x-wav",
         "text/asciidoc",
-        "text/markdown",
         "text/csv",
+        "text/markdown",
         "text/vtt",
-        "audio/x-wav",
-        "audio/wav",
-        "audio/mp3",
     ]
 
     @field_validator("binary_hash", mode="before")
@@ -6070,6 +6071,39 @@ class DoclingDocument(BaseModel):
 
         return result
 
+    @staticmethod
+    def _save_image_and_resolve_uri(
+        img: PILImage.Image,
+        loc_path: Path,
+        reference_path: Optional[Path],
+    ) -> Union[AnyUrl, Path]:
+        """Save *img* to *loc_path* and return the URI to store on the ImageRef.
+
+        Uses a BytesIO intermediate buffer so that the write is compatible with
+        UPath remote backends (PIL cannot write directly to non-local paths).
+        For remote paths the URI is returned as an absolute AnyUrl string; for
+        local paths it is returned relative to *reference_path* when available,
+        or as the absolute *loc_path* when *reference_path* is None.
+
+        Args:
+            img: The PIL image to save.
+            loc_path: Destination path (local or remote UPath).
+            reference_path: Base path used to compute a relative URI for local
+                storage. Pass ``None`` to store the absolute path instead.
+
+        Returns:
+            An AnyUrl for remote paths, or a Path (relative or absolute) for local paths.
+        """
+        buf = BytesIO()
+        img.save(buf, format="PNG")
+        loc_path.write_bytes(buf.getvalue())
+
+        if is_remote_path(loc_path) or is_remote_path(reference_path):
+            return AnyUrl(str(loc_path))
+        if reference_path is not None:
+            return relative_path(reference_path.resolve(), loc_path.resolve())
+        return loc_path
+
     def _with_pictures_refs(
         self,
         image_dir: Path,
@@ -6088,65 +6122,37 @@ class DoclingDocument(BaseModel):
         """
         result: DoclingDocument = copy.deepcopy(self)
 
-        img_count = 0
         image_dir.mkdir(parents=True, exist_ok=True)
 
-        if image_dir.is_dir():
-            for item, _ in result.iterate_items(page_no=page_no, with_groups=False):
-                if isinstance(item, PictureItem):
-                    img = item.get_image(doc=self)
-                    if img is not None:
-                        hexhash = PictureItem._image_to_hexhash(img)
-
-                        # loc_path = image_dir / f"image_{img_count:06}.png"
-                        if hexhash is not None:
-                            loc_path = image_dir / f"image_{img_count:06}_{hexhash}.png"
-
-                            img.save(loc_path)
-                            if reference_path is not None:
-                                obj_path = relative_path(
-                                    reference_path.resolve(),
-                                    loc_path.resolve(),
-                                )
-                            else:
-                                obj_path = loc_path
-
-                            if item.image is None:
-                                scale = img.size[0] / item.prov[0].bbox.width
-                                item.image = ImageRef.from_pil(image=img, dpi=round(72 * scale))
-                                item.image.uri = Path(obj_path)
-                            elif item.image is not None:
-                                item.image.uri = Path(obj_path)
-
-                        # if item.image._pil is not None:
-                        #    item.image._pil.close()
-
-                    img_count += 1
-
-            if include_page_images:
-                for p_no, page in result.pages.items():
-                    if page_no is not None and p_no != page_no:
-                        continue
-                    if page.image is None:
-                        continue
-                    img = page.image.pil_image
-                    if img is None:
-                        continue
+        img_count = 0
+        for item, _ in result.iterate_items(page_no=page_no, with_groups=False):
+            if isinstance(item, PictureItem):
+                img = item.get_image(doc=self)
+                if img is not None:
                     hexhash = PictureItem._image_to_hexhash(img)
-                    if hexhash is None:
-                        continue
-
-                    loc_path = image_dir / f"page_{p_no:06}_{hexhash}.png"
-                    img.save(loc_path)
-                    if reference_path is not None:
-                        obj_path = relative_path(
-                            reference_path.resolve(),
-                            loc_path.resolve(),
-                        )
-                    else:
-                        obj_path = loc_path
-
-                    page.image.uri = Path(obj_path)
+                    if hexhash is not None:
+                        loc_path = image_dir / f"image_{img_count:06}_{hexhash}.png"
+                        obj_path = self._save_image_and_resolve_uri(img, loc_path, reference_path)
+                        if item.image is None:
+                            scale = img.size[0] / item.prov[0].bbox.width
+                            item.image = ImageRef.from_pil(image=img, dpi=round(72 * scale))
+                        item.image.uri = obj_path  # type: ignore[assignment]
+                img_count += 1
+
+        if include_page_images:
+            for p_no, page in result.pages.items():
+                if page_no is not None and p_no != page_no:
+                    continue
+                if page.image is None:
+                    continue
+                img = page.image.pil_image
+                if img is None:
+                    continue
+                hexhash = PictureItem._image_to_hexhash(img)
+                if hexhash is None:
+                    continue
+                loc_path = image_dir / f"page_{p_no:06}_{hexhash}.png"
+                page.image.uri = self._save_image_and_resolve_uri(img, loc_path, reference_path)  # type: ignore[assignment]
 
         return result
 
@@ -6207,7 +6213,7 @@ class DoclingDocument(BaseModel):
         artifacts_dir, reference_path = self._get_output_paths(filename, artifacts_dir)
 
         if image_mode == ImageRefMode.REFERENCED:
-            os.makedirs(artifacts_dir, exist_ok=True)
+            artifacts_dir.mkdir(parents=True, exist_ok=True)
 
         new_doc = self._make_copy_with_refmode(
             artifacts_dir,
@@ -6218,8 +6224,7 @@ class DoclingDocument(BaseModel):
         )
 
         out = new_doc.export_to_dict(coord_precision=coord_precision, confid_precision=confid_precision)
-        with open(filename, "w", encoding="utf-8") as fw:
-            json.dump(out, fw, indent=indent)
+        filename.write_text(json.dumps(out, indent=indent), encoding="utf-8")
 
     @classmethod
     def load_from_json(cls, filename: Union[str, Path]) -> "DoclingDocument":
@@ -6234,8 +6239,7 @@ class DoclingDocument(BaseModel):
         """
         if isinstance(filename, str):
             filename = Path(filename)
-        with open(filename, encoding="utf-8") as f:
-            return cls.model_validate_json(f.read())
+        return cls.model_validate_json(filename.read_text(encoding="utf-8"))
 
     def save_as_yaml(
         self,
@@ -6252,7 +6256,7 @@ class DoclingDocument(BaseModel):
         artifacts_dir, reference_path = self._get_output_paths(filename, artifacts_dir)
 
         if image_mode == ImageRefMode.REFERENCED:
-            os.makedirs(artifacts_dir, exist_ok=True)
+            artifacts_dir.mkdir(parents=True, exist_ok=True)
 
         new_doc = self._make_copy_with_refmode(
             artifacts_dir,
@@ -6263,8 +6267,9 @@ class DoclingDocument(BaseModel):
         )
 
         out = new_doc.export_to_dict(coord_precision=coord_precision, confid_precision=confid_precision)
-        with open(filename, "w", encoding="utf-8") as fw:
-            yaml.dump(out, fw, default_flow_style=default_flow_style)
+        stream = StringIO()
+        yaml.dump(out, stream, default_flow_style=default_flow_style)
+        filename.write_text(stream.getvalue(), encoding="utf-8")
 
     @classmethod
     def load_from_yaml(cls, filename: Union[str, Path]) -> "DoclingDocument":
@@ -6278,8 +6283,7 @@ class DoclingDocument(BaseModel):
         """
         if isinstance(filename, str):
             filename = Path(filename)
-        with open(filename, encoding="utf-8") as f:
-            data = yaml.load(f, Loader=yaml.SafeLoader)
+        data = yaml.load(filename.read_text(encoding="utf-8"), Loader=yaml.SafeLoader)
         return DoclingDocument.model_validate(data)
 
     def export_to_dict(
@@ -6330,7 +6334,7 @@ class DoclingDocument(BaseModel):
         artifacts_dir, reference_path = self._get_output_paths(filename, artifacts_dir)
 
         if image_mode == ImageRefMode.REFERENCED:
-            os.makedirs(artifacts_dir, exist_ok=True)
+            artifacts_dir.mkdir(parents=True, exist_ok=True)
 
         new_doc = self._make_copy_with_refmode(artifacts_dir, image_mode, page_no, reference_path=reference_path)
 
@@ -6355,8 +6359,7 @@ class DoclingDocument(BaseModel):
             mark_meta=mark_meta,
         )
 
-        with open(filename, "w", encoding="utf-8") as fw:
-            fw.write(md_out)
+        filename.write_text(md_out, encoding="utf-8")
 
     def export_to_markdown(
         self,
@@ -6592,7 +6595,7 @@ class DoclingDocument(BaseModel):
         artifacts_dir, reference_path = self._get_output_paths(filename, artifacts_dir)
 
         if image_mode == ImageRefMode.REFERENCED:
-            os.makedirs(artifacts_dir, exist_ok=True)
+            artifacts_dir.mkdir(parents=True, exist_ok=True)
 
         new_doc = self._make_copy_with_refmode(artifacts_dir, image_mode, page_no, reference_path=reference_path)
 
@@ -6610,16 +6613,30 @@ class DoclingDocument(BaseModel):
             include_annotations=include_annotations,
         )
 
-        with open(filename, "w", encoding="utf-8") as fw:
-            fw.write(html_out)
+        filename.write_text(html_out, encoding="utf-8")
 
     def _get_output_paths(
-        self, filename: Union[str, Path], artifacts_dir: Optional[Path] = None
+        self,
+        filename: Path,
+        artifacts_dir: Optional[Path] = None,
     ) -> tuple[Path, Optional[Path]]:
-        if isinstance(filename, str):
-            filename = Path(filename)
+        """Resolve output and artifacts directory paths from the given filename.
+
+        Both ``Path`` and ``UPath`` objects are accepted since ``UPath`` is ``Path``-compatible for local paths, and remote ``UPath`` objects implement the same interface used here (``with_suffix``, ``with_name``,
+        ``is_absolute``, ``parent``, ``/``).
+
+        Args:
+            filename: Destination file path.
+            artifacts_dir: Optional explicit artifacts directory. When ``None``, a sibling
+                directory named ``<stem>_artifacts`` is derived from ``filename``.
+
+        Returns:
+            A tuple of ``(artifacts_dir, reference_path)`` where ``reference_path`` is
+            the parent of ``filename`` when ``artifacts_dir`` is relative, or ``None``
+            when it is absolute.
+        """
         if artifacts_dir is None:
-            # Remove the extension and add '_pictures'
+            # Remove the extension and add '_artifacts'
             artifacts_dir = filename.with_suffix("")
             artifacts_dir = artifacts_dir.with_name(artifacts_dir.name + "_artifacts")
         if artifacts_dir.is_absolute():
@@ -6767,8 +6784,7 @@ class DoclingDocument(BaseModel):
             omit_voice_end=omit_voice_end,
         )
 
-        with open(filename, "w", encoding="utf-8") as fw:
-            fw.write(vtt_out)
+        filename.write_text(vtt_out, encoding="utf-8")
 
     @staticmethod
     def load_from_doctags(  # noqa: C901
@@ -7379,8 +7395,7 @@ class DoclingDocument(BaseModel):
             minified=minified,
         )
 
-        with open(filename, "w", encoding="utf-8") as fw:
-            fw.write(out)
+        filename.write_text(out, encoding="utf-8")
 
     @deprecated("Use export_to_doctags() instead.")
     def export_to_document_tokens(self, *args, **kwargs):
@@ -7470,9 +7485,10 @@ class DoclingDocument(BaseModel):
         filename: Union[str, Path],
     ) -> None:
         """Save the document as DocLang."""
+        if isinstance(filename, str):
+            filename = Path(filename)
         out = self.export_to_doclang()
-        with open(filename, "w", encoding="utf-8") as fw:
-            fw.write(f"{out}\n")
+        filename.write_text(f"{out}\n", encoding="utf-8")
 
     def save_as_doclang_archive(
         self,

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core/types/doc/page.py

@@ -688,8 +688,7 @@ class SegmentedPdfPage(SegmentedPage):
         if isinstance(filename, str):
             filename = Path(filename)
         out = self.export_to_dict()
-        with open(filename, "w", encoding="utf-8") as fw:
-            json.dump(out, fw, indent=indent)
+        filename.write_text(json.dumps(out, indent=indent), encoding="utf-8")
 
     @classmethod
     def load_from_json(cls, filename: Union[str, Path]) -> "SegmentedPdfPage":
@@ -703,8 +702,7 @@ class SegmentedPdfPage(SegmentedPage):
         """
         if isinstance(filename, str):
             filename = Path(filename)
-        with open(filename, encoding="utf-8") as f:
-            return cls.model_validate_json(f.read())
+        return cls.model_validate_json(filename.read_text(encoding="utf-8"))
 
     def crop_text(self, cell_unit: TextCellUnit, bbox: BoundingBox, eps: float = 1.0) -> str:
         """Extract text from cells within the specified bounding box.
@@ -1390,8 +1388,7 @@ class PdfTableOfContents(BaseModel):
         if isinstance(filename, str):
             filename = Path(filename)
         out = self.export_to_dict()
-        with open(filename, "w", encoding="utf-8") as fw:
-            json.dump(out, fw, indent=indent)
+        filename.write_text(json.dumps(out, indent=indent), encoding="utf-8")
 
     @classmethod
     def load_from_json(cls, filename: Union[str, Path]) -> "PdfTableOfContents":
@@ -1405,8 +1402,7 @@ class PdfTableOfContents(BaseModel):
         """
         if isinstance(filename, str):
             filename = Path(filename)
-        with open(filename, encoding="utf-8") as f:
-            return cls.model_validate_json(f.read())
+        return cls.model_validate_json(filename.read_text(encoding="utf-8"))
 
 
 class ParsedPdfDocument(BaseModel):
@@ -1451,8 +1447,7 @@ class ParsedPdfDocument(BaseModel):
         if isinstance(filename, str):
             filename = Path(filename)
         out = self.export_to_dict()
-        with open(filename, "w", encoding="utf-8") as fw:
-            json.dump(out, fw, indent=indent)
+        filename.write_text(json.dumps(out, indent=indent), encoding="utf-8")
 
     @classmethod
     def load_from_json(cls, filename: Union[str, Path]) -> "ParsedPdfDocument":
@@ -1466,5 +1461,4 @@ class ParsedPdfDocument(BaseModel):
         """
         if isinstance(filename, str):
             filename = Path(filename)
-        with open(filename, encoding="utf-8") as f:
-            return cls.model_validate_json(f.read())
+        return cls.model_validate_json(filename.read_text(encoding="utf-8"))

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core/types/doc/utils.py

@@ -7,7 +7,7 @@ import shutil
 import unicodedata
 import zipfile
 from pathlib import Path
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Any
 
 from docling_core.types.doc.tokens import _LOC_PREFIX, DocumentToken, TableToken
 
@@ -15,21 +15,53 @@ if TYPE_CHECKING:
     from docling_core.types.doc.document import TableCell, TableData
 
 
-def relative_path(src: Path, target: Path) -> Path:
+def is_remote_path(p: Any) -> bool:
+    """Check if a path is a remote/cloud path (e.g., S3, GCS, Azure).
+
+    Works with UPath objects from universal-pathlib. Local paths return False.
+
+    Args:
+        p: A path object (Path, UPath, or similar)
+
+    Returns:
+        bool: True if the path is a remote/cloud path, False otherwise.
+    """
+    # UPath objects have a 'protocol' attribute
+    protocol = getattr(p, "protocol", None)
+    return protocol is not None and protocol not in ("file", "")
+
+
+def relative_path(src: str | Path, target: str | Path) -> Path:
     """Compute the relative path from `src` to `target`.
 
     Args:
-        src (str | Path): The source directory or file path (must be absolute).
-        target (str | Path): The target directory or file path (must be absolute).
+        src: The source directory or file path (must be absolute).
+        target: The target directory or file path (must be absolute).
 
     Returns:
         Path: The relative path from `src` to `target`.
 
     Raises:
         ValueError: If either `src` or `target` is not an absolute path.
+
+    Note:
+        For remote paths (UPath with non-file protocols), this function cannot
+            compute relative paths. Use is_remote_path() to check before calling.
     """
-    src = Path(src).resolve()
-    target = Path(target).resolve()
+    # Convert to Path only if string, otherwise keep original type
+    if isinstance(src, str):
+        src = Path(src)
+    if isinstance(target, str):
+        target = Path(target)
+
+    try:
+        src = src.resolve()
+        target = target.resolve()
+    except (AttributeError, NotImplementedError, OSError) as e:
+        raise ValueError(
+            f"Cannot resolve paths. This function only supports local filesystem paths. "
+            f"Remote paths should use absolute URIs. Error: {e}"
+        ) from e
 
     # Ensure both paths are absolute
     if not src.is_absolute():
@@ -93,7 +125,7 @@ def safe_extract_zip_archive(archive: Path, destination: Path) -> None:
                 shutil.copyfileobj(src, dst)
 
 
-def get_html_tag_with_text_direction(html_tag: str, text: str, attrs: Optional[dict] = None) -> str:
+def get_html_tag_with_text_direction(html_tag: str, text: str, attrs: dict | None = None) -> str:
     """Form the HTML element with tag, text, and optional dir attribute."""
     my_attrs = attrs or {}
     if (dir := my_attrs.get("dir")) is not None and dir != "ltr":

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core/utils/generate_docs.py

@@ -6,7 +6,6 @@ Example:
 
 import argparse
 import json
-import os
 from argparse import BooleanOptionalAction
 from pathlib import Path
 from shutil import rmtree
@@ -24,15 +23,16 @@ def _prepare_directory(folder: str, clean: bool = False) -> None:
         folder: The name of the directory.
         clean: Whether any existing content in the directory should be removed.
     """
-    if os.path.isdir(folder):
+    folder_path = Path(folder)
+    if folder_path.is_dir():
         if clean:
-            for path in Path(folder).glob("**/*"):
+            for path in folder_path.glob("**/*"):
                 if path.is_file():
                     path.unlink()
                 elif path.is_dir():
                     rmtree(path)
     else:
-        os.makedirs(folder, exist_ok=True)
+        folder_path.mkdir(parents=True, exist_ok=True)
 
 
 def generate_collection_jsonschema(folder: str):
@@ -41,10 +41,11 @@ def generate_collection_jsonschema(folder: str):
     Args:
         folder: The name of the directory.
     """
+    folder_path = Path(folder)
     for item in MODELS:
         json_schema = generate_json_schema(item)
-        with open(os.path.join(folder, f"{item}.json"), mode="w", encoding="utf8") as json_file:
-            json.dump(json_schema, json_file, ensure_ascii=False, indent=2)
+        output_file = folder_path / f"{item}.json"
+        output_file.write_text(json.dumps(json_schema, ensure_ascii=False, indent=2), encoding="utf-8")
 
 
 def main() -> None:

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.85.0
+Version: 2.86.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.85.0 → docling_core-2.86.0}/docling_core.egg-info/SOURCES.txt

@@ -110,6 +110,7 @@ test/test_serialization.py
 test/test_serialization_doclang.py
 test/test_serialization_doctag.py
 test/test_serialization_outline.py
+test/test_upath_support.py
 test/test_utils.py
 test/test_visualization.py
 test/test_webvtt.py

{docling_core-2.85.0 → docling_core-2.86.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-core"
-version = "2.85.0"  # DO NOT EDIT, updated automatically
+version = "2.86.0"  # DO NOT EDIT, updated automatically
 description = "A python library to define and validate data types in Docling."
 license = "MIT"
 license-files = ["LICENSE"]
@@ -116,6 +116,7 @@ dev = [
     "ruff>=0.14.11",
     "types-defusedxml (>=0.7.0.20250822, <0.8.0)",
     "opencv-python-headless>=4.6.0.66,<5.0.0.0",
+    "universal-pathlib>=0.3.10",
 ]
 constraints = [
     'pandas (>=2.1.4,<3.0.0); python_version < "3.11"',

docling_core-2.86.0/test/test_upath_support.py

@@ -0,0 +1,182 @@
+"""Tests for UPath/fsspec support for cloud storage compatibility."""
+
+import uuid
+from pathlib import Path
+
+import pytest
+from PIL import Image as PILImage
+from pydantic import AnyUrl
+from upath import UPath
+
+from docling_core.types.doc import DoclingDocument, ImageRefMode
+from docling_core.types.doc.base import Size
+from docling_core.types.doc.document import ImageRef
+from docling_core.types.doc.utils import is_remote_path, relative_path
+
+
+@pytest.fixture
+def memory_base():
+    """Provide a unique memory:// base path for each test."""
+    return UPath(f"memory://test-{uuid.uuid4()}")
+
+
+# =============================================================================
+# Tests for is_remote_path()
+# =============================================================================
+
+
+def test_is_remote_path():
+    """Test is_remote_path() function with various path types."""
+    # Local paths should return False
+    assert is_remote_path(Path("/local/path")) is False
+    assert is_remote_path(Path(".")) is False
+    assert is_remote_path(None) is False
+    assert is_remote_path("/some/path") is False
+    assert is_remote_path(object()) is False
+
+    # File protocol should return False
+    class MockFilePath:
+        protocol = "file"
+
+    class MockEmptyProtocol:
+        protocol = ""
+
+    assert is_remote_path(MockFilePath()) is False
+    assert is_remote_path(MockEmptyProtocol()) is False
+
+    # Cloud protocols should return True
+    for protocol in ["s3", "gcs", "az", "http", "https"]:
+
+        class MockCloudPath:
+            pass
+
+        MockCloudPath.protocol = protocol
+        assert is_remote_path(MockCloudPath()) is True
+
+    # Real UPath objects
+    assert is_remote_path(UPath("/tmp/test")) is False
+    assert is_remote_path(UPath("memory://test/path")) is True
+
+
+# =============================================================================
+# Tests for relative_path()
+# =============================================================================
+
+
+def test_relative_path():
+    """Test relative_path() function with various scenarios."""
+    # Basic relative path computation
+    assert relative_path(Path("/a/b"), Path("/a/b/c/d.txt")) == Path("c/d.txt")
+    assert relative_path("/a/b", "/a/b/c.txt") == Path("c.txt")
+
+    # Navigation with parent directories
+    # Sibling directory
+    assert relative_path(Path("/a/b/c"), Path("/a/b/d/e.txt")) == Path("../d/e.txt")
+    # Parent directory
+    assert relative_path(Path("/a/b/c/d"), Path("/a/b/e.txt")) == Path("../../e.txt")
+
+    # UPath with local file protocol
+    src = UPath("/home/user/docs")
+    target = UPath("/home/user/docs/images/img.png")
+    assert relative_path(src, target) == Path("images/img.png")
+
+
+# =============================================================================
+# UPath integration tests (memory filesystem)
+# =============================================================================
+
+
+def test_upath_integration(sample_doc, memory_base):
+    """Test UPath integration with various document operations."""
+    # JSON roundtrip
+    json_path = memory_base / "doc.json"
+    sample_doc.save_as_json(json_path)
+    assert json_path.exists()
+    loaded = DoclingDocument.load_from_json(json_path)
+    assert sample_doc.export_to_dict() == loaded.export_to_dict()
+
+    # YAML roundtrip
+    yaml_path = memory_base / "doc.yaml"
+    sample_doc.save_as_yaml(yaml_path)
+    assert yaml_path.exists()
+    loaded = DoclingDocument.load_from_yaml(yaml_path)
+    assert sample_doc.export_to_dict() == loaded.export_to_dict()
+
+    # Markdown export
+    md_path = memory_base / "doc.md"
+    sample_doc.save_as_markdown(md_path)
+    assert md_path.exists()
+    assert len(md_path.read_text()) > 0
+
+    # HTML export
+    html_path = memory_base / "doc.html"
+    sample_doc.save_as_html(html_path)
+    assert html_path.exists()
+    assert "<html" in html_path.read_text().lower()
+
+    # Doctags export
+    dt_path = memory_base / "doc.dt"
+    sample_doc.save_as_doctags(dt_path)
+    assert dt_path.exists()
+
+    # Referenced mode
+    json_ref_path = memory_base / "doc_ref.json"
+    artifacts_dir = memory_base / "artifacts"
+    sample_doc.save_as_json(json_ref_path, artifacts_dir=artifacts_dir, image_mode=ImageRefMode.REFERENCED)
+    assert json_ref_path.exists()
+
+    # Referenced images use string URI
+    image_dir = memory_base / "images"
+    doc_with_refs = sample_doc._with_pictures_refs(image_dir=image_dir, page_no=None)
+    for pic in doc_with_refs.pictures:
+        if pic.image is not None and pic.image.uri is not None:
+            # For remote storage, URI should not be a UPath (can't serialize)
+            assert not is_remote_path(pic.image.uri)
+
+    # Nested path support
+    nested_path = memory_base / "a" / "b" / "c" / "doc.json"
+    sample_doc.save_as_json(nested_path)
+    assert nested_path.exists()
+
+    # Empty document
+    empty_doc = DoclingDocument(name="Empty")
+    empty_path = memory_base / "empty.json"
+    empty_doc.save_as_json(empty_path)
+    loaded_empty = DoclingDocument.load_from_json(empty_path)
+    assert loaded_empty.name == "Empty"
+    assert len(loaded_empty.texts) == 0
+
+
+def test_upath_include_page_images(memory_base):
+    """Test _with_pictures_refs() with include_page_images=True on a remote path.
+
+    Ensures that page images are saved via BytesIO (UPath-compatible) and that
+    page.image.uri is stored as an AnyUrl, not a Path, for remote storage.
+    """
+    page_img = PILImage.new("RGB", (64, 64), "blue")
+    image_ref = ImageRef.from_pil(image=page_img, dpi=72)
+
+    doc = DoclingDocument(name="PageImageDoc")
+    doc.add_page(page_no=1, size=Size(width=64, height=64), image=image_ref)
+
+    image_dir = memory_base / "page_images"
+
+    result = doc._with_pictures_refs(
+        image_dir=image_dir,
+        page_no=None,
+        include_page_images=True,
+    )
+
+    # The image directory must have been created and contain the page image file
+    assert image_dir.exists()
+    saved_files = list(image_dir.iterdir())
+    assert len(saved_files) == 1, "Expected exactly one page image to be saved"
+    assert saved_files[0].name.endswith(".png")
+
+    # For a remote path the URI must be an AnyUrl, not a plain Path or UPath,
+    # so that the document remains JSON-serialisable
+    page = result.pages[1]
+    assert page.image is not None
+    assert page.image.uri is not None
+    assert isinstance(page.image.uri, AnyUrl), f"Expected AnyUrl for remote page image URI, got {type(page.image.uri)}"
+    assert not is_remote_path(page.image.uri)