docling-core 2.23.2__py3-none-any.whl → 2.24.0__py3-none-any.whl

docling_core/experimental/serializer/markdown.py

@@ -26,12 +26,14 @@ from docling_core.experimental.serializer.base import (
     BaseTextSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import DocSerializer
+from docling_core.experimental.serializer.common import CommonParams, DocSerializer
 from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
     CodeItem,
+    ContentLayer,
     DocItem,
     DoclingDocument,
+    FloatingItem,
     Formatting,
     FormItem,
     FormulaItem,
@@ -49,10 +51,20 @@ from docling_core.types.doc.document import (
 )
 
 
-class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
-    """Markdown-specific text item serializer."""
+class MarkdownParams(CommonParams):
+    """Markdown-specific serialization parameters."""
 
+    layers: set[ContentLayer] = {ContentLayer.BODY}
+    image_mode: ImageRefMode = ImageRefMode.PLACEHOLDER
+    image_placeholder: str = "<!-- image -->"
+    indent: int = 4
     wrap_width: Optional[PositiveInt] = None
+    page_break_placeholder: Optional[str] = None  # e.g. "<!-- page break -->"
+    escape_underscores: bool = True
+
+
+class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
+    """Markdown-specific text item serializer."""
 
     @override
     def serialize(
@@ -65,37 +77,47 @@ class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
+        params = MarkdownParams(**kwargs)
+        parts: list[str] = []
         escape_html = True
         escape_underscores = True
         if isinstance(item, TitleItem):
-            res = f"# {item.text}"
+            text = f"# {item.text}"
         elif isinstance(item, SectionHeaderItem):
-            res = f"{(item.level + 1) * '#'} {item.text}"
+            text = f"{(item.level + 1) * '#'} {item.text}"
         elif isinstance(item, CodeItem):
-            res = f"`{item.text}`" if is_inline_scope else f"```\n{item.text}\n```"
+            text = f"`{item.text}`" if is_inline_scope else f"```\n{item.text}\n```"
             escape_html = False
             escape_underscores = False
         elif isinstance(item, FormulaItem):
             if item.text:
-                res = f"${item.text}$" if is_inline_scope else f"$${item.text}$$"
+                text = f"${item.text}$" if is_inline_scope else f"$${item.text}$$"
             elif item.orig:
-                res = "<!-- formula-not-decoded -->"
+                text = "<!-- formula-not-decoded -->"
             else:
-                res = ""
+                text = ""
             escape_html = False
             escape_underscores = False
-        elif self.wrap_width:
-            res = textwrap.fill(item.text, width=self.wrap_width)
+        elif params.wrap_width:
+            text = textwrap.fill(item.text, width=params.wrap_width)
         else:
-            res = item.text
-        res = doc_serializer.post_process(
-            text=res,
+            text = item.text
+        parts.append(text)
+
+        if isinstance(item, FloatingItem):
+            cap_text = doc_serializer.serialize_captions(item=item, **kwargs).text
+            if cap_text:
+                parts.append(cap_text)
+
+        text_res = (" " if is_inline_scope else "\n\n").join(parts)
+        text_res = doc_serializer.post_process(
+            text=text_res,
             escape_html=escape_html,
             escape_underscores=escape_underscores,
             formatting=item.formatting,
             hyperlink=item.hyperlink,
         )
-        return SerializationResult(text=res)
+        return SerializationResult(text=text_res)
 
 
 class MarkdownTableSerializer(BaseTableSerializer):
@@ -113,12 +135,14 @@ class MarkdownTableSerializer(BaseTableSerializer):
         """Serializes the passed item."""
         text_parts: list[str] = []
 
-        if caption_txt := doc_serializer.serialize_captions(
+        cap_res = doc_serializer.serialize_captions(
             item=item,
-        ).text:
-            text_parts.append(caption_txt)
+            **kwargs,
+        )
+        if cap_res.text:
+            text_parts.append(cap_res.text)
 
-        if item.self_ref not in doc_serializer.get_excluded_refs():
+        if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             rows = [
                 [
                     # make sure that md tables are not broken
@@ -158,33 +182,26 @@ class MarkdownPictureSerializer(BasePictureSerializer):
         item: PictureItem,
         doc_serializer: BaseDocSerializer,
         doc: DoclingDocument,
-        image_mode: Optional[ImageRefMode] = None,
-        image_placeholder: Optional[str] = None,
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
-        my_image_mode = (
-            image_mode if image_mode is not None else ImageRefMode.PLACEHOLDER
-        )
-        my_image_placeholder = (
-            image_placeholder if image_placeholder is not None else "<!-- image -->"
-        )
+        params = MarkdownParams(**kwargs)
 
         texts: list[str] = []
 
         cap_res = doc_serializer.serialize_captions(
             item=item,
-            separator="\n",
+            **kwargs,
         )
         if cap_res.text:
             texts.append(cap_res.text)
 
-        if item.self_ref not in doc_serializer.get_excluded_refs():
+        if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             img_res = self._serialize_image_part(
                 item=item,
                 doc=doc,
-                image_mode=my_image_mode,
-                image_placeholder=my_image_placeholder,
+                image_mode=params.image_mode,
+                image_placeholder=params.image_placeholder,
             )
             if img_res.text:
                 texts.append(img_res.text)
@@ -288,8 +305,6 @@ class MarkdownFormSerializer(BaseFormSerializer):
 class MarkdownListSerializer(BaseModel, BaseListSerializer):
     """Markdown-specific list serializer."""
 
-    indent: int = 4
-
     @override
     def serialize(
         self,
@@ -303,16 +318,26 @@ class MarkdownListSerializer(BaseModel, BaseListSerializer):
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
+        params = MarkdownParams(**kwargs)
         my_visited = visited or set()
         parts = doc_serializer.get_parts(
-            node=item,
+            item=item,
             list_level=list_level + 1,
             is_inline_scope=is_inline_scope,
             visited=my_visited,
+            **kwargs,
         )
-        indent_str = list_level * self.indent * " "
+        sep = "\n"
+        my_parts: list[SerializationResult] = []
+        for p in parts:
+            if p.text and p.text[0] == " " and my_parts:
+                my_parts[-1].text = sep.join([my_parts[-1].text, p.text])  # update last
+            else:
+                my_parts.append(p)
+
+        indent_str = list_level * params.indent * " "
         is_ol = isinstance(item, OrderedList)
-        text_res = "\n".join(
+        text_res = sep.join(
             [
                 # avoid additional marker on already evaled sublists
                 (
@@ -320,7 +345,7 @@ class MarkdownListSerializer(BaseModel, BaseListSerializer):
                     if c.text and c.text[0] == " "
                     else f"{indent_str}{f'{i + 1}.' if is_ol else '-'} {c.text}"
                 )
-                for i, c in enumerate(parts)
+                for i, c in enumerate(my_parts)
             ]
         )
         return SerializationResult(text=text_res)
@@ -343,7 +368,7 @@ class MarkdownInlineSerializer(BaseInlineSerializer):
         """Serializes the passed item."""
         my_visited = visited or set()
         parts = doc_serializer.get_parts(
-            node=item,
+            item=item,
             list_level=list_level,
             is_inline_scope=True,
             visited=my_visited,
@@ -385,6 +410,8 @@ class MarkdownDocSerializer(DocSerializer):
     list_serializer: BaseListSerializer = MarkdownListSerializer()
     inline_serializer: BaseInlineSerializer = MarkdownInlineSerializer()
 
+    params: MarkdownParams = MarkdownParams()
+
     @override
     def serialize_bold(self, text: str, **kwargs):
         """Apply Markdown-specific bold serialization."""
@@ -442,7 +469,8 @@ class MarkdownDocSerializer(DocSerializer):
     ) -> str:
         """Apply some text post-processing steps."""
         res = text
-        if escape_underscores and self.escape_underscores:
+        params = self.params.merge_with_patch(patch=kwargs)
+        if escape_underscores and params.escape_underscores:
             res = self._escape_underscores(text)
         if escape_html:
             res = html.escape(res, quote=False)
@@ -454,8 +482,17 @@ class MarkdownDocSerializer(DocSerializer):
         return res
 
     @override
-    def serialize(self, **kwargs) -> SerializationResult:
-        """Run the serialization."""
-        parts = self.get_parts()
-        text_res = "\n\n".join([p.text for p in parts if p.text])
+    def serialize_page(self, parts: list[SerializationResult]) -> SerializationResult:
+        """Serialize a page out of its parts."""
+        text_res = "\n\n".join([p.text for p in parts])
         return SerializationResult(text=text_res)
+
+    @override
+    def serialize_doc(self, pages: list[SerializationResult]) -> SerializationResult:
+        """Serialize a document out of its pages."""
+        if self.params.page_break_placeholder is not None:
+            sep = f"\n\n{self.params.page_break_placeholder}\n\n"
+            text_res = sep.join([p.text for p in pages if p.text])
+            return SerializationResult(text=text_res)
+        else:
+            return self.serialize_page(parts=pages)