docling 2.37.0__py3-none-any.whl → 2.38.1__py3-none-any.whl

docling/backend/md_backend.py

@@ -1,17 +1,16 @@
 import logging
 import re
 import warnings
+from copy import deepcopy
+from enum import Enum
 from io import BytesIO
 from pathlib import Path
-from typing import List, Optional, Set, Union
+from typing import List, Literal, Optional, Set, Union
 
 import marko
 import marko.element
-import marko.ext
-import marko.ext.gfm
 import marko.inline
 from docling_core.types.doc import (
-    DocItem,
     DocItemLabel,
     DoclingDocument,
     DocumentOrigin,
@@ -21,7 +20,10 @@ from docling_core.types.doc import (
     TableData,
     TextItem,
 )
+from docling_core.types.doc.document import Formatting, OrderedList, UnorderedList
 from marko import Markdown
+from pydantic import AnyUrl, BaseModel, Field, TypeAdapter
+from typing_extensions import Annotated
 
 from docling.backend.abstract_backend import DeclarativeDocumentBackend
 from docling.backend.html_backend import HTMLDocumentBackend
@@ -35,6 +37,31 @@ _START_MARKER = f"#_#_{_MARKER_BODY}_START_#_#"
 _STOP_MARKER = f"#_#_{_MARKER_BODY}_STOP_#_#"
 
 
+class _PendingCreationType(str, Enum):
+    """CoordOrigin."""
+
+    HEADING = "heading"
+    LIST_ITEM = "list_item"
+
+
+class _HeadingCreationPayload(BaseModel):
+    kind: Literal["heading"] = "heading"
+    level: int
+
+
+class _ListItemCreationPayload(BaseModel):
+    kind: Literal["list_item"] = "list_item"
+
+
+_CreationPayload = Annotated[
+    Union[
+        _HeadingCreationPayload,
+        _ListItemCreationPayload,
+    ],
+    Field(discriminator="kind"),
+]
+
+
 class MarkdownDocumentBackend(DeclarativeDocumentBackend):
     def _shorten_underscore_sequences(self, markdown_text: str, max_length: int = 10):
         # This regex will match any sequence of underscores
@@ -71,7 +98,6 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
 
         self.in_table = False
         self.md_table_buffer: list[str] = []
-        self.inline_texts: list[str] = []
         self._html_blocks: int = 0
 
         try:
@@ -156,25 +182,65 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
                 doc.add_table(data=table_data)
         return
 
-    def _process_inline_text(
-        self, parent_item: Optional[NodeItem], doc: DoclingDocument
+    def _create_list_item(
+        self,
+        doc: DoclingDocument,
+        parent_item: Optional[NodeItem],
+        text: str,
+        formatting: Optional[Formatting] = None,
+        hyperlink: Optional[Union[AnyUrl, Path]] = None,
+    ):
+        if not isinstance(parent_item, (OrderedList, UnorderedList)):
+            _log.warning("ListItem would have not had a list parent, adding one.")
+            parent_item = doc.add_unordered_list(parent=parent_item)
+        item = doc.add_list_item(
+            text=text,
+            enumerated=(isinstance(parent_item, OrderedList)),
+            parent=parent_item,
+            formatting=formatting,
+            hyperlink=hyperlink,
+        )
+        return item
+
+    def _create_heading_item(
+        self,
+        doc: DoclingDocument,
+        parent_item: Optional[NodeItem],
+        text: str,
+        level: int,
+        formatting: Optional[Formatting] = None,
+        hyperlink: Optional[Union[AnyUrl, Path]] = None,
     ):
-        txt = " ".join(self.inline_texts)
-        if len(txt) > 0:
-            doc.add_text(
-                label=DocItemLabel.PARAGRAPH,
+        if level == 1:
+            item = doc.add_title(
+                text=text,
                 parent=parent_item,
-                text=txt,
+                formatting=formatting,
+                hyperlink=hyperlink,
             )
-        self.inline_texts = []
+        else:
+            item = doc.add_heading(
+                text=text,
+                level=level - 1,
+                parent=parent_item,
+                formatting=formatting,
+                hyperlink=hyperlink,
+            )
+        return item
 
     def _iterate_elements(  # noqa: C901
         self,
+        *,
         element: marko.element.Element,
         depth: int,
         doc: DoclingDocument,
         visited: Set[marko.element.Element],
+        creation_stack: list[
+            _CreationPayload
+        ],  # stack for lazy item creation triggered deep in marko's AST (on RawText)
         parent_item: Optional[NodeItem] = None,
+        formatting: Optional[Formatting] = None,
+        hyperlink: Optional[Union[AnyUrl, Path]] = None,
     ):
         if element in visited:
             return
@@ -183,44 +249,21 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
         # Check for different element types and process relevant details
         if isinstance(element, marko.block.Heading) and len(element.children) > 0:
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(
                 f" - Heading level {element.level}, content: {element.children[0].children}"  # type: ignore
             )
-            if element.level == 1:
-                doc_label = DocItemLabel.TITLE
+
+            if len(element.children) > 1:  # inline group will be created further down
+                parent_item = self._create_heading_item(
+                    doc=doc,
+                    parent_item=parent_item,
+                    text="",
+                    level=element.level,
+                    formatting=formatting,
+                    hyperlink=hyperlink,
+                )
             else:
-                doc_label = DocItemLabel.SECTION_HEADER
-
-            # Header could have arbitrary inclusion of bold, italic or emphasis,
-            # hence we need to traverse the tree to get full text of a header
-            strings: List[str] = []
-
-            # Define a recursive function to traverse the tree
-            def traverse(node: marko.block.BlockElement):
-                # Check if the node has a "children" attribute
-                if hasattr(node, "children"):
-                    # If "children" is a list, continue traversal
-                    if isinstance(node.children, list):
-                        for child in node.children:
-                            traverse(child)
-                    # If "children" is text, add it to header text
-                    elif isinstance(node.children, str):
-                        strings.append(node.children)
-
-            traverse(element)
-            snippet_text = "".join(strings)
-            if len(snippet_text) > 0:
-                if doc_label == DocItemLabel.SECTION_HEADER:
-                    parent_item = doc.add_heading(
-                        text=snippet_text,
-                        level=element.level - 1,
-                        parent=parent_item,
-                    )
-                else:
-                    parent_item = doc.add_text(
-                        label=doc_label, parent=parent_item, text=snippet_text
-                    )
+                creation_stack.append(_HeadingCreationPayload(level=element.level))
 
         elif isinstance(element, marko.block.List):
             has_non_empty_list_items = False
@@ -230,7 +273,6 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
                     break
 
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(f" - List {'ordered' if element.ordered else 'unordered'}")
             if has_non_empty_list_items:
                 label = GroupLabel.ORDERED_LIST if element.ordered else GroupLabel.LIST
@@ -240,41 +282,54 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
 
         elif (
             isinstance(element, marko.block.ListItem)
-            and len(element.children) > 0
-            and isinstance((first_child := element.children[0]), marko.block.Paragraph)
+            and len(element.children) == 1
+            and isinstance((child := element.children[0]), marko.block.Paragraph)
+            and len(child.children) > 0
         ):
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(" - List item")
 
-            snippet_text = str(first_child.children[0].children)  # type: ignore
-            is_numbered = False
-            if (
-                parent_item is not None
-                and isinstance(parent_item, DocItem)
-                and parent_item.label == GroupLabel.ORDERED_LIST
-            ):
-                is_numbered = True
-            doc.add_list_item(
-                enumerated=is_numbered, parent=parent_item, text=snippet_text
-            )
-            visited.add(first_child)
+            if len(child.children) > 1:  # inline group will be created further down
+                parent_item = self._create_list_item(
+                    doc=doc,
+                    parent_item=parent_item,
+                    text="",
+                    formatting=formatting,
+                    hyperlink=hyperlink,
+                )
+            else:
+                creation_stack.append(_ListItemCreationPayload())
 
         elif isinstance(element, marko.inline.Image):
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(f" - Image with alt: {element.title}, url: {element.dest}")
 
             fig_caption: Optional[TextItem] = None
             if element.title is not None and element.title != "":
                 fig_caption = doc.add_text(
-                    label=DocItemLabel.CAPTION, text=element.title
+                    label=DocItemLabel.CAPTION,
+                    text=element.title,
+                    formatting=formatting,
+                    hyperlink=hyperlink,
                 )
 
             doc.add_picture(parent=parent_item, caption=fig_caption)
 
-        elif isinstance(element, marko.block.Paragraph) and len(element.children) > 0:
-            self._process_inline_text(parent_item, doc)
+        elif isinstance(element, marko.inline.Emphasis):
+            _log.debug(f" - Emphasis: {element.children}")
+            formatting = deepcopy(formatting) if formatting else Formatting()
+            formatting.italic = True
+
+        elif isinstance(element, marko.inline.StrongEmphasis):
+            _log.debug(f" - StrongEmphasis: {element.children}")
+            formatting = deepcopy(formatting) if formatting else Formatting()
+            formatting.bold = True
+
+        elif isinstance(element, marko.inline.Link):
+            _log.debug(f" - Link: {element.children}")
+            hyperlink = TypeAdapter(Optional[Union[AnyUrl, Path]]).validate_python(
+                element.dest
+            )
 
         elif isinstance(element, marko.inline.RawText):
             _log.debug(f" - Paragraph (raw text): {element.children}")
@@ -287,28 +342,66 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
                     self.md_table_buffer[len(self.md_table_buffer) - 1] += snippet_text
                 else:
                     self.md_table_buffer.append(snippet_text)
-            else:
+            elif snippet_text:
                 self._close_table(doc)
-                # most likely just inline text
-                self.inline_texts.append(str(element.children))
+
+                if creation_stack:
+                    while len(creation_stack) > 0:
+                        to_create = creation_stack.pop()
+                        if isinstance(to_create, _ListItemCreationPayload):
+                            parent_item = self._create_list_item(
+                                doc=doc,
+                                parent_item=parent_item,
+                                text=snippet_text,
+                                formatting=formatting,
+                                hyperlink=hyperlink,
+                            )
+                        elif isinstance(to_create, _HeadingCreationPayload):
+                            # not keeping as parent_item as logic for correctly tracking
+                            # that not implemented yet (section components not captured
+                            # as heading children in marko)
+                            self._create_heading_item(
+                                doc=doc,
+                                parent_item=parent_item,
+                                text=snippet_text,
+                                level=to_create.level,
+                                formatting=formatting,
+                                hyperlink=hyperlink,
+                            )
+                else:
+                    doc.add_text(
+                        label=DocItemLabel.TEXT,
+                        parent=parent_item,
+                        text=snippet_text,
+                        formatting=formatting,
+                        hyperlink=hyperlink,
+                    )
 
         elif isinstance(element, marko.inline.CodeSpan):
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(f" - Code Span: {element.children}")
             snippet_text = str(element.children).strip()
-            doc.add_code(parent=parent_item, text=snippet_text)
+            doc.add_code(
+                parent=parent_item,
+                text=snippet_text,
+                formatting=formatting,
+                hyperlink=hyperlink,
+            )
 
         elif (
             isinstance(element, (marko.block.CodeBlock, marko.block.FencedCode))
             and len(element.children) > 0
-            and isinstance((first_child := element.children[0]), marko.inline.RawText)
-            and len(snippet_text := (first_child.children.strip())) > 0
+            and isinstance((child := element.children[0]), marko.inline.RawText)
+            and len(snippet_text := (child.children.strip())) > 0
         ):
             self._close_table(doc)
-            self._process_inline_text(parent_item, doc)
             _log.debug(f" - Code Block: {element.children}")
-            doc.add_code(parent=parent_item, text=snippet_text)
+            doc.add_code(
+                parent=parent_item,
+                text=snippet_text,
+                formatting=formatting,
+                hyperlink=hyperlink,
+            )
 
         elif isinstance(element, marko.inline.LineBreak):
             if self.in_table:
@@ -317,7 +410,6 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
 
         elif isinstance(element, marko.block.HTMLBlock):
             self._html_blocks += 1
-            self._process_inline_text(parent_item, doc)
             self._close_table(doc)
             _log.debug(f"HTML Block: {element}")
             if (
@@ -327,14 +419,24 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
 
                 # wrap in markers to enable post-processing in convert()
                 text_to_add = f"{_START_MARKER}{html_block}{_STOP_MARKER}"
-                doc.add_code(parent=parent_item, text=text_to_add)
+                doc.add_code(
+                    parent=parent_item,
+                    text=text_to_add,
+                    formatting=formatting,
+                    hyperlink=hyperlink,
+                )
         else:
             if not isinstance(element, str):
                 self._close_table(doc)
                 _log.debug(f"Some other element: {element}")
 
+        if (
+            isinstance(element, (marko.block.Paragraph, marko.block.Heading))
+            and len(element.children) > 1
+        ):
+            parent_item = doc.add_inline_group(parent=parent_item)
+
         processed_block_types = (
-            marko.block.Heading,
             marko.block.CodeBlock,
             marko.block.FencedCode,
             marko.inline.RawText,
@@ -350,7 +452,10 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
                     depth=depth + 1,
                     doc=doc,
                     visited=visited,
+                    creation_stack=creation_stack,
                     parent_item=parent_item,
+                    formatting=formatting,
+                    hyperlink=hyperlink,
                 )
 
     def is_valid(self) -> bool:
@@ -391,8 +496,8 @@ class MarkdownDocumentBackend(DeclarativeDocumentBackend):
                 doc=doc,
                 parent_item=None,
                 visited=set(),
+                creation_stack=[],
             )
-            self._process_inline_text(None, doc)  # handle last hanging inline text
             self._close_table(doc=doc)  # handle any last hanging table
 
             # if HTML blocks were detected, export to HTML and delegate to HTML backend

docling/backend/msword_backend.py

@@ -14,7 +14,7 @@ from docling_core.types.doc import (
     TableCell,
     TableData,
 )
-from docling_core.types.doc.document import Formatting
+from docling_core.types.doc.document import Formatting, OrderedList, UnorderedList
 from docx import Document
 from docx.document import Document as DocxDocument
 from docx.oxml.table import CT_Tc
@@ -84,7 +84,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             self.valid = True
         except Exception as e:
             raise RuntimeError(
-                f"MsPowerpointDocumentBackend could not load document with hash {self.document_hash}"
+                f"MsWordDocumentBackend could not load document with hash {self.document_hash}"
             ) from e
 
     @override
@@ -251,9 +251,15 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                     self._handle_tables(element, docx_obj, doc)
                 except Exception:
                     _log.debug("could not parse a table, broken docx table")
-
+            # Check for Image
             elif drawing_blip:
                 self._handle_pictures(docx_obj, drawing_blip, doc)
+                # Check for Text after the Image
+                if (
+                    tag_name in ["p"]
+                    and element.find(".//w:t", namespaces=namespaces) is not None
+                ):
+                    self._handle_text_elements(element, docx_obj, doc)
             # Check for the sdt containers, like table of contents
             elif tag_name in ["sdt"]:
                 sdt_content = element.find(".//w:sdtContent", namespaces=namespaces)
@@ -268,6 +274,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 self._handle_text_elements(element, docx_obj, doc)
             else:
                 _log.debug(f"Ignoring element in DOCX with tag: {tag_name}")
+
         return doc
 
     def _str_to_int(
@@ -390,7 +397,11 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             if isinstance(c, Hyperlink):
                 text = c.text
                 hyperlink = Path(c.address)
-                format = self._get_format_from_run(c.runs[0])
+                format = (
+                    self._get_format_from_run(c.runs[0])
+                    if c.runs and len(c.runs) > 0
+                    else None
+                )
             elif isinstance(c, Run):
                 text = c.text
                 hyperlink = None
@@ -578,7 +589,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         all_paragraphs = []
 
         # Sort paragraphs within each container, then process containers
-        for container_id, paragraphs in container_paragraphs.items():
+        for paragraphs in container_paragraphs.values():
             # Sort by vertical position within each container
             sorted_container_paragraphs = sorted(
                 paragraphs,
@@ -689,14 +700,13 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         doc: DoclingDocument,
     ) -> None:
         paragraph = Paragraph(element, docx_obj)
-
+        paragraph_elements = self._get_paragraph_elements(paragraph)
         text, equations = self._handle_equations_in_text(
             element=element, text=paragraph.text
         )
 
         if text is None:
             return
-        paragraph_elements = self._get_paragraph_elements(paragraph)
         text = text.strip()
 
         # Common styles for bullet and numbered lists.
@@ -912,6 +922,44 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         )
         return
 
+    def _add_formatted_list_item(
+        self,
+        doc: DoclingDocument,
+        elements: list,
+        marker: str,
+        enumerated: bool,
+        level: int,
+    ) -> None:
+        # This should not happen by construction
+        if not isinstance(self.parents[level], (OrderedList, UnorderedList)):
+            return
+        if len(elements) == 1:
+            text, format, hyperlink = elements[0]
+            doc.add_list_item(
+                marker=marker,
+                enumerated=enumerated,
+                parent=self.parents[level],
+                text=text,
+                formatting=format,
+                hyperlink=hyperlink,
+            )
+        else:
+            new_item = doc.add_list_item(
+                marker=marker,
+                enumerated=enumerated,
+                parent=self.parents[level],
+                text="",
+            )
+            new_parent = doc.add_group(label=GroupLabel.INLINE, parent=new_item)
+            for text, format, hyperlink in elements:
+                doc.add_text(
+                    label=DocItemLabel.TEXT,
+                    parent=new_parent,
+                    text=text,
+                    formatting=format,
+                    hyperlink=hyperlink,
+                )
+
     def _add_list_item(
         self,
         *,
@@ -921,6 +969,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         elements: list,
         is_numbered: bool = False,
     ) -> None:
+        # TODO: this method is always called with is_numbered. Numbered lists should be properly addressed.
+        if not elements:
+            return None
         enum_marker = ""
 
         level = self._get_level()
@@ -937,21 +988,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             if is_numbered:
                 enum_marker = str(self.listIter) + "."
                 is_numbered = True
-            new_parent = self._create_or_reuse_parent(
-                doc=doc,
-                prev_parent=self.parents[level],
-                paragraph_elements=elements,
+            self._add_formatted_list_item(
+                doc, elements, enum_marker, is_numbered, level
             )
-            for text, format, hyperlink in elements:
-                doc.add_list_item(
-                    marker=enum_marker,
-                    enumerated=is_numbered,
-                    parent=new_parent,
-                    text=text,
-                    formatting=format,
-                    hyperlink=hyperlink,
-                )
-
         elif (
             self._prev_numid() == numid
             and self.level_at_new_list is not None
@@ -981,28 +1020,20 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             if is_numbered:
                 enum_marker = str(self.listIter) + "."
                 is_numbered = True
-
-            new_parent = self._create_or_reuse_parent(
-                doc=doc,
-                prev_parent=self.parents[self.level_at_new_list + ilevel],
-                paragraph_elements=elements,
+            self._add_formatted_list_item(
+                doc,
+                elements,
+                enum_marker,
+                is_numbered,
+                self.level_at_new_list + ilevel,
             )
-            for text, format, hyperlink in elements:
-                doc.add_list_item(
-                    marker=enum_marker,
-                    enumerated=is_numbered,
-                    parent=new_parent,
-                    text=text,
-                    formatting=format,
-                    hyperlink=hyperlink,
-                )
         elif (
             self._prev_numid() == numid
             and self.level_at_new_list is not None
             and prev_indent is not None
             and ilevel < prev_indent
         ):  # Close list
-            for k, v in self.parents.items():
+            for k in self.parents:
                 if k > self.level_at_new_list + ilevel:
                     self.parents[k] = None
 
@@ -1011,20 +1042,13 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             if is_numbered:
                 enum_marker = str(self.listIter) + "."
                 is_numbered = True
-            new_parent = self._create_or_reuse_parent(
-                doc=doc,
-                prev_parent=self.parents[self.level_at_new_list + ilevel],
-                paragraph_elements=elements,
+            self._add_formatted_list_item(
+                doc,
+                elements,
+                enum_marker,
+                is_numbered,
+                self.level_at_new_list + ilevel,
             )
-            for text, format, hyperlink in elements:
-                doc.add_list_item(
-                    marker=enum_marker,
-                    enumerated=is_numbered,
-                    parent=new_parent,
-                    text=text,
-                    formatting=format,
-                    hyperlink=hyperlink,
-                )
             self.listIter = 0
 
         elif self._prev_numid() == numid or prev_indent == ilevel:
@@ -1033,21 +1057,10 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             if is_numbered:
                 enum_marker = str(self.listIter) + "."
                 is_numbered = True
-            new_parent = self._create_or_reuse_parent(
-                doc=doc,
-                prev_parent=self.parents[level - 1],
-                paragraph_elements=elements,
+            self._add_formatted_list_item(
+                doc, elements, enum_marker, is_numbered, level - 1
             )
-            for text, format, hyperlink in elements:
-                # Add the list item to the parent group
-                doc.add_list_item(
-                    marker=enum_marker,
-                    enumerated=is_numbered,
-                    parent=new_parent,
-                    text=text,
-                    formatting=format,
-                    hyperlink=hyperlink,
-                )
+
         return
 
     def _handle_tables(