docling-parse 7.17.0__tar.gz → 7.18.0__tar.gz

{docling_parse-7.17.0 → docling_parse-7.18.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [v7.18.0](https://github.com/docling-project/docling-parse/releases/tag/v7.18.0) - 2026-09-08
+
+### Feature
+
+* Resolve-bookmarks-using-page-aware-PDF-outlines ([#341](https://github.com/docling-project/docling-parse/issues/341)) ([`e6b04ca`](https://github.com/docling-project/docling-parse/commit/e6b04cab04f3d29ffd86ceb75b0d2a5548f96c97))
+
 ## [v7.17.0](https://github.com/docling-project/docling-parse/releases/tag/v7.17.0) - 2026-09-02
 
 ### Feature

{docling_parse-7.17.0 → docling_parse-7.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.17.0
+Version: 7.18.0
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pillow<13.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: docling-core<3.0.0,>=2.85.0
+Requires-Dist: docling-core<3.0.0,>=2.95.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"
 Dynamic: license-file
 

{docling_parse-7.17.0 → docling_parse-7.18.0}/app/pybind_parse.cpp

@@ -1102,6 +1102,19 @@ PYBIND11_MODULE(pdf_parsers, m) {
 
     Returns:
         int: Number of pages that will be emitted by the threaded parser.)")
+    .def("get_annotations",
+         [](docling::docling_threaded_parser& self, const std::string& key) -> nlohmann::json {
+           return self.get_annotations(key);
+         },
+         pybind11::arg("key"),
+         R"(
+    Retrieve annotations for a loaded document and return them as JSON.
+
+    Parameters:
+        key (str): The unique key identifying the document.
+
+    Returns:
+        dict: A JSON object containing the annotations for the document.)")
     .def("unload_document",
          [](docling::docling_threaded_parser& self, const std::string& key) -> bool {
            return self.unload_document(key);
@@ -1313,6 +1326,11 @@ PYBIND11_MODULE(pdf_parsers, m) {
            return self.scheduled_number_of_pages(key);
          },
          pybind11::arg("key"))
+    .def("get_annotations",
+         [](docling::docling_threaded_renderer& self, const std::string& key) -> nlohmann::json {
+           return self.get_annotations(key);
+         },
+         pybind11::arg("key"))
     .def("unload_document",
          [](docling::docling_threaded_renderer& self, const std::string& key) -> bool {
            return self.unload_document(key);

{docling_parse-7.17.0 → docling_parse-7.18.0}/docling_parse/pdf_parser.py

@@ -77,24 +77,6 @@ from docling_parse.pdf_parsers import (  # type: ignore[import]
 _log = logging.getLogger(__name__)
 
 
-class PdfTocEntry(BaseModel):
-    """PDF table of contents entry (recursive structure).
-
-    Attributes:
-        title: The text of the TOC entry
-        level: Nesting level in the hierarchy (0 for top level)
-        page: Page number this entry points to (optional)
-        children: Nested TOC entries (optional)
-    """
-
-    model_config = ConfigDict(extra="allow")
-
-    title: str
-    level: int | None = None
-    page: int | None = None
-    children: List["PdfTocEntry"] | None = None
-
-
 class PdfAnnotations(BaseModel):
     """PDF document annotations including form fields, language, metadata, and table of contents.
 
@@ -102,7 +84,8 @@ class PdfAnnotations(BaseModel):
         form: AcroForm data containing interactive form fields (raw dict structure). None if no forms present.
         language: Document language code (e.g., 'en-US', 'fr-FR'). None if not specified.
         meta_xml: XMP metadata as XML string. None if no metadata present.
-        table_of_contents: Document outline/bookmark structure as list of entries. None if no TOC.
+        table_of_contents: Document outline (bookmarks) as a tree under a synthetic root
+            entry. None if no outline present.
     """
 
     model_config = ConfigDict(validate_assignment=True, extra="allow")
@@ -110,7 +93,7 @@ class PdfAnnotations(BaseModel):
     form: Dict[str, Any] | None = None
     language: str | None = None
     meta_xml: str | None = None
-    table_of_contents: List[PdfTocEntry] | None = None
+    table_of_contents: PdfTableOfContents | None = None
 
 
 class Timings(BaseModel):
@@ -692,6 +675,42 @@ def _page_size_from_decoder(
     return abs(bbox[2] - bbox[0]), abs(bbox[3] - bbox[1])
 
 
+def _to_table_of_contents(toc: List[Dict[str, Any]]) -> List[PdfTableOfContents]:
+    """Convert raw outline entries into PdfTableOfContents entries.
+
+    The `destination` sub-dictionary is handed to pydantic as it comes: its keys are
+    the PdfDestination fields, so restating them here would only add a second place
+    to keep in sync. Recursion is safe: the C++ side caps the outline depth.
+    """
+    return [
+        PdfTableOfContents(
+            text=item.get("title", ""),
+            destination=item.get("destination"),
+            children=_to_table_of_contents(item.get("children") or []),
+        )
+        for item in toc
+    ]
+
+
+def _to_annotations(annots: Dict[str, Any]) -> PdfAnnotations:
+    """Convert the raw annotations dictionary into a PdfAnnotations.
+
+    Shared by the single-threaded and the threaded parser so the two cannot drift.
+    """
+    toc = annots.get("table_of_contents")
+
+    return PdfAnnotations(
+        form=annots.get("form"),
+        language=annots.get("language"),
+        meta_xml=annots.get("meta_xml"),
+        table_of_contents=(
+            PdfTableOfContents(text="<root>", children=_to_table_of_contents(toc))
+            if toc
+            else None
+        ),
+    )
+
+
 class PdfDocument:
     def __init__(
         self,
@@ -711,7 +730,6 @@ class PdfDocument:
         ] = {}
         # Per page: the content config the cached page-decoder satisfies.
         self._decoded_content_configs: Dict[int, ContentConfig] = {}
-        self._toc: PdfTableOfContents | None = None
         self._meta: PdfMetaData | None = None
         self._annotations: PdfAnnotations | None = None
 
@@ -847,21 +865,18 @@ class PdfDocument:
             raise RuntimeError("This document is not loaded.")
 
     def get_table_of_contents(self) -> PdfTableOfContents | None:
-        if self.is_loaded():
-            toc = self._parser.get_table_of_contents(key=self._key)
+        """Get the document outline (bookmarks) as a tree under a synthetic root entry.
 
-            if toc is None:
-                return self._toc
+        Each entry carries its `destination`, so a bookmark resolves to a page and,
+        where the PDF specifies one, to a position on that page.
 
-            if self._toc is not None:
-                return self._toc
-
-            self._toc = PdfTableOfContents(text="<root>")
-            self._toc.children = self._to_table_of_contents(toc=toc)
+        Returns:
+            Optional[PdfTableOfContents]: The root entry, or None if the document has
+                no outline.
+        """
+        annotations = self.get_annotations()
 
-            return self._toc
-        else:
-            raise RuntimeError("This document is not loaded.")
+        return annotations.table_of_contents if annotations is not None else None
 
     def iterate_pages(
         self,
@@ -874,31 +889,6 @@ class PdfDocument:
                 self.get_page(page_no + 1, content_config=content_config),
             )
 
-    def _to_table_of_contents(self, toc: dict) -> List[PdfTableOfContents]:
-
-        result = []
-        for item in toc:
-            subtoc = PdfTableOfContents(text=item["title"])
-            if "children" in item:
-                subtoc.children = self._to_table_of_contents(toc=item["children"])
-            result.append(subtoc)
-
-        return result
-
-    def _to_pdf_toc_entry(self, toc_list: List[Dict]) -> List[PdfTocEntry]:
-        """Convert raw TOC dict list to PdfTocEntry objects."""
-        result = []
-        for item in toc_list:
-            entry = PdfTocEntry(
-                title=item.get("title", ""),
-                level=item.get("level"),
-                page=item.get("page"),
-            )
-            if item.get("children"):
-                entry.children = self._to_pdf_toc_entry(item["children"])
-            result.append(entry)
-        return result
-
     def get_annotations(self) -> PdfAnnotations | None:
         """Get document annotations including form fields, language, metadata, and TOC.
 
@@ -915,17 +905,7 @@ class PdfDocument:
             if annots_dict is None:
                 return self._annotations
 
-            # Convert table_of_contents list of dicts to PdfTocEntry objects if present
-            toc_entries = None
-            if annots_dict.get("table_of_contents"):
-                toc_entries = self._to_pdf_toc_entry(annots_dict["table_of_contents"])
-
-            self._annotations = PdfAnnotations(
-                form=annots_dict.get("form"),
-                language=annots_dict.get("language"),
-                meta_xml=annots_dict.get("meta_xml"),
-                table_of_contents=toc_entries,
-            )
+            self._annotations = _to_annotations(annots_dict)
 
             return self._annotations
         else:
@@ -1624,6 +1604,24 @@ class DoclingThreadedPdfParser:
             raise ValueError(f"Document key not loaded: {doc_key}")
         return self._scheduled_page_counts[doc_key]
 
+    def get_annotations(self, doc_key: str) -> PdfAnnotations | None:
+        """Get the annotations of a loaded document.
+
+        The annotations are structure-only: reading them decodes no page, so the
+        outline of a document can be read without waiting for, or interfering with,
+        the threaded page decoding.
+
+        Returns:
+            Optional[PdfAnnotations]: Annotations object with form, language, meta_xml
+                and table_of_contents fields. None if the document has no annotations.
+        """
+        if doc_key not in self._page_counts:
+            raise ValueError(f"Document key not loaded: {doc_key}")
+
+        annots = self._parser.get_annotations(key=doc_key)
+
+        return _to_annotations(annots) if annots is not None else None
+
     def unload(self, doc_key: str) -> bool:
         """Unload one document after threaded processing has completed."""
         unloaded = self._parser.unload_document(doc_key)

{docling_parse-7.17.0 → docling_parse-7.18.0}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.17.0
+Version: 7.18.0
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pillow<13.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: docling-core<3.0.0,>=2.85.0
+Requires-Dist: docling-core<3.0.0,>=2.95.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"
 Dynamic: license-file
 

{docling_parse-7.17.0 → docling_parse-7.18.0}/docling_parse.egg-info/SOURCES.txt

@@ -553,6 +553,7 @@ src/parse/pdf_states/text.h
 src/parse/qpdf/annots.h
 src/parse/qpdf/logger.h
 src/parse/qpdf/object.h
+src/parse/qpdf/outline.h
 src/parse/qpdf/qpdf_compat.h
 src/parse/qpdf/stream_decoder.h
 src/parse/qpdf/stream_filters.h
@@ -674,6 +675,7 @@ tests/conftest.py
 tests/constants.py
 tests/data_utils.py
 tests/groundtruth_io.py
+tests/outline_fixtures.py
 tests/pdf_builder.py
 tests/regression_page_selection.py
 tests/rendering_regression.py

{docling_parse-7.17.0 → docling_parse-7.18.0}/docling_parse.egg-info/requires.txt

@@ -1,6 +1,6 @@
 pillow<13.0.0,>=10.0.0
 pydantic>=2.0.0
-docling-core<3.0.0,>=2.85.0
+docling-core<3.0.0,>=2.95.0
 
 [:sys_platform == "win32"]
 pywin32>=305

{docling_parse-7.17.0 → docling_parse-7.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-parse"
-version = "7.17.0"
+version = "7.18.0"
 description = "Simple package to extract text with coordinates from programmatic PDFs"
 license = "MIT"
 keywords = ["docling", "pdf", "parser"]
@@ -31,7 +31,7 @@ requires-python = ">=3.10"
 dependencies = [
     "pillow>=10.0.0,<13.0.0",
     "pydantic>=2.0.0",
-    "docling-core>=2.85.0,<3.0.0",
+    "docling-core>=2.95.0,<3.0.0",
     "pywin32>=305; sys_platform == 'win32'",
 ]
 [project.urls]

{docling_parse-7.17.0 → docling_parse-7.18.0}/src/parse/enums.h

@@ -383,6 +383,83 @@ namespace pdflib
     return BLEND_MODE_UNKNOWN;
   }
 
+  // Syntax of an explicit destination array (12.3.2.2, table 151). The name that
+  // follows the page in `[page /Kind args]` selects how the viewer positions the
+  // page, and thereby which of the args (if any) is a vertical position.
+  enum pdf_destination_kind {
+    DESTINATION_XYZ,     // [page /XYZ left top zoom]
+    DESTINATION_FIT,     // [page /Fit]
+    DESTINATION_FIT_H,   // [page /FitH top]
+    DESTINATION_FIT_V,   // [page /FitV left]
+    DESTINATION_FIT_R,   // [page /FitR left bottom right top]
+    DESTINATION_FIT_B,   // [page /FitB]
+    DESTINATION_FIT_BH,  // [page /FitBH top]
+    DESTINATION_FIT_BV,  // [page /FitBV left]
+
+    DESTINATION_UNKNOWN,
+  };
+
+  inline std::string to_string(pdf_destination_kind kind)
+  {
+    switch(kind)
+      {
+      case DESTINATION_XYZ:    { return "XYZ"; }
+      case DESTINATION_FIT:    { return "FIT"; }
+      case DESTINATION_FIT_H:  { return "FIT_H"; }
+      case DESTINATION_FIT_V:  { return "FIT_V"; }
+      case DESTINATION_FIT_R:  { return "FIT_R"; }
+      case DESTINATION_FIT_B:  { return "FIT_B"; }
+      case DESTINATION_FIT_BH: { return "FIT_BH"; }
+      case DESTINATION_FIT_BV: { return "FIT_BV"; }
+
+      default: { return "UNKNOWN"; }
+      }
+  }
+
+  inline pdf_destination_kind to_destination_kind(const std::string& name)
+  {
+    if(name=="/XYZ")   { return DESTINATION_XYZ; }
+    if(name=="/Fit")   { return DESTINATION_FIT; }
+    if(name=="/FitH")  { return DESTINATION_FIT_H; }
+    if(name=="/FitV")  { return DESTINATION_FIT_V; }
+    if(name=="/FitR")  { return DESTINATION_FIT_R; }
+    if(name=="/FitB")  { return DESTINATION_FIT_B; }
+    if(name=="/FitBH") { return DESTINATION_FIT_BH; }
+    if(name=="/FitBV") { return DESTINATION_FIT_BV; }
+
+    return DESTINATION_UNKNOWN;
+  }
+
+  // Index of the vertical (top) coordinate within the args of a destination
+  // array, or -1 for the kinds that carry no vertical position.
+  inline int destination_top_index(pdf_destination_kind kind)
+  {
+    switch(kind)
+      {
+      case DESTINATION_XYZ:    { return 1; }  // left top zoom
+      case DESTINATION_FIT_H:  { return 0; }  // top
+      case DESTINATION_FIT_BH: { return 0; }  // top
+      case DESTINATION_FIT_R:  { return 3; }  // left bottom right top
+
+      default: { return -1; }
+      }
+  }
+
+  // Index of the horizontal (left) coordinate within the args of a destination
+  // array, or -1 for the kinds that carry no horizontal position.
+  inline int destination_left_index(pdf_destination_kind kind)
+  {
+    switch(kind)
+      {
+      case DESTINATION_XYZ:    { return 0; }  // left top zoom
+      case DESTINATION_FIT_V:  { return 0; }  // left
+      case DESTINATION_FIT_BV: { return 0; }  // left
+      case DESTINATION_FIT_R:  { return 0; }  // left bottom right top
+
+      default: { return -1; }
+      }
+  }
+
 }
 
 #endif

{docling_parse-7.17.0 → docling_parse-7.18.0}/src/parse/pdf_decoders/document.h

@@ -164,6 +164,10 @@ namespace pdflib
         utils::timer annots_timer;
         json_annots = extract_document_annotations_in_json(qpdf_document, qpdf_root);
 
+        // composed here rather than inside the extractor above: resolving the
+        // outline's destinations needs the pages and their geometry
+        json_annots["table_of_contents"] = pdf_outline(qpdf_document, qpdf_pages).get();
+
         double annots_elapsed = annots_timer.get_time();
         timings.add_timing(pdf_timings::KEY_EXTRACT_DOC_ANNOTATIONS, annots_elapsed);
       }

{docling_parse-7.17.0 → docling_parse-7.18.0}/src/parse/qpdf/annots.h

@@ -169,163 +169,6 @@ namespace pdflib
     return result;
   }
   
-  /*** Table of Contents ***/
-
-  nlohmann::json extract_toc_entry_in_json(QPDF& pdf_obj, QPDFObjectHandle& node, int level,
-                                           std::unordered_set<std::string>& visited)
-  {
-    LOG_S(INFO) << __FUNCTION__;
-    
-    nlohmann::json toc_entry = nlohmann::json::object({});
-
-    // securing we dont crash ...
-    if(level>=16)
-      {
-	return toc_entry;
-      }
-
-    //for(auto key : node.getKeys())
-    //{
-    //LOG_S(INFO) << " -> key: " << key;
-    //}
-    
-    // Extract title
-    if(node.hasKey("/Title"))
-      {
-	auto title = node.getKey("/Title");
-	
-	if(title.isString())
-	  {
-	    std::string val = title.getUTF8Value();
-
-            if(utf8::is_valid(val.begin(), val.end()))
-              {
-                toc_entry["title"] = val;
-		LOG_S(INFO) << "level: " << level << "\t" << val;
-              }
-            else
-              {
-                utf8::replace_invalid(val.begin(), val.end(),
-                                      std::back_inserter(val));
-                toc_entry["title"] = val;
-              }	    
-	  }
-	else
-	  {
-	    LOG_S(WARNING) << "title is not a string!";
-	    toc_entry["title"] = "<unknown>";
-	  }
-	
-        toc_entry["level"] = level;
-      }
-    
-    // Extract title
-    if(node.hasKey("/A"))
-      {
-        //toc_entry["link"] = to_json(node.getKey("/A"), {}, 0, 8);
-      }
-    
-    // Extract destination
-    if(node.hasKey("/Dest"))
-      {
-	//LOG_S(INFO) << "found a destination!";
-	
-        // Depending on the type of destination, extract its value
-	//auto dest = node.getKey("/Dest");
-        //toc_entry["destination"] = to_json(dest, {}, 0, 8);
-      }
-    else
-      {
-        //toc_entry["destination"] = "No destination";
-      }
-
-    // Extract children
-    if (node.hasKey("/First"))
-      {
-        QPDFObjectHandle first = node.getKey("/First");
-
-        while(first.isDictionary())
-          {
-            // Check for circular reference
-            std::string obj_ref = first.unparse();
-            if (visited.count(obj_ref))
-              {
-                LOG_S(WARNING) << "Circular TOC reference detected, skipping: " << obj_ref;
-                break;
-              }
-            visited.insert(obj_ref);
-
-            auto child = extract_toc_entry_in_json(pdf_obj, first, level+1, visited);
-            toc_entry["children"].push_back(child);
-
-            if(first.hasKey("/Next"))
-              {
-                first = first.getKey("/Next");
-              }
-            else
-              {
-                break;
-              }
-          }
-      }
-
-    return toc_entry;
-  }
-  
-  nlohmann::json extract_toc_in_json(QPDF& pdf_obj, QPDFObjectHandle& root)
-  {
-    LOG_S(INFO) << __FUNCTION__;
-    
-    nlohmann::json toc = nlohmann::json::value_t::null;
-
-    if(root.hasKey("/Outlines"))
-      {
-	LOG_S(INFO) << "/Outlines (=table-of-contents) detected!";
-	
-        QPDFObjectHandle outlines = root.getKey("/Outlines");
-
-        if(outlines.hasKey("/First"))
-          {
-            QPDFObjectHandle first = outlines.getKey("/First");
-
-            toc = nlohmann::json::array({});
-
-            // Track visited nodes to prevent infinite loops
-            std::unordered_set<std::string> visited;
-
-            while(first.isDictionary())
-              {
-                // Check for circular reference
-                std::string obj_ref = first.unparse();
-                if (visited.count(obj_ref))
-                  {
-                    LOG_S(WARNING) << "Circular TOC reference detected at top level, skipping: " << obj_ref;
-                    break;
-                  }
-                visited.insert(obj_ref);
-
-		int level=0;
-                toc.push_back(extract_toc_entry_in_json(pdf_obj, first, level, visited));
-
-                if(first.hasKey("/Next"))
-                  {
-                    first = first.getKey("/Next");
-                  }
-                else
-                  {
-                    break;
-                  }
-              }
-          }
-      }
-    else
-      {
-        LOG_S(INFO) << "no /Outlines (=table-of-contents) detected ...";
-      }
-
-    return toc;
-  }
-  
   nlohmann::json extract_document_annotations_in_json(QPDF& pdf_obj,
 						      QPDFObjectHandle& root)
   {
@@ -339,8 +182,10 @@ namespace pdflib
 
     annots["language"] = extract_language_in_json(pdf_obj, root);
 
-    annots["table_of_contents"] = extract_toc_in_json(pdf_obj, root);
-    
+    // The table-of-contents is composed by pdf_decoder<DOCUMENT>, not here: it
+    // resolves destinations against the page geometry, and pdf_outline therefore
+    // depends on page_item<PAGE_DIMENSION>, which is declared after this header.
+
     LOG_S(INFO) << "annotations: " << annots.dump(2);
     
     return annots;