docling-parse 6.2.0__tar.gz → 7.2.0__tar.gz

{docling_parse-6.2.0 → docling_parse-7.2.0}/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [v7.2.0](https://github.com/docling-project/docling-parse/releases/tag/v7.2.0) - 2026-06-29
+
+### Feature
+
+* Upgrade bitmap rendering with clipping ([#284](https://github.com/docling-project/docling-parse/issues/284)) ([`b55da56`](https://github.com/docling-project/docling-parse/commit/b55da563b9eda2da30c9dead373d54656fb5f01f))
+
+## [v7.1.0](https://github.com/docling-project/docling-parse/releases/tag/v7.1.0) - 2026-06-26
+
+### Feature
+
+* Refactoring the parsing of XObjects ([#281](https://github.com/docling-project/docling-parse/issues/281)) ([`163f741`](https://github.com/docling-project/docling-parse/commit/163f7419bd6a98d7667cefe7e9c356b38135f9e8))
+
+### Documentation
+
+* Updates for docling-parse v7 usage ([#280](https://github.com/docling-project/docling-parse/issues/280)) ([`a81339e`](https://github.com/docling-project/docling-parse/commit/a81339efade7a904aac0bb64c0f871d9fbf03e1e))
+
+## [v7.0.0](https://github.com/docling-project/docling-parse/releases/tag/v7.0.0) - 2026-06-22
+
+### Feature
+
+* Improve pages/sec and scalability, new decode configuration shape ([#278](https://github.com/docling-project/docling-parse/issues/278)) ([`1d8f70c`](https://github.com/docling-project/docling-parse/commit/1d8f70cfad208d2a5bd96333ad13eaa157cf6339))
+
+### Breaking
+
+* improve pages/sec and scalability, new decode configuration shape ([#278](https://github.com/docling-project/docling-parse/issues/278)) ([`1d8f70c`](https://github.com/docling-project/docling-parse/commit/1d8f70cfad208d2a5bd96333ad13eaa157cf6339))
+
 ## [v6.2.0](https://github.com/docling-project/docling-parse/releases/tag/v6.2.0) - 2026-05-28
 
 ### Feature

{docling_parse-6.2.0 → docling_parse-7.2.0}/CMakeLists.txt

@@ -156,30 +156,35 @@ add_executable(parse.exe "${TOPLEVEL_PREFIX_PATH}/app/parse.cpp")
 add_executable(parse_fonts.exe "${TOPLEVEL_PREFIX_PATH}/app/parse_fonts.cpp")
 add_executable(render.exe "${TOPLEVEL_PREFIX_PATH}/app/render.cpp")
 add_executable(analyse.exe "${TOPLEVEL_PREFIX_PATH}/app/analyse.cpp")
+add_executable(run_scaling.exe "${TOPLEVEL_PREFIX_PATH}/app/run_scaling.cpp")
 # add_executable(page_images.exe "${TOPLEVEL_PREFIX_PATH}/app/page_images.cpp")
 
 set_property(TARGET parse.exe PROPERTY CXX_STANDARD 20)
 set_property(TARGET parse_fonts.exe PROPERTY CXX_STANDARD 20)
 set_property(TARGET render.exe PROPERTY CXX_STANDARD 20)
 set_property(TARGET analyse.exe PROPERTY CXX_STANDARD 20)
+set_property(TARGET run_scaling.exe PROPERTY CXX_STANDARD 20)
 # set_property(TARGET page_images.exe PROPERTY CXX_STANDARD 20)
 
 add_dependencies(parse.exe ${DEPENDENCIES})
 add_dependencies(parse_fonts.exe ${DEPENDENCIES})
 add_dependencies(render.exe ${DEPENDENCIES})
 add_dependencies(analyse.exe ${DEPENDENCIES})
+add_dependencies(run_scaling.exe ${DEPENDENCIES})
 # add_dependencies(page_images.exe ${DEPENDENCIES})
 
 target_include_directories(parse.exe INTERFACE ${DEPENDENCIES})
 target_include_directories(parse_fonts.exe INTERFACE ${DEPENDENCIES})
 target_include_directories(render.exe INTERFACE ${DEPENDENCIES})
 target_include_directories(analyse.exe INTERFACE ${DEPENDENCIES})
+target_include_directories(run_scaling.exe INTERFACE ${DEPENDENCIES})
 # target_include_directories(page_images.exe INTERFACE ${DEPENDENCIES})
 
 target_link_libraries(parse.exe ${DEPENDENCIES} ${LIB_LINK})
 target_link_libraries(parse_fonts.exe ${DEPENDENCIES} ${LIB_LINK})
 target_link_libraries(render.exe ${DEPENDENCIES} ${LIB_LINK})
 target_link_libraries(analyse.exe ${DEPENDENCIES} ${LIB_LINK})
+target_link_libraries(run_scaling.exe ${DEPENDENCIES} ${LIB_LINK})
 # target_link_libraries(page_images.exe ${DEPENDENCIES} ${LIB_LINK})
 
 # **********************

{docling_parse-6.2.0 → docling_parse-7.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 6.2.0
+Version: 7.2.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
@@ -23,10 +23,9 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tabulate<1.0.0,>=0.9.0
 Requires-Dist: pillow<13.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: docling-core>=2.65.2
+Requires-Dist: docling-core<3.0.0,>=2.85.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"
 Dynamic: license-file
 
@@ -88,75 +87,151 @@ uv run python ./docling_parse/visualize.py -i <path-to-pdf-file> -c word --inter
 
 ## Quick start
 
-Install the package from Pypi
+Install the package from PyPI:
 
 ```sh
 pip install docling-parse
 ```
 
-Convert a PDF (look in the [visualize.py](docling_parse/visualize.py) for a more detailed information)
+### Sequential parsing
+
+`docling-parse` v7 split page parsing into two public configs:
+
+- `DecodeConfig`: how to compute pages. This is fixed when a document is opened.
+- `ContentConfig`: what to keep or materialize per page. This can be overridden per page.
 
 ```python
 from docling_core.types.doc.page import TextCellUnit
-from docling_parse.pdf_parser import DoclingPdfParser, PdfDocument
-
-parser = DoclingPdfParser()
+from docling_parse.pdf_parser import (
+    ContentConfig,
+    ContentLevel,
+    DecodeConfig,
+    DoclingPdfParser,
+)
 
-pdf_doc: PdfDocument = parser.load(
-    path_or_stream="<path-to-pdf>"
+parser = DoclingPdfParser(loglevel="fatal")
+
+pdf_doc = parser.load(
+    path_or_stream="<path-to-pdf>",
+    decode_config=DecodeConfig(
+        do_sanitization=True,
+        keep_glyphs=False,
+    ),
+    content_config=ContentConfig(
+        char_cells_content_level=ContentLevel.SKIP,
+        word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        shapes_content_level=ContentLevel.SKIP,
+        bitmaps_content_level=ContentLevel.SKIP,
+    ),
 )
 
-# PdfDocument.iterate_pages() will automatically populate pages as they are yielded.
-for page_no, pred_page in pdf_doc.iterate_pages():
+for page_no, page in pdf_doc.iterate_pages():
+    print(page_no, len(page.word_cells), len(page.textline_cells))
 
-    # iterate over the word-cells
-    for word in pred_page.iterate_cells(unit_type=TextCellUnit.WORD):
-        print(word.rect, ": ", word.text)
+    for word in page.iterate_cells(unit_type=TextCellUnit.WORD):
+        print(word.rect, word.text)
 
-        # create a PIL image with the char cells
-    img = pred_page.render_as_image(cell_unit=TextCellUnit.CHAR)
-    img.show()
+    image = page.render_as_image(cell_unit=TextCellUnit.WORD)
+    image.show()
 ```
 
+If you open cheaply and later need richer output, request it per page. When the
+new `content_config` needs entities that were previously skipped, that page is
+re-decoded automatically:
+
+```python
+from docling_parse.pdf_parser import ContentConfig, ContentLevel
+
+page = pdf_doc.get_page(
+    1,
+    content_config=ContentConfig(
+        word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+    ),
+)
+```
+
+### v6 -> v7 migration
+
+The main API break in v7 is that the old public `DecodePageConfig` selection
+flags were split into two concerns:
+
+- `DecodeConfig`: compute-time tuning only
+- `ContentConfig`: what to skip, compute, or materialize per page
+
+In practice:
+
+- open-time `decode_config` replaces the old per-page decode tuning
+- per-page content selection now lives in `content_config`
+- `materialize_bitmap_bytes` became `include_bitmap_bytes`
+- threaded `page_materialization_config` became `page_content_config`
+
+Typical migration examples:
+
+- old `DecodePageConfig.keep_char_cells=True` -> `ContentConfig(char_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE)`
+- old `DecodePageConfig.create_word_cells=True` without surfacing them everywhere -> `ContentConfig(word_cells_content_level=ContentLevel.COMPUTE)`
+- old `materialize_bitmap_bytes=False` -> `ContentConfig(include_bitmap_bytes=False)`
+
+One semantic change matters: `decode_config` is now fixed when the document or
+threaded batch is opened. If you want richer page output later, override
+`content_config` on `get_page(...)` instead. On the sequential path this may
+re-decode that page; on the threaded path you can only materialize entities the
+batch already computed.
+
 ### Parallel parsing (multi-threaded)
 
-Parse pages from one or more PDFs in parallel using a thread pool with backpressure:
+Parse one or more PDFs in parallel with backpressure:
 
 ```python
 from docling_parse.pdf_parser import (
+    ContentConfig,
+    ContentLevel,
+    DecodeConfig,
     DoclingThreadedPdfParser,
     ThreadedPdfParserConfig,
 )
-from docling_parse.pdf_parsers import DecodePageConfig  # type: ignore[import]
-
-parser_config = ThreadedPdfParserConfig(
-    loglevel="fatal",
-    threads=4,                # worker threads
-    max_concurrent_results=32 # cap buffered results to limit memory
-)
-decode_config = DecodePageConfig()
 
 parser = DoclingThreadedPdfParser(
-    parser_config=parser_config,
-    decode_config=decode_config,
+    parser_config=ThreadedPdfParserConfig(
+        loglevel="fatal",
+        threads=4,
+        max_concurrent_results=32,
+        page_content_config=ContentConfig(
+            word_cells_content_level=ContentLevel.COMPUTE,
+            line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        ),
+    ),
+    decode_config=DecodeConfig(),
 )
 
-# load one or more documents
-for source in ["doc_a.pdf", "doc_b.pdf"]:
-    doc_key = parser.load(source)
-    print(doc_key, parser.page_count(doc_key))
+doc_key = parser.load("doc_a.pdf", page_numbers=[1, 3, 5])
+print(doc_key, parser.page_count(doc_key), parser.scheduled_page_count(doc_key))
 
-# consume decoded pages as they become available
 for result in parser.iterate_results():
-    if result.success:
-        seg_page = result.get_page()
-        timings = result.get_timings()
-        print(f"{result.doc_key} p{result.page_number}: "
-              f"{len(seg_page.word_cells)} words in {timings.total():.3f}s")
-    else:
-        print(f"error on {result.doc_key} p{result.page_number}: {result.error_message}")
+    if not result.success:
+        print(result.doc_key, result.page_number, result.error_message)
+        continue
+
+    # Batch decode kept word cells in C++, but did not materialize them by default.
+    page = result.get_page(
+        ContentConfig(
+            word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+            line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        )
+    )
+    print(
+        result.doc_key,
+        result.page_number,
+        len(page.word_cells),
+        result.timings.total_s,
+    )
 ```
 
+For threaded parse-and-render workloads, set
+`ThreadedPdfParserConfig.render_config` and use `result.get_image()`,
+`result.get_image(scale=...)`, or `result.get_image(canvas_size=...)`.
+
 Use the CLI
 
 ```sh
@@ -172,7 +247,11 @@ options:
 
 ## Performance Benchmarks
 
-*Coming soon - benchmarks will be updated for the current parser version.*
+Current perf tooling lives under [`perf/`](./perf/README.md):
+
+- [`perf/run_perf.py`](./perf/run_perf.py): per-page CSV benchmarking across `docling`, `docling-threaded`, `pdfplumber`, `pypdfium2`, and `pymupdf`
+- [`perf/run_scaling.py`](./perf/run_scaling.py): pages/sec and scaling sweeps for threaded parse and render workloads
+- [`docs/performance_code.md`](./docs/performance_code.md): usage notes and interpretation
 
 For historical V1 vs V2 benchmarks, see [legacy_performance_benchmarks.md](./docs/legacy_performance_benchmarks.md).
 
@@ -223,6 +302,12 @@ The latter will only work after a clean `git clone`. If you are developing and u
 rm -rf .venv; uv venv; uv pip install --force-reinstall --no-deps -e ".[perf-tools]"
 ```
 
+or 
+
+```sh
+BUILD_THREADS=12 uv pip install --force-reinstall --no-deps -e ".[perf]"
+```
+
 To test the package, run:
 
 ```sh

{docling_parse-6.2.0 → docling_parse-7.2.0}/README.md

@@ -56,75 +56,151 @@ uv run python ./docling_parse/visualize.py -i <path-to-pdf-file> -c word --inter
 
 ## Quick start
 
-Install the package from Pypi
+Install the package from PyPI:
 
 ```sh
 pip install docling-parse
 ```
 
-Convert a PDF (look in the [visualize.py](docling_parse/visualize.py) for a more detailed information)
+### Sequential parsing
+
+`docling-parse` v7 split page parsing into two public configs:
+
+- `DecodeConfig`: how to compute pages. This is fixed when a document is opened.
+- `ContentConfig`: what to keep or materialize per page. This can be overridden per page.
 
 ```python
 from docling_core.types.doc.page import TextCellUnit
-from docling_parse.pdf_parser import DoclingPdfParser, PdfDocument
-
-parser = DoclingPdfParser()
+from docling_parse.pdf_parser import (
+    ContentConfig,
+    ContentLevel,
+    DecodeConfig,
+    DoclingPdfParser,
+)
 
-pdf_doc: PdfDocument = parser.load(
-    path_or_stream="<path-to-pdf>"
+parser = DoclingPdfParser(loglevel="fatal")
+
+pdf_doc = parser.load(
+    path_or_stream="<path-to-pdf>",
+    decode_config=DecodeConfig(
+        do_sanitization=True,
+        keep_glyphs=False,
+    ),
+    content_config=ContentConfig(
+        char_cells_content_level=ContentLevel.SKIP,
+        word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        shapes_content_level=ContentLevel.SKIP,
+        bitmaps_content_level=ContentLevel.SKIP,
+    ),
 )
 
-# PdfDocument.iterate_pages() will automatically populate pages as they are yielded.
-for page_no, pred_page in pdf_doc.iterate_pages():
+for page_no, page in pdf_doc.iterate_pages():
+    print(page_no, len(page.word_cells), len(page.textline_cells))
 
-    # iterate over the word-cells
-    for word in pred_page.iterate_cells(unit_type=TextCellUnit.WORD):
-        print(word.rect, ": ", word.text)
+    for word in page.iterate_cells(unit_type=TextCellUnit.WORD):
+        print(word.rect, word.text)
 
-        # create a PIL image with the char cells
-    img = pred_page.render_as_image(cell_unit=TextCellUnit.CHAR)
-    img.show()
+    image = page.render_as_image(cell_unit=TextCellUnit.WORD)
+    image.show()
 ```
 
+If you open cheaply and later need richer output, request it per page. When the
+new `content_config` needs entities that were previously skipped, that page is
+re-decoded automatically:
+
+```python
+from docling_parse.pdf_parser import ContentConfig, ContentLevel
+
+page = pdf_doc.get_page(
+    1,
+    content_config=ContentConfig(
+        word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+    ),
+)
+```
+
+### v6 -> v7 migration
+
+The main API break in v7 is that the old public `DecodePageConfig` selection
+flags were split into two concerns:
+
+- `DecodeConfig`: compute-time tuning only
+- `ContentConfig`: what to skip, compute, or materialize per page
+
+In practice:
+
+- open-time `decode_config` replaces the old per-page decode tuning
+- per-page content selection now lives in `content_config`
+- `materialize_bitmap_bytes` became `include_bitmap_bytes`
+- threaded `page_materialization_config` became `page_content_config`
+
+Typical migration examples:
+
+- old `DecodePageConfig.keep_char_cells=True` -> `ContentConfig(char_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE)`
+- old `DecodePageConfig.create_word_cells=True` without surfacing them everywhere -> `ContentConfig(word_cells_content_level=ContentLevel.COMPUTE)`
+- old `materialize_bitmap_bytes=False` -> `ContentConfig(include_bitmap_bytes=False)`
+
+One semantic change matters: `decode_config` is now fixed when the document or
+threaded batch is opened. If you want richer page output later, override
+`content_config` on `get_page(...)` instead. On the sequential path this may
+re-decode that page; on the threaded path you can only materialize entities the
+batch already computed.
+
 ### Parallel parsing (multi-threaded)
 
-Parse pages from one or more PDFs in parallel using a thread pool with backpressure:
+Parse one or more PDFs in parallel with backpressure:
 
 ```python
 from docling_parse.pdf_parser import (
+    ContentConfig,
+    ContentLevel,
+    DecodeConfig,
     DoclingThreadedPdfParser,
     ThreadedPdfParserConfig,
 )
-from docling_parse.pdf_parsers import DecodePageConfig  # type: ignore[import]
-
-parser_config = ThreadedPdfParserConfig(
-    loglevel="fatal",
-    threads=4,                # worker threads
-    max_concurrent_results=32 # cap buffered results to limit memory
-)
-decode_config = DecodePageConfig()
 
 parser = DoclingThreadedPdfParser(
-    parser_config=parser_config,
-    decode_config=decode_config,
+    parser_config=ThreadedPdfParserConfig(
+        loglevel="fatal",
+        threads=4,
+        max_concurrent_results=32,
+        page_content_config=ContentConfig(
+            word_cells_content_level=ContentLevel.COMPUTE,
+            line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        ),
+    ),
+    decode_config=DecodeConfig(),
 )
 
-# load one or more documents
-for source in ["doc_a.pdf", "doc_b.pdf"]:
-    doc_key = parser.load(source)
-    print(doc_key, parser.page_count(doc_key))
+doc_key = parser.load("doc_a.pdf", page_numbers=[1, 3, 5])
+print(doc_key, parser.page_count(doc_key), parser.scheduled_page_count(doc_key))
 
-# consume decoded pages as they become available
 for result in parser.iterate_results():
-    if result.success:
-        seg_page = result.get_page()
-        timings = result.get_timings()
-        print(f"{result.doc_key} p{result.page_number}: "
-              f"{len(seg_page.word_cells)} words in {timings.total():.3f}s")
-    else:
-        print(f"error on {result.doc_key} p{result.page_number}: {result.error_message}")
+    if not result.success:
+        print(result.doc_key, result.page_number, result.error_message)
+        continue
+
+    # Batch decode kept word cells in C++, but did not materialize them by default.
+    page = result.get_page(
+        ContentConfig(
+            word_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+            line_cells_content_level=ContentLevel.COMPUTE_AND_MATERIALIZE,
+        )
+    )
+    print(
+        result.doc_key,
+        result.page_number,
+        len(page.word_cells),
+        result.timings.total_s,
+    )
 ```
 
+For threaded parse-and-render workloads, set
+`ThreadedPdfParserConfig.render_config` and use `result.get_image()`,
+`result.get_image(scale=...)`, or `result.get_image(canvas_size=...)`.
+
 Use the CLI
 
 ```sh
@@ -140,7 +216,11 @@ options:
 
 ## Performance Benchmarks
 
-*Coming soon - benchmarks will be updated for the current parser version.*
+Current perf tooling lives under [`perf/`](./perf/README.md):
+
+- [`perf/run_perf.py`](./perf/run_perf.py): per-page CSV benchmarking across `docling`, `docling-threaded`, `pdfplumber`, `pypdfium2`, and `pymupdf`
+- [`perf/run_scaling.py`](./perf/run_scaling.py): pages/sec and scaling sweeps for threaded parse and render workloads
+- [`docs/performance_code.md`](./docs/performance_code.md): usage notes and interpretation
 
 For historical V1 vs V2 benchmarks, see [legacy_performance_benchmarks.md](./docs/legacy_performance_benchmarks.md).
 
@@ -191,6 +271,12 @@ The latter will only work after a clean `git clone`. If you are developing and u
 rm -rf .venv; uv venv; uv pip install --force-reinstall --no-deps -e ".[perf-tools]"
 ```
 
+or 
+
+```sh
+BUILD_THREADS=12 uv pip install --force-reinstall --no-deps -e ".[perf]"
+```
+
 To test the package, run:
 
 ```sh

{docling_parse-6.2.0 → docling_parse-7.2.0}/app/parse.cpp

@@ -208,15 +208,9 @@ int main(int argc, char* argv[]) {
       parser.parse(config_file, page_config);
 
       double total_time = timer.get_time();
-      std::cout << "\ntimings:\n";
-      for(const auto& [key, val] : parser.get_timings())
-        {
-          if(pdflib::pdf_timings::is_static_key(key))
-            {
-              std::cout << "  " << std::setw(48) << std::left << key << val << " [sec]\n";
-            }
-        }
-      std::cout << std::setw(48) << std::left << "  total-time" << total_time << " [sec]" << std::endl;
+      std::cout << "\ntimings:\n"
+                << pdflib::pdf_timings::format_tree_table(parser.get_timings(), total_time)
+                << std::endl;
 
       return 0;
     }
@@ -267,15 +261,9 @@ int main(int argc, char* argv[]) {
       parser.parse(config, page_config);
 
       double total_time = timer.get_time();
-      std::cout << "\ntimings:\n";
-      for(const auto& [key, val] : parser.get_timings())
-        {
-          if(pdflib::pdf_timings::is_static_key(key))
-            {
-              std::cout << "  " << std::setw(48) << std::left << key << val << " [sec]\n";
-            }
-        }
-      std::cout << std::setw(48) << std::left << "  total-time" << total_time << " [sec]" << std::endl;
+      std::cout << "\ntimings:\n"
+                << pdflib::pdf_timings::format_tree_table(parser.get_timings(), total_time)
+                << std::endl;
 
       if (result.count("print-cells")) {
         std::string mode = result["print-cells"].as<std::string>();