docling-parse 7.18.0__tar.gz → 7.19.0__tar.gz

{docling_parse-7.18.0 → docling_parse-7.19.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [v7.19.0](https://github.com/docling-project/docling-parse/releases/tag/v7.19.0) - 2026-09-10
+
+### Feature
+
+* Adding static page-count methods ([#346](https://github.com/docling-project/docling-parse/issues/346)) ([`b36d823`](https://github.com/docling-project/docling-parse/commit/b36d8238cc7bb0bf0249d09b8b1999857c489fe7))
+
 ## [v7.18.0](https://github.com/docling-project/docling-parse/releases/tag/v7.18.0) - 2026-09-08
 
 ### Feature

{docling_parse-7.18.0 → docling_parse-7.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.18.0
+Version: 7.19.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

{docling_parse-7.18.0 → docling_parse-7.19.0}/app/pybind_parse.cpp

@@ -15,6 +15,9 @@
 // Include parse headers for typed bindings
 #include <parse.h>
 
+// Include edit headers for the lightweight, document-less helpers
+#include <edit.h>
+
 namespace
 {
   const char* pixel_format_name(pdflib::pixel_format fmt)
@@ -751,6 +754,62 @@ PYBIND11_MODULE(pdf_parsers, m) {
         level (str): Logging level as a string.
                      One of ['fatal', 'error', 'warning', 'info'])")
     
+    .def_static("get_number_of_pages",
+	 [](const std::string& filename,
+	    std::optional<std::string> password,
+	    bool keep_qpdf_warnings) -> int {
+	   std::string filename_ = filename;
+	   return pdflib::pdf_editor_tools::get_number_of_pages(filename_,
+								password,
+								keep_qpdf_warnings);
+	 },
+	 pybind11::arg("filename"),
+	 pybind11::arg("password") = pybind11::none(),
+	 pybind11::arg("keep_qpdf_warnings") = false,
+	 R"(
+    Get the number of pages of a PDF file without loading the document.
+
+    Parameters:
+        filename (str): Path to the PDF file.
+        password (str, optional): Password of the document.
+        keep_qpdf_warnings (bool): If true, QPDF warnings are emitted [default=False].
+
+    Returns:
+        int: The number of pages, or -1 if the document could not be read.)")
+
+    .def_static("get_number_of_pages_from_bytesio",
+	 [](pybind11::object bytes_io,
+	    std::optional<std::string> password,
+	    bool keep_qpdf_warnings) -> int {
+	   if(not pybind11::hasattr(bytes_io, "read"))
+	     {
+	       throw std::runtime_error("Expected a BytesIO object");
+	     }
+
+	   bytes_io.attr("seek")(0);
+	   pybind11::bytes data = bytes_io.attr("read")();
+
+	   auto data_buffer = std::make_shared<std::string>(data.cast<std::string>());
+
+	   return pdflib::pdf_editor_tools::get_number_of_pages(data_buffer,
+								password,
+								"counting pages from bytesio",
+								keep_qpdf_warnings);
+	 },
+	 pybind11::arg("bytes_io"),
+	 pybind11::arg("password") = pybind11::none(),
+	 pybind11::arg("keep_qpdf_warnings") = false,
+	 R"(
+    Get the number of pages of a PDF held in a BytesIO object without loading the document.
+
+    Parameters:
+        bytes_io (BytesIO): The PDF document as a BytesIO object.
+        password (str, optional): Password of the document.
+        keep_qpdf_warnings (bool): If true, QPDF warnings are emitted [default=False].
+
+    Returns:
+        int: The number of pages, or -1 if the document could not be read.)")
+
     .def("set_loglevel_with_label",
 	 [](docling::docling_parser &self, const std::string &level) -> void {
             self.set_loglevel_with_label(level);

{docling_parse-7.18.0 → docling_parse-7.19.0}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.18.0
+Version: 7.19.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

{docling_parse-7.18.0 → docling_parse-7.19.0}/docling_parse.egg-info/SOURCES.txt

@@ -484,9 +484,11 @@ docling_parse/pdf_resources/glyphs/standard/glyphlist.dat
 docling_parse/pdf_resources/glyphs/standard/missing.dat
 docling_parse/pdf_resources/glyphs/standard/scripts.dat
 docling_parse/pdf_resources/glyphs/standard/zapfdingbats.dat
+src/edit.h
 src/parse.h
 src/render.h
 src/resources.h
+src/edit/editor.h
 src/parse/config.h
 src/parse/enums.h
 src/parse/page_item.h
@@ -700,6 +702,7 @@ tests/test_unit_glyph_proportions.py
 tests/test_unit_indexed_images.py
 tests/test_unit_jpeg_images.py
 tests/test_unit_load_failure.py
+tests/test_unit_page_count.py
 tests/test_unit_patterns.py
 tests/test_unit_shading.py
 tests/test_unit_shadings.py

{docling_parse-7.18.0 → docling_parse-7.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-parse"
-version = "7.18.0"
+version = "7.19.0"
 description = "Simple package to extract text with coordinates from programmatic PDFs"
 license = "MIT"
 keywords = ["docling", "pdf", "parser"]

docling_parse-7.19.0/src/edit/editor.h

@@ -0,0 +1,107 @@
+//-*-C++-*-
+
+#ifndef PDF_DOCUMENT_EDITOR_H
+#define PDF_DOCUMENT_EDITOR_H
+
+#include <memory>
+#include <optional>
+#include <string>
+
+#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF
+#include <qpdf/QPDF.hh>
+
+#define LOGURU_WITH_STREAMS 1
+#include <loguru.hpp>
+
+namespace pdflib
+{
+
+  class pdf_editor_tools
+  {
+    
+  public:
+
+    static int get_number_of_pages(std::string& _filename,
+                                    std::optional<std::string>& _password,
+                                    bool keep_qpdf_warnings = false);
+
+    static int get_number_of_pages(std::shared_ptr<std::string> _buffer,
+				   std::optional<std::string>& _password,
+				   std::string description = "processing buffer",
+				   bool keep_qpdf_warnings = false);    
+  };
+
+  int pdf_editor_tools::get_number_of_pages(std::string& _filename,
+                                    std::optional<std::string>& _password,
+                                    bool keep_qpdf_warnings)
+  {
+    QPDF qpdf_document;
+
+    try
+      {
+        qpdf_document.setSuppressWarnings(not keep_qpdf_warnings);
+
+        // qpdf opens the file itself: the filename arrives UTF-8 encoded from the
+        // Python layer and processFile is UTF-8 aware on every platform. It also
+        // reads lazily, so only the page tree is touched here.
+        if(_password.has_value())
+          {
+            qpdf_document.processFile(_filename.c_str(), _password.value().c_str());
+          }
+        else
+          {
+            qpdf_document.processFile(_filename.c_str());
+          }
+
+        return qpdf_document.getAllPages().size();
+      }
+    catch(const std::exception& exc)
+      {
+        LOG_S(ERROR) << "could not process file '" << _filename << "' by qpdf: " << exc.what();
+        return -1;
+      }
+  }
+
+  int pdf_editor_tools::get_number_of_pages(std::shared_ptr<std::string> _buffer,
+				      std::optional<std::string>& _password,
+				      std::string description,
+				      bool keep_qpdf_warnings)
+  {
+    if(_buffer==nullptr)
+      {
+        LOG_S(ERROR) << "no buffer provided for '" << description << "'";
+        return -1;
+      }
+
+    QPDF qpdf_document;
+
+    try
+      {
+        qpdf_document.setSuppressWarnings(not keep_qpdf_warnings);
+
+        if(_password.has_value())
+          {
+            qpdf_document.processMemoryFile(description.c_str(),
+                                            _buffer->c_str(),
+                                            _buffer->size(),
+                                            _password.value().c_str());
+          }
+        else
+          {
+            qpdf_document.processMemoryFile(description.c_str(),
+                                            _buffer->c_str(),
+                                            _buffer->size());
+          }
+
+        return qpdf_document.getAllPages().size();
+      }
+    catch(const std::exception& exc)
+      {
+        LOG_S(ERROR) << "could not process buffer for '" << description << "' by qpdf: " << exc.what();
+        return -1;
+      }
+  }
+
+}
+
+#endif

docling_parse-7.19.0/src/edit.h

@@ -0,0 +1,3 @@
+//-*-C++-*-
+
+#include <edit/editor.h>

docling_parse-7.19.0/tests/test_unit_page_count.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python
+"""Counting pages must not require loading the document.
+
+`pdf_parser.get_number_of_pages` and `get_number_of_pages_from_bytesio` are
+static: they open a local QPDF, walk the page tree and drop it again, without
+registering a decoder or touching any page content. The point is that callers
+who only need the page count pay for the page tree and nothing else, so the
+tests here check the count itself, that a broken document reports the -1
+sentinel rather than raising, and that the count agrees with what a full load
+reports for the same bytes.
+"""
+
+from io import BytesIO
+from pathlib import Path
+
+import pytest
+from docling_parse.pdf_parsers import pdf_parser  # type: ignore[import]
+
+from docling_parse.pdf_parser import DoclingPdfParser
+from tests.pdf_builder import build_pdf, content_stream
+
+GARBAGE = b"%PDF-1.4\nthis is not a valid pdf at all"
+
+PAGE_COUNTS = [1, 3, 7]
+
+
+@pytest.fixture(autouse=True)
+def quiet_logging():
+    """Silence the qpdf/loguru error stream of the deliberately broken fixtures.
+
+    loguru's verbosity is process-global and the static counters have no
+    instance to configure, so a parser is constructed purely for its side
+    effect on that global.
+    """
+    DoclingPdfParser(loglevel="fatal")
+
+
+def multi_page_pdf(number_of_pages: int) -> bytes:
+    """A document of `number_of_pages` flat pages, each with its own content.
+
+    Objects: 1 catalog, 2 page-tree root, 3..2+N the pages, 3+N..2+2N their
+    content streams.
+    """
+    first_page = 3
+    first_content = first_page + number_of_pages
+
+    kids = " ".join(f"{first_page + i} 0 R" for i in range(number_of_pages))
+    objects: list[str | bytes] = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        f"<< /Type /Pages /Kids [{kids}] /Count {number_of_pages} >>",
+    ]
+    objects.extend(
+        f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] "
+        f"/Contents {first_content + i} 0 R >>"
+        for i in range(number_of_pages)
+    )
+    objects.extend(
+        content_stream(f"0 0 1 rg 10 {10 + 10 * i} 50 20 re f")
+        for i in range(number_of_pages)
+    )
+    return build_pdf(objects)
+
+
+def nested_page_tree_pdf() -> bytes:
+    """Three pages behind two intermediate /Pages nodes, with a lying /Count.
+
+    The count comes from walking the tree (as qpdf's getAllPages does), not
+    from trusting /Count on the root, and this fixture is the difference: a
+    reader of /Count alone answers 99.
+    """
+    objects: list[str | bytes] = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        "<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 99 >>",
+        "<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 >>",
+        "<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 >>",
+        "<< /Type /Page /Parent 3 0 R /MediaBox [0 0 200 200] /Contents 8 0 R >>",
+        "<< /Type /Page /Parent 3 0 R /MediaBox [0 0 200 200] /Contents 8 0 R >>",
+        "<< /Type /Page /Parent 4 0 R /MediaBox [0 0 200 200] /Contents 8 0 R >>",
+        content_stream("0 0 1 rg 10 10 50 20 re f"),
+    ]
+    return build_pdf(objects)
+
+
+def write_pdf(tmp_path: Path, name: str, payload: bytes) -> str:
+    path = tmp_path / name
+    path.write_bytes(payload)
+    return str(path)
+
+
+@pytest.mark.parametrize("number_of_pages", PAGE_COUNTS)
+def test_page_count_from_file(tmp_path, number_of_pages):
+    filename = write_pdf(
+        tmp_path, f"{number_of_pages}p.pdf", multi_page_pdf(number_of_pages)
+    )
+
+    assert pdf_parser.get_number_of_pages(filename) == number_of_pages
+
+
+@pytest.mark.parametrize("number_of_pages", PAGE_COUNTS)
+def test_page_count_from_bytesio(number_of_pages):
+    stream = BytesIO(multi_page_pdf(number_of_pages))
+
+    assert pdf_parser.get_number_of_pages_from_bytesio(stream) == number_of_pages
+
+
+@pytest.mark.parametrize("number_of_pages", PAGE_COUNTS)
+def test_matches_a_full_load(number_of_pages):
+    """The cheap count and the loaded document must never disagree."""
+    payload = multi_page_pdf(number_of_pages)
+
+    parser = DoclingPdfParser(loglevel="fatal")
+    doc = parser.load(path_or_stream=BytesIO(payload))
+
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(payload)) == (
+        doc.number_of_pages()
+    )
+
+
+def test_file_and_bytesio_agree(tmp_path):
+    payload = multi_page_pdf(4)
+    filename = write_pdf(tmp_path, "four.pdf", payload)
+
+    assert pdf_parser.get_number_of_pages(filename) == 4
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(payload)) == 4
+
+
+def test_nested_page_tree_is_walked():
+    assert (
+        pdf_parser.get_number_of_pages_from_bytesio(BytesIO(nested_page_tree_pdf()))
+        == 3
+    )
+
+
+def test_counting_leaves_the_parser_untouched():
+    """No decoder is registered: the static call has no document state."""
+    parser = DoclingPdfParser(loglevel="fatal")
+
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(multi_page_pdf(2))) == 2
+    assert parser.list_loaded_keys() == []
+
+
+def test_bytesio_is_rewound_before_reading():
+    """A stream already read to the end is still counted, and the caller's own
+    read position is not what the count depends on."""
+    stream = BytesIO(multi_page_pdf(3))
+    stream.read()
+
+    assert pdf_parser.get_number_of_pages_from_bytesio(stream) == 3
+
+
+def test_garbage_file_returns_the_sentinel(tmp_path):
+    filename = write_pdf(tmp_path, "garbage.pdf", GARBAGE)
+
+    assert pdf_parser.get_number_of_pages(filename) == -1
+
+
+def test_garbage_bytesio_returns_the_sentinel():
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(GARBAGE)) == -1
+
+
+def test_missing_file_returns_the_sentinel(tmp_path):
+    assert pdf_parser.get_number_of_pages(str(tmp_path / "does-not-exist.pdf")) == -1
+
+
+def test_empty_bytesio_returns_the_sentinel():
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(b"")) == -1
+
+
+def test_non_stream_argument_raises():
+    """bytes has no read(): that is a caller error, not a broken document."""
+    with pytest.raises(RuntimeError, match="Expected a BytesIO object"):
+        pdf_parser.get_number_of_pages_from_bytesio(multi_page_pdf(1))
+
+
+def test_unicode_filename(tmp_path):
+    """The filename reaches qpdf as UTF-8 (docling-parse#324)."""
+    filename = write_pdf(tmp_path, "página-ünïcode-文書.pdf", multi_page_pdf(2))
+
+    assert pdf_parser.get_number_of_pages(filename) == 2
+
+
+def _encrypted_pdf(password: str, number_of_pages: int) -> bytes:
+    pypdf = pytest.importorskip("pypdf", reason="pypdf writes the encrypted fixture")
+
+    writer = pypdf.PdfWriter(clone_from=BytesIO(multi_page_pdf(number_of_pages)))
+    writer.encrypt(password)
+
+    out = BytesIO()
+    writer.write(out)
+    return out.getvalue()
+
+
+def test_encrypted_document_with_password(tmp_path):
+    payload = _encrypted_pdf("secret", 3)
+    filename = write_pdf(tmp_path, "encrypted.pdf", payload)
+
+    assert pdf_parser.get_number_of_pages(filename, password="secret") == 3
+    assert (
+        pdf_parser.get_number_of_pages_from_bytesio(BytesIO(payload), password="secret")
+        == 3
+    )
+
+
+def test_encrypted_document_without_password(tmp_path):
+    payload = _encrypted_pdf("secret", 3)
+    filename = write_pdf(tmp_path, "encrypted.pdf", payload)
+
+    assert pdf_parser.get_number_of_pages(filename) == -1
+    assert pdf_parser.get_number_of_pages_from_bytesio(BytesIO(payload)) == -1

{docling_parse-7.18.0 → docling_parse-7.19.0}/uv.lock

@@ -702,7 +702,7 @@ wheels = [
 
 [[package]]
 name = "docling-parse"
-version = "7.18.0"
+version = "7.19.0"
 source = { editable = "." }
 dependencies = [
     { name = "docling-core" },