docling 2.53.0__py3-none-any.whl → 2.54.0__py3-none-any.whl

docling/backend/msword_backend.py

@@ -12,8 +12,11 @@ from docling_core.types.doc import (
     ImageRef,
     ListGroup,
     NodeItem,
+    RefItem,
+    RichTableCell,
     TableCell,
     TableData,
+    TextItem,
 )
 from docling_core.types.doc.document import Formatting
 from docx import Document
@@ -128,7 +131,8 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
         if self.is_valid():
             assert self.docx_obj is not None
-            doc = self._walk_linear(self.docx_obj.element.body, self.docx_obj, doc)
+            doc, _ = self._walk_linear(self.docx_obj.element.body, self.docx_obj, doc)
+            # doc, _ = doc_info
             return doc
         else:
             raise RuntimeError(
@@ -172,7 +176,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         body: BaseOxmlElement,
         docx_obj: DocxDocument,
         doc: DoclingDocument,
-    ) -> DoclingDocument:
+        # parent:
+    ) -> tuple[DoclingDocument, list[RefItem]]:
+        added_elements = []
         for element in body:
             tag_name = etree.QName(element).localname
             # Check for Inline Images (blip elements)
@@ -230,8 +236,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                                     parent=self.parents[level - 1],
                                     name="shape-text",
                                 )
+                                added_elements.append(shape_group.get_ref())
                                 doc.add_text(
-                                    label=DocItemLabel.PARAGRAPH,
+                                    label=DocItemLabel.TEXT,
                                     parent=shape_group,
                                     text=text_content,
                                 )
@@ -246,23 +253,27 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                     _log.debug(
                         f"Found textbox content with {len(textbox_elements)} elements"
                     )
-                    self._handle_textbox_content(textbox_elements, docx_obj, doc)
+                    tbc = self._handle_textbox_content(textbox_elements, docx_obj, doc)
+                    added_elements.extend(tbc)
 
             # Check for Tables
             if element.tag.endswith("tbl"):
                 try:
-                    self._handle_tables(element, docx_obj, doc)
+                    t = self._handle_tables(element, docx_obj, doc)
+                    added_elements.extend(t)
                 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)
+                pics = self._handle_pictures(docx_obj, drawing_blip, doc)
+                added_elements.extend(pics)
                 # 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)
+                    te1 = self._handle_text_elements(element, docx_obj, doc)
+                    added_elements.extend(te1)
             # Check for the sdt containers, like table of contents
             elif tag_name in ["sdt"]:
                 sdt_content = element.find(".//w:sdtContent", namespaces=namespaces)
@@ -270,15 +281,17 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                     # Iterate paragraphs, runs, or text inside <w:sdtContent>.
                     paragraphs = sdt_content.findall(".//w:p", namespaces=namespaces)
                     for p in paragraphs:
-                        self._handle_text_elements(p, docx_obj, doc)
+                        te = self._handle_text_elements(p, docx_obj, doc)
+                        added_elements.extend(te)
             # Check for Text
             elif tag_name in ["p"]:
                 # "tcPr", "sectPr"
-                self._handle_text_elements(element, docx_obj, doc)
+                te = self._handle_text_elements(element, docx_obj, doc)
+                added_elements.extend(te)
             else:
                 _log.debug(f"Ignoring element in DOCX with tag: {tag_name}")
 
-        return doc
+        return doc, added_elements
 
     def _str_to_int(
         self, s: Optional[str], default: Optional[int] = 0
@@ -674,14 +687,15 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         textbox_elements: list,
         docx_obj: DocxDocument,
         doc: DoclingDocument,
-    ) -> None:
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
         """Process textbox content and add it to the document structure."""
         level = self._get_level()
         # Create a textbox group to contain all text from the textbox
         textbox_group = doc.add_group(
             label=GroupLabel.SECTION, parent=self.parents[level - 1], name="textbox"
         )
-
+        elem_ref.append(textbox_group.get_ref())
         # Set this as the current parent to ensure textbox content
         # is properly nested in document structure
         original_parent = self.parents[level]
@@ -729,11 +743,11 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             # Mark this paragraph as processed
             processed_paragraphs.add(paragraph_id)
 
-            self._handle_text_elements(p, docx_obj, doc)
+            elem_ref.extend(self._handle_text_elements(p, docx_obj, doc))
 
         # Restore original parent
         self.parents[level] = original_parent
-        return
+        return elem_ref
 
     def _handle_equations_in_text(self, element, text):
         only_texts = []
@@ -803,7 +817,8 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         element: BaseOxmlElement,
         docx_obj: DocxDocument,
         doc: DoclingDocument,
-    ) -> None:
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
         paragraph = Paragraph(element, docx_obj)
         paragraph_elements = self._get_paragraph_elements(paragraph)
         text, equations = self._handle_equations_in_text(
@@ -811,7 +826,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         )
 
         if text is None:
-            return
+            return elem_ref
         text = text.strip()
 
         # Common styles for bullet and numbered lists.
@@ -832,15 +847,16 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             # Check if this is actually a numbered list by examining the numFmt
             is_numbered = self._is_numbered_list(docx_obj, numid, ilevel)
 
-            self._add_list_item(
+            li = self._add_list_item(
                 doc=doc,
                 numid=numid,
                 ilevel=ilevel,
                 elements=paragraph_elements,
                 is_numbered=is_numbered,
             )
+            elem_ref.extend(li)  # MUST BE REF!!!
             self._update_history(p_style_id, p_level, numid, ilevel)
-            return
+            return elem_ref
         elif (
             numid is None
             and self._prev_numid() is not None
@@ -860,9 +876,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         if p_style_id in ["Title"]:
             for key in range(len(self.parents)):
                 self.parents[key] = None
-            self.parents[0] = doc.add_text(
-                parent=None, label=DocItemLabel.TITLE, text=text
-            )
+            te = doc.add_text(parent=None, label=DocItemLabel.TITLE, text=text)
+            self.parents[0] = te
+            elem_ref.append(te.get_ref())
         elif "Heading" in p_style_id:
             style_element = getattr(paragraph.style, "element", None)
             if style_element is not None:
@@ -871,7 +887,8 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 )
             else:
                 is_numbered_style = False
-            self._add_header(doc, p_level, text, is_numbered_style)
+            h1 = self._add_header(doc, p_level, text, is_numbered_style)
+            elem_ref.extend(h1)
 
         elif len(equations) > 0:
             if (paragraph.text is None or len(paragraph.text.strip()) == 0) and len(
@@ -879,15 +896,17 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             ) > 0:
                 # Standalone equation
                 level = self._get_level()
-                doc.add_text(
+                t1 = doc.add_text(
                     label=DocItemLabel.FORMULA,
                     parent=self.parents[level - 1],
                     text=text.replace("<eq>", "").replace("</eq>", ""),
                 )
+                elem_ref.append(t1.get_ref())
             else:
                 # Inline equation
                 level = self._get_level()
                 inline_equation = doc.add_inline_group(parent=self.parents[level - 1])
+                elem_ref.append(inline_equation.get_ref())
                 text_tmp = text
                 for eq in equations:
                     if len(text_tmp) == 0:
@@ -899,23 +918,26 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                     text_tmp = "" if len(split_text_tmp) == 1 else split_text_tmp[1]
 
                     if len(pre_eq_text) > 0:
-                        doc.add_text(
-                            label=DocItemLabel.PARAGRAPH,
+                        e1 = doc.add_text(
+                            label=DocItemLabel.TEXT,
                             parent=inline_equation,
                             text=pre_eq_text,
                         )
-                    doc.add_text(
+                        elem_ref.append(e1.get_ref())
+                    e2 = doc.add_text(
                         label=DocItemLabel.FORMULA,
                         parent=inline_equation,
                         text=eq.replace("<eq>", "").replace("</eq>", ""),
                     )
+                    elem_ref.append(e2.get_ref())
 
                 if len(text_tmp) > 0:
-                    doc.add_text(
-                        label=DocItemLabel.PARAGRAPH,
+                    e3 = doc.add_text(
+                        label=DocItemLabel.TEXT,
                         parent=inline_equation,
                         text=text_tmp.strip(),
                     )
+                    elem_ref.append(e3.get_ref())
 
         elif p_style_id in [
             "Paragraph",
@@ -934,13 +956,14 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 paragraph_elements=paragraph_elements,
             )
             for text, format, hyperlink in paragraph_elements:
-                doc.add_text(
-                    label=DocItemLabel.PARAGRAPH,
+                t2 = doc.add_text(
+                    label=DocItemLabel.TEXT,
                     parent=parent,
                     text=text,
                     formatting=format,
                     hyperlink=hyperlink,
                 )
+                elem_ref.append(t2.get_ref())
 
         else:
             # Text style names can, and will have, not only default values but user values too
@@ -952,16 +975,17 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 paragraph_elements=paragraph_elements,
             )
             for text, format, hyperlink in paragraph_elements:
-                doc.add_text(
-                    label=DocItemLabel.PARAGRAPH,
+                t3 = doc.add_text(
+                    label=DocItemLabel.TEXT,
                     parent=parent,
                     text=text,
                     formatting=format,
                     hyperlink=hyperlink,
                 )
+                elem_ref.append(t3.get_ref())
 
         self._update_history(p_style_id, p_level, numid, ilevel)
-        return
+        return elem_ref
 
     def _add_header(
         self,
@@ -969,17 +993,21 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         curr_level: Optional[int],
         text: str,
         is_numbered_style: bool = False,
-    ) -> None:
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
         level = self._get_level()
         if isinstance(curr_level, int):
             if curr_level > level:
                 # add invisible group
                 for i in range(level, curr_level):
-                    self.parents[i] = doc.add_group(
+                    gr1 = doc.add_group(
                         parent=self.parents[i - 1],
                         label=GroupLabel.SECTION,
                         name=f"header-{i}",
                     )
+                    elem_ref.append(gr1.get_ref())
+                    self.parents[i] = gr1
+
             elif curr_level < level:
                 # remove the tail
                 for key in range(len(self.parents)):
@@ -1019,12 +1047,14 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 text = f"{self.numbered_headers[previous_level]}.{text}"
                 previous_level -= 1
 
-        self.parents[current_level] = doc.add_heading(
+        hd = doc.add_heading(
             parent=self.parents[parent_level],
             text=text,
             level=add_level,
         )
-        return
+        self.parents[current_level] = hd
+        elem_ref.append(hd.get_ref())
+        return elem_ref
 
     def _add_formatted_list_item(
         self,
@@ -1033,12 +1063,13 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         marker: str,
         enumerated: bool,
         level: int,
-    ) -> None:
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
         # This should not happen by construction
         if not isinstance(self.parents[level], ListGroup):
-            return
+            return elem_ref
         if not elements:
-            return
+            return elem_ref
 
         if len(elements) == 1:
             text, format, hyperlink = elements[0]
@@ -1068,6 +1099,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                         formatting=format,
                         hyperlink=hyperlink,
                     )
+        return elem_ref
 
     def _add_list_item(
         self,
@@ -1077,10 +1109,11 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
         ilevel: int,
         elements: list,
         is_numbered: bool = False,
-    ) -> None:
-        # TODO: this method is always called with is_numbered. Numbered lists should be properly addressed.
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
+        # this method is always called with is_numbered. Numbered lists should be properly addressed.
         if not elements:
-            return None
+            return elem_ref
         enum_marker = ""
 
         level = self._get_level()
@@ -1091,9 +1124,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             # Reset counters for the new numbering sequence
             self._reset_list_counters_for_new_sequence(numid)
 
-            self.parents[level] = doc.add_list_group(
-                name="list", parent=self.parents[level - 1]
-            )
+            list_gr = doc.add_list_group(name="list", parent=self.parents[level - 1])
+            self.parents[level] = list_gr
+            elem_ref.append(list_gr.get_ref())
 
             # Set marker and enumerated arguments if this is an enumeration element.
             if is_numbered:
@@ -1114,9 +1147,9 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 self.level_at_new_list + prev_indent + 1,
                 self.level_at_new_list + ilevel + 1,
             ):
-                self.parents[i] = doc.add_list_group(
-                    name="list", parent=self.parents[i - 1]
-                )
+                list_gr1 = doc.add_list_group(name="list", parent=self.parents[i - 1])
+                self.parents[i] = list_gr1
+                elem_ref.append(list_gr1.get_ref())
 
             # TODO: Set marker and enumerated arguments if this is an enumeration element.
             if is_numbered:
@@ -1156,7 +1189,7 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             )
 
         elif self._prev_numid() == numid or prev_indent == ilevel:
-            # TODO: Set marker and enumerated arguments if this is an enumeration element.
+            # Set marker and enumerated arguments if this is an enumeration element.
             if is_numbered:
                 counter = self._get_list_counter(numid, ilevel)
                 enum_marker = str(counter) + "."
@@ -1165,15 +1198,15 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             self._add_formatted_list_item(
                 doc, elements, enum_marker, is_numbered, level - 1
             )
-
-        return
+        return elem_ref
 
     def _handle_tables(
         self,
         element: BaseOxmlElement,
         docx_obj: DocxDocument,
         doc: DoclingDocument,
-    ) -> None:
+    ) -> List[RefItem]:
+        elem_ref: List[RefItem] = []
         table: Table = Table(element, docx_obj)
         num_rows = len(table.rows)
         num_cols = len(table.columns)
@@ -1184,9 +1217,13 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
             # In case we have a table of only 1 cell, we consider it furniture
             # And proceed processing the content of the cell as though it's in the document body
             self._walk_linear(cell_element._element, docx_obj, doc)
-            return
+            return elem_ref
 
         data = TableData(num_rows=num_rows, num_cols=num_cols)
+        level = self._get_level()
+        docling_table = doc.add_table(data=data, parent=self.parents[level - 1])
+        elem_ref.append(docling_table.get_ref())
+
         cell_set: set[CT_Tc] = set()
         for row_idx, row in enumerate(table.rows):
             _log.debug(f"Row index {row_idx} with {len(row.cells)} populated cells")
@@ -1223,27 +1260,87 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 else:
                     text = text.replace("<eq>", "$").replace("</eq>", "$")
 
-                table_cell = TableCell(
-                    text=text,
-                    row_span=spanned_idx - row_idx,
-                    col_span=cell.grid_span,
-                    start_row_offset_idx=row.grid_cols_before + row_idx,
-                    end_row_offset_idx=row.grid_cols_before + spanned_idx,
-                    start_col_offset_idx=col_idx,
-                    end_col_offset_idx=col_idx + cell.grid_span,
-                    column_header=row.grid_cols_before + row_idx == 0,
-                    row_header=False,
-                )
-                data.table_cells.append(table_cell)
-                col_idx += cell.grid_span
+                provs_in_cell: List[RefItem] = []
+                _, provs_in_cell = self._walk_linear(cell._element, docx_obj, doc)
+                ref_for_rich_cell = provs_in_cell[0]
+                rich_table_cell = False
+
+                def group_cell_elements(
+                    group_name: str, doc: DoclingDocument, provs_in_cell: List[RefItem]
+                ) -> RefItem:
+                    group_element = doc.add_group(
+                        label=GroupLabel.UNSPECIFIED,
+                        name=group_name,
+                        parent=docling_table,
+                    )
+                    for prov in provs_in_cell:
+                        group_element.children.append(prov)
+                        pr_item = prov.resolve(doc)
+                        item_parent = pr_item.parent.resolve(doc)
+                        if pr_item.get_ref() in item_parent.children:
+                            item_parent.children.remove(pr_item.get_ref())
+                        pr_item.parent = group_element.get_ref()
+                    ref_for_rich_cell = group_element.get_ref()
+                    return ref_for_rich_cell
+
+                if len(provs_in_cell) > 1:
+                    # Cell has multiple elements, we need to group them
+                    rich_table_cell = True
+                    group_name = f"rich_cell_group_{len(doc.tables)}_{col_idx}_{row.grid_cols_before + row_idx}"
+                    ref_for_rich_cell = group_cell_elements(
+                        group_name, doc, provs_in_cell
+                    )
 
-        level = self._get_level()
-        doc.add_table(data=data, parent=self.parents[level - 1])
-        return
+                elif len(provs_in_cell) == 1:
+                    item_ref = provs_in_cell[0]
+                    pr_item = item_ref.resolve(doc)
+                    if isinstance(pr_item, TextItem):
+                        # Cell has only one element and it's just a text
+                        rich_table_cell = False
+                        doc.delete_items(node_items=[pr_item])
+                    else:
+                        rich_table_cell = True
+                        group_name = f"rich_cell_group_{len(doc.tables)}_{col_idx}_{row.grid_cols_before + row_idx}"
+                        ref_for_rich_cell = group_cell_elements(
+                            group_name, doc, provs_in_cell
+                        )
+                else:
+                    rich_table_cell = False
+
+                if rich_table_cell:
+                    rich_cell = RichTableCell(
+                        text=text,
+                        row_span=spanned_idx - row_idx,
+                        col_span=cell.grid_span,
+                        start_row_offset_idx=row.grid_cols_before + row_idx,
+                        end_row_offset_idx=row.grid_cols_before + spanned_idx,
+                        start_col_offset_idx=col_idx,
+                        end_col_offset_idx=col_idx + cell.grid_span,
+                        column_header=row.grid_cols_before + row_idx == 0,
+                        row_header=False,
+                        ref=ref_for_rich_cell,  # points to an artificial group around children
+                    )
+                    doc.add_table_cell(table_item=docling_table, cell=rich_cell)
+                    col_idx += cell.grid_span
+                else:
+                    simple_cell = TableCell(
+                        text=text,
+                        row_span=spanned_idx - row_idx,
+                        col_span=cell.grid_span,
+                        start_row_offset_idx=row.grid_cols_before + row_idx,
+                        end_row_offset_idx=row.grid_cols_before + spanned_idx,
+                        start_col_offset_idx=col_idx,
+                        end_col_offset_idx=col_idx + cell.grid_span,
+                        column_header=row.grid_cols_before + row_idx == 0,
+                        row_header=False,
+                    )
+                    doc.add_table_cell(table_item=docling_table, cell=simple_cell)
+                    col_idx += cell.grid_span
+        return elem_ref
 
     def _handle_pictures(
         self, docx_obj: DocxDocument, drawing_blip: Any, doc: DoclingDocument
-    ) -> None:
+    ) -> List[RefItem]:
         def get_docx_image(drawing_blip: Any) -> Optional[bytes]:
             image_data: Optional[bytes] = None
             rId = drawing_blip[0].get(
@@ -1255,28 +1352,32 @@ class MsWordDocumentBackend(DeclarativeDocumentBackend):
                 image_data = image_part.blob  # Get the binary image data
             return image_data
 
+        elem_ref: List[RefItem] = []
         level = self._get_level()
         # Open the BytesIO object with PIL to create an Image
         image_data: Optional[bytes] = get_docx_image(drawing_blip)
         if image_data is None:
             _log.warning("Warning: image cannot be found")
-            doc.add_picture(
+            p1 = doc.add_picture(
                 parent=self.parents[level - 1],
                 caption=None,
             )
+            elem_ref.append(p1.get_ref())
         else:
             try:
                 image_bytes = BytesIO(image_data)
                 pil_image = Image.open(image_bytes)
-                doc.add_picture(
+                p2 = doc.add_picture(
                     parent=self.parents[level - 1],
                     image=ImageRef.from_pil(image=pil_image, dpi=72),
                     caption=None,
                 )
+                elem_ref.append(p2.get_ref())
             except (UnidentifiedImageError, OSError):
                 _log.warning("Warning: image cannot be loaded by Pillow")
-                doc.add_picture(
+                p3 = doc.add_picture(
                     parent=self.parents[level - 1],
                     caption=None,
                 )
-        return
+                elem_ref.append(p3.get_ref())
+        return elem_ref