feat: promote serializers to stable API (#276)

vagenas · web-flow · commit d05fe085468f · 2025-04-30T11:26:39.000+02:00
Signed-off-by: Panos Vagenas &lt;pva@zurich.ibm.com&gt;
diff --git a/docling_core/transforms/chunker/hierarchical_chunker.py b/docling_core/transforms/chunker/hierarchical_chunker.py
@@ -14,19 +14,19 @@
 from pydantic import ConfigDict, Field, StringConstraints, field_validator
 from typing_extensions import Annotated, override
 
-from docling_core.experimental.serializer.base import (
+from docling_core.search.package import VERSION_PATTERN
+from docling_core.transforms.chunker import BaseChunk, BaseChunker, BaseMeta
+from docling_core.transforms.serializer.base import (
     BaseDocSerializer,
     BaseSerializerProvider,
     BaseTableSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import create_ser_result
-from docling_core.experimental.serializer.markdown import (
+from docling_core.transforms.serializer.common import create_ser_result
+from docling_core.transforms.serializer.markdown import (
     MarkdownDocSerializer,
     MarkdownParams,
 )
-from docling_core.search.package import VERSION_PATTERN
-from docling_core.transforms.chunker import BaseChunk, BaseChunker, BaseMeta
 from docling_core.types import DoclingDocument as DLDocument
 from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
diff --git a/docling_core/transforms/chunker/hybrid_chunker.py b/docling_core/transforms/chunker/hybrid_chunker.py
@@ -25,17 +25,17 @@
         "`pip install 'docling-core[chunking-openai]'`"
     )
 
-from docling_core.experimental.serializer.base import (
-    BaseDocSerializer,
-    BaseSerializerProvider,
-)
 from docling_core.transforms.chunker import (
     BaseChunk,
     BaseChunker,
     DocChunk,
     DocMeta,
     HierarchicalChunker,
 )
+from docling_core.transforms.serializer.base import (
+    BaseDocSerializer,
+    BaseSerializerProvider,
+)
 from docling_core.types import DoclingDocument
 
 
diff --git a/docling_core/transforms/serializer/__init__.py b/docling_core/transforms/serializer/__init__.py
diff --git a/docling_core/transforms/serializer/base.py b/docling_core/transforms/serializer/base.py
diff --git a/docling_core/transforms/serializer/common.py b/docling_core/transforms/serializer/common.py
@@ -14,7 +14,7 @@
 from pydantic import AnyUrl, BaseModel, NonNegativeInt, computed_field
 from typing_extensions import Self, override
 
-from docling_core.experimental.serializer.base import (
+from docling_core.transforms.serializer.base import (
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
diff --git a/docling_core/transforms/serializer/doctags.py b/docling_core/transforms/serializer/doctags.py
@@ -6,7 +6,7 @@
 from pydantic import BaseModel
 from typing_extensions import override
 
-from docling_core.experimental.serializer.base import (
+from docling_core.transforms.serializer.base import (
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -18,7 +18,7 @@
     BaseTextSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import (
+from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
     create_ser_result,
diff --git a/docling_core/transforms/serializer/html.py b/docling_core/transforms/serializer/html.py
@@ -19,7 +19,7 @@
 from pydantic import AnyUrl, BaseModel
 from typing_extensions import override
 
-from docling_core.experimental.serializer.base import (
+from docling_core.transforms.serializer.base import (
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -31,12 +31,12 @@
     BaseTextSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import (
+from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
     create_ser_result,
 )
-from docling_core.experimental.serializer.html_styles import (
+from docling_core.transforms.serializer.html_styles import (
     _get_css_for_single_column,
     _get_css_for_split_page,
 )
diff --git a/docling_core/transforms/serializer/html_styles.py b/docling_core/transforms/serializer/html_styles.py
diff --git a/docling_core/transforms/serializer/markdown.py b/docling_core/transforms/serializer/markdown.py
@@ -14,7 +14,7 @@
 from tabulate import tabulate
 from typing_extensions import override
 
-from docling_core.experimental.serializer.base import (
+from docling_core.transforms.serializer.base import (
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -26,7 +26,7 @@
     BaseTextSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import (
+from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
     _PageBreakSerResult,
diff --git a/docling_core/types/doc/document.py b/docling_core/types/doc/document.py
@@ -872,7 +872,7 @@ def export_to_doctags(
         :param add_content: bool:  (Default value = True)
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -930,7 +930,7 @@ def export_to_doctags(
         :param add_content: bool:  (Default value = True)
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -1020,7 +1020,7 @@ def export_to_doctags(
         :param add_content: bool:  (Default value = True)
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -1091,7 +1091,7 @@ def export_to_markdown(
         image_placeholder: str = "<!-- image -->",
     ) -> str:
         """Export picture to Markdown format."""
-        from docling_core.experimental.serializer.markdown import (
+        from docling_core.transforms.serializer.markdown import (
             MarkdownDocSerializer,
             MarkdownParams,
         )
@@ -1118,7 +1118,7 @@ def export_to_html(
         image_mode: ImageRefMode = ImageRefMode.PLACEHOLDER,
     ) -> str:
         """Export picture to HTML format."""
-        from docling_core.experimental.serializer.html import (
+        from docling_core.transforms.serializer.html import (
             HTMLDocSerializer,
             HTMLParams,
         )
@@ -1159,7 +1159,7 @@ def export_to_doctags(
         :param # not used at the moment
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -1235,7 +1235,7 @@ def export_to_dataframe(self) -> pd.DataFrame:
     def export_to_markdown(self, doc: Optional["DoclingDocument"] = None) -> str:
         """Export the table as markdown."""
         if doc is not None:
-            from docling_core.experimental.serializer.markdown import (
+            from docling_core.transforms.serializer.markdown import (
                 MarkdownDocSerializer,
             )
 
@@ -1282,7 +1282,7 @@ def export_to_html(
     ) -> str:
         """Export the table as html."""
         if doc is not None:
-            from docling_core.experimental.serializer.html import HTMLDocSerializer
+            from docling_core.transforms.serializer.html import HTMLDocSerializer
 
             serializer = HTMLDocSerializer(doc=doc)
             text = serializer.serialize(item=self).text
@@ -1414,7 +1414,7 @@ def export_to_doctags(
         :param add_caption: bool:  (Default value = True)
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -1512,7 +1512,7 @@ def export_to_document_tokens(
         :param add_content: bool:  (Default value = True)
 
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
@@ -2999,7 +2999,7 @@ def export_to_markdown(  # noqa: C901
         :returns: The exported Markdown representation.
         :rtype: str
         """
-        from docling_core.experimental.serializer.markdown import (
+        from docling_core.transforms.serializer.markdown import (
             MarkdownDocSerializer,
             MarkdownParams,
         )
@@ -3153,7 +3153,7 @@ def export_to_html(  # noqa: C901
         split_page_view: bool = False,
     ) -> str:
         r"""Serialize to HTML."""
-        from docling_core.experimental.serializer.html import (
+        from docling_core.transforms.serializer.html import (
             HTMLDocSerializer,
             HTMLOutputStyle,
             HTMLParams,
@@ -3887,7 +3887,7 @@ def export_to_doctags(  # noqa: C901
         :returns: The content of the document formatted as a DocTags string.
         :rtype: str
         """
-        from docling_core.experimental.serializer.doctags import (
+        from docling_core.transforms.serializer.doctags import (
             DocTagsDocSerializer,
             DocTagsParams,
         )
diff --git a/examples/chunking_and_serialization.ipynb b/examples/chunking_and_serialization.ipynb
@@ -7,20 +7,6 @@
     "# Chunking and serialization"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<div class=\"alert alert-info\">\n",
-    "    <h3>Beta feature</h3>\n",
-    "    <p>The Serialization API used in this notebook is currently in <i>beta</i> under <code>docling_core.experimental.serializer</code>, i.e.:</p>\n",
-    "    <ul>\n",
-    "        <li>the import package WILL change</li>\n",
-    "        <li>the API MAY still slightly change</li>\n",
-    "    </ul>\n",
-    "</div>"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -35,7 +21,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from docling_core.experimental.serializer.markdown import MarkdownTableSerializer\n",
+    "from docling_core.transforms.serializer.markdown import MarkdownTableSerializer\n",
     "from docling_core.transforms.chunker.hierarchical_chunker import ChunkingDocSerializer\n",
     "from docling_core.transforms.chunker.hybrid_chunker import HybridChunker\n",
     "from docling_core.types.doc.document import DoclingDocument\n",
@@ -410,7 +396,7 @@
     }
    ],
    "source": [
-    "from docling_core.experimental.serializer.markdown import MarkdownParams\n",
+    "from docling_core.transforms.serializer.markdown import MarkdownParams\n",
     "\n",
     "class ImgPlaceholderSerializerProvider(ChunkingSerializerProvider):\n",
     "    def get_serializer(self, doc):\n",
@@ -456,11 +442,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from typing import Any",
+    "from typing import Any\n",
     "from typing_extensions import override\n",
-    "from docling_core.experimental.serializer.base import BaseDocSerializer, SerializationResult\n",
-    "from docling_core.experimental.serializer.common import create_ser_result\n",
-    "from docling_core.experimental.serializer.markdown import MarkdownPictureSerializer\n",
+    "from docling_core.transforms.serializer.base import BaseDocSerializer, SerializationResult\n",
+    "from docling_core.transforms.serializer.common import create_ser_result\n",
+    "from docling_core.transforms.serializer.markdown import MarkdownPictureSerializer\n",
     "from docling_core.types.doc.document import PictureClassificationData, PictureDescriptionData, PictureItem, PictureMoleculeData\n",
     "\n",
     "\n",
diff --git a/test/test_hierarchical_chunker.py b/test/test_hierarchical_chunker.py
@@ -5,13 +5,13 @@
 
 import json
 
-from docling_core.experimental.serializer.markdown import MarkdownTableSerializer
 from docling_core.transforms.chunker import HierarchicalChunker
 from docling_core.transforms.chunker.hierarchical_chunker import (
     ChunkingDocSerializer,
     ChunkingSerializerProvider,
     DocChunk,
 )
+from docling_core.transforms.serializer.markdown import MarkdownTableSerializer
 from docling_core.types.doc import DoclingDocument as DLDocument
 from docling_core.types.doc.document import DoclingDocument
 
diff --git a/test/test_hybrid_chunker.py b/test/test_hybrid_chunker.py
@@ -8,14 +8,14 @@
 import tiktoken
 from transformers import AutoTokenizer
 
-from docling_core.experimental.serializer.markdown import MarkdownTableSerializer
 from docling_core.transforms.chunker.hierarchical_chunker import (
     ChunkingDocSerializer,
     ChunkingSerializerProvider,
     DocChunk,
 )
 from docling_core.transforms.chunker.hybrid_chunker import HybridChunker
 from docling_core.transforms.chunker.tokenizer.openai import OpenAITokenizer
+from docling_core.transforms.serializer.markdown import MarkdownTableSerializer
 from docling_core.types.doc import DoclingDocument as DLDocument
 from docling_core.types.doc.document import DoclingDocument
 
diff --git a/test/test_serialization.py b/test/test_serialization.py
@@ -2,13 +2,13 @@
 
 from pathlib import Path
 
-from docling_core.experimental.serializer.common import _DEFAULT_LABELS
-from docling_core.experimental.serializer.html import (
+from docling_core.transforms.serializer.common import _DEFAULT_LABELS
+from docling_core.transforms.serializer.html import (
     HTMLDocSerializer,
     HTMLOutputStyle,
     HTMLParams,
 )
-from docling_core.experimental.serializer.markdown import (
+from docling_core.transforms.serializer.markdown import (
     MarkdownDocSerializer,
     MarkdownParams,
 )
