diff --git a/.plans/active/reduce-memory-footprint.md b/.plans/completed/reduce-memory-footprint.md similarity index 100% rename from .plans/active/reduce-memory-footprint.md rename to .plans/completed/reduce-memory-footprint.md diff --git a/.plans/active/regression_15424333971388669153-2_findings.md b/.plans/completed/regression_15424333971388669153-2_findings.md similarity index 100% rename from .plans/active/regression_15424333971388669153-2_findings.md rename to .plans/completed/regression_15424333971388669153-2_findings.md diff --git a/.plans/active/render-scaling-iteration-plan.md b/.plans/completed/render-scaling-iteration-plan.md similarity index 100% rename from .plans/active/render-scaling-iteration-plan.md rename to .plans/completed/render-scaling-iteration-plan.md diff --git a/.plans/active/resolve-bookmarks-using-page-aware-PDF-outlines.md b/.plans/completed/resolve-bookmarks-using-page-aware-PDF-outlines.md similarity index 100% rename from .plans/active/resolve-bookmarks-using-page-aware-PDF-outlines.md rename to .plans/completed/resolve-bookmarks-using-page-aware-PDF-outlines.md diff --git a/README.md b/README.md index c8e15165a..f14292d22 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,38 @@ options: -p PDF, --pdf PDF Path to the PDF file ``` +## PDF reading and editing + +`PdfReader`, `PdfWriter` and `PdfEditor` read, assemble and change PDF files. +Reader and Writer adapt the implemented pypdf workflows; Editor provides named +arguments, one-based page numbers and rendering. + +```python +from docling_parse import PdfEditor, PdfReader, PdfWriter + +# read +with PdfReader("document.pdf") as reader: + print(len(reader.pages), reader.metadata.get("Title")) + text = reader.pages[0].extract_text() + +# merge +writer = PdfWriter() +writer.append("file1.pdf") +writer.append("file2.pdf", pages=[0, 2]) +writer.write("merged.pdf") + +# edit and save +with PdfEditor(source="document.pdf") as editor: + editor.get_page(page_no=1).rotate(angle=90) + editor.remove_page(page_no=4) + editor.render_page(page_no=1, scale=2.0).save("preview.png") + editor.write(target="changed.pdf") +``` + +See [the editing guide](./docs/editing.md) for API coverage, numbering rules and +pypdf migration differences, with recipes for [pages](./docs/editing/pages.md), +[forms](./docs/editing/forms.md) and [rendering](./docs/editing/rendering.md). + ## System fonts A PDF may name a font without embedding it. There is then nothing in the file diff --git a/app/pybind_parse.cpp b/app/pybind_parse.cpp index 33305b0d5..58ef748ba 100644 --- a/app/pybind_parse.cpp +++ b/app/pybind_parse.cpp @@ -18,6 +18,10 @@ // Include edit headers for the lightweight, document-less helpers #include +// pdf_reader, pdf_writer and pdf_editor: all of their bindings live in this +// header, so this file only has to register them +#include + namespace { const char* pixel_format_name(pdflib::pixel_format fmt) @@ -1565,4 +1569,8 @@ PYBIND11_MODULE(pdf_parsers, m) { Returns: _PageRenderResult: The result of a page rendering task.)"); + + // ============= PDF Reader / Writer / Editor ============= + + docling::register_edit_bindings(m); } diff --git a/docling_parse/__init__.py b/docling_parse/__init__.py index 13c242869..5d2ba373b 100644 --- a/docling_parse/__init__.py +++ b/docling_parse/__init__.py @@ -40,3 +40,23 @@ def _ensure_safe_numeric_locale() -> None: _ensure_safe_numeric_locale() + +# PdfReader, PdfWriter and PdfEditor are importable from the package, but only +# loaded on first use: `import docling_parse` stays as cheap as before. +_LAZY_EXPORTS = { + "PdfReader": "docling_parse.pdf_reader", + "PdfWriter": "docling_parse.pdf_writer", + "PdfEditor": "docling_parse.pdf_editor", +} + + +def __getattr__(name: str): + module_name = _LAZY_EXPORTS.get(name) + if module_name is None: + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + import importlib + + value = getattr(importlib.import_module(module_name), name) + globals()[name] = value + return value diff --git a/docling_parse/_pdf_compat.py b/docling_parse/_pdf_compat.py new file mode 100644 index 000000000..41dcc70a2 --- /dev/null +++ b/docling_parse/_pdf_compat.py @@ -0,0 +1,570 @@ +"""Signature adapters; all document operations are implemented by PdfEditor. + +The native subset still enforces reader immutability. Each adapter invokes a +named editor operation against the same native object, without cloning it. +""" + +from __future__ import annotations + +import os +from collections.abc import Iterable, Sequence +from dataclasses import dataclass +from typing import Any, BinaryIO + +from docling_parse._pdf_document import ( + _UNSET, + PdfEditablePage, + PdfPage, + _pdf_images, + _PdfDocument, + _PdfEditing, +) +from docling_parse.pdf_editor import PdfEditor + + +@dataclass(frozen=True) +class _Fit: + fit_type: str = "/Fit" + fit_args: tuple[float | None, ...] = () + + +_DEFAULT_FIT = _Fit() + + +class _PdfReaderCompat(_PdfDocument): + @property + def _editor(self) -> PdfEditor: + editor = object.__new__(PdfEditor) + editor._native = self._native + editor._page_owner = self + return editor + + def _compat_page_no(self, index: int, *, insertion: bool = False) -> int: + count = len(self.pages) + resolved = index + count if index < 0 else index + maximum = count if insertion else count - 1 + if not 0 <= resolved <= maximum: + raise IndexError(f"page index {index} out of range") + return resolved + 1 + + def get_page(self, page_number: int) -> PdfPage: + return self._editor.get_page( + page_no=self._compat_page_no(page_number, insertion=False) + ) + + def get_page_number(self, page: PdfPage) -> int: + return self._editor.get_page_no(page=page) - 1 + + def get_pages_showing_field(self, field: Any) -> list[PdfPage]: + return self._editor._compat_pages_showing_field(field=field) + + def get_fields( + self, + tree=None, + retval=None, + fileobj=None, + stack=_UNSET, + *, + _visited=None, + _depth=0, + _traversal_state=None, + ): + return self._editor._compat_get_fields( + tree=tree, + retval=retval, + fileobj=fileobj, + stack=stack, + visited=_visited, + depth=_depth, + traversal_state=_traversal_state, + ) + + def get_form_text_fields(self, full_qualified_name: bool = False) -> dict[str, Any]: + return self._editor._compat_text_fields(full_qualified_name=full_qualified_name) + + def get_attachment(self, name: str) -> bytes: + return self._editor.get_attachment(name=name) + + +class _PdfWriterCompat(_PdfReaderCompat, _PdfEditing): + def append( + self, + fileobj: Any, + outline_item: Any = None, + pages: Any = None, + import_outline: bool = True, + excluded_fields: Any = None, + ) -> None: + return self._editor._compat_append( + fileobj=fileobj, + outline_item=outline_item, + pages=pages, + import_outline=import_outline, + excluded_fields=excluded_fields, + ) + + def merge( + self, + position: int | None, + fileobj: Any, + outline_item: str | None = None, + pages: Any = None, + import_outline: bool = True, + excluded_fields: Any = (), + ) -> None: + return self._editor._compat_append( + position=position, + fileobj=fileobj, + outline_item=outline_item, + pages=pages, + import_outline=import_outline, + excluded_fields=excluded_fields, + ) + + def add_page( + self, page: PdfPage, excluded_keys: Iterable[str] = () + ) -> PdfEditablePage: + return self._editor._compat_insert_page( + page=page, index=len(self.pages), excluded_keys=excluded_keys + ) + + def insert_page( + self, page: PdfPage, index: int = 0, excluded_keys: Iterable[str] = () + ) -> PdfEditablePage: + return self._editor._compat_insert_page( + page=page, index=index, excluded_keys=excluded_keys + ) + + def add_blank_page( + self, width: float | None = None, height: float | None = None + ) -> PdfEditablePage: + return self._editor._compat_blank_page( + width=width, height=height, index=len(self.pages) + ) + + def insert_blank_page( + self, width: float | None = None, height: float | None = None, index: int = 0 + ) -> PdfEditablePage: + return self._editor._compat_blank_page(width=width, height=height, index=index) + + def add_image( + self, + image: _pdf_images.ImageSource, + *, + index: int | None = None, + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> list[PdfEditablePage]: + return self._editor.add_image( + image=image, + before_page_no=index + if index is None or index is _UNSET + else self._compat_page_no(index, insertion=True), + page_size=page_size, + margin=margin, + dpi=dpi, + ) + + @classmethod + def from_images( + cls, + images: Iterable[_pdf_images.ImageSource], + *, + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> Any: + constructor: Any = cls + return constructor( + clone_from=PdfEditor.from_images( + images=images, page_size=page_size, margin=margin, dpi=dpi + ) + ) + + def duplicate_page(self, index: int, to: int | None = None) -> PdfEditablePage: + return self._editor.duplicate_page( + page_no=self._compat_page_no(index, insertion=False), + before_page_no=to + if to is None or to is _UNSET + else self._compat_page_no(to, insertion=True), + ) + + def remove_page(self, page: Any, clean: bool = False) -> None: + return self._editor.remove_page( + page_no=self._compat_page_no( + page.index if isinstance(page, PdfPage) else page + ), + clean=clean, + ) + + def move_page(self, from_index: int, to_index: int) -> None: + return self._editor.move_page( + page_no=self._compat_page_no(from_index, insertion=False), + to_page_no=self._compat_page_no(to_index, insertion=False), + ) + + def add_metadata(self, infos: dict[str, str | None]) -> None: + return self._editor.add_metadata(infos=infos) + + def set_xmp_metadata(self, packet: str | bytes | None) -> None: + return self._editor.set_xmp_metadata(packet=packet) + + def set_page_layout(self, layout: str | None) -> None: + return self._editor.set_page_layout(layout=layout) + + def set_page_mode(self, mode: str | None) -> None: + return self._editor.set_page_mode(mode=mode) + + def set_viewer_preferences(self, preferences: dict[str, Any] | None) -> None: + return self._editor.set_viewer_preferences(preferences=preferences) + + def set_open_destination(self, page_number: int | None) -> None: + return self._editor.set_open_destination( + page_no=None + if page_number is None + else self._compat_page_no(page_number, insertion=False) + ) + + def set_page_label( + self, + page_index_from: int, + page_index_to: int, + style: Any = None, + prefix: str | None = None, + start: int | None = 0, + ) -> None: + self._editor.set_page_label( + first_page_no=self._compat_page_no(page_index_from), + last_page_no=self._compat_page_no(page_index_to), + style=style, + prefix=prefix, + start=start or 1, + ) + + def add_named_destination( + self, title: str, page_number: int, fit: Any = None + ) -> Any: + return self._editor._compat_named_destination( + title=title, page_no=self._compat_page_no(page_number), fit=fit + ) + + def add_outline_item( + self, + title: str, + page_number: Any, + parent: Any = None, + before: Any = None, + color: Any = None, + bold: bool = False, + italic: bool = False, + fit: Any = _DEFAULT_FIT, + is_open: bool = True, + ) -> Any: + return self._editor._compat_outline_item( + title=title, + page_number=page_number, + parent=parent, + before=before, + color=color, + bold=bold, + italic=italic, + fit=fit, + is_open=is_open, + ) + + def update_outline_item( + self, + item_id: int, + *, + title: str = _UNSET, + page_number: int | None = _UNSET, + url: str | None = _UNSET, + left: float | None = _UNSET, + top: float | None = _UNSET, + zoom: float | None = _UNSET, + color: Sequence[float] | str | None = _UNSET, + bold: bool = _UNSET, + italic: bool = _UNSET, + is_open: bool = _UNSET, + ) -> None: + return self._editor.update_outline_item( + item_id=item_id, + title=title, + page_no=page_number + if page_number is None or page_number is _UNSET + else self._compat_page_no(page_number, insertion=False), + url=url, + left=left, + top=top, + zoom=zoom, + color=color, + bold=bold, + italic=italic, + is_open=is_open, + ) + + def remove_outline_item(self, item_id: int) -> None: + return self._editor.remove_outline_item(item_id=item_id) + + def move_outline_item( + self, item_id: int, parent: int | None = None, index: int | None = None + ) -> None: + return self._editor.move_outline_item( + item_id=item_id, parent=parent, index=index + ) + + def clear_outline(self) -> None: + return self._editor.clear_outline() + + def add_table_of_contents( + self, + index: int = 0, + *, + title: str = "Contents", + font: str = "Helvetica", + size: float = 11, + max_depth: int | None = None, + page_size: str | Sequence[float] | None = None, + ) -> list[PdfEditablePage]: + return self._editor.add_table_of_contents( + before_page_no=self._compat_page_no(index, insertion=True), + title=title, + font=font, + size=size, + max_depth=max_depth, + page_size=page_size, + ) + + def update_form_field_values( + self, fields: dict[str, str | bool], *, flatten: bool = False + ) -> int: + return self._editor.update_form_field_values(fields=fields, flatten=flatten) + + def add_text_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + value: str | None = None, + *, + multiline: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + return self._editor.add_text_field( + page_no=self._compat_page_no(page_number, insertion=False), + name=name, + rect=rect, + value=value, + multiline=multiline, + font_size=font_size, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_checkbox( + self, + page_number: int, + name: str, + rect: Sequence[float], + checked: bool = False, + *, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + return self._editor.add_checkbox( + page_no=self._compat_page_no(page_number, insertion=False), + name=name, + rect=rect, + checked=checked, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_choice_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + options: Sequence[str], + value: str | None = None, + *, + editable: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + return self._editor.add_choice_field( + page_no=self._compat_page_no(page_number, insertion=False), + name=name, + rect=rect, + options=options, + value=value, + editable=editable, + font_size=font_size, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_radio_group( + self, + page_number: int, + name: str, + buttons: dict[str, Sequence[float]], + selected: str | None = None, + *, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + return self._editor.add_radio_group( + page_no=self._compat_page_no(page_number, insertion=False), + name=name, + buttons=buttons, + selected=selected, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_signature_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + *, + required: bool = False, + tooltip: str | None = None, + ) -> None: + return self._editor.add_signature_field( + page_no=self._compat_page_no(page_number, insertion=False), + name=name, + rect=rect, + required=required, + tooltip=tooltip, + ) + + def update_form_field( + self, + name: str, + *, + new_name: str = _UNSET, + rect: Sequence[float] = _UNSET, + read_only: bool = _UNSET, + required: bool = _UNSET, + tooltip: str | None = _UNSET, + options: Sequence[str] = _UNSET, + ) -> None: + return self._editor.update_form_field( + name=name, + new_name=new_name, + rect=rect, + read_only=read_only, + required=required, + tooltip=tooltip, + options=options, + ) + + def remove_form_field(self, name: str) -> None: + return self._editor.remove_form_field(name=name) + + def set_need_appearances_writer(self, state: bool = True) -> None: + return self._editor.set_need_appearances_writer(state=state) + + def flatten_annotations(self) -> None: + return self._editor.flatten_annotations() + + def add_annotation( + self, page_number: int | PdfPage, annotation: dict[str, Any] + ) -> dict[str, Any]: + return self._editor._compat_add_annotation( + page_number=page_number, annotation=annotation + ) + + def add_uri( + self, + page_number: int, + uri: str, + rect: Sequence[float], + border: Sequence[float] | None = None, + ) -> None: + return self._editor.add_uri( + page_no=self._compat_page_no(page_number, insertion=False), + uri=uri, + rect=rect, + border=border, + ) + + def add_link( + self, page_number: int, rect: Sequence[float], target_page_number: int + ) -> None: + return self._editor.add_link( + page_no=self._compat_page_no(page_number, insertion=False), + rect=rect, + target_page_no=self._compat_page_no(target_page_number, insertion=False), + ) + + def remove_annotations(self, subtypes: Any) -> None: + self._editor.remove_annotations(subtypes=subtypes) + + def remove_links(self) -> None: + self._editor.remove_links() + + def add_attachment(self, filename: str, data: str | bytes) -> Any: + return self._editor.add_attachment(filename=filename, data=data) + + def remove_attachment(self, name: str) -> bool: + return self._editor.remove_attachment(name=name) + + def add_js(self, javascript: str) -> None: + return self._editor.add_js(javascript=javascript) + + def remove_javascript(self) -> int: + return self._editor.remove_javascript() + + def encrypt( + self, + user_password: str, + owner_password: str | None = None, + use_128bit: bool = True, + permissions_flag: int = 4294967292, + *, + algorithm: str | None = None, + ) -> None: + return self._editor._compat_encrypt( + user_password=user_password, + owner_password=owner_password, + use_128bit=use_128bit, + permissions_flag=permissions_flag, + algorithm=algorithm, + ) + + def set_output_options( + self, + *, + compress_streams: bool = True, + object_streams: str = "preserve", + linearize: bool = False, + ) -> None: + return self._editor.set_output_options( + compress_streams=compress_streams, + object_streams=object_streams, + linearize=linearize, + ) + + def remove_encryption(self) -> None: + return self._editor.remove_encryption() + + def to_bytes(self) -> bytes: + return self._editor.to_bytes() + + def write(self, stream: Any) -> tuple[bool, Any]: + return self._editor._compat_write(stream=stream) diff --git a/docling_parse/_pdf_document.py b/docling_parse/_pdf_document.py new file mode 100644 index 000000000..a195cc17b --- /dev/null +++ b/docling_parse/_pdf_document.py @@ -0,0 +1,1778 @@ +"""Shared Python half of PdfReader, PdfWriter and PdfEditor. + +All PDF work happens in the native `docling_editor` class; the three public +classes bind three native types that publish different subsets of it. This +module holds the Python conveniences they share: opening from a path, bytes or +a stream, the `pages` sequence, page handles and error translation. + +Nothing here imports docling-core, pydantic or PIL, and nothing imports +`docling_parse.pdf_parser`. +""" + +from __future__ import annotations + +import math +import os +from collections.abc import Iterable, Iterator, Sequence +from contextlib import contextmanager +from typing import Any, BinaryIO, NamedTuple, Union, overload + +from docling_parse import ( + _pdf_images, + pdf_parsers as _native, # type: ignore[attr-defined] +) +from docling_parse.pdf_errors import ( + PdfEditError, + PdfEditErrorCategory, + PdfLoadError, + PdfLoadErrorCategory, + PdfPasswordError, + PdfStaleHandleError, + PdfUnsupportedError, + PdfWriteError, +) + +PdfSource = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, BinaryIO] + +# A sentinel for "not given", where None is a value (it removes something). +_UNSET: Any = object() + +# The fonts text can be drawn in: the standard 14 fonts that hold Latin text, +# which every PDF viewer provides without embedding. +STANDARD_FONTS = ( + "Helvetica", + "Helvetica-Bold", + "Helvetica-Oblique", + "Helvetica-BoldOblique", + "Times-Roman", + "Times-Bold", + "Times-Italic", + "Times-BoldItalic", + "Courier", + "Courier-Bold", + "Courier-Oblique", + "Courier-BoldOblique", +) + + +def _color(value: Sequence[float] | str | None) -> list[float] | None: + """An RGB color as three numbers in 0..1, from a tuple or "#rrggbb".""" + if value is None: + return None + if isinstance(value, str): + text = value.lstrip("#") + if len(text) != 6: + raise ValueError(f"a color is (r, g, b) or '#rrggbb', not {value!r}") + return [int(text[i : i + 2], 16) / 255 for i in (0, 2, 4)] + components = [float(component) for component in value] + if len(components) != 3 or not all(0 <= c <= 1 for c in components): + raise ValueError("a color is three numbers between 0 and 1") + return components + + +def _rect(value: Sequence[float]) -> list[float]: + numbers = [float(v) for v in value] + if len(numbers) != 4: + raise ValueError("a rectangle is (left, bottom, right, top)") + return numbers + + +def _win_ansi(text: str) -> str: + """`text` with every character the standard fonts cannot show replaced + by "?". cp1252 is WinAnsiEncoding up to five unassigned codes.""" + return "".join( + character if character.encode("cp1252", errors="ignore") else "?" + for character in text + ) + + +_ERROR_TYPES: dict[PdfEditErrorCategory, type[PdfEditError]] = { + PdfEditErrorCategory.STALE_HANDLE: PdfStaleHandleError, + PdfEditErrorCategory.WRITE: PdfWriteError, + PdfEditErrorCategory.UNSUPPORTED: PdfUnsupportedError, +} + + +@contextmanager +def _native_errors() -> Iterator[None]: + """Turn the native (category, message) error into its typed exception.""" + try: + yield + except _native.pdf_edit_error as exc: + raw_category, detail = exc.args + try: + category = PdfEditErrorCategory(raw_category) + except ValueError: + category = PdfEditErrorCategory.UNKNOWN + raise _ERROR_TYPES.get(category, PdfEditError)(category, detail) from None + + +def _pdf_syntax(value: Any) -> str: + """Write a Python value as a PDF object, for the native calls that take a + dictionary: annotations and viewer preferences. + + A `str` starting with "/" is a PDF name, any other `str` a text string. + `bool`, `int`, `float`, `None`, lists/tuples and dicts map to their PDF + counterparts; dict keys are names, with or without their slash. + """ + if value is None: + return "null" + if isinstance(value, bool): + return "true" if value else "false" + if isinstance(value, int): + return str(value) + if isinstance(value, float): + if not math.isfinite(value): + raise ValueError("a PDF number must be finite") + return f"{value:.6f}".rstrip("0").rstrip(".") or "0" + if isinstance(value, str): + if value.startswith("/"): + return _pdf_name(value) + # Hexadecimal strings need no escaping. Text outside ASCII is written + # as UTF-16BE with its byte order mark (ISO 32000-1, 7.9.2.2). + try: + raw = value.encode("ascii") + except UnicodeEncodeError: + raw = b"\xfe\xff" + value.encode("utf-16-be") + return f"<{raw.hex()}>" + if isinstance(value, (list, tuple)): + return "[" + " ".join(_pdf_syntax(item) for item in value) + "]" + if isinstance(value, dict): + items = " ".join( + f"{_pdf_name(str(key))} {_pdf_syntax(item)}" for key, item in value.items() + ) + return f"<< {items} >>" + raise TypeError(f"cannot write {type(value).__name__} as a PDF object") + + +def _pdf_name(name: str) -> str: + """A PDF name with its slash; bytes outside the regular characters are + written as #xx (ISO 32000-1, 7.3.5).""" + body = name[1:] if name.startswith("/") else name + if not body: + raise ValueError("a PDF name must not be empty") + encoded = "".join( + chr(byte) + if 0x21 <= byte <= 0x7E and chr(byte) not in "#/()<>[]{}%" + else f"#{byte:02x}" + for byte in body.encode("utf-8") + ) + return "/" + encoded + + +# /P of an encryption dictionary: bit positions are 1-based (ISO 32000-1, +# table 22). +_PERMISSION_BITS = { + "print": 3, + "modify": 4, + "extract": 5, + "annotate": 6, + "fill_forms": 9, + "accessibility": 10, + "assemble": 11, + "print_high_quality": 12, +} + + +class PdfBox(NamedTuple): + """A page boundary in default user space units, normalized so that + `left < right` and `bottom < top`.""" + + left: float + bottom: float + right: float + top: float + + @property + def width(self) -> float: + return self.right - self.left + + @property + def height(self) -> float: + return self.top - self.bottom + + +_IMAGE_EXTENSIONS = {"jpeg": ".jpg", "jp2": ".jp2", "jbig2": ".jb2"} + + +class PdfImage(NamedTuple): + """An image drawn by a page, with the bytes to save it. + + `format` says what `data` is: "jpeg" and "jp2" are complete image files, + "jbig2" is the embedded JBIG2 stream, and "raw" is uncompressed samples in + `mode` ("1", "L", "RGB" or "CMYK"), `width` x `height` pixels. `data` is + empty when the image could not be decoded. + """ + + name: str + """The resource name the page draws the image under.""" + bbox: PdfBox + """Where the image sits on the page.""" + width: int + height: int + format: str + mode: str + data: bytes + + @property + def extension(self) -> str: + """A file extension for `data`, with its dot: ".jpg", ".jp2", ...""" + return _IMAGE_EXTENSIONS.get(self.format, ".bin") + + def save(self, path: str | os.PathLike[str]) -> None: + """Write `data` to `path` as it is.""" + with open(path, "wb") as stream: + stream.write(self.data) + + def to_pil(self) -> Any: + """The image as a PIL image. Needs Pillow, which is imported here and + nowhere else in this module.""" + from io import BytesIO + + from PIL import Image + + if self.format in ("jpeg", "jp2"): + return Image.open(BytesIO(self.data)) + if self.format == "raw": + return Image.frombytes(self.mode, (self.width, self.height), self.data) + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + f"cannot build a PIL image from {self.format} data", + ) + + +class PdfPage: + """A page of a document, by position. Nothing is decoded until asked for. + + The handle belongs to the page list it was taken from: once pages are + inserted, removed or moved, using it raises `PdfStaleHandleError` instead + of silently addressing whichever page now has that index. + """ + + __slots__ = ("_generation", "_index", "_owner") + + def __init__(self, owner: _PdfDocument, index: int, generation: int): + self._owner = owner + self._index = index + self._generation = generation + + def __repr__(self) -> str: + return f"{type(self).__name__}(index={self._index})" + + @property + def index(self) -> int: + """Zero-based position of the page in its document.""" + return self._index + + @property + def page_number(self) -> int: + """Same as `index`: the zero-based position, under pypdf's name.""" + return self._index + + def _info(self) -> dict[str, Any]: + with _native_errors(): + return self._owner._native.page_info(self._index, self._generation) + + @property + def mediabox(self) -> PdfBox: + return PdfBox(*self._info()["media_box"]) + + @property + def cropbox(self) -> PdfBox: + return PdfBox(*self._info()["crop_box"]) + + @property + def bleedbox(self) -> PdfBox: + return PdfBox(*self._info()["bleed_box"]) + + @property + def trimbox(self) -> PdfBox: + return PdfBox(*self._info()["trim_box"]) + + @property + def artbox(self) -> PdfBox: + return PdfBox(*self._info()["art_box"]) + + @property + def rotation(self) -> int: + """Clockwise display rotation in degrees: 0, 90, 180 or 270.""" + return self._info()["rotation"] + + @property + def user_unit(self) -> float: + """Size of one user space unit in 1/72 inch; 1.0 unless the page says otherwise.""" + return self._info()["user_unit"] + + def extract_text(self, extraction_mode: str = "plain") -> str: + """The text of the page. + + "plain" returns the text lines in the parser's reading order, joined + by newlines. "layout" places the text on a character grid, so + columns, indentation and vertical spacing of the page survive in the + string; it suits tables and forms read as fixed-width text. + """ + if extraction_mode not in ("plain", "layout"): + raise ValueError('extraction_mode is "plain" or "layout"') + with _native_errors(): + return self._owner._native.extract_text( + self._index, self._generation, layout=extraction_mode == "layout" + ) + + @property + def annotations(self) -> list[dict[str, Any]]: + """The page's annotations, one dictionary each, keyed by PDF name + ("/Subtype", "/Rect", "/Contents", ...). A link into the document + also has "page", the zero-based index of its target.""" + with _native_errors(): + return self._owner._native.page_annotations(self._index, self._generation) + + @property + def images(self) -> list[PdfImage]: + """The images the page draws, in drawing order. Decodes the page.""" + with _native_errors(): + items = self._owner._native.page_images(self._index, self._generation) + return [ + PdfImage( + name=item["name"], + bbox=PdfBox(*item["bbox"]), + width=item["width"], + height=item["height"], + format=item["format"], + mode=item["mode"], + data=item["data"], + ) + for item in items + ] + + +class PdfEditablePage(PdfPage): + """A page of a writer or editor: `PdfPage` plus in-place changes.""" + + __slots__ = () + + def rotate(self, angle: int) -> PdfEditablePage: + """Rotate clockwise by `angle` degrees (a multiple of 90), on top of + the page's current rotation.""" + with _native_errors(): + self._owner._native.rotate_page( + self._index, angle, relative=True, generation=self._generation + ) + return self + + def merge_page( + self, page: PdfPage, over: bool = True, *, fit: bool = False + ) -> PdfEditablePage: + """Draw another page on this one as vector content: a stamp or + overlay with `over=True`, a watermark or underlay with `over=False`. + + By default the two pages are superimposed at their own coordinates, + unscaled. With `fit=True` the other page is centered on this one and + scaled to fill it, upright with respect to this page's rotation. + + `page` may belong to any reader, writer or editor, including this + one. Its text and graphics are drawn; its annotations and form + fields are not copied. + """ + return self._overlay(page, over, fit, (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)) + + def _overlay( + self, page: PdfPage, over: bool, fit: bool, ctm: Sequence[float] + ) -> PdfEditablePage: + matrix = [float(value) for value in ctm] + if len(matrix) != 6: + raise ValueError("a transformation matrix has six entries") + with _native_errors(): + self._owner._native.overlay_page( + self._index, + page._owner._native, + page._index, + under=not over, + fit=fit, + matrix=matrix, + generation=self._generation, + other_generation=page._generation, + ) + return self + + def merge_transformed_page( + self, page: PdfPage, ctm: Sequence[float], over: bool = True + ) -> PdfEditablePage: + """`merge_page`, with the other page transformed by the matrix + `(a, b, c, d, e, f)` before it is drawn.""" + return self._overlay(page, over, False, ctm) + + def merge_scaled_page( + self, page: PdfPage, scale: float, over: bool = True + ) -> PdfEditablePage: + """`merge_page`, with the other page scaled about the origin.""" + return self._overlay(page, over, False, (scale, 0.0, 0.0, scale, 0.0, 0.0)) + + def merge_translated_page( + self, page: PdfPage, tx: float, ty: float, over: bool = True + ) -> PdfEditablePage: + """`merge_page`, with the other page moved by `(tx, ty)`.""" + return self._overlay(page, over, False, (1.0, 0.0, 0.0, 1.0, tx, ty)) + + def merge_rotated_page( + self, page: PdfPage, rotation: float, over: bool = True + ) -> PdfEditablePage: + """`merge_page`, with the other page turned counter-clockwise by + `rotation` degrees about the origin.""" + angle = math.radians(rotation) + cos, sin = math.cos(angle), math.sin(angle) + return self._overlay(page, over, False, (cos, sin, -sin, cos, 0.0, 0.0)) + + def draw_text( + self, + text: str, + x: float, + y: float, + *, + size: float = 12, + font: str = "Helvetica", + color: Sequence[float] | str = (0, 0, 0), + ) -> PdfEditablePage: + """Draw `text` on the page, its first baseline starting at (x, y). + + `font` is one of `STANDARD_FONTS`, which every viewer has, so nothing + is embedded. Those fonts hold Latin text (WinAnsiEncoding); other + characters raise `PdfUnsupportedError`. A newline starts a new line + 1.2 x `size` lower. `color` is (r, g, b) in 0..1, or "#rrggbb". + """ + with _native_errors(): + self._owner._native.draw_text( + self._index, + text, + float(x), + float(y), + size=float(size), + font=font, + color=_color(color), + generation=self._generation, + ) + return self + + def transfer_rotation_to_content(self) -> PdfEditablePage: + """Turn the page's rotation into a rotation of its content, boxes and + annotations. The page looks the same and `rotation` becomes 0.""" + with _native_errors(): + self._owner._native.flatten_page_rotation(self._index, self._generation) + return self + + def add_transformation(self, ctm: Sequence[float]) -> PdfEditablePage: + """Apply the matrix `(a, b, c, d, e, f)` to the page's content and + annotations. The page boundaries are not changed.""" + matrix = [float(value) for value in ctm] + if len(matrix) != 6: + raise ValueError("a transformation matrix has six entries") + with _native_errors(): + self._owner._native.transform_page(self._index, matrix, self._generation) + return self + + def scale(self, sx: float, sy: float) -> PdfEditablePage: + """Scale the page by `sx` horizontally and `sy` vertically: its + content, its annotations and all of its boundaries.""" + with _native_errors(): + self._owner._native.scale_page( + self._index, float(sx), float(sy), self._generation + ) + return self + + def scale_by(self, factor: float) -> PdfEditablePage: + """Scale the page by the same factor in both directions.""" + return self.scale(factor, factor) + + def scale_to(self, width: float, height: float) -> PdfEditablePage: + """Scale the page so that its media box gets the given size.""" + box = self.mediabox + if not (box.width > 0 and box.height > 0): + raise PdfEditError( + PdfEditErrorCategory.INVALID_EDIT, "the page has an empty media box" + ) + return self.scale(width / box.width, height / box.height) + + def _set_box(self, name: str, box: Sequence[float]) -> None: + left, bottom, right, top = (float(value) for value in box) + with _native_errors(): + self._owner._native.set_page_box( + self._index, name, [left, bottom, right, top], self._generation + ) + + # The setters repeat the getters because a property is one object: a + # subclass cannot add only the setter to an inherited read-only property. + + @property + def rotation(self) -> int: + return self._info()["rotation"] + + @rotation.setter + def rotation(self, angle: int) -> None: + with _native_errors(): + self._owner._native.rotate_page( + self._index, angle, relative=False, generation=self._generation + ) + + @property + def mediabox(self) -> PdfBox: + return PdfBox(*self._info()["media_box"]) + + @mediabox.setter + def mediabox(self, box: Sequence[float]) -> None: + self._set_box("media", box) + + @property + def cropbox(self) -> PdfBox: + return PdfBox(*self._info()["crop_box"]) + + @cropbox.setter + def cropbox(self, box: Sequence[float]) -> None: + self._set_box("crop", box) + + @property + def bleedbox(self) -> PdfBox: + return PdfBox(*self._info()["bleed_box"]) + + @bleedbox.setter + def bleedbox(self, box: Sequence[float]) -> None: + self._set_box("bleed", box) + + @property + def trimbox(self) -> PdfBox: + return PdfBox(*self._info()["trim_box"]) + + @trimbox.setter + def trimbox(self, box: Sequence[float]) -> None: + self._set_box("trim", box) + + @property + def artbox(self) -> PdfBox: + return PdfBox(*self._info()["art_box"]) + + @artbox.setter + def artbox(self, box: Sequence[float]) -> None: + self._set_box("art", box) + + +class PdfPages(Sequence[PdfPage]): + """The pages of a document: zero-based, with negative indices and slices. + + On a writer or editor, `del pages[i]` removes a page. + """ + + def __init__(self, owner: _PdfDocument): + self._owner = owner + + def __len__(self) -> int: + with _native_errors(): + return self._owner._native.page_count() + + def _resolve(self, index: int, count: int) -> int: + resolved = index + count if index < 0 else index + if not 0 <= resolved < count: + raise IndexError(f"page index {index} out of range for {count} pages") + return resolved + + @overload + def __getitem__(self, index: int) -> PdfPage: ... + + @overload + def __getitem__(self, index: slice) -> list[PdfPage]: ... + + def __getitem__(self, index: int | slice) -> PdfPage | list[PdfPage]: + # Generation first: if the page list changes between the two reads, + # the handles made here are stale rather than wrong. + generation = self._owner._native.generation() + count = len(self) + page_class = self._owner._page_class + + if isinstance(index, slice): + return [ + page_class(self._owner, i, generation) + for i in range(*index.indices(count)) + ] + return page_class(self._owner, self._resolve(index, count), generation) + + def __delitem__(self, index: int) -> None: + if not isinstance(self._owner, _PdfEditing): + raise TypeError(f"{type(self._owner).__name__} is read-only") + self._owner._remove_page(index) + + +class _PdfDocument: + """Opening, closing and inspection: common to reader, writer and editor.""" + + _native_class: type + _page_owner: _PdfDocument + _page_class: type[PdfPage] = PdfPage + + def __init__(self, loglevel: str = "fatal"): + self._native = self._native_class(loglevel) + + def _open(self, source: Any, password: str | None) -> None: + native = self._native + + if isinstance(source, _PdfDocument): + description = repr(source) + with _native_errors(): + opened = native.open_source(source._native) + elif isinstance(source, (str, os.PathLike)): + description = os.fspath(source) + opened = native.open_file(description, password) + elif isinstance(source, (bytes, bytearray, memoryview)): + description = "" + opened = native.open_bytes(bytes(source), password) + elif hasattr(source, "read"): + # The stream stays the caller's: it is read, never closed. + description = getattr(source, "name", "") + if hasattr(source, "seek") and source.seekable(): + source.seek(0) + opened = native.open_bytes(bytes(source.read()), password) + else: + raise TypeError( + f"cannot open a PDF from {type(source).__name__}: expected a path, " + "bytes, a binary stream, or a PdfReader/PdfWriter/PdfEditor" + ) + + if not opened: + raise self._load_error(str(description), password) + + def _load_error(self, key: str, password: str | None) -> PdfLoadError: + info = self._native.take_open_error() + try: + category = PdfLoadErrorCategory(info.get("category", "unknown")) + except ValueError: + category = PdfLoadErrorCategory.UNKNOWN + detail = info.get("message", "") + + if category is PdfLoadErrorCategory.PASSWORD: + return PdfPasswordError(key, detail, password_supplied=password is not None) + return PdfLoadError(key, category, detail) + + def close(self) -> None: + """Release the document. The object can not be used afterwards.""" + self._native.close() + + def __enter__(self): + return self + + def __exit__(self, *exc_info: object) -> None: + self.close() + + def _document_info(self) -> dict[str, Any]: + with _native_errors(): + return self._native.document_info() + + @property + def pages(self) -> PdfPages: + return PdfPages(getattr(self, "_page_owner", self)) + + def get_num_pages(self) -> int: + """The number of pages; same as `len(self.pages)`.""" + return len(self.pages) + + def _get_page(self, page_number: int) -> PdfPage: + """The page at a zero-based position; same as `self.pages[page_number]`.""" + return self.pages[page_number] + + def _get_page_number(self, page: PdfPage) -> int: + """The zero-based position of a page of this document.""" + if page._owner is not getattr(self, "_page_owner", self): + raise ValueError("the page belongs to another document") + return page.index + + def _get_pages_showing_field(self, name: str) -> list[PdfPage]: + """The pages that show the form field with this fully qualified name.""" + fields = self._get_fields() + if name not in fields: + raise KeyError(name) + return [self.pages[index] for index in fields[name]["pages"]] + + @property + def pdf_header(self) -> str: + """The first line of the file, for example "%PDF-1.7".""" + return f"%PDF-{self.pdf_version}" + + @property + def pdf_version(self) -> str: + """The PDF version the file declares, for example "1.7".""" + return self._document_info()["pdf_version"] + + @property + def is_encrypted(self) -> bool: + return self._document_info()["encryption"] is not None + + @property + def encryption(self) -> dict[str, Any] | None: + """The encryption parameters, or None for an unencrypted document. + + `permissions` is the raw /P flag word. The flags are reported, not + enforced. + """ + return self._document_info()["encryption"] + + @property + def metadata(self) -> dict[str, str]: + """The document information dictionary (/Info): Title, Author, ...""" + return self._document_info()["info"] + + @property + def xmp_metadata(self) -> str | None: + """The XMP metadata packet, or None when the document has none.""" + xmp = self._document_info()["xmp"] + return None if xmp is None else xmp.decode("utf-8", errors="replace") + + @property + def permissions(self) -> dict[str, bool] | None: + """What the user password allows, by name, or None for an unencrypted + document. The flags are reported, not enforced.""" + encryption = self.encryption + if encryption is None: + return None + flags = encryption["permissions"] + return { + name: bool(flags & (1 << (bit - 1))) + for name, bit in _PERMISSION_BITS.items() + } + + @property + def outline(self) -> list[dict[str, Any]]: + """The document outline (bookmarks) as a tree: each item has "title", + "page" (zero-based index, or None), "children" and "id".""" + with _native_errors(): + return self._native.outline_tree() + + def _settings(self) -> dict[str, Any]: + with _native_errors(): + return self._native.document_settings() + + @property + def page_layout(self) -> str | None: + """How pages are laid out when the document opens ("/OneColumn", + "/TwoPageLeft", ...), or None when the document does not say.""" + return self._settings()["page_layout"] + + @property + def page_mode(self) -> str | None: + """What a viewer shows beside the pages ("/UseOutlines", + "/FullScreen", ...), or None when the document does not say.""" + return self._settings()["page_mode"] + + @property + def viewer_preferences(self) -> dict[str, Any] | None: + """The viewer preferences dictionary, keyed by PDF name.""" + return self._settings()["viewer_preferences"] + + @property + def open_destination(self) -> dict[str, Any] | None: + """Where the document opens: "page", "kind" and "arguments", or None + when it has no open destination.""" + return self._settings()["open_destination"] + + @property + def page_labels(self) -> list[str]: + """The label of every page as a viewer shows it ("i", "ii", "1", + "A-1", ...); "1", "2", ... when the document defines none.""" + with _native_errors(): + return self._native.page_labels() + + @property + def named_destinations(self) -> dict[str, dict[str, Any]]: + """Named destinations: name to "page", "kind" and "arguments".""" + with _native_errors(): + return self._native.named_destinations() + + def _form(self) -> dict[str, Any]: + with _native_errors(): + return self._native.form() + + def _get_fields(self) -> dict[str, dict[str, Any]]: + """The form fields by fully qualified name. Each field has "kind" + (text, checkbox, radio, choice, pushbutton, signature), "value", + "default_value", "choices", "states", "read_only", "pages", and the + raw "type" and "flags".""" + return {field["name"]: field for field in self._form()["fields"]} + + def _get_form_text_fields(self) -> dict[str, str]: + """The value of every text field, by fully qualified name.""" + return { + field["name"]: field["value"] + for field in self._form()["fields"] + if field["kind"] == "text" + } + + @property + def has_form(self) -> bool: + return self._form()["has_form"] + + @property + def has_xfa(self) -> bool: + """Whether the form carries an XFA definition. XFA is reported, not + interpreted: values set here do not reach the XFA data.""" + return self._form()["has_xfa"] + + @property + def attachment_info(self) -> list[dict[str, Any]]: + """The embedded files: "name", "filename", "description", "size", + "mime_type", "creation_date" and "modification_date" of each.""" + with _native_errors(): + return self._native.attachments() + + def _get_attachment(self, name: str) -> bytes: + """The content of the embedded file registered under `name`.""" + with _native_errors(): + return self._native.attachment_data(name) + + @property + def attachments(self) -> dict[str, list[bytes]]: + """The embedded files by name; each value is a list with the file's + content, the shape pypdf uses.""" + return { + item["name"]: [self._get_attachment(item["name"])] + for item in self.attachment_info + } + + @property + def javascript(self) -> dict[str, str]: + """The document-level scripts by name. They are data: docling-parse + never runs them.""" + with _native_errors(): + return self._native.javascript() + + +class _PdfEditing(_PdfDocument): + """Page assembly and output: common to writer and editor.""" + + _page_class = PdfEditablePage + + def _import_source( + self, source: Any, password: str | None + ) -> tuple[Any, _PdfDocument | None]: + """The native object to import from, and a reader to close if one was + opened just for this call.""" + if isinstance(source, _PdfDocument): + return source._native, None + + temporary = _ImportReader() + temporary._open(source, password) + return temporary._native, temporary + + def _append( + self, + source: Any, + pages: Iterable[int] | slice | None = None, + *, + index: int | None = None, + password: str | None = None, + import_outline: bool = True, + ) -> None: + """Copy pages of another PDF into this document. + + `source` is a path, bytes, a binary stream, or a PdfReader, PdfWriter + or PdfEditor. `pages` selects zero-based pages of the source (all by + default) and may repeat or reorder them. `index` is the position the + first copied page gets; by default pages go at the end. + + With `import_outline`, the source's bookmarks that lead to a copied + page are added to this document's outline, pointing at the copies. + """ + native, temporary = self._import_source(source, password) + try: + with _native_errors(): + selection: list[int] | None = None + if pages is not None: + count = native.page_count() + if isinstance(pages, slice): + selection = list(range(*pages.indices(count))) + else: + selection = [p + count if p < 0 else p for p in pages] + + self._native.append_pages( + native, + selection, + -1 if index is None else self._position(index), + import_outline=import_outline, + ) + finally: + if temporary is not None: + temporary.close() + + def _merge( + self, + position: int | None, + fileobj: Any, + pages: Iterable[int] | slice | None = None, + *, + password: str | None = None, + import_outline: bool = True, + ) -> None: + """Copy pages of another PDF into this document at `position` + (None for the end). Same as `append(fileobj, pages, index=position)`.""" + self._append( + fileobj, + pages, + index=position, + password=password, + import_outline=import_outline, + ) + + def _add_page(self, page: PdfPage) -> PdfEditablePage: + """Append a copy of a page of any reader, writer or editor.""" + return self._insert_page(page, len(self.pages)) + + def _insert_page(self, page: PdfPage, index: int = 0) -> PdfEditablePage: + """Insert a copy of a page of any reader, writer or editor so that it + becomes page `index`.""" + with _native_errors(): + position = self._native.append_pages( + page._owner._native, + [page._index], + self._position(index), + other_generation=page._generation, + ) + return self.pages[position] # type: ignore[return-value] + + def _position(self, index: int) -> int: + """An insertion position: 0..len, negative counted from the end.""" + count = len(self.pages) + position = index + count if index < 0 else index + if not 0 <= position <= count: + raise IndexError(f"position {index} out of range for {count} pages") + return position + + def _add_blank_page(self, width: float, height: float) -> PdfEditablePage: + """Add an empty page at the end. Sizes are in points (1/72 inch).""" + return self._insert_blank_page(len(self.pages), width, height) + + def _insert_blank_page( + self, index: int, width: float, height: float + ) -> PdfEditablePage: + """Insert an empty page so that it becomes page `index`.""" + with _native_errors(): + position = self._native.insert_blank_page( + float(width), float(height), self._position(index) + ) + return self.pages[position] # type: ignore[return-value] + + def _add_image( + self, + image: _pdf_images.ImageSource, + *, + index: int | None = None, + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> list[PdfEditablePage]: + """Add pages showing an image: one page, or one per frame of a + multi-page TIFF or animated GIF. Returns the pages added. + + `image` is a path, bytes, a binary stream, or a PIL image, in any + format Pillow reads: PNG, JPEG, TIFF, GIF, BMP, WebP, ... JPEG files + are stored as they are, without re-encoding; other formats are + stored losslessly, transparency included. + + Without `page_size` each page is the size of its image at the + image's resolution (`dpi`, or the resolution the file declares, or + 72: one pixel per point), plus `margin` on every side. With + `page_size` ("A4", "Letter", "A3", "A5", "Legal", or (width, height) + in points) the image is centered and scaled to fill the page inside + the margin. Pages turned by the image's EXIF orientation show it + upright. + """ + size = _pdf_images.page_size_of(page_size) + position = len(self.pages) if index is None else self._position(index) + + added: list[int] = [] + for picture in _pdf_images.pictures(image): + geometry = _pdf_images.layout(picture, size, dpi, float(margin)) + with _native_errors(): + added.append( + self._native.insert_image_page( + picture.width, + picture.height, + picture.colorspace, + picture.data, + picture.is_jpeg, + geometry.page_width, + geometry.page_height, + list(geometry.placement), + invert=picture.invert, + alpha=picture.alpha, + rotate=picture.rotate, + at=position, + ) + ) + position += 1 + + return [self.pages[i] for i in added] # type: ignore[misc] + + @classmethod + def _from_images( + cls, + images: Iterable[_pdf_images.ImageSource], + *, + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> Any: + """A new document with one page per image, in order. The arguments + are those of `add_image`.""" + document = cls() + for image in images: + document._add_image(image, page_size=page_size, margin=margin, dpi=dpi) + return document + + def _duplicate_page(self, index: int, to: int | None = None) -> PdfEditablePage: + """Add a copy of the page at `index`, at position `to` or, by + default, at the end. The copy can be edited independently.""" + count = len(self.pages) + resolved = index + count if index < 0 else index + with _native_errors(): + position = self._native.duplicate_page( + resolved, -1 if to is None else self._position(to) + ) + return self.pages[position] # type: ignore[return-value] + + def _remove_page(self, index: int, clean: bool = False) -> None: + """Remove the page at `index`. Existing page handles become stale.""" + count = len(self.pages) + resolved = index + count if index < 0 else index + with _native_errors(): + self._native.remove_page(resolved, clean=clean) + + def _move_page(self, from_index: int, to_index: int) -> None: + """Move a page so that it ends up at `to_index`.""" + count = len(self.pages) + source = from_index + count if from_index < 0 else from_index + target = to_index + count if to_index < 0 else to_index + with _native_errors(): + self._native.move_page(source, target) + + # ---- document information ---- + + def _add_metadata(self, infos: dict[str, str | None]) -> None: + """Set entries of the document information dictionary. Keys may be + written "Title" or "/Title"; a value of None removes the entry.""" + with _native_errors(): + self._native.set_info(dict(infos)) + + def _set_xmp_metadata(self, packet: str | bytes | None) -> None: + """Replace the XMP metadata packet, or remove it with None.""" + data = packet.encode("utf-8") if isinstance(packet, str) else packet + with _native_errors(): + self._native.set_xmp(data) + + def _set_page_layout(self, layout: str | None) -> None: + """Set how pages are laid out when the document opens: "/SinglePage", + "/OneColumn", "/TwoColumnLeft", "/TwoColumnRight", "/TwoPageLeft" or + "/TwoPageRight". None removes the setting.""" + with _native_errors(): + self._native.set_page_layout(layout or "") + + def _set_page_mode(self, mode: str | None) -> None: + """Set what a viewer shows beside the pages: "/UseNone", + "/UseOutlines", "/UseThumbs", "/FullScreen", "/UseOC" or + "/UseAttachments". None removes the setting.""" + with _native_errors(): + self._native.set_page_mode(mode or "") + + def _set_viewer_preferences(self, preferences: dict[str, Any] | None) -> None: + """Replace the viewer preferences, for example + `{"/HideToolbar": True, "/Direction": "/R2L"}`. None removes them.""" + text = "" if preferences is None else _pdf_syntax(dict(preferences)) + with _native_errors(): + self._native.set_viewer_preferences(text) + + def _set_open_destination(self, page_number: int | None) -> None: + """Open the document at this page, fitted to the window. None removes + the open action.""" + with _native_errors(): + self._native.set_open_destination( + -1 if page_number is None else self._page_index(page_number) + ) + + def _page_index(self, index: int) -> int: + """An existing page: 0..len-1, negative counted from the end.""" + count = len(self.pages) + resolved = index + count if index < 0 else index + if not 0 <= resolved < count: + raise IndexError(f"page index {index} out of range for {count} pages") + return resolved + + # ---- navigation ---- + + def _set_page_label( + self, + page_index_from: int, + page_index_to: int, + style: str | None = None, + prefix: str | None = None, + start: int | None = None, + ) -> None: + """Label the pages `page_index_from` .. `page_index_to` (inclusive). + + `style` is "/D" (1, 2, 3), "/R" (I, II, III), "/r" (i, ii, iii), + "/A" (A, B, C) or "/a" (a, b, c); None gives labels made of `prefix` + alone. `start` is the number of the first page of the range, 1 by + default. Pages after the range keep their labels. + """ + with _native_errors(): + self._native.set_page_label( + self._page_index(page_index_from), + self._page_index(page_index_to), + style or "", + prefix or "", + start or 1, + ) + + def _add_named_destination(self, title: str, page_number: int) -> None: + """Add, or replace, a named destination that opens a page.""" + with _native_errors(): + self._native.add_named_destination(title, self._page_index(page_number)) + + def _add_outline_item( + self, + title: str, + page_number: int | None, + parent: int | None = None, + *, + url: str | None = None, + left: float | None = None, + top: float | None = None, + zoom: float | None = None, + color: Sequence[float] | str | None = None, + bold: bool = False, + italic: bool = False, + is_open: bool = True, + ) -> int: + """Add a bookmark. Returns its id, which `parent` and the other + outline methods take. + + The bookmark opens `page_number`, fitted to the window; with `left`, + `top` or `zoom` it opens at that position and magnification instead + (None keeps what the viewer has). With `url` it opens a web address; + with neither it is a heading without a target. It becomes the last + child of `parent`, or the last top-level item. + + `color` is (r, g, b) in 0..1 or "#rrggbb"; `is_open=False` shows the + bookmark with its children folded away. + """ + spec: dict[str, Any] = {"title": title, "parent": parent or 0} + spec.update(self._outline_target(page_number, url, left, top, zoom)) + if color is not None: + spec["color"] = _color(color) + if bold: + spec["bold"] = True + if italic: + spec["italic"] = True + if not is_open: + spec["open"] = False + + with _native_errors(): + return self._native.add_outline_entry(spec) + + def _outline_target( + self, + page_number: Any, + url: Any, + left: Any, + top: Any, + zoom: Any, + ) -> dict[str, Any]: + """The target entries of an outline spec. A page or a URL becomes the + target; when either was given as None, the target is removed.""" + positioned = any(value not in (None, _UNSET) for value in (left, top, zoom)) + + if url not in (None, _UNSET) and page_number not in (None, _UNSET): + raise ValueError("a bookmark opens a page or a URL, not both") + if positioned and page_number in (None, _UNSET): + raise ValueError("left, top and zoom need a page_number") + + target: dict[str, Any] = {} + if url not in (None, _UNSET): + target["url"] = url + elif page_number not in (None, _UNSET): + target["page"] = self._page_index(page_number) + if positioned: + for key, value in (("left", left), ("top", top), ("zoom", zoom)): + target[key] = None if value is _UNSET else value + elif page_number is not _UNSET or url is not _UNSET: + target["page"] = None + return target + + def _update_outline_item( + self, + item_id: int, + *, + title: str = _UNSET, + page_number: int | None = _UNSET, + url: str | None = _UNSET, + left: float | None = _UNSET, + top: float | None = _UNSET, + zoom: float | None = _UNSET, + color: Sequence[float] | str | None = _UNSET, + bold: bool = _UNSET, + italic: bool = _UNSET, + is_open: bool = _UNSET, + ) -> None: + """Change a bookmark. Only the arguments given change; `page_number` + or `url` replaces the target, and None for both removes it. `color` + None goes back to the viewer's default.""" + changes: dict[str, Any] = {} + if title is not _UNSET: + changes["title"] = title + if page_number is not _UNSET or url is not _UNSET: + changes.update(self._outline_target(page_number, url, left, top, zoom)) + elif any(value is not _UNSET for value in (left, top, zoom)): + raise ValueError("left, top and zoom need a page_number") + if color is not _UNSET: + changes["color"] = _color(color) + if bold is not _UNSET: + changes["bold"] = bool(bold) + if italic is not _UNSET: + changes["italic"] = bool(italic) + if is_open is not _UNSET: + changes["open"] = bool(is_open) + + with _native_errors(): + self._native.update_outline_item(item_id, changes) + + def _remove_outline_item(self, item_id: int) -> None: + """Remove a bookmark and every bookmark below it.""" + with _native_errors(): + self._native.remove_outline_item(item_id) + + def _move_outline_item( + self, item_id: int, parent: int | None = None, index: int | None = None + ) -> None: + """Move a bookmark below `parent` (None: the top level), at position + `index` among its new siblings (None: last). Its children move with + it.""" + with _native_errors(): + self._native.move_outline_item( + item_id, parent or 0, -1 if index is None else index + ) + + def _clear_outline(self) -> None: + """Remove every bookmark.""" + with _native_errors(): + self._native.clear_outline() + + def _add_table_of_contents( + self, + index: int = 0, + *, + title: str = "Contents", + font: str = "Helvetica", + size: float = 11, + max_depth: int | None = None, + page_size: str | Sequence[float] | None = None, + ) -> list[PdfEditablePage]: + """Insert contents pages, made from the outline, at `index`. + + Every bookmark becomes a line, indented by its depth, with the label + of the page it opens on the right; the whole line is a link to that + page. Bookmarks deeper than `max_depth` (0: top level only) are left + out. The pages take the size of the page they are inserted in front + of, or `page_size` ("A4", "Letter", or (width, height) in points). + Returns the pages added; none when the document has no outline. + + Text is drawn in a standard font; characters it cannot show become + "?". Long titles are shortened to fit, by an estimate of the font's + average character width. + """ + entries = [ + entry + for entry in self._outline_entries(self.outline, 0) + if max_depth is None or entry[0] <= max_depth + ] + if not entries: + return [] + + count = len(self.pages) + position = self._position(index) + size_given = _pdf_images.page_size_of(page_size) + if size_given is not None: + width, height = size_given + elif count > 0: + box = self.pages[min(position, count - 1)].mediabox + width, height = box.width, box.height + else: + width, height = _pdf_images.PAGE_SIZES["a4"] + + margin = 72.0 + line_height = 1.6 * size + title_height = 3.0 * size + per_page = max(1, int((height - 2 * margin - title_height) // line_height)) + number_of_pages = -(-len(entries) // per_page) + + added = [ + self._insert_blank_page(position + offset, width, height) + for offset in range(number_of_pages) + ] + + # Read again: the targets moved behind the new pages. + entries = [ + entry + for entry in self._outline_entries(self.outline, 0) + if max_depth is None or entry[0] <= max_depth + ] + labels = self.page_labels + + number_column = width - margin - 4 * size + for page_offset in range(number_of_pages): + page: PdfEditablePage = self.pages[position + page_offset] # type: ignore[assignment] + page_number = position + page_offset + y = height - margin - size + if page_offset == 0: + page.draw_text(_win_ansi(title), margin, y, size=1.6 * size, font=font) + y -= title_height + + for depth, text, target in entries[ + page_offset * per_page : (page_offset + 1) * per_page + ]: + x = margin + 1.5 * size * depth + # Helvetica and Times average about half an em per + # character; Courier is exactly 0.6 em. + ratio = 0.6 if font.startswith("Courier") else 0.5 + room = int((number_column - x - size) / (ratio * size)) + line = _win_ansi(text) + if len(line) > room: + line = line[: max(room - 1, 1)] + "\u2026" + page.draw_text(line, x, y, size=size, font=font) + + if target is not None: + page.draw_text( + labels[target], number_column, y, size=size, font=font + ) + self._add_link( + page_number, + (x, y - 0.3 * size, width - margin, y + size), + target, + ) + y -= line_height + + return [self.pages[page.index] for page in added] # type: ignore[misc] + + @staticmethod + def _outline_entries( + items: list[dict[str, Any]], depth: int + ) -> list[tuple[int, str, int | None]]: + result: list[tuple[int, str, int | None]] = [] + for item in items: + result.append((depth, item["title"], item["page"])) + result.extend(_PdfEditing._outline_entries(item["children"], depth + 1)) + return result + + # ---- forms ---- + + def _update_form_field_values( + self, fields: dict[str, str | bool], *, flatten: bool = False + ) -> int: + """Fill in form fields, by fully qualified name; a partial name works + when only one field has it. + + Text and choice fields take a string. A checkbox takes True, False, + or one of its states; a radio group takes the state to select + ("/Choice1", or "Choice1"), or "/Off". The fields' appearances are + regenerated so the values show in every viewer. + + With `flatten`, the form is then turned into page content. Returns + the number of fields set; an unknown name raises `PdfEditError`. + """ + values = { + name: ("true" if value else "false") + if isinstance(value, bool) + else str(value) + for name, value in fields.items() + } + with _native_errors(): + updated = self._native.set_form_values(values) + if flatten: + self._flatten_annotations() + return updated + + def _add_field( + self, + page_number: int, + spec: dict[str, Any], + read_only: bool, + required: bool, + tooltip: str | None, + ) -> None: + spec["read_only"] = bool(read_only) + spec["required"] = bool(required) + if tooltip is not None: + spec["tooltip"] = tooltip + with _native_errors(): + self._native.add_form_field(self._page_index(page_number), spec) + + def _add_text_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + value: str | None = None, + *, + multiline: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + """Add a text field over `rect` (left, bottom, right, top) on a page. + + `name` must be new in the form and contain no period. The field is + drawn with a thin frame and its value in Helvetica, so it shows in + every viewer. + """ + spec: dict[str, Any] = { + "kind": "text", + "name": name, + "rect": _rect(rect), + "multiline": bool(multiline), + "font_size": float(font_size), + } + if value is not None: + spec["value"] = value + self._add_field(page_number, spec, read_only, required, tooltip) + + def _add_checkbox( + self, + page_number: int, + name: str, + rect: Sequence[float], + checked: bool = False, + *, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + """Add a checkbox over `rect`. Its on state is "/Yes".""" + spec = { + "kind": "checkbox", + "name": name, + "rect": _rect(rect), + "checked": bool(checked), + } + self._add_field(page_number, spec, read_only, required, tooltip) + + def _add_choice_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + options: Sequence[str], + value: str | None = None, + *, + editable: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + """Add a drop-down list over `rect`. `value` must be one of `options` + unless `editable` lets the user type a value of their own.""" + spec: dict[str, Any] = { + "kind": "choice", + "name": name, + "rect": _rect(rect), + "options": list(options), + "editable": bool(editable), + "font_size": float(font_size), + } + if value is not None: + spec["value"] = value + self._add_field(page_number, spec, read_only, required, tooltip) + + def _add_radio_group( + self, + page_number: int, + name: str, + buttons: dict[str, Sequence[float]], + selected: str | None = None, + *, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + """Add a group of radio buttons: `buttons` maps each button's state + name to its rectangle. At most one button is on; `selected` names it. + """ + spec: dict[str, Any] = { + "kind": "radio", + "name": name, + "options": [ + {"state": state, "rect": _rect(rect)} for state, rect in buttons.items() + ], + "selected": selected, + } + self._add_field(page_number, spec, read_only, required, tooltip) + + def _add_signature_field( + self, + page_number: int, + name: str, + rect: Sequence[float], + *, + required: bool = False, + tooltip: str | None = None, + ) -> None: + """Add an empty signature field over `rect`, for a signing + application to fill. docling-parse does not sign.""" + spec = {"kind": "signature", "name": name, "rect": _rect(rect)} + self._add_field(page_number, spec, False, required, tooltip) + + def _update_form_field( + self, + name: str, + *, + new_name: str = _UNSET, + rect: Sequence[float] = _UNSET, + read_only: bool = _UNSET, + required: bool = _UNSET, + tooltip: str | None = _UNSET, + options: Sequence[str] = _UNSET, + ) -> None: + """Change a form field. Only the arguments given change. + + `new_name` renames the field (its last name part). `rect` moves or + resizes a field that has one widget. `tooltip` None removes it. + `options` replaces the entries of a choice field. + """ + changes: dict[str, Any] = {} + if new_name is not _UNSET: + changes["name"] = new_name + if rect is not _UNSET: + changes["rect"] = _rect(rect) + if read_only is not _UNSET: + changes["read_only"] = bool(read_only) + if required is not _UNSET: + changes["required"] = bool(required) + if tooltip is not _UNSET: + changes["tooltip"] = tooltip + if options is not _UNSET: + changes["options"] = list(options) + with _native_errors(): + self._native.update_form_field(name, changes) + + def _remove_form_field(self, name: str) -> None: + """Remove a form field, and its widgets from the pages.""" + with _native_errors(): + self._native.remove_form_field(name) + + def _set_need_appearances_writer(self, state: bool = True) -> None: + """Set the form's NeedAppearances flag, which asks a viewer to build + the field appearances itself.""" + with _native_errors(): + self._native.set_need_appearances(bool(state)) + + def _flatten_annotations(self) -> None: + """Draw every visible annotation, form fields included, into its + page and remove the annotations. Values stay visible; the document + is no longer interactive.""" + with _native_errors(): + self._native.flatten_annotations() + + # ---- annotations ---- + + def _add_annotation(self, page_number: int, annotation: dict[str, Any]) -> None: + """Add an annotation to a page, given as a dictionary keyed by PDF + name, for example + `{"/Subtype": "/Text", "/Rect": [50, 700, 70, 720], "/Contents": "Note"}`. + "/Subtype" and "/Rect" are required.""" + with _native_errors(): + self._native.add_annotation( + self._page_index(page_number), _pdf_syntax(dict(annotation)) + ) + + def _add_uri( + self, + page_number: int, + uri: str, + rect: Sequence[float], + border: Sequence[float] | None = None, + ) -> None: + """Add a link over `rect` (left, bottom, right, top) that opens a + URL. Without `border` the link has no visible frame.""" + self._add_annotation( + page_number, + { + "/Subtype": "/Link", + "/Rect": [float(value) for value in rect], + "/Border": list(border) if border is not None else [0, 0, 0], + "/A": {"/Type": "/Action", "/S": "/URI", "/URI": uri}, + }, + ) + + def _add_link( + self, page_number: int, rect: Sequence[float], target_page_number: int + ) -> None: + """Add a link over `rect` that jumps to another page of this + document.""" + with _native_errors(): + self._native.add_page_link( + self._page_index(page_number), + [float(value) for value in rect], + self._page_index(target_page_number), + ) + + def _remove_annotations(self, subtypes: Iterable[str] | str | None = None) -> int: + """Remove annotations from every page: those of the given subtypes + ("/Link", "/Highlight", ...), or with None all of them except form + fields. Naming "/Widget" removes form fields too. Returns the number + removed.""" + if isinstance(subtypes, str): + subtypes = [subtypes] + selected = {s if s.startswith("/") else "/" + s for s in subtypes or ()} + + removed = 0 + with _native_errors(): + for index in range(len(self.pages)): + removed += self._native.remove_annotations(index, selected) + return removed + + def _remove_links(self) -> int: + """Remove every link annotation. Returns the number removed.""" + return self._remove_annotations("/Link") + + # ---- attachments and scripts ---- + + def _add_attachment( + self, + filename: str, + data: str | bytes, + *, + description: str | None = None, + mime_type: str | None = None, + ) -> None: + """Embed a file in the document. An attachment of the same name is + replaced.""" + content = data.encode("utf-8") if isinstance(data, str) else bytes(data) + with _native_errors(): + self._native.add_attachment( + filename, content, description or "", mime_type or "" + ) + + def _remove_attachment(self, name: str) -> bool: + """Remove an embedded file. Returns False if there was none.""" + with _native_errors(): + return self._native.remove_attachment(name) + + def _add_js(self, javascript: str, name: str | None = None) -> None: + """Add a document-level script, which a viewer runs when it opens + the document. docling-parse stores the script and never runs it.""" + if name is None: + name = f"script-{len(self.javascript) + 1}" + with _native_errors(): + self._native.add_javascript(name, javascript) + + def _remove_javascript(self) -> int: + """Remove the document-level scripts and scripted document actions. + Returns the number of entries removed.""" + with _native_errors(): + return self._native.remove_javascript() + + # ---- output ---- + + def _encrypt( + self, + user_password: str, + owner_password: str | None = None, + *, + algorithm: str = "AES-256", + allow_print: bool | str = True, + allow_modify: bool = True, + allow_extract: bool = True, + allow_annotate: bool = True, + allow_fill_forms: bool = True, + allow_accessibility: bool = True, + allow_assemble: bool = True, + ) -> None: + """Protect everything written from now on with a password. + + The output is encrypted with AES-256, the only password scheme PDF + 2.0 keeps; older, weaker algorithms are not offered. `user_password` + is needed to open the document; pass "" together with an + `owner_password` to let anyone open it. `owner_password` defaults to + the user password. + + The `allow_*` arguments say what someone who opens the document with + the user password may do. `allow_print` is True, False, or "low" for + low-resolution printing only. Viewers honor these flags; they are + not access control. + + Without this call the output is unencrypted, even when the source was + encrypted. + """ + if allow_print == "low": + print_level = 1 + elif isinstance(allow_print, bool): + print_level = 0 if allow_print else 2 + else: + raise ValueError('allow_print is True, False or "low"') + + with _native_errors(): + self._native.set_encryption( + user_password, + owner_password or "", + print=print_level, + modify=allow_modify, + extract=allow_extract, + annotate=allow_annotate, + fill_forms=allow_fill_forms, + accessibility=allow_accessibility, + assemble=allow_assemble, + algorithm=algorithm, + ) + + def _set_output_options( + self, + *, + compress_streams: bool = True, + object_streams: str = "preserve", + linearize: bool = False, + ) -> None: + """Choose how the file is written. + + `compress_streams` compresses streams that are stored uncompressed. + `object_streams` is "preserve", "generate" (pack objects into + compressed object streams: smaller files) or "disable" (larger, and + readable by PDF 1.4 software). `linearize` orders the file so a + viewer can show the first page before the rest has arrived. + """ + with _native_errors(): + self._native.set_output_options(compress_streams, object_streams, linearize) + + def _remove_encryption(self) -> None: + """Undo `encrypt`: write unencrypted output again.""" + with _native_errors(): + self._native.clear_encryption() + + def _to_bytes(self) -> bytes: + """The document serialized as a complete PDF file.""" + with _native_errors(): + return self._native.write_to_bytes() + + def _write(self, target: str | os.PathLike[str] | BinaryIO) -> None: + """Write the document to a path or a binary stream. + + A path is written through a temporary sibling file that replaces the + target only once it is complete. A stream receives the whole file in + one `write` call and is not closed. + """ + if isinstance(target, (str, os.PathLike)): + with _native_errors(): + self._native.write_to_file(os.fspath(target)) + elif hasattr(target, "write"): + target.write(self._to_bytes()) + else: + raise TypeError( + f"cannot write a PDF to {type(target).__name__}: " + "expected a path or a binary stream" + ) + + +class _ImportReader(_PdfDocument): + """A reader opened only to copy pages out of a path, bytes or stream.""" + + _native_class = _native.pdf_reader diff --git a/docling_parse/_pdf_images.py b/docling_parse/_pdf_images.py new file mode 100644 index 000000000..907e80196 --- /dev/null +++ b/docling_parse/_pdf_images.py @@ -0,0 +1,322 @@ +"""Turning image files into PDF pages. + +JPEG files go into the PDF as they are: the file is the image's /DCTDecode +stream, so there is no loss and no re-encoding. Every other format (PNG, TIFF, +GIF, BMP, WebP, ...) is decoded with Pillow and stored losslessly; transparency +becomes a soft mask. Pillow is imported only when an image is added. +""" + +from __future__ import annotations + +import math +import os +from collections.abc import Iterator, Sequence +from io import BytesIO +from typing import Any, BinaryIO, NamedTuple, Union + +ImageSource = Union[ + str, "os.PathLike[str]", bytes, bytearray, memoryview, BinaryIO, Any +] + +# Page sizes in points (1/72 inch), portrait. +PAGE_SIZES: dict[str, tuple[float, float]] = { + "a3": (841.89, 1190.55), + "a4": (595.28, 841.89), + "a5": (419.53, 595.28), + "letter": (612.0, 792.0), + "legal": (612.0, 1008.0), +} + +# EXIF orientation (tag 0x0112) to the clockwise page rotation that shows the +# stored image upright. The mirrored orientations (2, 4, 5, 7) have no page +# rotation that undoes them; those images are decoded and turned instead. +_ORIENTATION_TO_ROTATION = {1: 0, 3: 180, 6: 90, 8: 270} + +# JPEG start-of-frame markers: baseline, extended, progressive and lossless, +# Huffman and arithmetic coded (ITU T.81, table B.1). +_SOF_MARKERS = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7} +_SOF_MARKERS |= {0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF} + + +class Picture(NamedTuple): + """One image, ready for docling_editor::insert_image_page.""" + + width: int + height: int + colorspace: str # "gray", "rgb" or "cmyk" + data: bytes # a JPEG file, or width x height x components samples + is_jpeg: bool + invert: bool # samples stored inverted (Adobe CMYK JPEG) + alpha: bytes | None # width x height opacity samples + dpi: tuple[float, float] | None + rotate: int # clockwise page rotation that shows the image upright + + +class JpegHeader(NamedTuple): + width: int + height: int + components: int + precision: int + adobe: bool + + +def read_source(source: ImageSource) -> bytes | Any: + """The bytes of a path, bytes object or stream; a PIL image unchanged.""" + if isinstance(source, (str, os.PathLike)): + with open(source, "rb") as stream: + return stream.read() + if isinstance(source, (bytes, bytearray, memoryview)): + return bytes(source) + if hasattr(source, "read"): + # the stream stays the caller's: read, never closed + if hasattr(source, "seek") and source.seekable(): + source.seek(0) + return bytes(source.read()) + if hasattr(source, "mode") and hasattr(source, "size"): + return source + raise TypeError( + f"cannot read an image from {type(source).__name__}: expected a path, " + "bytes, a binary stream or a PIL image" + ) + + +def parse_jpeg_header(data: bytes) -> JpegHeader | None: + """Size, components and sample precision of a JPEG file, or None when + `data` is not a JPEG file with a frame header.""" + if not data.startswith(b"\xff\xd8"): + return None + + adobe = False + position = 2 + while position + 4 <= len(data): + if data[position] != 0xFF: + return None + marker = data[position + 1] + + # fill bytes, and markers that have no segment + if marker == 0xFF: + position += 1 + continue + if marker == 0x01 or 0xD0 <= marker <= 0xD7: + position += 2 + continue + + length = int.from_bytes(data[position + 2 : position + 4], "big") + segment = data[position + 4 : position + 2 + length] + + if marker == 0xEE and segment.startswith(b"Adobe"): + adobe = True + elif marker in _SOF_MARKERS and len(segment) >= 6: + return JpegHeader( + width=int.from_bytes(segment[3:5], "big"), + height=int.from_bytes(segment[1:3], "big"), + components=segment[5], + precision=segment[0], + adobe=adobe, + ) + elif marker == 0xDA: + # start of scan without a frame header + return None + + position += 2 + length + + return None + + +def _dpi_of(info: Any) -> tuple[float, float] | None: + dpi = info.get("dpi") + if not dpi: + return None + try: + x, y = float(dpi[0]), float(dpi[1]) + except (TypeError, ValueError, IndexError): + return None + if not (x > 0 and y > 0 and math.isfinite(x) and math.isfinite(y)): + return None + return (x, y) + + +def _from_jpeg(data: bytes, header: JpegHeader) -> Picture | None: + """The JPEG file as it is, or None when it has to be decoded instead.""" + colorspaces = {1: "gray", 3: "rgb", 4: "cmyk"} + + # PDF readers decode 8-bit DCT data only. + if header.precision != 8 or header.components not in colorspaces: + return None + + from PIL import Image + + with Image.open(BytesIO(data)) as image: + orientation = image.getexif().get(0x0112, 1) + dpi = _dpi_of(image.info) + + rotation = _ORIENTATION_TO_ROTATION.get(orientation) + if rotation is None: + return None + + return Picture( + width=header.width, + height=header.height, + colorspace=colorspaces[header.components], + data=data, + is_jpeg=True, + # Adobe applications store CMYK JPEG samples inverted. + invert=header.components == 4 and header.adobe, + alpha=None, + dpi=dpi, + rotate=rotation, + ) + + +def _from_pil(image: Any, dpi: tuple[float, float] | None) -> Picture: + """Raw 8-bit samples of a decoded image, with its opacity split off.""" + mode = image.mode + has_transparency = "transparency" in image.info + + if mode == "P" or mode == "PA": + image = image.convert("RGBA" if has_transparency or mode == "PA" else "RGB") + elif mode == "1": + image = image.convert("L") + elif mode in ("I", "I;16", "I;16B", "I;16L", "I;16N"): + # 16-bit gray to 8 bit + image = image.convert("I").point(lambda value: value * (1 / 256)).convert("L") + elif mode == "F": + image = image.convert("L") + elif mode in ("L", "LA", "RGB", "RGBA", "CMYK"): + pass + else: + # YCbCr, LAB, HSV, RGBX, ... + image = image.convert("RGBA" if has_transparency else "RGB") + + alpha: bytes | None = None + if image.mode in ("LA", "RGBA"): + opacity = image.getchannel("A") + # a fully opaque mask only costs space + if opacity.getextrema() != (255, 255): + alpha = opacity.tobytes() + image = image.convert("L" if image.mode == "LA" else "RGB") + + colorspace = {"L": "gray", "RGB": "rgb", "CMYK": "cmyk"}[image.mode] + + return Picture( + width=image.width, + height=image.height, + colorspace=colorspace, + data=image.tobytes(), + is_jpeg=False, + invert=False, + alpha=alpha, + dpi=dpi, + rotate=0, + ) + + +def pictures(source: ImageSource) -> Iterator[Picture]: + """The images of `source`: one for most files, one per frame for + multi-page TIFF and animated GIF files.""" + content = read_source(source) + + if isinstance(content, bytes): + header = parse_jpeg_header(content) + if header is not None: + picture = _from_jpeg(content, header) + if picture is not None: + yield picture + return + + from PIL import Image, ImageOps, ImageSequence + + image = Image.open(BytesIO(content)) if isinstance(content, bytes) else content + for frame in ImageSequence.Iterator(image): + dpi = _dpi_of(frame.info) or _dpi_of(image.info) + upright = ImageOps.exif_transpose(frame) + yield _from_pil(upright if upright is not None else frame, dpi) + + +class PageLayout(NamedTuple): + """Where an image goes, in the page's unrotated coordinates.""" + + page_width: float + page_height: float + placement: tuple[float, float, float, float] # x, y, width, height + + +def page_size_of(page_size: str | Sequence[float] | None) -> tuple[float, float] | None: + if page_size is None: + return None + if isinstance(page_size, str): + size = PAGE_SIZES.get(page_size.lower()) + if size is None: + names = ", ".join(sorted(PAGE_SIZES)) + raise ValueError( + f"unknown page size {page_size!r}: expected one of {names}" + ) + return size + width, height = (float(value) for value in page_size) + if not (width > 0 and height > 0): + raise ValueError("a page size has a positive width and height") + return (width, height) + + +def layout( + picture: Picture, + page_size: tuple[float, float] | None, + dpi: float | None, + margin: float, +) -> PageLayout: + """Page size and image placement. + + Without a page size the page is the image at its resolution (`dpi`, the + image's own, or 72 so that a pixel is a point), plus the margin. With a + page size the image is centered and scaled to fill the page inside the + margin, keeping its proportions. + """ + if margin < 0: + raise ValueError("the margin cannot be negative") + + if dpi is not None: + if not dpi > 0: + raise ValueError("dpi must be positive") + x_dpi = y_dpi = float(dpi) + else: + x_dpi, y_dpi = picture.dpi or (72.0, 72.0) + + # the image's natural size as stored, then as displayed + stored_width = picture.width * 72.0 / x_dpi + stored_height = picture.height * 72.0 / y_dpi + + turned = picture.rotate in (90, 270) + shown_width, shown_height = ( + (stored_height, stored_width) if turned else (stored_width, stored_height) + ) + + if page_size is None: + page_width = shown_width + 2 * margin + page_height = shown_height + 2 * margin + draw_width, draw_height = shown_width, shown_height + else: + page_width, page_height = page_size + room_width = page_width - 2 * margin + room_height = page_height - 2 * margin + if not (room_width > 0 and room_height > 0): + raise ValueError("the margin leaves no room on the page") + scale = min(room_width / shown_width, room_height / shown_height) + draw_width, draw_height = shown_width * scale, shown_height * scale + + # The page is stored unrotated and turned by /Rotate, so for a quarter + # turn its stored width is the height it is shown with. The image is + # centered, which is the same in both frames. + if turned: + page_width, page_height = page_height, page_width + draw_width, draw_height = draw_height, draw_width + + return PageLayout( + page_width=page_width, + page_height=page_height, + placement=( + (page_width - draw_width) / 2, + (page_height - draw_height) / 2, + draw_width, + draw_height, + ), + ) diff --git a/docling_parse/pdf_editor.py b/docling_parse/pdf_editor.py new file mode 100644 index 000000000..ee615d12a --- /dev/null +++ b/docling_parse/pdf_editor.py @@ -0,0 +1,1122 @@ +"""PdfEditor: the complete docling-parse PDF surface in one object. + +PdfReader and PdfWriter offer the subset of these operations that matches +pypdf. PdfEditor offers all of them, and is where functionality without a +pypdf counterpart appears first. + +```python +from docling_parse.pdf_editor import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + print(editor.metadata, editor.pages[0].extract_text()) + editor.pages[0].rotate(angle=90) + editor.append(source="appendix.pdf") + editor.write(target="out.pdf") +``` +""" + +from __future__ import annotations + +import math +import operator +import os +from collections.abc import Iterable, Sequence +from typing import Any, BinaryIO + +from docling_parse import pdf_parsers as _native # type: ignore[attr-defined] +from docling_parse._pdf_document import ( + _UNSET, + STANDARD_FONTS, + PdfBox, + PdfEditablePage, + PdfImage, + PdfPage, + PdfPages, + PdfSource, + _native_errors, + _pdf_images, + _PdfDocument, + _PdfEditing, +) +from docling_parse.pdf_errors import ( + PdfEditError, + PdfEditErrorCategory, + PdfLoadError, + PdfLoadErrorCategory, + PdfUnsupportedError, +) + +__all__ = [ + "STANDARD_FONTS", + "PdfBox", + "PdfEditablePage", + "PdfEditor", + "PdfImage", + "PdfPages", +] + + +class PdfEditor(_PdfEditing): + """A PDF document that can be inspected, changed and written. + + `PdfEditor(source=source)` opens a document; `PdfEditor()` starts empty. An + opened document is only read until the first change, at which point the + editor continues on its own complete copy. The source is never modified + unless `write` is pointed at its path. + + Output is a full, unencrypted rewrite: signatures of the source do not + stay valid, and an encrypted source is written in the clear. + + One editor may be shared between threads: calls are serialized. + """ + + _native_class = _native.pdf_editor + + def __init__( + self, + *, + source: PdfSource | _PdfDocument | None = None, + password: str | None = None, + loglevel: str = "fatal", + ): + super().__init__(loglevel) + if source is None: + self._native.create_empty() + else: + self._open(source, password) + + @property + def is_modified(self) -> bool: + """True once the editor works on its own copy of the document.""" + return self._native.is_editing() + + def render_page(self, *, page_no: int, scale: float = 1.0) -> Any: + """Render a page of the current document as a PIL RGBA image. + + ``page_no`` starts at 1. ``scale=1`` gives one pixel per PDF point + (72 dpi); ``scale=2`` gives 144 dpi. Rendering includes unsaved edits + and leaves the document unchanged. Pillow is imported on demand. + """ + if isinstance(page_no, bool): + raise TypeError("page_no must be an integer, starting at 1") + page_no = operator.index(page_no) + if page_no < 1: + raise ValueError("page_no must be at least 1") + if not math.isfinite(scale) or scale <= 0: + raise ValueError("scale must be finite and positive") + with _native_errors(): + data, shape = self._native.render_page(page_no=page_no, scale=scale) + + from PIL import Image + + height, width, _ = shape + return Image.frombytes("RGBA", (width, height), data) + + def get_object(self, *, object_id: int, depth: int = 3) -> Any: + """A read-only view of the PDF object with this object number, as + nested dicts and lists down to `depth` levels. Names keep their + slash; a stream is shown as its dictionary.""" + if object_id < 1: + raise ValueError("object numbers start at 1") + with _native_errors(): + return self._native.object_json(object_id, depth) + + @property + def trailer(self) -> Any: + """A read-only view of the file trailer.""" + with _native_errors(): + return self._native.object_json(0, 2) + + @property + def root_object(self) -> Any: + """A read-only view of the document catalog.""" + with _native_errors(): + return self._native.object_json(-1, 3) + + @property + def annotations(self) -> Any: + """Form, language, XMP, outline and structure tree of the document + as it currently is, including edits not yet written.""" + with _native_errors(): + return self._native.annotations() + + def open( + self, *, source: PdfSource | _PdfDocument, password: str | None = None + ) -> None: + """Open a document, replacing the current state.""" + self._open(source, password) + + def _page_no_index(self, *, page_no: int, insertion: bool = False) -> int: + if isinstance(page_no, bool): + raise TypeError("page_no must be an integer, starting at 1") + value = operator.index(page_no) + maximum = len(self.pages) + int(insertion) + if not 1 <= value <= maximum: + raise IndexError(f"page_no {value} out of range; expected 1..{maximum}") + return value - 1 + + def _selection(self, *, page_nos: Iterable[int] | None) -> list[int] | None: + if page_nos is None: + return None + result = [] + for value in page_nos: + if isinstance(value, bool): + raise TypeError("page_nos must contain integers, starting at 1") + value = operator.index(value) + if value < 1: + raise ValueError("page_nos must start at 1") + result.append(value - 1) + return result + + def get_page(self, *, page_no: int) -> PdfPage: + "Get page. Page numbers start at 1." + return _PdfDocument._get_page( + self, page_number=self._page_no_index(page_no=page_no, insertion=False) + ) + + def get_page_no(self, *, page: PdfPage) -> int: + """The one-based number of a page belonging to this document.""" + return _PdfDocument._get_page_number(self, page=page) + 1 + + def get_pages_showing_field(self, *, name: str) -> list[PdfPage]: + "The pages that show the form field with this fully qualified name." + return _PdfDocument._get_pages_showing_field(self, name=name) + + def get_fields(self) -> dict[str, dict[str, Any]]: + 'The form fields by fully qualified name. Each field has "kind"\n(text, checkbox, radio, choice, pushbutton, signature), "value",\n"default_value", "choices", "states", "read_only", "pages", and the\nraw "type" and "flags".' + return _PdfDocument._get_fields( + self, + ) + + def get_form_text_fields(self) -> dict[str, str]: + "The value of every text field, by fully qualified name." + return _PdfDocument._get_form_text_fields( + self, + ) + + def get_attachment(self, *, name: str) -> bytes: + "The content of the embedded file registered under `name`." + return _PdfDocument._get_attachment(self, name=name) + + def append( + self, + *, + source: Any, + page_nos: Iterable[int] | None = None, + before_page_no: int | None = None, + password: str | None = None, + import_outline: bool = True, + ) -> None: + "Append. Page numbers start at 1." + return _PdfEditing._append( + self, + source=source, + pages=self._selection(page_nos=page_nos), + index=( + before_page_no + if before_page_no is None or before_page_no is _UNSET + else self._page_no_index(page_no=before_page_no, insertion=True) + ), + password=password, + import_outline=import_outline, + ) + + def merge( + self, + *, + before_page_no: int | None, + fileobj: Any, + page_nos: Iterable[int] | None = None, + password: str | None = None, + import_outline: bool = True, + ) -> None: + "Merge. Page numbers start at 1." + return _PdfEditing._merge( + self, + position=( + None + if before_page_no is None + else self._page_no_index(page_no=before_page_no, insertion=True) + ), + fileobj=fileobj, + pages=self._selection(page_nos=page_nos), + password=password, + import_outline=import_outline, + ) + + def add_page(self, *, page: PdfPage) -> PdfEditablePage: + "Append a copy of a page of any reader, writer or editor." + return _PdfEditing._add_page(self, page=page) + + def insert_page(self, *, page: PdfPage, before_page_no: int = 1) -> PdfEditablePage: + "Insert page. Page numbers start at 1." + return _PdfEditing._insert_page( + self, + page=page, + index=self._page_no_index(page_no=before_page_no, insertion=True), + ) + + def add_blank_page(self, *, width: float, height: float) -> PdfEditablePage: + "Add an empty page at the end. Sizes are in points (1/72 inch)." + return _PdfEditing._add_blank_page(self, width=width, height=height) + + def insert_blank_page( + self, *, before_page_no: int, width: float, height: float + ) -> PdfEditablePage: + "Insert blank page. Page numbers start at 1." + return _PdfEditing._insert_blank_page( + self, + index=self._page_no_index(page_no=before_page_no, insertion=True), + width=width, + height=height, + ) + + def add_image( + self, + *, + image: _pdf_images.ImageSource, + before_page_no: int | None = None, + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> list[PdfEditablePage]: + "Add image. Page numbers start at 1." + return _PdfEditing._add_image( + self, + image=image, + index=( + before_page_no + if before_page_no is None or before_page_no is _UNSET + else self._page_no_index(page_no=before_page_no, insertion=True) + ), + page_size=page_size, + margin=margin, + dpi=dpi, + ) + + @classmethod + def from_images( + cls, + *, + images: Iterable[_pdf_images.ImageSource], + page_size: str | Sequence[float] | None = None, + margin: float = 0, + dpi: float | None = None, + ) -> Any: + document = cls() + for image in images: + document.add_image(image=image, page_size=page_size, margin=margin, dpi=dpi) + return document + + def duplicate_page( + self, *, page_no: int, before_page_no: int | None = None + ) -> PdfEditablePage: + "Duplicate page. Page numbers start at 1." + return _PdfEditing._duplicate_page( + self, + index=self._page_no_index(page_no=page_no, insertion=False), + to=( + before_page_no + if before_page_no is None or before_page_no is _UNSET + else self._page_no_index(page_no=before_page_no, insertion=True) + ), + ) + + def remove_page(self, *, page_no: int, clean: bool = False) -> None: + "Remove page. Page numbers start at 1." + return _PdfEditing._remove_page( + self, + index=self._page_no_index(page_no=page_no, insertion=False), + clean=clean, + ) + + def move_page(self, *, page_no: int, to_page_no: int) -> None: + "Move page. Page numbers start at 1." + return _PdfEditing._move_page( + self, + from_index=self._page_no_index(page_no=page_no, insertion=False), + to_index=self._page_no_index(page_no=to_page_no, insertion=False), + ) + + def add_metadata(self, *, infos: dict[str, str | None]) -> None: + 'Set entries of the document information dictionary. Keys may be\nwritten "Title" or "/Title"; a value of None removes the entry.' + return _PdfEditing._add_metadata(self, infos=infos) + + def set_xmp_metadata(self, *, packet: str | bytes | None) -> None: + "Replace the XMP metadata packet, or remove it with None." + return _PdfEditing._set_xmp_metadata(self, packet=packet) + + def set_page_layout(self, *, layout: str | None) -> None: + 'Set how pages are laid out when the document opens: "/SinglePage",\n"/OneColumn", "/TwoColumnLeft", "/TwoColumnRight", "/TwoPageLeft" or\n"/TwoPageRight". None removes the setting.' + return _PdfEditing._set_page_layout(self, layout=layout) + + def set_page_mode(self, *, mode: str | None) -> None: + 'Set what a viewer shows beside the pages: "/UseNone",\n"/UseOutlines", "/UseThumbs", "/FullScreen", "/UseOC" or\n"/UseAttachments". None removes the setting.' + return _PdfEditing._set_page_mode(self, mode=mode) + + def set_viewer_preferences(self, *, preferences: dict[str, Any] | None) -> None: + 'Replace the viewer preferences, for example\n`{"/HideToolbar": True, "/Direction": "/R2L"}`. None removes them.' + return _PdfEditing._set_viewer_preferences(self, preferences=preferences) + + def set_open_destination(self, *, page_no: int | None) -> None: + "Set open destination. Page numbers start at 1." + return _PdfEditing._set_open_destination( + self, + page_number=( + None + if page_no is None + else self._page_no_index(page_no=page_no, insertion=False) + ), + ) + + def set_page_label( + self, + *, + first_page_no: int, + last_page_no: int, + style: str | None = None, + prefix: str | None = None, + start: int | None = None, + ) -> None: + "Set page label. Page numbers start at 1." + return _PdfEditing._set_page_label( + self, + page_index_from=self._page_no_index(page_no=first_page_no, insertion=False), + page_index_to=self._page_no_index(page_no=last_page_no, insertion=False), + style=style, + prefix=prefix, + start=start, + ) + + def add_named_destination(self, *, title: str, page_no: int) -> None: + "Add named destination. Page numbers start at 1." + return _PdfEditing._add_named_destination( + self, + title=title, + page_number=( + None + if page_no is None + else self._page_no_index(page_no=page_no, insertion=False) + ), + ) + + def add_outline_item( + self, + *, + title: str, + page_no: int | None, + parent: int | None = None, + url: str | None = None, + left: float | None = None, + top: float | None = None, + zoom: float | None = None, + color: Sequence[float] | str | None = None, + bold: bool = False, + italic: bool = False, + is_open: bool = True, + ) -> int: + "Add outline item. Page numbers start at 1." + return _PdfEditing._add_outline_item( + self, + title=title, + page_number=( + None + if page_no is None + else self._page_no_index(page_no=page_no, insertion=False) + ), + parent=parent, + url=url, + left=left, + top=top, + zoom=zoom, + color=color, + bold=bold, + italic=italic, + is_open=is_open, + ) + + def update_outline_item( + self, + *, + item_id: int, + title: str = _UNSET, + page_no: int | None = _UNSET, + url: str | None = _UNSET, + left: float | None = _UNSET, + top: float | None = _UNSET, + zoom: float | None = _UNSET, + color: Sequence[float] | str | None = _UNSET, + bold: bool = _UNSET, + italic: bool = _UNSET, + is_open: bool = _UNSET, + ) -> None: + "Update outline item. Page numbers start at 1." + return _PdfEditing._update_outline_item( + self, + item_id=item_id, + title=title, + page_number=( + page_no + if page_no is None or page_no is _UNSET + else self._page_no_index(page_no=page_no, insertion=False) + ), + url=url, + left=left, + top=top, + zoom=zoom, + color=color, + bold=bold, + italic=italic, + is_open=is_open, + ) + + def remove_outline_item(self, *, item_id: int) -> None: + "Remove a bookmark and every bookmark below it." + return _PdfEditing._remove_outline_item(self, item_id=item_id) + + def move_outline_item( + self, *, item_id: int, parent: int | None = None, index: int | None = None + ) -> None: + "Move a bookmark below `parent` (None: the top level), at position\n`index` among its new siblings (None: last). Its children move with\nit." + return _PdfEditing._move_outline_item( + self, item_id=item_id, parent=parent, index=index + ) + + def clear_outline(self) -> None: + "Remove every bookmark." + return _PdfEditing._clear_outline( + self, + ) + + def add_table_of_contents( + self, + *, + before_page_no: int = 1, + title: str = "Contents", + font: str = "Helvetica", + size: float = 11, + max_depth: int | None = None, + page_size: str | Sequence[float] | None = None, + ) -> list[PdfEditablePage]: + "Add table of contents. Page numbers start at 1." + return _PdfEditing._add_table_of_contents( + self, + index=self._page_no_index(page_no=before_page_no, insertion=True), + title=title, + font=font, + size=size, + max_depth=max_depth, + page_size=page_size, + ) + + def update_form_field_values( + self, *, fields: dict[str, str | bool], flatten: bool = False + ) -> int: + 'Fill in form fields, by fully qualified name; a partial name works\nwhen only one field has it.\n\nText and choice fields take a string. A checkbox takes True, False,\nor one of its states; a radio group takes the state to select\n("/Choice1", or "Choice1"), or "/Off". The fields\' appearances are\nregenerated so the values show in every viewer.\n\nWith `flatten`, the form is then turned into page content. Returns\nthe number of fields set; an unknown name raises `PdfEditError`.' + return _PdfEditing._update_form_field_values( + self, fields=fields, flatten=flatten + ) + + def add_text_field( + self, + *, + page_no: int, + name: str, + rect: Sequence[float], + value: str | None = None, + multiline: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + "Add text field. Page numbers start at 1." + return _PdfEditing._add_text_field( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + name=name, + rect=rect, + value=value, + multiline=multiline, + font_size=font_size, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_checkbox( + self, + *, + page_no: int, + name: str, + rect: Sequence[float], + checked: bool = False, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + "Add checkbox. Page numbers start at 1." + return _PdfEditing._add_checkbox( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + name=name, + rect=rect, + checked=checked, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_choice_field( + self, + *, + page_no: int, + name: str, + rect: Sequence[float], + options: Sequence[str], + value: str | None = None, + editable: bool = False, + font_size: float = 12, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + "Add choice field. Page numbers start at 1." + return _PdfEditing._add_choice_field( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + name=name, + rect=rect, + options=options, + value=value, + editable=editable, + font_size=font_size, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_radio_group( + self, + *, + page_no: int, + name: str, + buttons: dict[str, Sequence[float]], + selected: str | None = None, + read_only: bool = False, + required: bool = False, + tooltip: str | None = None, + ) -> None: + "Add radio group. Page numbers start at 1." + return _PdfEditing._add_radio_group( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + name=name, + buttons=buttons, + selected=selected, + read_only=read_only, + required=required, + tooltip=tooltip, + ) + + def add_signature_field( + self, + *, + page_no: int, + name: str, + rect: Sequence[float], + required: bool = False, + tooltip: str | None = None, + ) -> None: + "Add signature field. Page numbers start at 1." + return _PdfEditing._add_signature_field( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + name=name, + rect=rect, + required=required, + tooltip=tooltip, + ) + + def update_form_field( + self, + *, + name: str, + new_name: str = _UNSET, + rect: Sequence[float] = _UNSET, + read_only: bool = _UNSET, + required: bool = _UNSET, + tooltip: str | None = _UNSET, + options: Sequence[str] = _UNSET, + ) -> None: + "Change a form field. Only the arguments given change.\n\n`new_name` renames the field (its last name part). `rect` moves or\nresizes a field that has one widget. `tooltip` None removes it.\n`options` replaces the entries of a choice field." + return _PdfEditing._update_form_field( + self, + name=name, + new_name=new_name, + rect=rect, + read_only=read_only, + required=required, + tooltip=tooltip, + options=options, + ) + + def remove_form_field(self, *, name: str) -> None: + "Remove a form field, and its widgets from the pages." + return _PdfEditing._remove_form_field(self, name=name) + + def set_need_appearances_writer(self, *, state: bool = True) -> None: + "Set the form's NeedAppearances flag, which asks a viewer to build\nthe field appearances itself." + return _PdfEditing._set_need_appearances_writer(self, state=state) + + def flatten_annotations(self) -> None: + "Draw every visible annotation, form fields included, into its\npage and remove the annotations. Values stay visible; the document\nis no longer interactive." + return _PdfEditing._flatten_annotations( + self, + ) + + def add_annotation(self, *, page_no: int, annotation: dict[str, Any]) -> None: + "Add annotation. Page numbers start at 1." + return _PdfEditing._add_annotation( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + annotation=annotation, + ) + + def add_uri( + self, + *, + page_no: int, + uri: str, + rect: Sequence[float], + border: Sequence[float] | None = None, + ) -> None: + "Add uri. Page numbers start at 1." + return _PdfEditing._add_uri( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + uri=uri, + rect=rect, + border=border, + ) + + def add_link( + self, *, page_no: int, rect: Sequence[float], target_page_no: int + ) -> None: + "Add link. Page numbers start at 1." + return _PdfEditing._add_link( + self, + page_number=self._page_no_index(page_no=page_no, insertion=False), + rect=rect, + target_page_number=self._page_no_index( + page_no=target_page_no, insertion=False + ), + ) + + def remove_annotations(self, *, subtypes: Iterable[str] | str | None = None) -> int: + 'Remove annotations from every page: those of the given subtypes\n("/Link", "/Highlight", ...), or with None all of them except form\nfields. Naming "/Widget" removes form fields too. Returns the number\nremoved.' + return _PdfEditing._remove_annotations(self, subtypes=subtypes) + + def remove_links(self) -> int: + "Remove every link annotation. Returns the number removed." + return _PdfEditing._remove_links( + self, + ) + + def add_attachment( + self, + *, + filename: str, + data: str | bytes, + description: str | None = None, + mime_type: str | None = None, + ) -> None: + "Embed a file in the document. An attachment of the same name is\nreplaced." + return _PdfEditing._add_attachment( + self, + filename=filename, + data=data, + description=description, + mime_type=mime_type, + ) + + def remove_attachment(self, *, name: str) -> bool: + "Remove an embedded file. Returns False if there was none." + return _PdfEditing._remove_attachment(self, name=name) + + def add_js(self, *, javascript: str, name: str | None = None) -> None: + "Add a document-level script, which a viewer runs when it opens\nthe document. docling-parse stores the script and never runs it." + return _PdfEditing._add_js(self, javascript=javascript, name=name) + + def remove_javascript(self) -> int: + "Remove the document-level scripts and scripted document actions.\nReturns the number of entries removed." + return _PdfEditing._remove_javascript( + self, + ) + + def encrypt( + self, + *, + user_password: str, + owner_password: str | None = None, + algorithm: str = "AES-256", + allow_print: bool | str = True, + allow_modify: bool = True, + allow_extract: bool = True, + allow_annotate: bool = True, + allow_fill_forms: bool = True, + allow_accessibility: bool = True, + allow_assemble: bool = True, + ) -> None: + 'Protect everything written from now on with a password.\n\nThe output is encrypted with AES-256, the only password scheme PDF\n2.0 keeps; older, weaker algorithms are not offered. `user_password`\nis needed to open the document; pass "" together with an\n`owner_password` to let anyone open it. `owner_password` defaults to\nthe user password.\n\nThe `allow_*` arguments say what someone who opens the document with\nthe user password may do. `allow_print` is True, False, or "low" for\nlow-resolution printing only. Viewers honor these flags; they are\nnot access control.\n\nWithout this call the output is unencrypted, even when the source was\nencrypted.' + return _PdfEditing._encrypt( + self, + user_password=user_password, + owner_password=owner_password, + algorithm=algorithm, + allow_print=allow_print, + allow_modify=allow_modify, + allow_extract=allow_extract, + allow_annotate=allow_annotate, + allow_fill_forms=allow_fill_forms, + allow_accessibility=allow_accessibility, + allow_assemble=allow_assemble, + ) + + def set_output_options( + self, + *, + compress_streams: bool = True, + object_streams: str = "preserve", + linearize: bool = False, + ) -> None: + 'Choose how the file is written.\n\n`compress_streams` compresses streams that are stored uncompressed.\n`object_streams` is "preserve", "generate" (pack objects into\ncompressed object streams: smaller files) or "disable" (larger, and\nreadable by PDF 1.4 software). `linearize` orders the file so a\nviewer can show the first page before the rest has arrived.' + return _PdfEditing._set_output_options( + self, + compress_streams=compress_streams, + object_streams=object_streams, + linearize=linearize, + ) + + def remove_encryption(self) -> None: + "Undo `encrypt`: write unencrypted output again." + return _PdfEditing._remove_encryption( + self, + ) + + def to_bytes(self) -> bytes: + "The document serialized as a complete PDF file." + return _PdfEditing._to_bytes( + self, + ) + + def write(self, *, target: str | os.PathLike[str] | BinaryIO) -> None: + "Write the document to a path or a binary stream.\n\nA path is written through a temporary sibling file that replaces the\ntarget only once it is complete. A stream receives the whole file in\none `write` call and is not closed." + return _PdfEditing._write(self, target=target) + + # Compatibility policy belongs here. Reader and writer adapters only bind + # pypdf-shaped arguments and forward them to these named operations. + def _compat_open( + self, + *, + stream: Any, + strict: bool = False, + password: str | bytes | None = None, + root_object_recovery_limit: int | None = 10000, + ) -> None: + if root_object_recovery_limit != 10000: + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "qpdf does not expose pypdf's root-object recovery limit", + ) + self.open( + source=stream, + password=password.decode("latin-1") + if isinstance(password, bytes) + else password, + ) + if strict: + try: + with _native_errors(): + self._native.validate_strict() + except PdfEditError as exc: + self.close() + raise PdfLoadError( + "", PdfLoadErrorCategory.DAMAGED, str(exc) + ) from exc + + def _compat_init_writer( + self, + *, + fileobj: Any, + clone_from: Any, + incremental: bool, + full: bool, + strict: bool, + keep_initial_header: bool, + incremental_clone_object_count_limit: int | None, + incremental_clone_object_id_limit: int | None, + ) -> None: + if incremental: + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "incremental output requires the incremental serializer", + ) + source = clone_from + if source is None and fileobj is not None and fileobj != "": + if isinstance(fileobj, (str, os.PathLike)): + if os.path.isfile(fileobj) and os.path.getsize(fileobj): + source = fileobj + elif hasattr(fileobj, "read"): + position = fileobj.tell() + if fileobj.seek(0, 2): + source = fileobj + fileobj.seek(position) + else: + source = fileobj + if source is None: + self._native.create_empty() + else: + self._compat_open(stream=source, strict=strict) + + def _compat_get_fields( + self, + *, + tree: Any, + retval: Any, + fileobj: Any, + stack: Any, + visited: Any, + depth: int, + traversal_state: Any, + ) -> dict[str, Any]: + if ( + tree is not None + or visited is not None + or depth + or traversal_state is not None + ): + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "subtree traversal requires the PDF object editing API", + ) + fields = self.get_fields() + if retval is not None: + retval.update(fields) + fields = retval + if fileobj is not None: + for name, field in fields.items(): + fileobj.write(f"{name}: {field['value']}\n") + return fields + + def _compat_text_fields(self, *, full_qualified_name: bool) -> dict[str, Any]: + fields = self.get_form_text_fields() + if full_qualified_name: + return fields + result: dict[str, Any] = {} + for name, value in fields.items(): + partial = name.rsplit(".", 1)[-1] + key, suffix = partial, 2 + while key in result: + key = f"{partial}.{suffix}" + suffix += 1 + result[key] = value + return result + + def _compat_pages_showing_field(self, *, field: Any) -> list[PdfPage]: + if isinstance(field, str): + name = field + else: + name = field.get("name", field.get("/T", "")) + return self.get_pages_showing_field(name=str(name)) + + def _compat_append( + self, + *, + fileobj: Any, + outline_item: Any = None, + pages: Any = None, + import_outline: bool = True, + excluded_fields: Any = None, + position: int | None = None, + ) -> None: + if outline_item is not None and not isinstance(outline_item, str): + if pages is not None: + raise TypeError("page selection supplied twice") + pages, outline_item = outline_item, None + if excluded_fields: + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "excluding imported page keys requires the PDF object editing API", + ) + native, temporary = self._import_source(fileobj, None) + try: + count = native.page_count() + if pages is None: + selected = list(range(count)) + elif isinstance(pages, slice): + selected = list(range(*pages.indices(count))) + elif isinstance(pages, tuple): + selected = list(range(*pages)) + elif hasattr(pages, "indices"): + selected = list(range(*pages.indices(count))) + else: + selected = [ + p.index if isinstance(p, PdfPage) else operator.index(p) + for p in pages + ] + selected = [p + count if p < 0 else p for p in selected] + if any(p < 0 or p >= count for p in selected): + raise IndexError("source page index out of range") + insertion = ( + len(self.pages) if position is None else self._position(position) + ) + # Reuse an already-open source and keep it alive until copying ends. + source = temporary if temporary is not None else fileobj + self.append( + source=source, + page_nos=[p + 1 for p in selected], + before_page_no=insertion + 1, + import_outline=import_outline, + ) + if outline_item is not None and selected: + self.add_outline_item(title=outline_item, page_no=insertion + 1) + finally: + if temporary is not None: + temporary.close() + + def _compat_insert_page( + self, *, page: PdfPage, index: int, excluded_keys: Iterable[str] + ) -> PdfEditablePage: + if tuple(excluded_keys): + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "excluding page keys requires the PDF object editing API", + ) + return self.insert_page(page=page, before_page_no=self._position(index) + 1) + + def _compat_blank_page( + self, *, width: float | None, height: float | None, index: int + ) -> PdfEditablePage: + if width is None or height is None: + if not self.pages: + raise ValueError("width and height are required for the first page") + box = self.pages[min(index, len(self.pages) - 1)].mediabox + width = box.width if width is None else width + height = box.height if height is None else height + return self.insert_blank_page( + before_page_no=self._position(index) + 1, width=width, height=height + ) + + def _compat_add_annotation( + self, *, page_number: int | PdfPage, annotation: dict[str, Any] + ) -> dict[str, Any]: + index = ( + page_number.index + if isinstance(page_number, PdfPage) + else self._page_index(page_number) + ) + self.add_annotation(page_no=index + 1, annotation=annotation) + return self.pages[index].annotations[-1] + + def _compat_named_destination(self, *, title: str, page_no: int, fit: Any) -> Any: + if fit is not None and getattr(fit, "fit_type", "/Fit") != "/Fit": + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "this destination fit mode is not supported", + ) + return self.add_named_destination(title=title, page_no=page_no) + + def _compat_outline_item( + self, + *, + title: str, + page_number: Any, + parent: Any, + before: Any, + color: Any, + bold: bool, + italic: bool, + fit: Any, + is_open: bool, + ) -> int: + page_no = ( + None + if page_number is None + else ( + page_number.index + 1 + if isinstance(page_number, PdfPage) + else self._page_index(page_number) + 1 + ) + ) + options: dict[str, Any] = {} + if fit is not None: + kind = getattr(fit, "fit_type", "/Fit") + if kind == "/XYZ": + options.update(zip(("left", "top", "zoom"), fit.fit_args)) + elif kind != "/Fit": + raise PdfUnsupportedError( + PdfEditErrorCategory.UNSUPPORTED, + "this outline fit mode is not supported", + ) + item = self.add_outline_item( + title=title, + page_no=page_no, + parent=parent, + color=color, + bold=bold, + italic=italic, + is_open=is_open, + **options, + ) + if before is not None: + siblings = self.outline + if parent is not None: + pending = list(siblings) + while pending: + entry = pending.pop() + if entry["id"] == parent: + siblings = entry["children"] + break + pending.extend(entry["children"]) + indices = [i for i, entry in enumerate(siblings) if entry["id"] == before] + if not indices: + self.remove_outline_item(item_id=item) + raise ValueError("before must be a bookmark with the same parent") + self.move_outline_item(item_id=item, parent=parent, index=indices[0]) + return item + + def _compat_encrypt( + self, + *, + user_password: str, + owner_password: str | None, + use_128bit: bool, + permissions_flag: int, + algorithm: str | None, + ) -> None: + flags = int(permissions_flag) + self.encrypt( + user_password=user_password, + owner_password=owner_password, + algorithm=algorithm or ("RC4-128" if use_128bit else "RC4-40"), + allow_print=(True if flags & 2048 else "low") if flags & 4 else False, + allow_modify=bool(flags & 8), + allow_extract=bool(flags & 16), + allow_annotate=bool(flags & 32), + allow_fill_forms=bool(flags & 256), + allow_accessibility=bool(flags & 512), + allow_assemble=bool(flags & 1024), + ) + + def _compat_write(self, *, stream: Any) -> tuple[bool, Any]: + if stream == "": + raise ValueError("output path is empty") + self.write(target=stream) + if isinstance(stream, (str, os.PathLike)): + with open(stream, "rb+") as result: + result.seek(0, 2) + return True, result + if hasattr(stream, "flush"): + stream.flush() + return False, stream diff --git a/docling_parse/pdf_errors.py b/docling_parse/pdf_errors.py new file mode 100644 index 000000000..71803c9a9 --- /dev/null +++ b/docling_parse/pdf_errors.py @@ -0,0 +1,118 @@ +"""Exceptions raised by docling-parse when a PDF cannot be loaded or edited. + +This module imports nothing but the standard library, so the reader, writer +and editor can raise the same load errors as `docling_parse.pdf_parser` +without importing docling-core or pydantic. `docling_parse.pdf_parser` +re-exports the load errors under their former names. +""" + +from __future__ import annotations + +from enum import Enum + + +class PdfLoadErrorCategory(str, Enum): + """Why docling-parse could not load a document. + + The values are the categories the native loader reports, see + `src/parse/qpdf/load_error.h`. + """ + + PASSWORD = "password" + """The document is encrypted and the password is missing or wrong.""" + DAMAGED = "damaged" + """qpdf could not repair the file.""" + UNSUPPORTED = "unsupported" + """The file uses a feature qpdf does not implement.""" + IO = "io" + """The file is missing or unreadable.""" + UNKNOWN = "unknown" + + +class PdfLoadError(RuntimeError): + """docling-parse could not load a document. + + A RuntimeError, so handlers written for the former generic error keep + working, and the message keeps its former prefix. `category` says what + went wrong; `detail` is the message of the underlying (qpdf) failure. + """ + + def __init__( + self, + key: str, + category: PdfLoadErrorCategory, + detail: str, + *, + reason: str | None = None, + ): + self.key = key + self.category = category + self.detail = detail + + message = f"Failed to load document with key {key}" + description = reason or detail + if description: + message = f"{message}: {description}" + super().__init__(message) + + +class PdfPasswordError(PdfLoadError): + """The document is encrypted and was opened without a valid password. + + `password_supplied` tells whether the caller gave a (wrong) password or + none at all: qpdf reports both as the same invalid-password error. + """ + + def __init__(self, key: str, detail: str, *, password_supplied: bool): + self.password_supplied = password_supplied + if password_supplied: + reason = "the supplied password is incorrect" + else: + reason = "the document is encrypted and requires a password" + super().__init__(key, PdfLoadErrorCategory.PASSWORD, detail, reason=reason) + + +class PdfEditErrorCategory(str, Enum): + """Why an inspection, an edit or a write failed. + + The values are the categories the native editor reports: the load + categories of `src/parse/qpdf/load_error.h` plus those of + `src/edit/edit_error.h`. + """ + + PASSWORD = "password" + DAMAGED = "damaged" + UNSUPPORTED = "unsupported" + IO = "io" + UNKNOWN = "unknown" + INVALID_EDIT = "invalid_edit" + """A bad argument, or an operation the document's state does not allow.""" + STALE_HANDLE = "stale_handle" + """A page handle obtained before the page list changed.""" + WRITE = "write" + """The output could not be produced.""" + + +class PdfEditError(RuntimeError): + """An operation on a PdfReader, PdfWriter or PdfEditor failed. + + `category` says what went wrong; `detail` is the message of the + underlying (qpdf) failure. + """ + + def __init__(self, category: PdfEditErrorCategory, detail: str): + self.category = category + self.detail = detail + super().__init__(detail) + + +class PdfStaleHandleError(PdfEditError): + """A page handle was used after pages were inserted, removed or moved.""" + + +class PdfWriteError(PdfEditError): + """The document could not be serialized or the output could not be written.""" + + +class PdfUnsupportedError(PdfEditError): + """The document uses a feature that is not supported.""" diff --git a/docling_parse/pdf_parser.py b/docling_parse/pdf_parser.py index 11e235e30..7f29e7905 100644 --- a/docling_parse/pdf_parser.py +++ b/docling_parse/pdf_parser.py @@ -3,7 +3,7 @@ import hashlib import logging import math -from enum import Enum, IntEnum +from enum import IntEnum from io import BytesIO from pathlib import Path from typing import ( @@ -41,6 +41,11 @@ from PIL import Image as PILImage from pydantic import BaseModel, ConfigDict, Field +from docling_parse.pdf_errors import ( + PdfLoadError, + PdfLoadErrorCategory, + PdfPasswordError, +) from docling_parse.pdf_parsers import ( # type: ignore[import] TIMING_KEY_CREATE_LINE_CELLS, TIMING_KEY_CREATE_WORD_CELLS, @@ -88,67 +93,6 @@ _log = logging.getLogger(__name__) -class PdfLoadErrorCategory(str, Enum): - """Why docling-parse could not load a document. - - The values are the categories the native loader reports, see - `src/parse/qpdf/load_error.h`. - """ - - PASSWORD = "password" - """The document is encrypted and the password is missing or wrong.""" - DAMAGED = "damaged" - """qpdf could not repair the file.""" - UNSUPPORTED = "unsupported" - """The file uses a feature qpdf does not implement.""" - IO = "io" - """The file is missing or unreadable.""" - UNKNOWN = "unknown" - - -class PdfLoadError(RuntimeError): - """docling-parse could not load a document. - - A RuntimeError, so handlers written for the former generic error keep - working, and the message keeps its former prefix. `category` says what - went wrong; `detail` is the message of the underlying (qpdf) failure. - """ - - def __init__( - self, - key: str, - category: PdfLoadErrorCategory, - detail: str, - *, - reason: str | None = None, - ): - self.key = key - self.category = category - self.detail = detail - - message = f"Failed to load document with key {key}" - description = reason or detail - if description: - message = f"{message}: {description}" - super().__init__(message) - - -class PdfPasswordError(PdfLoadError): - """The document is encrypted and was opened without a valid password. - - `password_supplied` tells whether the caller gave a (wrong) password or - none at all: qpdf reports both as the same invalid-password error. - """ - - def __init__(self, key: str, detail: str, *, password_supplied: bool): - self.password_supplied = password_supplied - if password_supplied: - reason = "the supplied password is incorrect" - else: - reason = "the document is encrypted and requires a password" - super().__init__(key, PdfLoadErrorCategory.PASSWORD, detail, reason=reason) - - def _load_error(native_parser, key: str, password: str | None) -> PdfLoadError: """Build the exception for a failed load from the native parser's record.""" info = native_parser.take_load_error(key) diff --git a/docling_parse/pdf_reader.py b/docling_parse/pdf_reader.py new file mode 100644 index 000000000..0264dbffe --- /dev/null +++ b/docling_parse/pdf_reader.py @@ -0,0 +1,55 @@ +"""PdfReader: open a PDF and inspect it without changing it. + +```python +from docling_parse.pdf_reader import PdfReader + +with PdfReader("document.pdf") as reader: + print(len(reader.pages), reader.metadata.get("Title")) + for page in reader.pages: + print(page.extract_text()) +``` +""" + +from __future__ import annotations + +from docling_parse import pdf_parsers as _native # type: ignore[attr-defined] +from docling_parse._pdf_compat import _PdfReaderCompat +from docling_parse._pdf_document import ( + PdfBox, + PdfImage, + PdfPage, + PdfPages, + PdfSource, + _PdfDocument, +) + +__all__ = ["PdfBox", "PdfImage", "PdfPage", "PdfPages", "PdfReader"] + + +class PdfReader(_PdfReaderCompat): + """A read-only PDF document. + + `source` is a path, bytes, a binary stream (read, never closed), or + another PdfReader, PdfWriter or PdfEditor. Opening parses the document + structure only; a page is decoded when its text is asked for. + + One reader may be shared between threads: calls are serialized. + """ + + _native_class = _native.pdf_reader + + def __init__( + self, + stream: PdfSource | _PdfDocument, + strict: bool = False, + password: str | bytes | None = None, + *, + root_object_recovery_limit: int | None = 10000, + ): + super().__init__() + self._editor._compat_open( + stream=stream, + strict=strict, + password=password, + root_object_recovery_limit=root_object_recovery_limit, + ) diff --git a/docling_parse/pdf_writer.py b/docling_parse/pdf_writer.py new file mode 100644 index 000000000..95a85ddc8 --- /dev/null +++ b/docling_parse/pdf_writer.py @@ -0,0 +1,80 @@ +"""PdfWriter: assemble, change and write PDF documents. + +```python +from docling_parse.pdf_writer import PdfWriter + +writer = PdfWriter() +writer.append("file1.pdf") +writer.append("file2.pdf", pages=[0, 2]) +writer.write("merged.pdf") + +writer = PdfWriter(clone_from="document.pdf") +writer.pages[0].rotate(90) +del writer.pages[3] +writer.write("changed.pdf") +``` +""" + +from __future__ import annotations + +from docling_parse import pdf_parsers as _native # type: ignore[attr-defined] +from docling_parse._pdf_compat import _PdfWriterCompat +from docling_parse._pdf_document import ( + STANDARD_FONTS, + PdfBox, + PdfEditablePage, + PdfImage, + PdfPages, + PdfSource, + _PdfDocument, +) + +__all__ = [ + "STANDARD_FONTS", + "PdfBox", + "PdfEditablePage", + "PdfImage", + "PdfPages", + "PdfWriter", +] + + +class PdfWriter(_PdfWriterCompat): + """A PDF document being written. + + `PdfWriter()` starts empty; pages are added with `append` and + `add_blank_page`. `PdfWriter(clone_from=...)` starts from a complete copy + of an existing document, keeping everything it contains (forms, outline, + structure, attachments), and never modifies that source. + + Output is a full, unencrypted rewrite: signatures of the source do not + stay valid, and an encrypted source is written in the clear. + + One writer may be shared between threads: calls are serialized. + """ + + _native_class = _native.pdf_writer + + def __init__( + self, + fileobj: PdfSource | _PdfDocument | None = "", + clone_from: PdfSource | _PdfDocument | None = None, + incremental: bool = False, + full: bool = False, + strict: bool = False, + *, + keep_initial_header: bool = False, + incremental_clone_object_count_limit: int | None = 500000, + incremental_clone_object_id_limit: int | None = 1000000, + ): + super().__init__() + self._editor._compat_init_writer( + fileobj=fileobj, + clone_from=clone_from, + incremental=incremental, + full=full, + strict=strict, + keep_initial_header=keep_initial_header, + incremental_clone_object_count_limit=incremental_clone_object_count_limit, + incremental_clone_object_id_limit=incremental_clone_object_id_limit, + ) diff --git a/docs/editing.md b/docs/editing.md new file mode 100644 index 000000000..f331f9e48 --- /dev/null +++ b/docs/editing.md @@ -0,0 +1,210 @@ +# PDF reading and editing + +Use `PdfReader` to inspect a PDF, `PdfWriter` for the implemented pypdf-style +workflows, and `PdfEditor` for the full editing API and page rendering. The +three classes share one native implementation; Reader and Writer adapt their +calls to the editor. + +The compatibility reference is **pypdf 6.21.1**, pinned in the development +dependencies. Signatures of the implemented Reader/Writer methods are checked +against that version. This is a supported subset, with different result types +and unsupported options; it is not a drop-in replacement for all pypdf code. +See [API coverage](#api-coverage) before migrating a workflow. + +## Guides + +| Guide | Topics | +|---|---| +| [Pages](editing/pages.md) | Opening, text extraction, assembly, geometry, stamps and watermarks | +| [Navigation](editing/navigation.md) | Bookmarks, destinations, labels and contents pages; preservation limits | +| [Forms](editing/forms.md) | Inspect, fill, create, update, remove and flatten fields | +| [Annotations and attachments](editing/annotations-and-attachments.md) | Links, comments, embedded files and scripts | +| [Text and images](editing/text-and-images.md) | Draw text, export images and create PDFs from images | +| [Rendering](editing/rendering.md) | Render a selected page, including unsaved edits | +| [Output and encryption](editing/output-and-encryption.md) | Paths, streams, passwords, permissions and serialization | + +## Which class to use + +| Class | Purpose | Can edit | +|---|---|---| +| `PdfReader` | Inspect pages, text, images and document information | No | +| `PdfWriter` | Assemble or clone documents through pypdf-style methods | Yes | +| `PdfEditor` | Inspect, edit, render and write through named methods | Yes | + +`PdfReader` exposes read-only page handles. `PdfWriter` and `PdfEditor` expose +editable ones. Import all three from the package: + +```python +from docling_parse import PdfEditor, PdfReader, PdfWriter +``` + +## Arguments and page numbering + +**All public PdfEditor method parameters, including its constructor, are +keyword-only.** Arguments such as `page_no` and `before_page_no` start at 1. +`page_nos` selects one-based source pages. Zero and negative page numbers are +rejected. + +Reader/Writer compatibility methods keep the pypdf argument names, order and +zero-based page indices. Every `pages` sequence is a Python sequence, including +`editor.pages`: indexing starts at 0, negative indices count from the end, and +slices are half-open. + +| Expression | Meaning | +|---|---| +| `editor.get_page(page_no=1)` | First page | +| `editor.render_page(page_no=1, scale=2.0)` | Render the first page | +| `editor.remove_page(page_no=1)` | Remove the first page | +| `editor.append(source=other, page_nos=[1, 3])` | Copy the first and third source pages | +| `reader.get_page(0)` or `reader.pages[0]` | First page | +| `writer.remove_page(0)` | Remove the first page | +| `writer.append(other, pages=[0, 2])` | Copy the first and third source pages | + +Page handles keep zero-based `index` and `page_number` properties. +`editor.get_page_no(page=page)` returns a one-based number; +`reader.get_page_number(page)` returns a zero-based index. Inspection +dictionaries also retain zero-based `page` and `pages` values on all three +classes. Convert such a value with `index + 1` when passing it to an editor +page-number argument. Bookmark sibling positions, such as +`move_outline_item(index=0)`, are ordinary zero-based positions, not page numbers. + +## Quick start + +Read text and metadata: + +```python +from docling_parse import PdfReader + +with PdfReader("document.pdf") as reader: + print(len(reader.pages), reader.metadata.get("Title")) + for page in reader.pages: + print(page.extract_text()) +``` + +Merge selected pages through the compatibility API: + +```python +from docling_parse import PdfWriter + +with PdfWriter() as writer: + writer.append("document.pdf") + writer.append("appendix.pdf", pages=[0, 2]) + writer.write("merged.pdf") +``` + +Edit and render before saving (this example assumes at least four pages): + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.get_page(page_no=1).rotate(angle=90) + editor.remove_page(page_no=4) + editor.render_page(page_no=1, scale=2.0).save("preview.png") + editor.write(target="changed.pdf") +``` + +Make a PDF from image files: + +```python +from docling_parse import PdfEditor + +with PdfEditor.from_images( + images=["scan-1.jpg", "scan-2.png"], page_size="A4" +) as editor: + editor.write(target="scans.pdf") +``` + +## Document information + +These properties are available on Reader, Writer and Editor: + +| Property | Result | +|---|---| +| `metadata` | `/Info` strings as a dictionary: `{"Title": "..."}` | +| `xmp_metadata` | Raw XMP packet as text, or `None` | +| `pdf_header`, `pdf_version` | Header such as `"%PDF-1.7"`, and version such as `"1.7"` | +| `is_encrypted`, `encryption` | Encryption status and parameters | +| `permissions` | Permission booleans, or `None` for an unencrypted document | +| `outline` | Bookmark dictionaries with resolved page indices | +| `named_destinations`, `open_destination` | Resolved destinations | +| `page_labels` | Display labels, one per page | +| `page_layout`, `page_mode`, `viewer_preferences` | Viewer settings | +| `has_form`, `has_xfa` | AcroForm/XFA presence | +| `attachment_info`, `attachments`, `javascript` | Embedded-file metadata, bytes and scripts | + +These are detached Python values, not pypdf's `DocumentInformation`, +`Destination` or `Field` objects. Editing a returned dictionary does not edit +the PDF. On `PdfEditor`, `get_object(object_id=12, depth=2)`, `trailer` and +`root_object` provide read-only object views; `annotations` returns the current +document's form, language, XMP, outline and structure information. + +## Behavior to know about + +- **Lazy work.** Opening parses document structure; text, image and render + requests decode pages on demand. Editing and serialization run in C++. + Measured comparisons of these editing workflows against pypdf are still + outstanding; no speedup is claimed here. +- **Source ownership.** Input streams are read and never closed by the library. + An opened document costs at least its input byte size in memory. An editor + starts a separate editing copy on its first change. Imported source + documents remain alive until the importing document closes. +- **Page handles.** Removing or moving pages, or inserting before existing + pages, invalidates old handles with `PdfStaleHandleError`. Take a new handle + afterward. In-place edits and appending at the end keep them valid. +- **Thread safety.** Calls on one object are serialized. Use separate objects + for parallel throughput. +- **Signatures.** Output is a full rewrite; existing digital signatures do not + remain valid. Signature fields can be created, but signing and signature + validation are not implemented. +- **Permissions and scripts.** Permission flags are reported, not enforced. + JavaScript is stored, listed and removed; it is never executed by this library. + +Errors are in `docling_parse.pdf_errors`: + +| Exception | Meaning | +|---|---| +| `PdfLoadError` | Input could not be opened; `category` gives the reason | +| `PdfPasswordError` | Password is missing or wrong; a `PdfLoadError` | +| `PdfEditError` | Invalid edit or failure in a native operation | +| `PdfUnsupportedError` | A requested feature is unsupported; a `PdfEditError` | +| `PdfStaleHandleError` | A handle no longer identifies its original page | +| `PdfWriteError` | Native serialization or output failed | + +Python argument and stream operations can also raise `TypeError`, +`ValueError`, `IndexError` or `OSError`. + +## API coverage + +| Workflow | Current support and limits | +|---|---| +| Input and pages | Paths, bytes, binary streams, passwords; lazy page sequence | +| Text extraction | Plain and layout modes; no visitors or other pypdf extraction options | +| Assembly | Clone, append, insert, delete, reorder, duplicate and blank pages | +| Geometry and composition | Boxes, rotation, scale, affine transforms, vector overlays and underlays | +| Navigation | Read/add/edit/move/remove bookmarks; contents pages; read/add named destinations; page labels and viewer settings | +| Forms | Read/fill/create/update/remove/flatten; XFA presence only | +| Annotations and attachments | Read/add/remove annotations and links; read/add/replace/remove attachments; script storage/removal | +| Text drawing | Twelve Latin standard fonts and WinAnsi characters | +| Images | Export; new image pages, including multi-frame files; no image replacement or placement on existing pages | +| Rendering | `PdfEditor.render_page(page_no=..., scale=...)` | +| Encryption | AES-256 editor default; pypdf-compatible writer algorithm and permission arguments | +| Output | Stream compression, object streams and linearization; full rewrites | +| Raw PDF objects | Read-only JSON-like views on Editor; no editable object/stream model | +| Missing workflows | Incremental writing, text/image removal, deduplication, image recompression, article threads and signing | + +Matching a method signature does not imply that every pypdf option is +implemented. In particular, nonempty `excluded_fields`/`excluded_keys`, +non-default root-object recovery limits, subtree form traversal, and fit modes +other than `/Fit` (plus `/XYZ` for bookmarks) raise `PdfUnsupportedError`. +`PdfWriter(incremental=True)` also raises that error. + +`PdfWriter.write(stream)` returns `(opened_by_writer, stream)`, following pypdf; +`PdfEditor.write(target=...)` returns `None`. Writer methods that resemble +pypdf object factories do not provide its live object model; for example, +`add_attachment` and `add_named_destination` currently return `None`. + +The topic guides document these implemented workflows and their limits. +The unsupported capabilities listed above remain unfinished work; signature +compatibility alone is not evidence of full feature parity. + diff --git a/docs/editing/annotations-and-attachments.md b/docs/editing/annotations-and-attachments.md new file mode 100644 index 000000000..1d32c05cf --- /dev/null +++ b/docs/editing/annotations-and-attachments.md @@ -0,0 +1,117 @@ +# Annotations, attachments and scripts + +[Editing overview](../editing.md) · [Navigation preservation](navigation.md#what-assembly-preserves) + +## Inspect annotations + +```python +from docling_parse import PdfReader + +with PdfReader("document.pdf") as reader: + for annotation in reader.pages[0].annotations: + print(annotation["/Subtype"], annotation["/Rect"], annotation.get("/Contents")) +``` + +Annotations are detached dictionaries keyed by PDF names, such as `/Subtype` +and `/Contents`. A local link also reports a resolved zero-based `page` index. +Appearance streams and back-references such as `/P` are omitted from this +inspection view. Changing the dictionary does not change the document. + +## Add comments and links + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.add_uri( + page_no=1, uri="https://example.org", rect=(72, 700, 200, 720) + ) + editor.add_link(page_no=1, rect=(72, 660, 200, 680), target_page_no=3) + editor.add_annotation( + page_no=1, + annotation={ + "/Subtype": "/Text", + "/Rect": [300, 700, 320, 720], + "/Contents": "Please check this figure", + } + ) + editor.write(target="annotated.pdf") +``` + +Rectangles are `(left, bottom, right, top)`. For dictionary input, strings +starting with `/` represent PDF names; other strings represent text. +`/Subtype` and `/Rect` are required for generic annotations. +A URI link has no border unless `border` is supplied to `add_uri`. + +## Remove or flatten + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="annotated.pdf") as editor: + editor.remove_links() + editor.remove_annotations(subtypes="/Text") + editor.remove_annotations() + editor.write(target="without-annotations.pdf") +``` + +An omitted Editor `subtypes` removes non-widget annotations and keeps form +fields. Name `/Widget` explicitly to remove widgets and their fields. +`flatten_annotations()` instead draws visible appearances into the page and +removes interactive annotations. + +The Writer compatibility method requires the `subtypes` argument: +`writer.remove_annotations(None)` removes non-widget annotations. +`writer.remove_annotations` and `writer.remove_links` return `None`; +the named Editor operations return removal counts. + +## Embedded files + +```python +from docling_parse import PdfEditor, PdfReader + +with PdfEditor(source="document.pdf") as editor: + editor.add_attachment( + filename="data.csv", data=b"year,value\n2026,42\n", + description="Source data", mime_type="text/csv" + ) + editor.add_attachment(filename="notes.txt", data="Reviewer notes") + editor.write(target="with-attachments.pdf") + +with PdfReader("with-attachments.pdf") as reader: + print(reader.attachment_info) + print(reader.attachments["data.csv"]) + print(reader.get_attachment("data.csv")) + +with PdfEditor(source="with-attachments.pdf") as editor: + editor.remove_attachment(name="notes.txt") + editor.write(target="remaining-attachments.pdf") +``` + +`attachments` maps names to lists of byte strings. `attachment_info` includes +filename, description, size, MIME type and dates. Adding the same name replaces +its existing entry. The Writer adapter takes `add_attachment(filename, data)`; +description and MIME type options belong to the named Editor API. +Neither currently returns pypdf's live `EmbeddedFile` object. + +## JavaScript as data + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.add_js(javascript="this.print({bUI: true});", name="print") + print(editor.javascript) + editor.remove_javascript() + editor.write(target="without-scripts.pdf") +``` + +Scripts are never executed by docling-parse. `remove_javascript()` removes +document-level scripts, a scripted open action and document additional actions. +It does not promise to sanitize every page, annotation or nested action graph. + +Cloning retains document-level scripts and embedded files initially. +`append()` and `merge()` do **not** import these document-level collections. +Page-local actions or file-attachment annotations may still arrive with copied +pages. See [assembly preservation](navigation.md#what-assembly-preserves). + diff --git a/docs/editing/forms.md b/docs/editing/forms.md new file mode 100644 index 000000000..125dd09d6 --- /dev/null +++ b/docs/editing/forms.md @@ -0,0 +1,140 @@ +# Forms + +[Editing overview](../editing.md) · [Rendering](rendering.md) + +## Read fields + +The inspection example assumes the form has a field named `name`. + +```python +from docling_parse import PdfReader + +with PdfReader("form.pdf") as reader: + fields = reader.get_fields() + for name, field in fields.items(): + print(name, field["kind"], field["value"], field["states"], field["pages"]) + print(reader.get_form_text_fields(full_qualified_name=True)) + print(reader.get_pages_showing_field(fields["name"])) + print(reader.has_form, reader.has_xfa) +``` + +`get_fields()` returns a dictionary keyed by fully qualified field name. +Each field reports `kind`, `value`, `default_value`, `choices`, `states`, +`flags`, `read_only`, `rects`, `pages` and its names. `pages` contains +zero-based page indices, even when reading through `PdfEditor`. +Radio groups report their combined selectable states and all widget rectangles. + +Reader/Writer accept a field dictionary or a name in +`get_pages_showing_field(field)`. Editor uses +`get_pages_showing_field(name="name")`. The returned values are page handles. + +Kinds include text, checkbox, radio, choice, pushbutton and signature. +XFA presence is reported; XFA data is not parsed or updated. +The compatibility `get_fields` signature accepts pypdf's traversal arguments, +but non-default subtree traversal is unsupported. + +## Create fields + +This example creates a new one-page form: + +```python +from docling_parse import PdfEditor + +with PdfEditor() as editor: + editor.add_blank_page(width=595, height=842) + editor.add_text_field( + page_no=1, name="name", rect=(72, 700, 300, 720), + value="Ada", tooltip="Your full name" + ) + editor.add_text_field( + page_no=1, name="notes", rect=(72, 600, 300, 690), multiline=True + ) + editor.add_checkbox( + page_no=1, name="agree", rect=(72, 570, 86, 584), checked=True + ) + editor.add_choice_field( + page_no=1, name="country", rect=(72, 540, 300, 560), + options=["Belgium", "Italy", "Switzerland"], value="Italy" + ) + editor.add_radio_group( + page_no=1, name="plan", + buttons={"basic": (72, 510, 86, 524), "premium": (120, 510, 134, 524)}, + selected="premium" + ) + editor.add_signature_field( + page_no=1, name="signature", rect=(72, 420, 300, 480), + required=True, tooltip="Signature" + ) + editor.write(target="created-form.pdf") +``` + +Names must be unique in the form and contain no period. Rectangles are +`(left, bottom, right, top)` in PDF user space. + +| Field | Additional options | +|---|---| +| Text | `value`, `multiline`, `font_size`, `read_only`, `required`, `tooltip` | +| Checkbox | `checked`, `read_only`, `required`, `tooltip` | +| Choice | `options`, `value`, `editable`, `font_size`, `read_only`, `required`, `tooltip` | +| Radio group | `buttons`, `selected`, `read_only`, `required`, `tooltip` | +| Signature placeholder | `required`, `tooltip`; no constructor `read_only` argument | + +Choice fields are drop-downs; `editable=True` allows a value outside the +option list. Radio button names must be distinct and cannot be `Off`. +Signature fields are empty placeholders for a signing application; the library +does not sign. + +Creation builds appearance streams: text and choices use Helvetica, while +checkboxes, radio buttons and signature frames are drawn by the editor. +List boxes, comb fields, custom field fonts and setting default values are +not exposed. + +## Fill and update + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="created-form.pdf") as editor: + editor.update_form_field_values( + fields={"name": "Grace", "agree": False, "country": "Belgium", "plan": "/basic"} + ) + editor.update_form_field( + name="name", new_name="full_name", + rect=(72, 690, 400, 720), read_only=True + ) + editor.update_form_field(name="country", options=["Belgium", "France"]) + editor.update_form_field(name="full_name", tooltip=None) + editor.remove_form_field(name="notes") + editor.write(target="filled.pdf") +``` + +Fields are addressed by fully qualified name, such as `address.street`. +An unambiguous partial name also works. Unknown names and button states raise +`PdfEditError`. Text and choice values are strings; checkbox values can be +booleans or state names. A radio value selects a named state, with or without +its leading slash; `/Off` clears the selection. + +Values update the appearance streams. `update_form_field` changes only the +arguments supplied. `rect` requires a single widget; it cannot resize an +entire multi-widget radio group. `options` applies to choice fields. +Removal takes all of the field's widgets off their pages. + +Reader/Writer's `get_form_text_fields()` defaults to partial names, adding +suffixes to distinguish duplicate partial names. +`full_qualified_name=True` returns fully qualified names. Editor's no-argument +`get_form_text_fields()` returns fully qualified names. + +## Flatten + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="filled.pdf") as editor: + editor.update_form_field_values(fields={"full_name": "Grace Hopper"}, flatten=True) + editor.write(target="flattened.pdf") +``` + +Alternatively call `editor.flatten_annotations()`. Flattening draws visible +annotations, including form appearances, into page content and removes the +interactive annotations. It affects other visible annotations as well as forms. + diff --git a/docs/editing/navigation.md b/docs/editing/navigation.md new file mode 100644 index 000000000..f808c4f0c --- /dev/null +++ b/docs/editing/navigation.md @@ -0,0 +1,154 @@ +# Navigation: bookmarks, destinations and contents + +[Editing overview](../editing.md) · [Pages](pages.md) + +## Inspect navigation + +```python +from docling_parse import PdfReader + +with PdfReader("document.pdf") as reader: + print(reader.outline) + print(reader.named_destinations) + print(reader.page_labels) + print(reader.open_destination) + print(reader.page_layout, reader.page_mode, reader.viewer_preferences) +``` + +Bookmarks are dictionaries containing `id`, `title`, `page`, `url`, `open`, +`children`, destination details and styling. Destination dictionaries contain +`page`, `kind` and `arguments`. Their `page` values are zero-based indices, or +`None` when no surviving page is resolved, on all three classes. Add 1 when +passing an inspected index into an editor `page_no` argument. + +Bookmark IDs are PDF object numbers valid within the object that returned +them. Reopen a written file and retrieve its IDs again; serialization can +renumber objects. The dictionaries are inspection results, not live PDF objects. + +## Create and edit bookmarks + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + chapter = editor.add_outline_item(title="Chapter 1", page_no=1) + section = editor.add_outline_item(title="Section 1.1", page_no=2, parent=chapter) + editor.add_outline_item(title="Figure", page_no=3, top=400, zoom=1.5) + editor.add_outline_item(title="Notes", page_no=None) + editor.add_outline_item( + title="Project", page_no=None, url="https://example.org" + ) + editor.update_outline_item( + item_id=section, title="1.1 Introduction", page_no=3, + color="#c00000", bold=True, is_open=False + ) + editor.move_outline_item(item_id=section, parent=None, index=0) + editor.remove_outline_item(item_id=chapter) + editor.write(target="bookmarks.pdf") +``` + +`left`, `top` and `zoom` choose an `/XYZ` target; omitted coordinates preserve +the viewer's corresponding setting. `page_no=None` makes a heading without a +page target. `url` selects a URI action. `color=None` restores default color. +Only arguments supplied to `update_outline_item` are changed. + +`move_outline_item` moves children with their parent. Its `index` is a +zero-based sibling position; `None` appends. An item cannot move beneath +itself or its descendants. `clear_outline()` removes the complete outline. + +The Writer compatibility method follows pypdf's +`add_outline_item(title, page_number, parent, before, color, bold, italic, fit, is_open)`. +It supports `before` and `/Fit` or `/XYZ` fit objects. Other fit modes are +unsupported. Use the named editor methods for URL targets and direct +`left`/`top`/`zoom` arguments. + +## Generate contents pages + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.add_outline_item(title="Introduction", page_no=1) + editor.add_outline_item(title="Results", page_no=3) + editor.add_table_of_contents( + before_page_no=1, title="Contents", max_depth=1, + page_size="A4", font="Times-Roman", size=12 + ) + editor.write(target="with-contents.pdf") +``` + +As many pages as needed are inserted. Lines are indented by bookmark depth, +show the destination's display label, and link to that page. URL bookmarks +and headings without page targets are listed without a page number or link. +`max_depth=0` includes top-level entries only. + +This is a simple generated layout: widths are estimated, long titles are +shortened, and unsupported characters become `?`. For exact typography, +import a designed contents page and add links separately. + +## Labels, destinations and viewer settings + +This example uses a document with at least five pages. + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.set_page_label(first_page_no=1, last_page_no=2, style="/r", start=1) + editor.set_page_label(first_page_no=3, last_page_no=5, style="/D", start=1) + editor.add_named_destination(title="summary", page_no=3) + editor.set_open_destination(page_no=3) + editor.set_page_layout(layout="/TwoColumnLeft") + editor.set_page_mode(mode="/UseOutlines") + editor.set_viewer_preferences(preferences={"HideToolbar": True, "FitWindow": True}) + editor.write(target="navigation.pdf") +``` + +Label styles are `/D` (decimal), `/R`/`/r` (Roman) and `/A`/`/a` +(alphabetic); `prefix` adds text. A `None` style gives a prefix-only label. +Label ranges are inclusive. Named destinations are added or replaced by name +and currently target a fitted page. + +Pass `None` to the open destination, layout, mode or preference setter to +remove that setting. Labels are stored by page position; reapply them after +inserting, deleting or reordering pages if the intended labels should follow +the original pages. + +## What assembly preserves + +Cloning (`PdfEditor(source=...)` or `PdfWriter(clone_from=...)`) starts from +the complete source catalog. `append()`/`merge()` assemble selected pages +into the destination and have narrower preservation behavior: + +| Content | Clone starting state | Append/merge | +|---|---|---| +| Page text, graphics and resources | Retained | Copied with selected pages | +| Page annotations and form widgets | Retained | Copied, with qpdf widget repair | +| Bookmarks | Retained | Imported by default when they lead to copied pages | +| Named destination definitions | Retained | Not imported | +| Page label ranges | Retained | Not imported | +| `/Info` and XMP | Retained | Source metadata is not imported | +| Document-level embedded files | Retained | Not imported | +| Document-level JavaScript | Retained | Not imported | +| Viewer settings and open action | Retained | Source settings are not imported | +| Tagged structure | Retained initially | Structure trees are not merged | + +Set `import_outline=False` to omit source bookmarks. Bookmarks to omitted +source pages are excluded. When a source page is imported more than once, +imported bookmarks target its first copy. + +Moving an existing page preserves destinations that reference that page +object. Removing a page clears local links and named destinations resolved +to it, clears its open action, and leaves its bookmarks as headings without +a page target. Link annotations whose target was removed can remain as +inactive rectangles. + +**Cross-document links are not comprehensively remapped during assembly.** +Copied local links and references to named destinations may not target the +intended imported page, especially for subsets or repeated imports. Check +and recreate them with `add_link` as needed. General action graphs and +tagged-structure repair are not implemented. + +These preservation limits also apply when contents pages or other insertions +change page positions. See [output and signatures](output-and-encryption.md#signatures-and-unsupported-output). + diff --git a/docs/editing/output-and-encryption.md b/docs/editing/output-and-encryption.md new file mode 100644 index 000000000..bc9730848 --- /dev/null +++ b/docs/editing/output-and-encryption.md @@ -0,0 +1,141 @@ +# Output and encryption + +[Editing overview](../editing.md) · [Assembly preservation](navigation.md#what-assembly-preserves) + +## Write to a path, stream or bytes + +```python +from io import BytesIO + +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.add_metadata(infos={"/Title": "Annual report", "/Author": "Finance"}) + editor.write(target="report.pdf") + output = BytesIO() + editor.write(target=output) + pdf_bytes = editor.to_bytes() +``` + +Path output uses a temporary sibling and atomic replacement, so a failed +serialization does not leave a partially written target. Writing to the +source path is supported because input is already in memory. + +Stream output serializes to memory and performs a Python write; the stream +is not closed. Output-sized memory is needed, and a stream failure can leave +partial output in that stream. `PdfEditor.write` returns `None`. + +The Writer compatibility return value follows pypdf: + +```python +from io import BytesIO + +from docling_parse import PdfWriter + +with PdfWriter(clone_from="document.pdf") as writer: + output = BytesIO() + opened_by_writer, stream = writer.write(output) + assert opened_by_writer is False and stream is output +``` + +For path output, the returned flag is `True` and the returned file object is +closed. For a caller-supplied stream, it is `False` and the stream remains open. + +## Metadata and output options + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.add_metadata(infos={"Title": "Report", "Subject": None}) + editor.set_xmp_metadata(packet=None) + editor.set_output_options( + compress_streams=True, object_streams="generate", linearize=False + ) + editor.write(target="compact.pdf") +``` + +Metadata keys accept an optional leading slash. A `None` value removes an +entry. XMP is supplied as a raw string or byte packet; `None` removes it. + +Streams are compressed by default. `object_streams` is `"preserve"` (default), +`"generate"` or `"disable"`. `linearize=True` enables fast-web-view ordering. +Each `set_output_options` call supplies a complete option set; omitted +parameters take their defaults. These options do not merge identical objects +or recompress images, and they do not promise a smaller file for every input. + +## Passwords and permissions + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.encrypt( + user_password="secret", owner_password="owner-secret", + allow_print="low", allow_extract=False, allow_modify=False + ) + editor.write(target="protected-output.pdf") +``` + +Editor defaults to `algorithm="AES-256"`. `owner_password` defaults to the user +password. A nonempty owner password with an empty user password permits opening +without a password while still setting owner permissions. + +Editor permission arguments are `allow_print`, `allow_modify`, `allow_extract`, +`allow_annotate`, `allow_fill_forms`, `allow_accessibility` and `allow_assemble`. +Printing accepts `True`, `False` or `"low"`. Defaults allow all permissions. +Conforming viewers interpret the flags; docling-parse reports them and does +not enforce them as access control. Older encryption revisions cannot represent +all newer permission distinctions. + +The Writer adapter accepts pypdf's `use_128bit`, `permissions_flag` and +`algorithm` arguments. Its default algorithm follows pypdf: **RC4-128**, or +RC4-40 when `use_128bit=False` and no algorithm is specified. Request AES-256 +explicitly for this workflow: + +```python +from docling_parse import PdfWriter + +with PdfWriter(clone_from="document.pdf") as writer: + writer.encrypt("secret", owner_password="owner-secret", algorithm="AES-256") + writer.write("protected-compat.pdf") +``` + +Accepted algorithm names are `"RC4-40"`, `"RC4-128"`, `"AES-128"`, +`"AES-256-R5"` and `"AES-256"`. The older schemes exist for compatibility; +AES-256 is the current editor default. + +`remove_encryption()` clears requested output encryption. Output is +unencrypted unless `encrypt` was called, including when the input was encrypted. +While editing, `is_encrypted` and `encryption` describe the planned output. + +To clone a protected document through Writer, open a Reader with its password +and pass that Reader as `clone_from`; the Writer constructor has no password +argument: + +```python +from docling_parse import PdfReader, PdfWriter + +with PdfReader("protected.pdf", password="secret") as reader: + with PdfWriter(clone_from=reader) as writer: + writer.write("unprotected-copy.pdf") +``` + +`PdfReader(..., strict=True)` rejects input that qpdf repaired or that produced +structural warnings. This concerns input loading; it is not a strict +signature-preservation option. Custom `root_object_recovery_limit` values are +unsupported. + +## Signatures and unsupported output + +Every write is a full rewrite. Existing digital signatures do not remain +valid. The current API does not implement signing, signature validation, or +a warn/refuse policy specifically for signed input. + +Incremental writing is unavailable: +`PdfWriter(..., incremental=True)` raises `PdfUnsupportedError`. +The other pypdf-shaped constructor options do not add an incremental serializer +or editable PDF object model. Use the documented workflows rather than +assuming that accepting a constructor signature implies every corresponding +pypdf mode is implemented. + diff --git a/docs/editing/pages.md b/docs/editing/pages.md new file mode 100644 index 000000000..a055e650f --- /dev/null +++ b/docs/editing/pages.md @@ -0,0 +1,155 @@ +# Pages: reading, assembly and geometry + +[Editing overview](../editing.md) · [Navigation and preservation](navigation.md) + +Editor examples use named arguments and one-based page numbers. Reader/Writer +examples keep zero-based indices; all `pages[...]` sequences are zero-based. + +## Open and inspect + +A source can be a path, bytes, a binary stream, or another Reader, Writer or +Editor. Streams you provide are read and remain open. Passwords are supplied +when opening; there is no separate `decrypt()` step. + +```python +from docling_parse import PdfEditor, PdfReader + +with PdfEditor(source="document.pdf") as editor: + first = editor.get_page(page_no=1) + print(editor.get_page_no(page=first)) # 1 + print(first.index, first.page_number) # 0, 0 + print(first.extract_text()) + print(first.extract_text(extraction_mode="layout")) + print(first.mediabox, first.cropbox, first.rotation, first.user_unit) + +with PdfReader("protected.pdf", password="secret") as reader: + print(reader.get_page(0).extract_text()) + print(len(reader.pages), reader.pages[-1].mediabox) +``` + +Plain extraction joins the decoder's line cells with newlines. Layout mode +places words on a character grid to retain columns, indentation and vertical +spacing. Neither promises character-for-character agreement with pypdf. +Visitor functions and other pypdf text extraction options are unavailable. + +`mediabox`, `cropbox`, `trimbox`, `bleedbox` and `artbox` are +`PdfBox(left, bottom, right, top)` values with `width` and `height`. +Coordinates are in default PDF user space: normally one unit is 1/72 inch; +`user_unit` reports any additional physical scale. The crop box defaults to +the media box, and the other three boxes default to the crop box. + +## Assemble or split + +```python +from docling_parse import PdfEditor + +with PdfEditor() as editor: + editor.append(source="document.pdf", page_nos=[1, 3]) + editor.append(source="appendix.pdf", before_page_no=2) + editor.insert_blank_page(before_page_no=1, width=595, height=842) + editor.write(target="assembled.pdf") +``` + +Omit `page_nos` to copy all source pages. A list can reorder or repeat pages. +Omit `before_page_no` to append at the end; insertion accepts 1 through +`len(editor.pages) + 1`. + +The compatibility methods use pypdf's argument order: + +```python +from docling_parse import PdfWriter + +with PdfWriter() as writer: + writer.append("document.pdf", pages=[0, 2]) + writer.merge(1, "appendix.pdf", pages=[0]) + writer.insert_blank_page(width=595, height=842, index=0) + writer.write("assembled-compat.pdf") +``` + +Writer page selection also accepts half-open range tuples such as `(0, 3)` +and `(0, 6, 2)`, slices, and objects with pypdf PageRange-style `indices()`. +Use a list such as `[0, 3]` to select individual pages rather than a range. +A second positional argument to `append` can be an outline heading; use the +`pages` keyword for clarity. + +Page-local content, annotations and form widgets are copied. Document-level +preservation differs from cloning: see [the preservation table](navigation.md#what-assembly-preserves). +Nonempty pypdf `excluded_fields` and `excluded_keys` arguments are unsupported. + +## Clone and change an existing document + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.get_page(page_no=1).rotate(angle=90) + editor.get_page(page_no=2).cropbox = (20, 20, 180, 280) + editor.duplicate_page(page_no=1) + editor.move_page(page_no=3, to_page_no=1) + editor.remove_page(page_no=4) + editor.write(target="reordered.pdf") +``` + +Cloning starts with the whole document graph, including its metadata, forms, +bookmarks, structure, attachments and scripts. The source is only overwritten +if you explicitly write to its path. `PdfWriter(clone_from=source)` offers the +same starting point through the compatibility API. + +`duplicate_page` appends by default, or inserts before `before_page_no`. +For a page handle from any Reader, Writer or Editor, use +`editor.add_page(page=page)` or `editor.insert_page(page=page, before_page_no=1)`. + +`remove_page(page_no=..., clean=True)` additionally replaces the detached +page object with PDF null so stray references cannot keep it as a page. +This does not provide general structure-tree repair. + +## Transform pages + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + page = editor.get_page(page_no=1) + page.scale_by(factor=0.5) + page.scale_to(width=300, height=400) + page.add_transformation(ctm=(1, 0, 0, 1, 20, 30)) + page.rotation = 180 + page.transfer_rotation_to_content() + editor.write(target="transformed.pdf") +``` + +`scale(sx=..., sy=...)`, `scale_by` and `scale_to` scale content, annotations +and all five page boxes. `add_transformation` transforms content and annotation +geometry but leaves the boxes alone. A matrix is `(a, b, c, d, e, f)`. + +`rotate(angle=90)` adds clockwise display rotation; setting `rotation` sets +the absolute value. Both require multiples of 90. Flattening rotation moves +it into content and annotation coordinates and adjusts page boxes. + +After insertion, removal or reordering, reacquire page handles. Old handles +raise `PdfStaleHandleError`; they do not silently follow a different page. + +## Stamps and watermarks + +```python +from docling_parse import PdfEditor, PdfReader + +with PdfReader("stamp.pdf") as stamp, PdfEditor(source="document.pdf") as editor: + overlay = stamp.pages[0] + editor.get_page(page_no=1).merge_page(page=overlay, over=True) + editor.get_page(page_no=2).merge_page(page=overlay, over=False) + editor.get_page(page_no=3).merge_page(page=overlay, fit=True) + editor.get_page(page_no=4).merge_translated_page(page=overlay, tx=40, ty=60) + editor.write(target="stamped.pdf") +``` + +Composition uses vector Form XObjects. The default keeps the other page at +its own coordinates. `fit=True` centers and fits it within the target trim +box, accounting for display rotation. Explicit placement is available through +`merge_transformed_page(page=..., ctm=...)`, `merge_scaled_page(page=..., scale=...)` +and `merge_rotated_page(page=..., rotation=...)`. The latter rotates content +counter-clockwise about the origin. + +The overlaid page's annotations and form widgets are not copied. Its text +and graphics are drawn; interactive links and controls require separate edits. + diff --git a/docs/editing/rendering.md b/docs/editing/rendering.md new file mode 100644 index 000000000..21f2fd489 --- /dev/null +++ b/docs/editing/rendering.md @@ -0,0 +1,72 @@ +# Render a page + +[Editing overview](../editing.md) · [Page geometry](pages.md) + +`PdfEditor` renders a selected page using the native Blend2D rendering path. +It decodes the page's text, shapes, images and available widget appearances, +then returns a Pillow image. + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + page_image = editor.render_page(page_no=1, scale=2.0) + page_image.save("page-1.png") +``` + +Both arguments are named. `page_no` starts at **1**. `scale` defaults to 1.0: +one pixel per PDF point, or 72 dpi at the usual `UserUnit=1`. +`scale=2.0` gives 144 dpi at that user unit. Scale must be finite and positive. + +## Preview unsaved edits + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.get_page(page_no=1).rotate(angle=90) + editor.get_page(page_no=1).draw_text( + text="DRAFT", x=72, y=120, size=32, color="#c00000" + ) + modified = editor.is_modified + preview = editor.render_page(page_no=1, scale=2.0) + assert editor.is_modified == modified + editor.write(target="previewed.pdf") + +preview.save("edited-page.png") +``` + +Rendering uses the current document snapshot, including edits not yet written +to a path. It leaves the document's modification state unchanged. +The returned image owns its pixels and remains usable after the editor closes. +Rendering accounts for the page crop box and display rotation. + +## Image format and resource use + +Images are in `RGBA` mode. Save PNG directly; convert for formats that do +not accept alpha: + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + editor.render_page(page_no=1).convert("RGB").save("page-1.jpg") +``` + +Pillow is imported on demand. Larger scales increase pixel count in both +dimensions, so doubling the scale uses roughly four times the pixel memory. +Font programs and image samples are requested when rendering; simply opening +an editor does not rasterize its pages. + +Missing embedded fonts can require system font substitution. Results then +depend on the available fonts; see [system-font setup](../../README.md#system-fonts). +Rendering remains subject to the renderer's supported PDF features. + +This API currently exposes `page_no` and `scale`. It has no region, canvas-size, +or `RenderConfig` argument. `PdfReader` and `PdfWriter` do not expose +`render_page`; use an Editor when a preview is needed. + +A zero or negative page number raises `ValueError`; an out-of-range positive +number raises `PdfEditError`. Non-integer page numbers raise `TypeError`, and +non-finite or non-positive scales raise `ValueError`. + diff --git a/docs/editing/text-and-images.md b/docs/editing/text-and-images.md new file mode 100644 index 000000000..fe1493bd9 --- /dev/null +++ b/docs/editing/text-and-images.md @@ -0,0 +1,112 @@ +# Drawing text and working with images + +[Editing overview](../editing.md) · [Rendering](rendering.md) + +## Draw text + +```python +from docling_parse import PdfEditor + +with PdfEditor(source="document.pdf") as editor: + page = editor.get_page(page_no=1) + page.draw_text( + text="CONFIDENTIAL", x=72, y=780, size=24, + font="Helvetica-Bold", color="#c00000" + ) + page.draw_text(text="Approved by:\nDate:", x=72, y=120) + editor.write(target="labelled.pdf") +``` + +`x` and `y` locate the first baseline, measured from the lower-left origin +in default PDF user space. At the usual `UserUnit=1`, units and font sizes are +points. Each newline moves down by 1.2 times `size`. +`color` is `"#rrggbb"` or an RGB triple with components from 0 to 1. +The output is PDF text that can be selected, searched and extracted. + +`font` is one of the twelve Latin standard fonts, also exported as +`STANDARD_FONTS`: + +| Family | Names | +|---|---| +| Helvetica | `Helvetica`, `Helvetica-Bold`, `Helvetica-Oblique`, `Helvetica-BoldOblique` | +| Times | `Times-Roman`, `Times-Bold`, `Times-Italic`, `Times-BoldItalic` | +| Courier | `Courier`, `Courier-Bold`, `Courier-Oblique`, `Courier-BoldOblique` | + +No font program is embedded. WinAnsiEncoding supports Western European text, +including the euro sign and smart quotes. Characters outside that encoding, +such as Greek, Cyrillic and CJK text, raise `PdfUnsupportedError`. General +Unicode text drawing and exact font-metric layout are not implemented. +The [contents-page generator](navigation.md#generate-contents-pages) has its own +replacement and truncation policy for unsupported or long titles. + +## Export existing page images + +```python +from docling_parse import PdfReader + +with PdfReader("document.pdf") as reader: + for index, image in enumerate(reader.pages[0].images): + print(image.name, image.bbox, image.width, image.height, image.format) + if image.format == "raw": + image.to_pil().save(f"extracted-{index}.png") + else: + image.save(f"extracted-{index}{image.extension}") +``` + +Each `PdfImage` carries `name`, `bbox`, `width`, `height`, `format`, `mode` and +`data`. Enumeration decodes the page. `save` writes the stored bytes as-is; +it does not convert their format. Formats include: + +| Format | Stored data | +|---|---| +| `jpeg`, `jp2` | Encoded image file | +| `jbig2` | Embedded JBIG2 stream | +| `raw` | Uncompressed samples described by `mode`, `width` and `height` | + +Raw samples saved directly with `save` are not a PNG or JPEG. Use `to_pil()` +and Pillow's save methods to encode them. `to_pil()` supports JPEG, JP2 and raw +samples; unsupported formats raise `PdfUnsupportedError`. +Failed decoding can produce an empty `data` value. + +## Create PDFs from images + +```python +from docling_parse import PdfEditor + +with PdfEditor.from_images( + images=["scan-1.jpg", "scan-2.png"], page_size="A4", margin=36 +) as editor: + editor.add_image(image="photo.jpg", before_page_no=1, dpi=300) + editor.write(target="image-pages.pdf") +``` + +An image source can be a path, bytes, a binary stream or a PIL image, in a +format Pillow can read. Pillow is imported when image operations need it. + +- Suitable 8-bit JPEG files are embedded without re-encoding. Mirrored EXIF + orientations and unsupported JPEG sample formats take the decoded path. +- Other supported formats, including PNG, TIFF, GIF, BMP and WebP, are decoded + and stored losslessly at the supported sample depth. Transparency becomes + a soft mask. Sixteen-bit grayscale is reduced to eight bits. +- Multi-page TIFF and animated GIF inputs add one page per frame. + `add_image` returns the added page handles. +- EXIF orientation is applied. CMYK JPEG handling accounts for Adobe sample + inversion. + +Without `page_size`, image dimensions use the requested `dpi`, the file's +declared resolution, or 72 dpi. `margin` adds a border. +With `page_size`, the image is centered and scaled to **fit within** the area +inside the margins, preserving its proportions. It may leave unused space; +it is not cropped to fill the page. + +Page sizes are `"A3"`, `"A4"`, `"A5"`, `"Letter"`, `"Legal"` or +`(width, height)` in points. Image input failures can raise Pillow's +`UnidentifiedImageError`, an `OSError`. + +The Writer convenience API also offers +`PdfWriter.from_images(images, page_size=...)` and +`writer.add_image(image, index=...)`, with zero-based insertion positions. +Creating an image page does not place an image onto an existing page: +replacement, recompression and drawing new images on existing pages are not +currently exposed. + diff --git a/pyproject.toml b/pyproject.toml index ab725508f..5dcbfa708 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,6 +66,8 @@ build = [ dev = [ "pytest>=9.0.3,<10.0.0", "pytest-xdist>=3.8.0,<4.0.0", + "pypdf==6.21.1", + "pypdfium2==5.14.0", "ruff>=0.11,<1.0", "python-semantic-release>=7.32.2,<8.0.0", "pre-commit>=3.7.1,<4.0.0", diff --git a/src/edit.h b/src/edit.h index 7b87b4345..4c2370119 100644 --- a/src/edit.h +++ b/src/edit.h @@ -1,3 +1,17 @@ //-*-C++-*- #include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include diff --git a/src/edit/annotation_ops.h b/src/edit/annotation_ops.h new file mode 100644 index 000000000..4be64b346 --- /dev/null +++ b/src/edit/annotation_ops.h @@ -0,0 +1,250 @@ +//-*-C++-*- + +#ifndef PDF_ANNOTATION_OPS_H +#define PDF_ANNOTATION_OPS_H + +#include +#include +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include + +#include +#include +#include + +namespace pdflib +{ + // The annotations of a page (ISO 32000-1, 12.5): reading them, adding one + // given as a dictionary, and removing them by subtype. + class pdf_annotation_ops + { + public: + + // One JSON object per annotation: its dictionary, without the entries + // that lead back into the document (/P, /Parent, /Popup) or hold drawing + // code (/AP). A link's target page is added as "page" when the link + // points into the document. + static nlohmann::json read(QPDF& qpdf, QPDFPageObjectHelper page); + + // Add the annotation written as a dictionary in PDF syntax. /Subtype and + // /Rect are required; /Type is filled in. + static void add(QPDF& qpdf, QPDFPageObjectHelper page, const std::string& dictionary); + + // Add a link over `rectangle` that opens page `target` of this document. + static void add_page_link(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::array& rectangle, + int target); + + // Remove the annotations whose /Subtype is in `subtypes` (with their + // slash); an empty set removes all except form widgets, which have to be + // named to be removed, and then take their form fields with them. + // Returns the number removed. + static int remove(QPDF& qpdf, QPDFPageObjectHelper page, const std::set& subtypes); + + private: + + static void append(QPDFPageObjectHelper page, QPDFObjectHandle annotation); + }; + + inline nlohmann::json pdf_annotation_ops::read(QPDF& qpdf, QPDFPageObjectHelper page) + { + nlohmann::json result = nlohmann::json::array(); + + QPDFObjectHandle annotations = page.getObjectHandle().getKey("/Annots"); + if(not annotations.isArray()) + { + return result; + } + + std::map indices = pdf_object_json::page_indices(qpdf); + const std::set skipped = {"/P", "/Parent", "/Popup", "/AP", "/IRT"}; + + for(QPDFObjectHandle& annotation : annotations.getArrayAsVector()) + { + if(not annotation.isDictionary()) + { + continue; + } + + // /Dest and an action's /D start with a page object: show the page + // index instead of walking into the page. + std::set skipped_here = skipped; + skipped_here.insert("/Dest"); + + nlohmann::json entry = pdf_object_json::to_json(annotation, 4, skipped_here); + + QPDFObjectHandle destination = annotation.getKey("/Dest"); + QPDFObjectHandle action = annotation.getKey("/A"); + if(not destination.isArray() and + action.isDictionary() and + action.getKey("/S").isNameAndEquals("/GoTo")) + { + destination = action.getKey("/D"); + if(entry.contains("/A") and entry["/A"].is_object()) + { + entry["/A"].erase("/D"); + } + } + + int target = pdf_object_json::destination_page(destination, indices); + if(target >= 0) + { + entry["page"] = target; + } + + result.push_back(entry); + } + + return result; + } + + inline void pdf_annotation_ops::append(QPDFPageObjectHelper page, QPDFObjectHandle annotation) + { + QPDFObjectHandle page_object = page.getObjectHandle(); + + QPDFObjectHandle annotations = page_object.getKey("/Annots"); + if(not annotations.isArray()) + { + annotations = QPDFObjectHandle::newArray(); + page_object.replaceKey("/Annots", annotations); + } + + annotation.replaceKey("/P", page_object); + annotations.appendItem(annotation); + } + + inline void pdf_annotation_ops::add(QPDF& qpdf, QPDFPageObjectHelper page, const std::string& dictionary) + { + QPDFObjectHandle annotation = QPDFObjectHandle::parse(dictionary, "annotation"); + + if(not annotation.isDictionary()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an annotation must be a dictionary"); + } + if(not annotation.getKey("/Subtype").isName()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an annotation needs a /Subtype"); + } + if(not annotation.getKey("/Rect").isRectangle()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an annotation needs a /Rect of four numbers"); + } + + annotation.replaceKey("/Type", QPDFObjectHandle::newName("/Annot")); + + append(page, qpdf.makeIndirectObject(annotation)); + } + + inline void pdf_annotation_ops::add_page_link(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::array& rectangle, + int target) + { + if(not (rectangle[0] < rectangle[2] and rectangle[1] < rectangle[3])) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a link rectangle must have a positive width and height"); + } + + QPDFObjectHandle link = QPDFObjectHandle::newDictionary(); + link.replaceKey("/Type", QPDFObjectHandle::newName("/Annot")); + link.replaceKey("/Subtype", QPDFObjectHandle::newName("/Link")); + link.replaceKey("/Rect", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(rectangle[0], rectangle[1], + rectangle[2], rectangle[3]))); + // no visible border, as link annotations are usually written + link.replaceKey("/Border", QPDFObjectHandle::parse("[0 0 0]")); + link.replaceKey("/Dest", pdf_catalog_ops::fit_destination(qpdf, target)); + + append(page, qpdf.makeIndirectObject(link)); + } + + inline int pdf_annotation_ops::remove(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::set& subtypes) + { + QPDFObjectHandle page_object = page.getObjectHandle(); + + QPDFObjectHandle annotations = page_object.getKey("/Annots"); + if(not annotations.isArray()) + { + return 0; + } + + std::vector kept; + std::vector removed_widgets; + int removed = 0; + + for(QPDFObjectHandle& annotation : annotations.getArrayAsVector()) + { + std::string subtype; + if(annotation.isDictionary() and annotation.getKey("/Subtype").isName()) + { + subtype = annotation.getKey("/Subtype").getName(); + } + + bool selected = subtypes.empty() ? (subtype != "/Widget") : (subtypes.count(subtype) > 0); + if(not selected) + { + kept.push_back(annotation); + continue; + } + + if(subtype == "/Widget") + { + removed_widgets.push_back(annotation); + } + removed += 1; + } + + if(removed == 0) + { + return 0; + } + + // A widget is the visible part of a form field: without it the field + // would stay in the form with nothing to show it. + if(not removed_widgets.empty()) + { + QPDFAcroFormDocumentHelper acroform(qpdf); + + std::set fields; + for(QPDFObjectHandle& widget : removed_widgets) + { + QPDFFormFieldObjectHelper field = + acroform.getFieldForAnnotation(QPDFAnnotationObjectHelper(widget)); + if(not field.isNull()) + { + fields.insert(field.getObjectHandle().getObjGen()); + } + } + acroform.removeFormFields(fields); + } + + if(kept.empty()) + { + page_object.removeKey("/Annots"); + } + else + { + page_object.replaceKey("/Annots", QPDFObjectHandle::newArray(kept)); + } + + return removed; + } + +} + +#endif diff --git a/src/edit/attachment_ops.h b/src/edit/attachment_ops.h new file mode 100644 index 000000000..0ec365e79 --- /dev/null +++ b/src/edit/attachment_ops.h @@ -0,0 +1,292 @@ +//-*-C++-*- + +#ifndef PDF_ATTACHMENT_OPS_H +#define PDF_ATTACHMENT_OPS_H + +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include +#include +#include +#include + +#include + +namespace pdflib +{ + // Files embedded in the document (ISO 32000-1, 7.11.4) and document-level + // JavaScript (12.6.4.16). Scripts are data here: they are stored, listed + // and removed, never run. + class pdf_attachment_ops + { + public: + + // [{"name", "filename", "description", "size", "mime_type", + // "creation_date", "modification_date"}, ...], ordered by name + static nlohmann::json read(QPDF& qpdf); + + // The bytes of the attachment registered under `name`. + static std::string data(QPDF& qpdf, const std::string& name); + + // Add an attachment, or replace the one with the same name. + static void add(QPDF& qpdf, + const std::string& name, + const std::string& bytes, + const std::string& description, + const std::string& mime_type); + + // False when there is no attachment of that name. + static bool remove(QPDF& qpdf, const std::string& name); + + // {name: script} of the document-level scripts. + static nlohmann::json javascript(QPDF& qpdf); + + // Register a script that a viewer runs when it opens the document. + static void add_javascript(QPDF& qpdf, const std::string& name, const std::string& script); + + // Remove the document-level scripts, a scripted open action and the + // document's additional actions. Returns the number of entries removed. + static int remove_javascript(QPDF& qpdf); + + private: + + static std::string script_of(QPDFObjectHandle action); + }; + + inline nlohmann::json pdf_attachment_ops::read(QPDF& qpdf) + { + nlohmann::json result = nlohmann::json::array(); + + QPDFEmbeddedFileDocumentHelper helper(qpdf); + if(not helper.hasEmbeddedFiles()) + { + return result; + } + + for(auto& item : helper.getEmbeddedFiles()) + { + nlohmann::json entry = nlohmann::json::object(); + + entry["name"] = item.first; + entry["filename"] = item.second->getFilename(); + entry["description"] = item.second->getDescription(); + + entry["size"] = 0; + entry["mime_type"] = ""; + entry["creation_date"] = ""; + entry["modification_date"] = ""; + + QPDFObjectHandle stream = item.second->getEmbeddedFileStream(); + if(stream.isStream()) + { + QPDFEFStreamObjectHelper embedded(stream); + + entry["size"] = embedded.getSize(); + entry["mime_type"] = embedded.getSubtype(); + entry["creation_date"] = embedded.getCreationDate(); + entry["modification_date"] = embedded.getModDate(); + } + + result.push_back(entry); + } + + return result; + } + + inline std::string pdf_attachment_ops::data(QPDF& qpdf, const std::string& name) + { + QPDFEmbeddedFileDocumentHelper helper(qpdf); + + std::shared_ptr file = helper.getEmbeddedFile(name); + if(file == nullptr) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the document has no attachment named '" + name + "'"); + } + + QPDFObjectHandle stream = file->getEmbeddedFileStream(); + if(not stream.isStream()) + { + throw pdf_edit_error(load_error::DAMAGED, + "attachment '" + name + "' has no embedded file stream"); + } + + std::shared_ptr buffer = stream.getStreamData(qpdf_dl_all); + if(buffer == nullptr) + { + return std::string(); + } + + return std::string(reinterpret_cast(buffer->getBuffer()), buffer->getSize()); + } + + inline void pdf_attachment_ops::add(QPDF& qpdf, + const std::string& name, + const std::string& bytes, + const std::string& description, + const std::string& mime_type) + { + if(name.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an attachment needs a name"); + } + + QPDFEFStreamObjectHelper embedded = QPDFEFStreamObjectHelper::createEFStream(qpdf, bytes); + + std::string now = QUtil::qpdf_time_to_pdf_time(QUtil::get_current_qpdf_time()); + embedded.setCreationDate(now); + embedded.setModDate(now); + if(not mime_type.empty()) + { + embedded.setSubtype(mime_type); + } + + QPDFFileSpecObjectHelper file = QPDFFileSpecObjectHelper::createFileSpec(qpdf, name, embedded); + if(not description.empty()) + { + file.setDescription(description); + } + + QPDFEmbeddedFileDocumentHelper helper(qpdf); + helper.replaceEmbeddedFile(name, file); + } + + inline bool pdf_attachment_ops::remove(QPDF& qpdf, const std::string& name) + { + QPDFEmbeddedFileDocumentHelper helper(qpdf); + return helper.removeEmbeddedFile(name); + } + + inline std::string pdf_attachment_ops::script_of(QPDFObjectHandle action) + { + if(not action.isDictionary()) + { + return ""; + } + + // /JS is a text string or a stream holding one. + QPDFObjectHandle script = action.getKey("/JS"); + if(script.isString()) + { + return script.getUTF8Value(); + } + if(script.isStream()) + { + std::shared_ptr buffer = script.getStreamData(qpdf_dl_all); + if(buffer != nullptr) + { + return std::string(reinterpret_cast(buffer->getBuffer()), buffer->getSize()); + } + } + + return ""; + } + + inline nlohmann::json pdf_attachment_ops::javascript(QPDF& qpdf) + { + nlohmann::json result = nlohmann::json::object(); + + QPDFObjectHandle names = qpdf.getRoot().getKey("/Names"); + if(not (names.isDictionary() and names.getKey("/JavaScript").isDictionary())) + { + return result; + } + + QPDFNameTreeObjectHelper tree(names.getKey("/JavaScript"), qpdf); + for(auto itr = tree.begin(); itr != tree.end(); ++itr) + { + result[itr->first] = script_of(itr->second); + } + + return result; + } + + inline void pdf_attachment_ops::add_javascript(QPDF& qpdf, + const std::string& name, + const std::string& script) + { + if(name.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a script needs a name"); + } + + QPDFObjectHandle action = QPDFObjectHandle::newDictionary(); + action.replaceKey("/Type", QPDFObjectHandle::newName("/Action")); + action.replaceKey("/S", QPDFObjectHandle::newName("/JavaScript")); + action.replaceKey("/JS", QPDFObjectHandle::newUnicodeString(script)); + action = qpdf.makeIndirectObject(action); + + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle names = root.getKey("/Names"); + if(not names.isDictionary()) + { + names = QPDFObjectHandle::newDictionary(); + root.replaceKey("/Names", names); + } + + QPDFObjectHandle existing = names.getKey("/JavaScript"); + if(existing.isDictionary()) + { + QPDFNameTreeObjectHelper tree(existing, qpdf); + tree.insert(name, action); + } + else + { + QPDFNameTreeObjectHelper tree = QPDFNameTreeObjectHelper::newEmpty(qpdf); + tree.insert(name, action); + names.replaceKey("/JavaScript", tree.getObjectHandle()); + } + } + + inline int pdf_attachment_ops::remove_javascript(QPDF& qpdf) + { + int removed = 0; + + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle names = root.getKey("/Names"); + if(names.isDictionary() and names.hasKey("/JavaScript")) + { + QPDFObjectHandle scripts = names.getKey("/JavaScript"); + if(scripts.isDictionary()) + { + QPDFNameTreeObjectHelper tree(scripts, qpdf); + for(auto itr = tree.begin(); itr != tree.end(); ++itr) + { + removed += 1; + } + } + names.removeKey("/JavaScript"); + } + + QPDFObjectHandle open_action = root.getKey("/OpenAction"); + if(open_action.isDictionary() and open_action.getKey("/S").isNameAndEquals("/JavaScript")) + { + root.removeKey("/OpenAction"); + removed += 1; + } + + // Document-level additional actions (will close, will save, ...) exist + // to run scripts. + if(root.hasKey("/AA")) + { + root.removeKey("/AA"); + removed += 1; + } + + return removed; + } + +} + +#endif diff --git a/src/edit/catalog_ops.h b/src/edit/catalog_ops.h new file mode 100644 index 000000000..ea2ce543d --- /dev/null +++ b/src/edit/catalog_ops.h @@ -0,0 +1,564 @@ +//-*-C++-*- + +#ifndef PDF_CATALOG_OPS_H +#define PDF_CATALOG_OPS_H + +#include +#include +#include +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include + +#include +#include + +namespace pdflib +{ + // Document-level entries of the trailer and the catalog: /Info, XMP, page + // layout and mode, viewer preferences, the open action, page labels and + // named destinations. Stateless; the caller owns the QPDF and serializes + // access to it. + class pdf_catalog_ops + { + public: + + // ---- /Info and XMP (ISO 32000-1, 14.3) ---- + + // Set, or with no value remove, entries of the /Info dictionary. Keys are + // accepted with or without their leading slash. + static void set_info(QPDF& qpdf, + const std::map >& entries); + + // Replace the catalog's /Metadata stream by this XMP packet, or remove it. + static void set_xmp(QPDF& qpdf, const std::optional& packet); + + // ---- viewer settings (ISO 32000-1, 7.7.2 and 12.2) ---- + + // {"page_layout", "page_mode", "viewer_preferences", "open_destination"} + static nlohmann::json read_settings(QPDF& qpdf); + + // Empty name removes the entry. + static void set_page_layout(QPDF& qpdf, const std::string& name); + static void set_page_mode(QPDF& qpdf, const std::string& name); + + // `dictionary` is the new /ViewerPreferences in PDF syntax; empty removes it. + static void set_viewer_preferences(QPDF& qpdf, const std::string& dictionary); + + // Open the document at this page, fitted to the window; -1 removes the + // open action. + static void set_open_destination(QPDF& qpdf, int page); + + // ---- page labels (ISO 32000-1, 12.4.2) ---- + + // The label of every page, as a viewer shows it; "1", "2", ... for a + // document without /PageLabels. + static std::vector page_labels(QPDF& qpdf); + + // Label pages from..to (inclusive). `style` is "/D", "/R", "/r", "/A", + // "/a" or empty for a prefix-only label; `start` is the number of the + // first page of the range. Pages after `to` keep the labels they had. + static void set_page_label(QPDF& qpdf, + int from, + int to, + const std::string& style, + const std::string& prefix, + int start); + + // ---- named destinations (ISO 32000-1, 12.3.2.3) ---- + + // {name: {"page", "kind", "arguments"}} from the /Dests dictionary and + // the /Names /Dests name tree. + static nlohmann::json named_destinations(QPDF& qpdf); + + // Add or replace a name that opens `page` fitted to the window. + static void add_named_destination(QPDF& qpdf, const std::string& name, int page); + + // A destination array [page /Fit] for a page of `qpdf`. + static QPDFObjectHandle fit_destination(QPDF& qpdf, int page); + + private: + + static std::string strip_slash(const std::string& key); + + static void set_root_name(QPDF& qpdf, + const std::string& key, + const std::string& name, + const std::set& allowed); + + static std::string format_label(QPDFObjectHandle label); + static std::string to_roman(long long number); + static std::string to_letters(long long number); + }; + + inline std::string pdf_catalog_ops::strip_slash(const std::string& key) + { + return (key.size() > 0 and key.front() == '/') ? key.substr(1) : key; + } + + inline void pdf_catalog_ops::set_info(QPDF& qpdf, + const std::map >& entries) + { + QPDFObjectHandle trailer = qpdf.getTrailer(); + + QPDFObjectHandle info = trailer.getKey("/Info"); + if(not info.isDictionary()) + { + info = qpdf.makeIndirectObject(QPDFObjectHandle::newDictionary()); + trailer.replaceKey("/Info", info); + } + + for(const auto& entry : entries) + { + std::string name = strip_slash(entry.first); + if(name.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a metadata key must not be empty"); + } + + std::string key = "/" + name; + if(entry.second.has_value()) + { + info.replaceKey(key, QPDFObjectHandle::newUnicodeString(entry.second.value())); + } + else + { + info.removeKey(key); + } + } + } + + inline void pdf_catalog_ops::set_xmp(QPDF& qpdf, const std::optional& packet) + { + QPDFObjectHandle root = qpdf.getRoot(); + + if(not packet.has_value()) + { + root.removeKey("/Metadata"); + return; + } + + QPDFObjectHandle stream = qpdf.newStream(packet.value()); + + QPDFObjectHandle dictionary = stream.getDict(); + dictionary.replaceKey("/Type", QPDFObjectHandle::newName("/Metadata")); + dictionary.replaceKey("/Subtype", QPDFObjectHandle::newName("/XML")); + + root.replaceKey("/Metadata", stream); + } + + inline nlohmann::json pdf_catalog_ops::read_settings(QPDF& qpdf) + { + QPDFObjectHandle root = qpdf.getRoot(); + + nlohmann::json result = nlohmann::json::object(); + + QPDFObjectHandle layout = root.getKey("/PageLayout"); + result["page_layout"] = layout.isName() ? nlohmann::json(layout.getName()) : nlohmann::json(nullptr); + + QPDFObjectHandle mode = root.getKey("/PageMode"); + result["page_mode"] = mode.isName() ? nlohmann::json(mode.getName()) : nlohmann::json(nullptr); + + QPDFObjectHandle preferences = root.getKey("/ViewerPreferences"); + result["viewer_preferences"] = preferences.isDictionary() ? + pdf_object_json::to_json(preferences, 3) : nlohmann::json(nullptr); + + // An open action is a destination or an action; only the first is a + // place in the document. + result["open_destination"] = pdf_object_json::destination_to_json(root.getKey("/OpenAction"), + pdf_object_json::page_indices(qpdf)); + + return result; + } + + inline void pdf_catalog_ops::set_root_name(QPDF& qpdf, + const std::string& key, + const std::string& name, + const std::set& allowed) + { + QPDFObjectHandle root = qpdf.getRoot(); + + if(name.empty()) + { + root.removeKey(key); + return; + } + + std::string value = "/" + strip_slash(name); + if(allowed.count(value) == 0) + { + std::string choices; + for(const std::string& choice : allowed) + { + choices += (choices.empty() ? "" : ", ") + choice; + } + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + name + "' is not a valid " + key + ": expected one of " + choices); + } + + root.replaceKey(key, QPDFObjectHandle::newName(value)); + } + + inline void pdf_catalog_ops::set_page_layout(QPDF& qpdf, const std::string& name) + { + set_root_name(qpdf, "/PageLayout", name, + {"/SinglePage", "/OneColumn", "/TwoColumnLeft", "/TwoColumnRight", + "/TwoPageLeft", "/TwoPageRight"}); + } + + inline void pdf_catalog_ops::set_page_mode(QPDF& qpdf, const std::string& name) + { + set_root_name(qpdf, "/PageMode", name, + {"/UseNone", "/UseOutlines", "/UseThumbs", "/FullScreen", + "/UseOC", "/UseAttachments"}); + } + + inline void pdf_catalog_ops::set_viewer_preferences(QPDF& qpdf, const std::string& dictionary) + { + QPDFObjectHandle root = qpdf.getRoot(); + + if(dictionary.empty()) + { + root.removeKey("/ViewerPreferences"); + return; + } + + QPDFObjectHandle preferences = QPDFObjectHandle::parse(dictionary, "viewer preferences"); + if(not preferences.isDictionary()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "viewer preferences must be a dictionary"); + } + + root.replaceKey("/ViewerPreferences", preferences); + } + + inline QPDFObjectHandle pdf_catalog_ops::fit_destination(QPDF& qpdf, int page) + { + std::vector pages = qpdf.getAllPages(); + if(page < 0 or page >= static_cast(pages.size())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page index " + std::to_string(page) + " is out of range for a document of " + + std::to_string(pages.size()) + " pages"); + } + + QPDFObjectHandle destination = QPDFObjectHandle::newArray(); + destination.appendItem(pages.at(page)); + destination.appendItem(QPDFObjectHandle::newName("/Fit")); + + return destination; + } + + inline void pdf_catalog_ops::set_open_destination(QPDF& qpdf, int page) + { + QPDFObjectHandle root = qpdf.getRoot(); + + if(page < 0) + { + root.removeKey("/OpenAction"); + return; + } + + root.replaceKey("/OpenAction", fit_destination(qpdf, page)); + } + + inline std::string pdf_catalog_ops::to_roman(long long number) + { + static const std::vector > numerals = { + {1000, "m"}, {900, "cm"}, {500, "d"}, {400, "cd"}, {100, "c"}, {90, "xc"}, + {50, "l"}, {40, "xl"}, {10, "x"}, {9, "ix"}, {5, "v"}, {4, "iv"}, {1, "i"}}; + + std::string result; + for(const auto& numeral : numerals) + { + while(number >= numeral.first) + { + result += numeral.second; + number -= numeral.first; + } + } + + return result; + } + + inline std::string pdf_catalog_ops::to_letters(long long number) + { + // a..z, then aa..zz, then aaa..zzz (ISO 32000-1, table 159). + if(number < 1) + { + return ""; + } + + char letter = static_cast('a' + ((number - 1) % 26)); + std::size_t repeats = static_cast((number - 1) / 26 + 1); + + return std::string(repeats, letter); + } + + inline std::string pdf_catalog_ops::format_label(QPDFObjectHandle label) + { + std::string prefix; + QPDFObjectHandle prefix_object = label.getKey("/P"); + if(prefix_object.isString()) + { + prefix = prefix_object.getUTF8Value(); + } + + QPDFObjectHandle style = label.getKey("/S"); + if(not style.isName()) + { + // no numeric portion: the label is the prefix alone + return prefix; + } + + long long number = 1; + QPDFObjectHandle start = label.getKey("/St"); + if(start.isInteger()) + { + number = start.getIntValue(); + } + + std::string name = style.getName(); + std::string numeric; + + if(name == "/D") + { + numeric = std::to_string(number); + } + else if(name == "/r" or name == "/R") + { + numeric = to_roman(number); + } + else if(name == "/a" or name == "/A") + { + numeric = to_letters(number); + } + + if(name == "/R" or name == "/A") + { + for(char& character : numeric) + { + character = static_cast(std::toupper(static_cast(character))); + } + } + + return prefix + numeric; + } + + inline std::vector pdf_catalog_ops::page_labels(QPDF& qpdf) + { + std::size_t number_of_pages = qpdf.getAllPages().size(); + + std::vector labels; + labels.reserve(number_of_pages); + + QPDFPageLabelDocumentHelper helper(qpdf); + bool has_labels = helper.hasPageLabels(); + + for(std::size_t index = 0; index < number_of_pages; index++) + { + // qpdf returns the label dictionary that applies to this page, with + // /St already advanced to this page's number. + QPDFObjectHandle label = has_labels ? + helper.getLabelForPage(static_cast(index)) : QPDFObjectHandle::newNull(); + + if(label.isDictionary()) + { + labels.push_back(format_label(label)); + } + else + { + labels.push_back(std::to_string(index + 1)); + } + } + + return labels; + } + + inline void pdf_catalog_ops::set_page_label(QPDF& qpdf, + int from, + int to, + const std::string& style, + const std::string& prefix, + int start) + { + int number_of_pages = static_cast(qpdf.getAllPages().size()); + + if(from < 0 or to < from or to >= number_of_pages) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page label range " + std::to_string(from) + ".." + std::to_string(to) + + " is not within a document of " + std::to_string(number_of_pages) + " pages"); + } + if(start < 1) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a page label numbering starts at 1 or higher"); + } + + qpdf_page_label_e label_type = pl_none; + if(style == "/D") { label_type = pl_digits; } + else if(style == "/R") { label_type = pl_roman_upper; } + else if(style == "/r") { label_type = pl_roman_lower; } + else if(style == "/A") { label_type = pl_alpha_upper; } + else if(style == "/a") { label_type = pl_alpha_lower; } + else if(not style.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + style + "' is not a page label style: expected /D, /R, /r, /A or /a"); + } + + // The ranges as they are now, by first page. A document without labels + // behaves as one decimal range from the first page. + std::map ranges; + + QPDFObjectHandle root = qpdf.getRoot(); + QPDFObjectHandle existing = root.getKey("/PageLabels"); + + QPDFPageLabelDocumentHelper helper(qpdf); + bool has_labels = helper.hasPageLabels(); + + if(has_labels and existing.isDictionary()) + { + QPDFNumberTreeObjectHelper tree(existing, qpdf); + for(auto itr = tree.begin(); itr != tree.end(); ++itr) + { + ranges[itr->first] = itr->second; + } + } + else + { + ranges[0] = QPDFPageLabelDocumentHelper::pageLabelDict(pl_digits, 1, ""); + } + + // What the page after the range is labelled today: it has to say so + // itself once the range in front of it changes. + QPDFObjectHandle following = QPDFObjectHandle::newNull(); + if(to + 1 < number_of_pages) + { + following = has_labels ? + helper.getLabelForPage(static_cast(to) + 1) : + QPDFPageLabelDocumentHelper::pageLabelDict(pl_digits, to + 2, ""); + } + + for(auto itr = ranges.begin(); itr != ranges.end(); ) + { + if(itr->first >= from and itr->first <= static_cast(to) + 1) + { + itr = ranges.erase(itr); + } + else + { + ++itr; + } + } + + ranges[from] = QPDFPageLabelDocumentHelper::pageLabelDict(label_type, start, prefix); + if(following.isDictionary()) + { + ranges[static_cast(to) + 1] = following; + } + + // The number tree shall have an entry for page 0 (ISO 32000-1, 12.4.2). + if(ranges.count(0) == 0) + { + ranges[0] = QPDFPageLabelDocumentHelper::pageLabelDict(pl_digits, 1, ""); + } + + QPDFObjectHandle numbers = QPDFObjectHandle::newArray(); + for(const auto& range : ranges) + { + numbers.appendItem(QPDFObjectHandle::newInteger(range.first)); + numbers.appendItem(range.second); + } + + QPDFObjectHandle labels = QPDFObjectHandle::newDictionary(); + labels.replaceKey("/Nums", numbers); + + root.replaceKey("/PageLabels", labels); + } + + inline nlohmann::json pdf_catalog_ops::named_destinations(QPDF& qpdf) + { + nlohmann::json result = nlohmann::json::object(); + + std::map indices = pdf_object_json::page_indices(qpdf); + QPDFObjectHandle root = qpdf.getRoot(); + + // PDF 1.1: a dictionary of names in the catalog. + QPDFObjectHandle dictionary = root.getKey("/Dests"); + if(dictionary.isDictionary()) + { + for(const std::string& key : dictionary.getKeys()) + { + nlohmann::json destination = + pdf_object_json::destination_to_json(dictionary.getKey(key), indices); + if(not destination.is_null()) + { + result[strip_slash(key)] = destination; + } + } + } + + // PDF 1.2 and later: a name tree under /Names. + QPDFObjectHandle names = root.getKey("/Names"); + if(names.isDictionary() and names.getKey("/Dests").isDictionary()) + { + QPDFNameTreeObjectHelper tree(names.getKey("/Dests"), qpdf); + for(auto itr = tree.begin(); itr != tree.end(); ++itr) + { + nlohmann::json destination = + pdf_object_json::destination_to_json(itr->second, indices); + if(not destination.is_null()) + { + result[itr->first] = destination; + } + } + } + + return result; + } + + inline void pdf_catalog_ops::add_named_destination(QPDF& qpdf, const std::string& name, int page) + { + if(name.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a named destination needs a name"); + } + + QPDFObjectHandle destination = fit_destination(qpdf, page); + + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle names = root.getKey("/Names"); + if(not names.isDictionary()) + { + names = QPDFObjectHandle::newDictionary(); + root.replaceKey("/Names", names); + } + + QPDFObjectHandle existing = names.getKey("/Dests"); + if(existing.isDictionary()) + { + QPDFNameTreeObjectHelper tree(existing, qpdf); + tree.insert(name, destination); + } + else + { + QPDFNameTreeObjectHelper tree = QPDFNameTreeObjectHelper::newEmpty(qpdf); + tree.insert(name, destination); + names.replaceKey("/Dests", tree.getObjectHandle()); + } + } + +} + +#endif diff --git a/src/edit/document_info.h b/src/edit/document_info.h new file mode 100644 index 000000000..108b101ff --- /dev/null +++ b/src/edit/document_info.h @@ -0,0 +1,322 @@ +//-*-C++-*- + +#ifndef PDF_DOCUMENT_INFO_H +#define PDF_DOCUMENT_INFO_H + +#include +#include +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include + +namespace pdflib +{ + // The /Encrypt parameters of a document (ISO 32000-1, 7.6). The permission + // flags are reported as stored; nothing in docling-parse enforces them. + class pdf_encryption_info + { + public: + + pdf_encryption_info(); + + static pdf_encryption_info read(QPDF& qpdf); + + bool is_encrypted() const; + + int get_revision() const; // /R + int get_version() const; // /V + int get_permissions() const; // /P, the raw signed flag word + + // "none", "rc4", "aes", "aesv3" or "unknown" + const std::string& get_stream_method() const; + const std::string& get_string_method() const; + const std::string& get_file_method() const; + + private: + + static std::string method_name(QPDF::encryption_method_e method); + + private: + + bool encrypted; + + int revision; + int version; + int permissions; + + std::string stream_method; + std::string string_method; + std::string file_method; + }; + + // What the holder of the user password may do with an encrypted document + // (ISO 32000-1, table 22). Everything is allowed unless turned off. A + // conforming viewer honors these; they are not access control. + class pdf_permissions + { + public: + + pdf_permissions(); + + // 0: full-quality printing, 1: low resolution only, 2: no printing + int get_print() const; + void set_print(int level); + + bool get_modify() const; // change the document's content + void set_modify(bool allowed); + + bool get_extract() const; // copy text and graphics out + void set_extract(bool allowed); + + bool get_annotate() const; // add or change annotations and form fields + void set_annotate(bool allowed); + + bool get_fill_forms() const; // fill in existing form fields + void set_fill_forms(bool allowed); + + bool get_accessibility() const; // extract for assistive technology + void set_accessibility(bool allowed); + + bool get_assemble() const; // insert, rotate and delete pages + void set_assemble(bool allowed); + + private: + + int print; + + bool modify; + bool extract; + bool annotate; + bool fill_forms; + bool accessibility; + bool assemble; + }; + + // Document-scoped facts that belong to no page: header version, the trailer + // /Info dictionary (ISO 32000-1, 14.3.3), the XMP packet (14.3.2) and the + // encryption parameters. Typed, self-contained and detached from the QPDF it + // was read from. + class pdf_document_info + { + public: + + pdf_document_info(); + + // Caller serializes access to `qpdf`. + static pdf_document_info read(QPDF& qpdf); + + const std::string& get_pdf_version() const; + int get_extension_level() const; + + int get_number_of_pages() const; + + // /Info entries with a string value, keys without the leading slash + // ("Title", "Author", ...), values in UTF-8. + const std::map& get_info() const; + + // The raw XMP packet of the catalog's /Metadata stream, if there is one. + const std::optional& get_xmp() const; + + const pdf_encryption_info& get_encryption() const; + + // For a document being edited, the encryption that matters is the one + // its output will have, which the editor knows and the in-memory QPDF + // does not. + void set_encryption(const pdf_encryption_info& encryption_); + + private: + + std::string pdf_version; + int extension_level; + + int number_of_pages; + + std::map info; + std::optional xmp; + + pdf_encryption_info encryption; + }; + + inline pdf_permissions::pdf_permissions(): + print(0), + modify(true), + extract(true), + annotate(true), + fill_forms(true), + accessibility(true), + assemble(true) + {} + + inline int pdf_permissions::get_print() const { return print; } + + inline void pdf_permissions::set_print(int level) { print = level; } + + inline bool pdf_permissions::get_modify() const { return modify; } + + inline void pdf_permissions::set_modify(bool allowed) { modify = allowed; } + + inline bool pdf_permissions::get_extract() const { return extract; } + + inline void pdf_permissions::set_extract(bool allowed) { extract = allowed; } + + inline bool pdf_permissions::get_annotate() const { return annotate; } + + inline void pdf_permissions::set_annotate(bool allowed) { annotate = allowed; } + + inline bool pdf_permissions::get_fill_forms() const { return fill_forms; } + + inline void pdf_permissions::set_fill_forms(bool allowed) { fill_forms = allowed; } + + inline bool pdf_permissions::get_accessibility() const { return accessibility; } + + inline void pdf_permissions::set_accessibility(bool allowed) { accessibility = allowed; } + + inline bool pdf_permissions::get_assemble() const { return assemble; } + + inline void pdf_permissions::set_assemble(bool allowed) { assemble = allowed; } + + inline pdf_encryption_info::pdf_encryption_info(): + encrypted(false), + revision(0), + version(0), + permissions(0), + stream_method("none"), + string_method("none"), + file_method("none") + {} + + inline std::string pdf_encryption_info::method_name(QPDF::encryption_method_e method) + { + switch(method) + { + case QPDF::e_none: return "none"; + case QPDF::e_rc4: return "rc4"; + case QPDF::e_aes: return "aes"; + case QPDF::e_aesv3: return "aesv3"; + default: return "unknown"; + } + } + + inline pdf_encryption_info pdf_encryption_info::read(QPDF& qpdf) + { + pdf_encryption_info result; + + int R = 0; + int P = 0; + int V = 0; + + QPDF::encryption_method_e stream_method = QPDF::e_none; + QPDF::encryption_method_e string_method = QPDF::e_none; + QPDF::encryption_method_e file_method = QPDF::e_none; + + result.encrypted = qpdf.isEncrypted(R, P, V, stream_method, string_method, file_method); + + if(result.encrypted) + { + result.revision = R; + result.version = V; + result.permissions = P; + + result.stream_method = method_name(stream_method); + result.string_method = method_name(string_method); + result.file_method = method_name(file_method); + } + + return result; + } + + inline bool pdf_encryption_info::is_encrypted() const { return encrypted; } + + inline int pdf_encryption_info::get_revision() const { return revision; } + + inline int pdf_encryption_info::get_version() const { return version; } + + inline int pdf_encryption_info::get_permissions() const { return permissions; } + + inline const std::string& pdf_encryption_info::get_stream_method() const { return stream_method; } + + inline const std::string& pdf_encryption_info::get_string_method() const { return string_method; } + + inline const std::string& pdf_encryption_info::get_file_method() const { return file_method; } + + inline pdf_document_info::pdf_document_info(): + pdf_version(""), + extension_level(0), + number_of_pages(0), + info({}), + xmp(std::nullopt), + encryption() + {} + + inline pdf_document_info pdf_document_info::read(QPDF& qpdf) + { + pdf_document_info result; + + result.pdf_version = qpdf.getPDFVersion(); + result.extension_level = qpdf.getExtensionLevel(); + + result.number_of_pages = static_cast(qpdf.getAllPages().size()); + + result.encryption = pdf_encryption_info::read(qpdf); + + // /Info is optional and, in damaged files, not always a dictionary. + QPDFObjectHandle trailer = qpdf.getTrailer(); + if(trailer.isDictionary() and trailer.hasKey("/Info")) + { + QPDFObjectHandle info_dict = trailer.getKey("/Info"); + if(info_dict.isDictionary()) + { + for(const std::string& key : info_dict.getKeys()) + { + QPDFObjectHandle value = info_dict.getKey(key); + if(value.isString()) + { + // keys are PDF names: drop the leading slash + std::string name = (key.size()>0 and key.front()=='/') ? key.substr(1) : key; + result.info[name] = value.getUTF8Value(); + } + } + } + } + + QPDFObjectHandle root = qpdf.getRoot(); + if(root.isDictionary() and root.hasKey("/Metadata")) + { + QPDFObjectHandle metadata = root.getKey("/Metadata"); + if(metadata.isStream()) + { + std::shared_ptr data = metadata.getStreamData(); + if(data != nullptr) + { + result.xmp = std::string(reinterpret_cast(data->getBuffer()), + data->getSize()); + } + } + } + + return result; + } + + inline const std::string& pdf_document_info::get_pdf_version() const { return pdf_version; } + + inline int pdf_document_info::get_extension_level() const { return extension_level; } + + inline int pdf_document_info::get_number_of_pages() const { return number_of_pages; } + + inline const std::map& pdf_document_info::get_info() const { return info; } + + inline const std::optional& pdf_document_info::get_xmp() const { return xmp; } + + inline const pdf_encryption_info& pdf_document_info::get_encryption() const { return encryption; } + + inline void pdf_document_info::set_encryption(const pdf_encryption_info& encryption_) + { + encryption = encryption_; + } + +} + +#endif diff --git a/src/edit/edit_error.h b/src/edit/edit_error.h new file mode 100644 index 000000000..c31f1a770 --- /dev/null +++ b/src/edit/edit_error.h @@ -0,0 +1,52 @@ +//-*-C++-*- + +#ifndef PDF_EDIT_ERROR_H +#define PDF_EDIT_ERROR_H + +#include +#include + +#include + +namespace pdflib +{ + // Why an edit, an inspection or a write failed. These extend the load + // categories of parse/qpdf/load_error.h (password, damaged, unsupported, io, + // unknown); the strings cross into Python as docling_parse.pdf_errors, so + // they change together. + namespace edit_error + { + constexpr const char* INVALID_EDIT = "invalid_edit"; // bad argument or wrong state + constexpr const char* STALE_HANDLE = "stale_handle"; // page handle from before a page-list change + constexpr const char* WRITE = "write"; // the output could not be produced + } + + // The only exception type that leaves docling_editor: a category plus the + // message of the underlying failure. No QPDF exception reaches the binding. + class pdf_edit_error: public std::runtime_error + { + public: + + pdf_edit_error(const std::string& category_, const std::string& message_); + + const std::string& get_category() const; + + private: + + std::string category; + }; + + inline pdf_edit_error::pdf_edit_error(const std::string& category_, + const std::string& message_): + std::runtime_error(message_), + category(category_) + {} + + inline const std::string& pdf_edit_error::get_category() const + { + return category; + } + +} + +#endif diff --git a/src/edit/exported_image.h b/src/edit/exported_image.h new file mode 100644 index 000000000..c93a5d040 --- /dev/null +++ b/src/edit/exported_image.h @@ -0,0 +1,104 @@ +//-*-C++-*- + +#ifndef PDF_EXPORTED_IMAGE_H +#define PDF_EXPORTED_IMAGE_H + +#include +#include +#include + +namespace pdflib +{ + // One image of a page, detached from the page decoder that produced it: + // where it sits on the page, what its samples are, and the bytes to save. + class pdf_exported_image + { + public: + + typedef std::array box_type; + + pdf_exported_image(); + pdf_exported_image(const std::string& name_, + const box_type& bbox_, + int width_, + int height_, + const std::string& format_, + const std::string& mode_, + std::vector&& data_); + + // The /XObject resource name the page draws the image under. + const std::string& get_name() const; + + // [x0, y0, x1, y1] of the image on the page, in the page's coordinates. + const box_type& get_bbox() const; + + // Size of the sample grid, in pixels. + int get_width() const; + int get_height() const; + + // "jpeg", "jp2", "jbig2" or "raw": what `data` is encoded as. + const std::string& get_format() const; + + // PIL-style mode of the samples: "1", "L", "RGB" or "CMYK". + const std::string& get_mode() const; + + // Empty when the image data could not be produced. + const std::vector& get_data() const; + + private: + + std::string name; + box_type bbox; + + int width; + int height; + + std::string format; + std::string mode; + + std::vector data; + }; + + inline pdf_exported_image::pdf_exported_image(): + name(""), + bbox({0.0, 0.0, 0.0, 0.0}), + width(0), + height(0), + format("raw"), + mode("RGB"), + data({}) + {} + + inline pdf_exported_image::pdf_exported_image(const std::string& name_, + const box_type& bbox_, + int width_, + int height_, + const std::string& format_, + const std::string& mode_, + std::vector&& data_): + name(name_), + bbox(bbox_), + width(width_), + height(height_), + format(format_), + mode(mode_), + data(std::move(data_)) + {} + + inline const std::string& pdf_exported_image::get_name() const { return name; } + + inline const pdf_exported_image::box_type& pdf_exported_image::get_bbox() const { return bbox; } + + inline int pdf_exported_image::get_width() const { return width; } + + inline int pdf_exported_image::get_height() const { return height; } + + inline const std::string& pdf_exported_image::get_format() const { return format; } + + inline const std::string& pdf_exported_image::get_mode() const { return mode; } + + inline const std::vector& pdf_exported_image::get_data() const { return data; } + +} + +#endif diff --git a/src/edit/form_ops.h b/src/edit/form_ops.h new file mode 100644 index 000000000..862283c32 --- /dev/null +++ b/src/edit/form_ops.h @@ -0,0 +1,1209 @@ +//-*-C++-*- + +#ifndef PDF_FORM_OPS_H +#define PDF_FORM_OPS_H + +#include +#include +#include +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include + +namespace pdflib +{ + // Interactive forms (AcroForm; ISO 32000-1, 12.7): reading the fields, + // setting their values, and flattening them into page content. + class pdf_form_ops + { + public: + + // {"has_form", "has_xfa", "need_appearances", "fields": [{"name", + // "partial_name", "alternate_name", "type", "kind", "value", + // "default_value", "flags", "read_only", "choices", "states", + // "pages"}, ...]} + // + // "kind" is text, checkbox, radio, pushbutton, choice, signature or + // other. "states" are the appearance states a checkbox or radio group + // can take besides /Off. "pages" are the pages showing a widget of the + // field. + static nlohmann::json read(QPDF& qpdf); + + // Set field values by fully qualified name; a partial name is accepted + // when it identifies exactly one field. Text and choice fields take the + // value as text. A checkbox or radio group takes one of its states + // ("/Yes", or "Yes"), or "/Off"; for a checkbox, "true"/"false" select + // its on state and "/Off". Appearance streams are regenerated. Returns + // the number of fields set; an unknown name is an error. + static int set_values(QPDF& qpdf, const std::map& values); + + static void set_need_appearances(QPDF& qpdf, bool value); + + // Draw every visible annotation, form widgets included, into its page's + // content and remove the annotations: the values stay visible, the + // interactive form is gone. + static void flatten(QPDF& qpdf); + + // Create a field on `page`. Entries of `spec`: + // + // "kind" text, checkbox, radio, choice or signature (required) + // "name" the field's name, unique in the form, without "." + // "rect" [left, bottom, right, top] of the widget; not for radio + // "value" text and choice: the initial text + // "checked" checkbox: true or false + // "options" choice: the entries to pick from; + // radio: [{"state": name, "rect": [...]}, ...], one + // button per entry + // "selected" radio: the state that starts selected, or null + // "multiline" text: true for a field of several lines + // "editable" choice: true lets the user type a value of their own + // "font_size" text and choice: in points, 12 by default + // "read_only", "required" booleans + // "tooltip" the description a viewer shows for the field, or null + // + // Text is drawn in Helvetica; a field's appearance is built here, so it + // shows in viewers that do not draw forms themselves. + static void add_field(QPDF& qpdf, QPDFPageObjectHelper page, const nlohmann::json& spec); + + // Change a field found by name as in set_values. Entries of `changes`, + // all optional: "name" (the new partial name), "rect" (fields with one + // widget), "read_only", "required", "tooltip" (text or null) and + // "options" (choice fields). + static void update_field(QPDF& qpdf, const std::string& name, const nlohmann::json& changes); + + // Remove a field and its widgets from the form and from their pages. + static void remove_field(QPDF& qpdf, const std::string& name); + + private: + + static std::string kind_of(QPDFFormFieldObjectHelper& field); + + // qpdf may expose unnamed widgets as terminal fields. Resolve them to + // their nearest named owner, preserving named fields in nested forms. + static QPDFFormFieldObjectHelper field_of(QPDFFormFieldObjectHelper field); + static std::vector fields_of(QPDFAcroFormDocumentHelper& acroform); + static std::vector widgets_of(QPDFAcroFormDocumentHelper& acroform, + QPDFFormFieldObjectHelper& field); + + // The names of a widget's normal appearances other than /Off. + static std::set states_of(QPDFAcroFormDocumentHelper& acroform, + QPDFFormFieldObjectHelper& field); + + static std::string with_slash(const std::string& name); + + // The one field `name` stands for: its fully qualified name, or a + // partial name that only one field has. + static QPDFFormFieldObjectHelper find_field(std::vector& fields, + const std::string& name); + + // The form's default font, /Helv: Helvetica in WinAnsiEncoding, present + // in the form's default resources. Creates the form if there is none. + static QPDFObjectHandle ensure_form_font(QPDF& qpdf, QPDFAcroFormDocumentHelper& acroform); + + static void check_new_name(QPDFAcroFormDocumentHelper& acroform, + const std::string& name, + const std::string& qualified_name); + + static std::array rect_of(const nlohmann::json& value); + static bool flag_of(const nlohmann::json& spec, const char* key, bool fallback); + + // A widget annotation on `page` over `rect`, not yet a field. + static QPDFObjectHandle make_widget(QPDFPageObjectHelper page, const std::array& rect); + + // A form XObject of width x height showing `content`. + static QPDFObjectHandle make_appearance(QPDF& qpdf, + double width, + double height, + const std::string& content, + QPDFObjectHandle font); + + // Content stream fragments, in a width x height box with its origin at + // the lower left corner. + static std::string box_path(double width, double height); + static std::string check_path(double width, double height); + static std::string circle_path(double center_x, double center_y, double radius); + + // The normal appearance of a text or choice field: a frame, plus the + // marked-content section qpdf fills with the field's value. + static void set_text_appearance(QPDF& qpdf, + QPDFObjectHandle widget, + const std::array& rect, + QPDFObjectHandle font); + + static void append_widget(QPDFPageObjectHelper page, QPDFObjectHandle widget); + + static constexpr long long FLAG_READ_ONLY = 1LL << 0; + static constexpr long long FLAG_REQUIRED = 1LL << 1; + static constexpr long long FLAG_MULTILINE = 1LL << 12; + static constexpr long long FLAG_NO_TOGGLE_TO_OFF = 1LL << 14; + static constexpr long long FLAG_RADIO = 1LL << 15; + static constexpr long long FLAG_COMBO = 1LL << 17; + static constexpr long long FLAG_EDIT = 1LL << 18; + }; + + inline std::string pdf_form_ops::with_slash(const std::string& name) + { + return (name.size() > 0 and name.front() == '/') ? name : "/" + name; + } + + inline std::string pdf_form_ops::kind_of(QPDFFormFieldObjectHelper& field) + { + if(field.isText()) { return "text"; } + if(field.isCheckbox()) { return "checkbox"; } + if(field.isRadioButton()) { return "radio"; } + if(field.isPushbutton()) { return "pushbutton"; } + if(field.isChoice()) { return "choice"; } + if(field.getFieldType() == "/Sig") { return "signature"; } + + return "other"; + } + + inline QPDFFormFieldObjectHelper pdf_form_ops::field_of(QPDFFormFieldObjectHelper field) + { + std::set seen; + for(int depth = 0; depth < 100; depth++) + { + QPDFObjectHandle object = field.getObjectHandle(); + if(object.hasKey("/T") or not seen.insert(object.getObjGen()).second) + { + break; + } + QPDFObjectHandle parent = object.getKey("/Parent"); + if(not parent.isDictionary()) + { + break; + } + field = QPDFFormFieldObjectHelper(parent); + } + return field; + } + + inline std::vector pdf_form_ops::fields_of(QPDFAcroFormDocumentHelper& acroform) + { + std::vector fields; + std::set seen; + for(QPDFFormFieldObjectHelper field : acroform.getFormFields()) + { + field = field_of(field); + if(seen.insert(field.getObjectHandle().getObjGen()).second) + { + fields.push_back(field); + } + } + return fields; + } + + inline std::vector pdf_form_ops::widgets_of(QPDFAcroFormDocumentHelper& acroform, + QPDFFormFieldObjectHelper& field) + { + std::vector widgets; + std::set seen; + QPDFObjGen owner = field.getObjectHandle().getObjGen(); + for(QPDFFormFieldObjectHelper candidate : acroform.getFormFields()) + { + if(field_of(candidate).getObjectHandle().getObjGen() != owner) + { + continue; + } + for(QPDFAnnotationObjectHelper& widget : acroform.getAnnotationsForField(candidate)) + { + if(seen.insert(widget.getObjectHandle().getObjGen()).second) + { + widgets.push_back(widget); + } + } + } + return widgets; + } + + inline std::set pdf_form_ops::states_of(QPDFAcroFormDocumentHelper& acroform, + QPDFFormFieldObjectHelper& field) + { + std::set states; + + for(QPDFAnnotationObjectHelper& widget : widgets_of(acroform, field)) + { + QPDFObjectHandle appearances = widget.getAppearanceDictionary(); + if(not appearances.isDictionary()) + { + continue; + } + + QPDFObjectHandle normal = appearances.getKey("/N"); + if(not normal.isDictionary()) + { + continue; + } + + for(const std::string& state : normal.getKeys()) + { + if(state != "/Off") + { + states.insert(state); + } + } + } + + return states; + } + + inline nlohmann::json pdf_form_ops::read(QPDF& qpdf) + { + nlohmann::json result = nlohmann::json::object(); + result["fields"] = nlohmann::json::array(); + + QPDFAcroFormDocumentHelper acroform(qpdf); + + result["has_form"] = acroform.hasAcroForm(); + result["has_xfa"] = false; + result["need_appearances"] = false; + + if(not acroform.hasAcroForm()) + { + return result; + } + + QPDFObjectHandle form = qpdf.getRoot().getKey("/AcroForm"); + result["has_xfa"] = (form.isDictionary() and form.hasKey("/XFA")); + result["need_appearances"] = acroform.getNeedAppearances(); + + // Index widgets themselves: qpdf's page lookup may return a top-level + // field while its field lookup returns a terminal child. + std::map > pages_of; + int page_index = 0; + for(QPDFPageObjectHelper& page : QPDFPageDocumentHelper(qpdf).getAllPages()) + { + for(QPDFAnnotationObjectHelper& widget : acroform.getWidgetAnnotationsForPage(page)) + { + pages_of[widget.getObjectHandle().getObjGen()].insert(page_index); + } + page_index += 1; + } + + for(QPDFFormFieldObjectHelper& field : fields_of(acroform)) + { + nlohmann::json entry = nlohmann::json::object(); + + entry["name"] = field.getFullyQualifiedName(); + entry["partial_name"] = field.getPartialName(); + entry["alternate_name"] = field.getAlternativeName(); + entry["type"] = field.getFieldType(); + entry["kind"] = kind_of(field); + + // A button's value is a name (/Yes, /Off); text and choice values + // are strings. + QPDFObjectHandle value = field.getValue(); + entry["value"] = value.isName() ? value.getName() : field.getValueAsString(); + + QPDFObjectHandle default_value = field.getDefaultValue(); + entry["default_value"] = default_value.isName() ? + default_value.getName() : field.getDefaultValueAsString(); + + int flags = field.getFlags(); + entry["flags"] = flags; + entry["read_only"] = ((flags & ff_all_read_only) != 0); + + entry["choices"] = field.isChoice() ? nlohmann::json(field.getChoices()) : nlohmann::json::array(); + + entry["states"] = nlohmann::json::array(); + if(field.isCheckbox() or field.isRadioButton()) + { + for(const std::string& state : states_of(acroform, field)) + { + entry["states"].push_back(state); + } + } + + // where each widget of the field sits, [left, bottom, right, top] + entry["rects"] = nlohmann::json::array(); + std::set field_pages; + for(QPDFAnnotationObjectHelper& widget : widgets_of(acroform, field)) + { + QPDFObjectHandle::Rectangle rect = widget.getRect(); + entry["rects"].push_back({rect.llx, rect.lly, rect.urx, rect.ury}); + auto itr = pages_of.find(widget.getObjectHandle().getObjGen()); + if(itr != pages_of.end()) + { + field_pages.insert(itr->second.begin(), itr->second.end()); + } + } + + entry["pages"] = nlohmann::json::array(); + for(int page : field_pages) + { + entry["pages"].push_back(page); + } + + result["fields"].push_back(entry); + } + + return result; + } + + inline int pdf_form_ops::set_values(QPDF& qpdf, const std::map& values) + { + QPDFAcroFormDocumentHelper acroform(qpdf); + + if(not acroform.hasAcroForm()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the document has no form"); + } + + std::vector fields = fields_of(acroform); + + int updated = 0; + + for(const auto& entry : values) + { + const std::string& name = entry.first; + const std::string& value = entry.second; + + std::vector matches = {find_field(fields, name)}; + + for(QPDFFormFieldObjectHelper& field : matches) + { + if(field.isCheckbox() or field.isRadioButton()) + { + std::set states = states_of(acroform, field); + + std::string state = with_slash(value); + if(field.isCheckbox() and (value == "true" or value == "True")) + { + // a checkbox has one on state, whatever it is called + state = states.empty() ? "/Yes" : *states.begin(); + } + else if(field.isCheckbox() and (value == "false" or value == "False" or value.empty())) + { + state = "/Off"; + } + + // A widget without appearance streams declares no states; + // there is then nothing to check the name against. + if(state != "/Off" and not states.empty() and states.count(state) == 0) + { + std::string choices = "/Off"; + for(const std::string& choice : states) + { + choices += ", " + choice; + } + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + value + "' is not a state of form field '" + name + + "': expected one of " + choices); + } + + // qpdf sets /V and each widget's /AS for a name value. + field.setV(QPDFObjectHandle::newName(state), true); + } + else if(field.isPushbutton() or field.getFieldType() == "/Sig") + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "form field '" + name + "' has no value that can be set"); + } + else + { + field.setV(value, true); + } + + updated += 1; + } + } + + // setV flagged the form as needing appearances; build them now, so the + // values show in viewers that do not regenerate appearances themselves. + acroform.generateAppearancesIfNeeded(); + + return updated; + } + + inline void pdf_form_ops::set_need_appearances(QPDF& qpdf, bool value) + { + QPDFAcroFormDocumentHelper acroform(qpdf); + + if(not acroform.hasAcroForm()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the document has no form"); + } + + acroform.setNeedAppearances(value); + } + + inline void pdf_form_ops::flatten(QPDF& qpdf) + { + { + QPDFAcroFormDocumentHelper acroform(qpdf); + if(acroform.hasAcroForm()) + { + acroform.generateAppearancesIfNeeded(); + } + } + + QPDFPageDocumentHelper(qpdf).flattenAnnotations(); + } + + inline QPDFFormFieldObjectHelper pdf_form_ops::find_field(std::vector& fields, + const std::string& name) + { + // Fully qualified name first; a partial name only when unambiguous. + for(QPDFFormFieldObjectHelper& field : fields) + { + if(field.getFullyQualifiedName() == name) + { + return field; + } + } + + std::vector matches; + for(QPDFFormFieldObjectHelper& field : fields) + { + if(field.getPartialName() == name) + { + matches.push_back(field); + } + } + + if(matches.size() > 1) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "form field name '" + name + "' is ambiguous: use the fully qualified name"); + } + if(matches.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the form has no field named '" + name + "'"); + } + + return matches.front(); + } + + inline QPDFObjectHandle pdf_form_ops::ensure_form_font(QPDF& qpdf, QPDFAcroFormDocumentHelper& acroform) + { + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle form = root.getKey("/AcroForm"); + if(not form.isDictionary()) + { + form = QPDFObjectHandle::newDictionary(); + form.replaceKey("/Fields", QPDFObjectHandle::newArray()); + form = qpdf.makeIndirectObject(form); + root.replaceKey("/AcroForm", form); + + // the helper looked at the document before it had a form + acroform.invalidateCache(); + } + + // /DA and /DR are what a field without its own falls back to, and what + // a viewer uses when it redraws a field (ISO 32000-1, table 218). + if(not form.getKey("/DA").isString()) + { + form.replaceKey("/DA", QPDFObjectHandle::newString("/Helv 12 Tf 0 g")); + } + + QPDFObjectHandle resources = form.getKey("/DR"); + if(not resources.isDictionary()) + { + resources = QPDFObjectHandle::newDictionary(); + form.replaceKey("/DR", resources); + } + + QPDFObjectHandle fonts = resources.getKey("/Font"); + if(not fonts.isDictionary()) + { + fonts = QPDFObjectHandle::newDictionary(); + resources.replaceKey("/Font", fonts); + } + + QPDFObjectHandle font = fonts.getKey("/Helv"); + if(not font.isDictionary()) + { + font = pdf_page_ops::make_standard_font(qpdf, "Helvetica"); + fonts.replaceKey("/Helv", font); + } + + return font; + } + + inline void pdf_form_ops::check_new_name(QPDFAcroFormDocumentHelper& acroform, + const std::string& name, + const std::string& qualified_name) + { + if(name.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field needs a name"); + } + + // A period separates the levels of a fully qualified name, so a partial + // name shall not contain one (ISO 32000-1, 12.7.3.2). + if(name.find('.') != std::string::npos) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a form field name must not contain a period: '" + name + "'"); + } + + if(not acroform.getFieldsWithQualifiedName(qualified_name).empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the form already has a field named '" + qualified_name + "'"); + } + } + + inline std::array pdf_form_ops::rect_of(const nlohmann::json& value) + { + bool valid = (value.is_array() and value.size() == 4); + for(std::size_t index = 0; valid and index < 4; index++) + { + valid = value[index].is_number(); + } + + std::array rect = {0.0, 0.0, 0.0, 0.0}; + if(valid) + { + rect = {value[0].get(), value[1].get(), + value[2].get(), value[3].get()}; + valid = (std::isfinite(rect[0]) and std::isfinite(rect[1]) and + rect[0] < rect[2] and rect[1] < rect[3]); + } + + if(not valid) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a field rectangle is [left, bottom, right, top] with a positive width and height"); + } + + return rect; + } + + inline bool pdf_form_ops::flag_of(const nlohmann::json& spec, const char* key, bool fallback) + { + auto itr = spec.find(key); + if(itr == spec.end() or itr->is_null()) + { + return fallback; + } + if(not itr->is_boolean()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + std::string("form field '") + key + "' must be true or false"); + } + + return itr->get(); + } + + inline QPDFObjectHandle pdf_form_ops::make_widget(QPDFPageObjectHelper page, + const std::array& rect) + { + QPDFObjectHandle widget = QPDFObjectHandle::newDictionary(); + widget.replaceKey("/Type", QPDFObjectHandle::newName("/Annot")); + widget.replaceKey("/Subtype", QPDFObjectHandle::newName("/Widget")); + widget.replaceKey("/Rect", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(rect[0], rect[1], rect[2], rect[3]))); + widget.replaceKey("/P", page.getObjectHandle()); + widget.replaceKey("/F", QPDFObjectHandle::newInteger(an_print)); + + return widget; + } + + inline QPDFObjectHandle pdf_form_ops::make_appearance(QPDF& qpdf, + double width, + double height, + const std::string& content, + QPDFObjectHandle font) + { + QPDFObjectHandle stream = qpdf.newStream(content); + + QPDFObjectHandle dictionary = stream.getDict(); + dictionary.replaceKey("/Type", QPDFObjectHandle::newName("/XObject")); + dictionary.replaceKey("/Subtype", QPDFObjectHandle::newName("/Form")); + dictionary.replaceKey("/BBox", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(0.0, 0.0, width, height))); + + QPDFObjectHandle resources = QPDFObjectHandle::newDictionary(); + if(font.isDictionary()) + { + QPDFObjectHandle fonts = QPDFObjectHandle::newDictionary(); + fonts.replaceKey("/Helv", font); + resources.replaceKey("/Font", fonts); + } + dictionary.replaceKey("/Resources", resources); + + return stream; + } + + inline std::string pdf_form_ops::box_path(double width, double height) + { + // a one-point black frame, drawn half a point inside the box so the + // stroke is not clipped by it + return "0 G 1 w 0.5 0.5 " + pdf_page_ops::number(width - 1.0) + " " + + pdf_page_ops::number(height - 1.0) + " re S\n"; + } + + inline std::string pdf_form_ops::check_path(double width, double height) + { + std::string path = "0 G " + pdf_page_ops::number(std::max(1.0, 0.1 * std::min(width, height))) + " w 1 J 1 j\n"; + path += pdf_page_ops::number(0.22 * width) + " " + pdf_page_ops::number(0.50 * height) + " m\n"; + path += pdf_page_ops::number(0.42 * width) + " " + pdf_page_ops::number(0.26 * height) + " l\n"; + path += pdf_page_ops::number(0.80 * width) + " " + pdf_page_ops::number(0.76 * height) + " l S\n"; + + return path; + } + + inline std::string pdf_form_ops::circle_path(double center_x, double center_y, double radius) + { + // four cubic Bezier quarters; the control points sit 0.5523 of the + // radius from each end + const double k = 0.5523 * radius; + + auto point = [](double x, double y) { + return pdf_page_ops::number(x) + " " + pdf_page_ops::number(y); + }; + + std::string path = point(center_x + radius, center_y) + " m\n"; + path += point(center_x + radius, center_y + k) + " " + point(center_x + k, center_y + radius) + " " + + point(center_x, center_y + radius) + " c\n"; + path += point(center_x - k, center_y + radius) + " " + point(center_x - radius, center_y + k) + " " + + point(center_x - radius, center_y) + " c\n"; + path += point(center_x - radius, center_y - k) + " " + point(center_x - k, center_y - radius) + " " + + point(center_x, center_y - radius) + " c\n"; + path += point(center_x + k, center_y - radius) + " " + point(center_x + radius, center_y - k) + " " + + point(center_x + radius, center_y) + " c\n"; + + return path; + } + + inline void pdf_form_ops::set_text_appearance(QPDF& qpdf, + QPDFObjectHandle widget, + const std::array& rect, + QPDFObjectHandle font) + { + double width = rect[2] - rect[0]; + double height = rect[3] - rect[1]; + + // qpdf writes the value between /Tx BMC and EMC and keeps the rest. + std::string content = "q\n" + box_path(width, height) + "Q\n/Tx BMC\nEMC\n"; + + QPDFObjectHandle appearances = QPDFObjectHandle::newDictionary(); + appearances.replaceKey("/N", make_appearance(qpdf, width, height, content, font)); + widget.replaceKey("/AP", appearances); + + QPDFAnnotationObjectHelper annotation(widget); + QPDFFormFieldObjectHelper(widget).generateAppearance(annotation); + } + + inline void pdf_form_ops::append_widget(QPDFPageObjectHelper page, QPDFObjectHandle widget) + { + QPDFObjectHandle page_object = page.getObjectHandle(); + + QPDFObjectHandle annotations = page_object.getKey("/Annots"); + if(not annotations.isArray()) + { + annotations = QPDFObjectHandle::newArray(); + page_object.replaceKey("/Annots", annotations); + } + + annotations.appendItem(widget); + } + + inline void pdf_form_ops::add_field(QPDF& qpdf, QPDFPageObjectHelper page, const nlohmann::json& spec) + { + if(not (spec.is_object() and spec.contains("kind") and spec["kind"].is_string())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field needs a kind"); + } + if(not (spec.contains("name") and spec["name"].is_string())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field needs a name"); + } + + std::string kind = spec["kind"].get(); + std::string name = spec["name"].get(); + + QPDFAcroFormDocumentHelper acroform(qpdf); + check_new_name(acroform, name, name); + + long long flags = 0; + if(flag_of(spec, "read_only", false)) { flags |= FLAG_READ_ONLY; } + if(flag_of(spec, "required", false)) { flags |= FLAG_REQUIRED; } + + double font_size = 12.0; + if(spec.contains("font_size") and not spec["font_size"].is_null()) + { + if(not spec["font_size"].is_number() or not (spec["font_size"].get() > 0.0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field font size must be positive"); + } + font_size = spec["font_size"].get(); + } + + // Everything the spec can get wrong is checked before the document is + // touched; `field` is the object that goes into the form's /Fields. + QPDFObjectHandle field = QPDFObjectHandle::newNull(); + std::vector widgets; + std::vector > text_rects; + + if(kind == "text" or kind == "choice") + { + std::array rect = rect_of(spec.value("rect", nlohmann::json())); + + std::string value; + if(spec.contains("value") and not spec["value"].is_null()) + { + if(not spec["value"].is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field value must be text"); + } + value = spec["value"].get(); + } + + field = make_widget(page, rect); + field.replaceKey("/FT", QPDFObjectHandle::newName(kind == "text" ? "/Tx" : "/Ch")); + field.replaceKey("/DA", QPDFObjectHandle::newString("/Helv " + pdf_page_ops::number(font_size) + " Tf 0 g")); + + if(kind == "text") + { + if(flag_of(spec, "multiline", false)) { flags |= FLAG_MULTILINE; } + } + else + { + const nlohmann::json options = spec.value("options", nlohmann::json()); + if(not (options.is_array() and options.size() > 0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a choice field needs a list of options"); + } + + bool editable = flag_of(spec, "editable", false); + + // a drop-down list: the kind of choice field whose appearance + // is one line of text + flags |= FLAG_COMBO; + if(editable) { flags |= FLAG_EDIT; } + + bool value_is_option = false; + QPDFObjectHandle entries = QPDFObjectHandle::newArray(); + for(const nlohmann::json& option : options) + { + if(not option.is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "choice field options must be text"); + } + value_is_option = value_is_option or (option.get() == value); + entries.appendItem(QPDFObjectHandle::newUnicodeString(option.get())); + } + + if(not value.empty() and not value_is_option and not editable) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + value + "' is not one of the options of choice field '" + name + "'"); + } + + field.replaceKey("/Opt", entries); + } + + if(not value.empty()) + { + field.replaceKey("/V", QPDFObjectHandle::newUnicodeString(value)); + } + + widgets.push_back(field); + text_rects.push_back(rect); + } + else if(kind == "checkbox") + { + std::array rect = rect_of(spec.value("rect", nlohmann::json())); + bool checked = flag_of(spec, "checked", false); + + double width = rect[2] - rect[0]; + double height = rect[3] - rect[1]; + + QPDFObjectHandle states = QPDFObjectHandle::newDictionary(); + states.replaceKey("/Yes", make_appearance(qpdf, width, height, + "q\n" + box_path(width, height) + check_path(width, height) + "Q\n", + QPDFObjectHandle::newNull())); + states.replaceKey("/Off", make_appearance(qpdf, width, height, + "q\n" + box_path(width, height) + "Q\n", + QPDFObjectHandle::newNull())); + + QPDFObjectHandle appearances = QPDFObjectHandle::newDictionary(); + appearances.replaceKey("/N", states); + + field = make_widget(page, rect); + field.replaceKey("/FT", QPDFObjectHandle::newName("/Btn")); + field.replaceKey("/V", QPDFObjectHandle::newName(checked ? "/Yes" : "/Off")); + field.replaceKey("/AS", QPDFObjectHandle::newName(checked ? "/Yes" : "/Off")); + field.replaceKey("/AP", appearances); + + widgets.push_back(field); + } + else if(kind == "radio") + { + const nlohmann::json options = spec.value("options", nlohmann::json()); + if(not (options.is_array() and options.size() > 0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a radio group needs a list of buttons, each with a state and a rect"); + } + + std::string selected = "/Off"; + if(spec.contains("selected") and not spec["selected"].is_null()) + { + if(not spec["selected"].is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the selected radio button is a state name"); + } + selected = with_slash(spec["selected"].get()); + } + + // the group is the field; its buttons are widgets below it + field = QPDFObjectHandle::newDictionary(); + field.replaceKey("/FT", QPDFObjectHandle::newName("/Btn")); + flags |= FLAG_RADIO | FLAG_NO_TOGGLE_TO_OFF; + + std::set states_seen; + for(const nlohmann::json& option : options) + { + if(not (option.is_object() and option.contains("state") and option["state"].is_string())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a radio button needs a state name"); + } + + std::string state = with_slash(option["state"].get()); + if(state == "/Off" or state == "/" or not states_seen.insert(state).second) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "radio button states must be distinct names other than Off"); + } + + std::array rect = rect_of(option.value("rect", nlohmann::json())); + + double width = rect[2] - rect[0]; + double height = rect[3] - rect[1]; + double radius = 0.5 * std::min(width, height) - 1.0; + + std::string ring = "0 G 1 w\n" + circle_path(0.5 * width, 0.5 * height, std::max(radius, 1.0)) + "S\n"; + std::string dot = "0 g\n" + circle_path(0.5 * width, 0.5 * height, std::max(0.5 * radius, 0.5)) + "f\n"; + + QPDFObjectHandle button_states = QPDFObjectHandle::newDictionary(); + button_states.replaceKey(state, make_appearance(qpdf, width, height, "q\n" + ring + dot + "Q\n", + QPDFObjectHandle::newNull())); + button_states.replaceKey("/Off", make_appearance(qpdf, width, height, "q\n" + ring + "Q\n", + QPDFObjectHandle::newNull())); + + QPDFObjectHandle appearances = QPDFObjectHandle::newDictionary(); + appearances.replaceKey("/N", button_states); + + QPDFObjectHandle widget = make_widget(page, rect); + widget.replaceKey("/AS", QPDFObjectHandle::newName(state == selected ? state : "/Off")); + widget.replaceKey("/AP", appearances); + + widgets.push_back(widget); + } + + if(selected != "/Off" and states_seen.count(selected) == 0) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + selected + "' is not a button of radio group '" + name + "'"); + } + + field.replaceKey("/V", QPDFObjectHandle::newName(selected)); + } + else if(kind == "signature") + { + std::array rect = rect_of(spec.value("rect", nlohmann::json())); + + double width = rect[2] - rect[0]; + double height = rect[3] - rect[1]; + + // an empty signature field: a frame where a signing application + // puts the signature + QPDFObjectHandle appearances = QPDFObjectHandle::newDictionary(); + appearances.replaceKey("/N", make_appearance(qpdf, width, height, + "q\n" + box_path(width, height) + "Q\n", + QPDFObjectHandle::newNull())); + + field = make_widget(page, rect); + field.replaceKey("/FT", QPDFObjectHandle::newName("/Sig")); + field.replaceKey("/AP", appearances); + + widgets.push_back(field); + } + else + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + kind + "' is not a kind of form field: expected text, checkbox, radio, " + "choice or signature"); + } + + // ---- from here on the document changes ---- + + QPDFObjectHandle font = ensure_form_font(qpdf, acroform); + + field.replaceKey("/T", QPDFObjectHandle::newUnicodeString(name)); + if(flags != 0) + { + field.replaceKey("/Ff", QPDFObjectHandle::newInteger(flags)); + } + if(spec.contains("tooltip") and spec["tooltip"].is_string()) + { + field.replaceKey("/TU", QPDFObjectHandle::newUnicodeString(spec["tooltip"].get())); + } + + field = qpdf.makeIndirectObject(field); + + if(kind == "radio") + { + QPDFObjectHandle kids = QPDFObjectHandle::newArray(); + for(QPDFObjectHandle& widget : widgets) + { + widget.replaceKey("/Parent", field); + widget = qpdf.makeIndirectObject(widget); + kids.appendItem(widget); + } + field.replaceKey("/Kids", kids); + } + else + { + // field and widget are one dictionary + widgets[0] = field; + } + + for(QPDFObjectHandle& widget : widgets) + { + append_widget(page, widget); + } + + acroform.addFormField(QPDFFormFieldObjectHelper(field)); + + for(std::size_t index = 0; index < text_rects.size(); index++) + { + set_text_appearance(qpdf, widgets[index], text_rects[index], font); + } + } + + inline void pdf_form_ops::update_field(QPDF& qpdf, const std::string& name, const nlohmann::json& changes) + { + if(not changes.is_object()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "form field changes must be a dictionary"); + } + + QPDFAcroFormDocumentHelper acroform(qpdf); + if(not acroform.hasAcroForm()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the document has no form"); + } + + std::vector fields = fields_of(acroform); + QPDFFormFieldObjectHelper field = find_field(fields, name); + QPDFObjectHandle field_object = field.getObjectHandle(); + + // ---- validate everything first ---- + + std::string new_name; + if(changes.contains("name")) + { + if(not changes["name"].is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field name must be text"); + } + new_name = changes["name"].get(); + + // the new fully qualified name: same parents, new last part + std::string qualified = field.getFullyQualifiedName(); + std::string partial = field.getPartialName(); + std::string prefix = (qualified.size() >= partial.size()) ? + qualified.substr(0, qualified.size() - partial.size()) : ""; + + if(new_name != partial) + { + check_new_name(acroform, new_name, prefix + new_name); + } + } + + std::vector widgets = widgets_of(acroform, field); + + std::array rect = {0.0, 0.0, 0.0, 0.0}; + if(changes.contains("rect")) + { + rect = rect_of(changes["rect"]); + if(widgets.size() != 1) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "form field '" + name + "' has " + std::to_string(widgets.size()) + + " widgets: only a field with one widget can be given a new rectangle"); + } + } + + QPDFObjectHandle options = QPDFObjectHandle::newNull(); + if(changes.contains("options")) + { + if(not field.isChoice()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "form field '" + name + "' is not a choice field and has no options"); + } + if(not (changes["options"].is_array() and changes["options"].size() > 0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a choice field needs a list of options"); + } + + options = QPDFObjectHandle::newArray(); + for(const nlohmann::json& option : changes["options"]) + { + if(not option.is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "choice field options must be text"); + } + options.appendItem(QPDFObjectHandle::newUnicodeString(option.get())); + } + } + + long long flags = field.getFlags(); + bool flags_changed = false; + for(const auto& flag : {std::make_pair("read_only", FLAG_READ_ONLY), std::make_pair("required", FLAG_REQUIRED)}) + { + if(changes.contains(flag.first) and not changes[flag.first].is_null()) + { + flags = flag_of(changes, flag.first, false) ? (flags | flag.second) : (flags & ~flag.second); + flags_changed = true; + } + } + + if(changes.contains("tooltip") and not (changes["tooltip"].is_null() or changes["tooltip"].is_string())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a form field tooltip must be text"); + } + + // ---- apply ---- + + if(flags_changed) + { + field_object.replaceKey("/Ff", QPDFObjectHandle::newInteger(flags)); + } + + if(changes.contains("tooltip")) + { + if(changes["tooltip"].is_null()) + { + field_object.removeKey("/TU"); + } + else + { + field_object.replaceKey("/TU", QPDFObjectHandle::newUnicodeString(changes["tooltip"].get())); + } + } + + if(options.isArray()) + { + field_object.replaceKey("/Opt", options); + } + + if(changes.contains("rect")) + { + QPDFObjectHandle widget = widgets[0].getObjectHandle(); + widget.replaceKey("/Rect", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(rect[0], rect[1], rect[2], rect[3]))); + + // A viewer scales an appearance to the rectangle, which is right + // for a check mark and wrong for text: text is laid out again. + if(field.isText() or field.isChoice()) + { + set_text_appearance(qpdf, widget, rect, ensure_form_font(qpdf, acroform)); + } + } + + if(changes.contains("name") and new_name != field.getPartialName()) + { + acroform.setFormFieldName(field, new_name); + } + } + + inline void pdf_form_ops::remove_field(QPDF& qpdf, const std::string& name) + { + QPDFAcroFormDocumentHelper acroform(qpdf); + if(not acroform.hasAcroForm()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the document has no form"); + } + + std::vector fields = fields_of(acroform); + QPDFFormFieldObjectHelper field = find_field(fields, name); + QPDFObjectHandle field_object = field.getObjectHandle(); + + std::set widget_ids; + for(QPDFAnnotationObjectHelper& widget : widgets_of(acroform, field)) + { + widget_ids.insert(widget.getObjectHandle().getObjGen()); + } + + // the widgets leave the pages that show them + for(QPDFPageObjectHelper& page : QPDFPageDocumentHelper(qpdf).getAllPages()) + { + QPDFObjectHandle page_object = page.getObjectHandle(); + QPDFObjectHandle annotations = page_object.getKey("/Annots"); + if(not annotations.isArray()) + { + continue; + } + + std::vector kept; + bool changed = false; + for(QPDFObjectHandle& annotation : annotations.getArrayAsVector()) + { + if(annotation.isIndirect() and widget_ids.count(annotation.getObjGen()) > 0) + { + changed = true; + } + else + { + kept.push_back(annotation); + } + } + + if(not changed) + { + continue; + } + + if(kept.empty()) { page_object.removeKey("/Annots"); } + else { page_object.replaceKey("/Annots", QPDFObjectHandle::newArray(kept)); } + } + + // the field leaves the form: from its parent's /Kids when it has a + // parent, from the form's /Fields otherwise + QPDFObjectHandle parent = field_object.getKey("/Parent"); + QPDFObjectHandle kids = parent.isDictionary() ? parent.getKey("/Kids") : QPDFObjectHandle::newNull(); + if(kids.isArray()) + { + for(int index = kids.getArrayNItems() - 1; index >= 0; index--) + { + QPDFObjectHandle kid = kids.getArrayItem(index); + if(kid.isIndirect() and kid.getObjGen() == field_object.getObjGen()) + { + kids.eraseItem(index); + } + } + acroform.invalidateCache(); + } + else + { + acroform.removeFormFields({field_object.getObjGen()}); + } + } + +} + +#endif diff --git a/src/edit/import_document.h b/src/edit/import_document.h new file mode 100644 index 000000000..e0f79d368 --- /dev/null +++ b/src/edit/import_document.h @@ -0,0 +1,140 @@ +//-*-C++-*- + +#ifndef PDF_IMPORT_DOCUMENT_H +#define PDF_IMPORT_DOCUMENT_H + +#include +#include +#include +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include + +namespace pdflib +{ + // The bytes a document can be parsed from, plus the password that opens + // them. This is all one editor ever takes from another: the importer parses + // the bytes into a QPDF of its own, so two editors never share a QPDF and + // never need each other's lock. The buffer is immutable once published. + class pdf_source + { + public: + + pdf_source(); + pdf_source(std::shared_ptr buffer_, + std::optional password_); + + bool is_valid() const; + + const std::shared_ptr& get_buffer() const; + const std::optional& get_password() const; + + private: + + std::shared_ptr buffer; + std::optional password; + }; + + // A source parsed for the purpose of copying pages out of it. It keeps the + // bytes and the QPDF alive for as long as the destination may still read + // from them: QPDF copies foreign stream data lazily, at write time. + class pdf_import_document + { + public: + + // Throws (QPDFExc) when the bytes cannot be parsed. + pdf_import_document(const pdf_source& source, const std::string& description); + + QPDF& get_qpdf(); + + std::vector get_pages(); + + // Built on first use: its constructor walks every form field and page. + QPDFAcroFormDocumentHelper& get_acroform(); + + private: + + pdf_source source; + + QPDF qpdf; + std::unique_ptr acroform; + }; + + inline pdf_source::pdf_source(): + buffer(nullptr), + password(std::nullopt) + {} + + inline pdf_source::pdf_source(std::shared_ptr buffer_, + std::optional password_): + buffer(buffer_), + password(password_) + {} + + inline bool pdf_source::is_valid() const + { + return buffer != nullptr; + } + + inline const std::shared_ptr& pdf_source::get_buffer() const + { + return buffer; + } + + inline const std::optional& pdf_source::get_password() const + { + return password; + } + + inline pdf_import_document::pdf_import_document(const pdf_source& source_, + const std::string& description): + source(source_), + qpdf(), + acroform(nullptr) + { + qpdf.setSuppressWarnings(true); + + const std::shared_ptr& buffer = source.get_buffer(); + + if(source.get_password().has_value()) + { + qpdf.processMemoryFile(description.c_str(), + buffer->c_str(), + buffer->size(), + source.get_password().value().c_str()); + } + else + { + qpdf.processMemoryFile(description.c_str(), + buffer->c_str(), + buffer->size()); + } + } + + inline QPDF& pdf_import_document::get_qpdf() + { + return qpdf; + } + + inline std::vector pdf_import_document::get_pages() + { + return QPDFPageDocumentHelper(qpdf).getAllPages(); + } + + inline QPDFAcroFormDocumentHelper& pdf_import_document::get_acroform() + { + if(acroform == nullptr) + { + acroform = std::make_unique(qpdf); + } + + return *acroform; + } + +} + +#endif diff --git a/src/edit/navigation_ops.h b/src/edit/navigation_ops.h new file mode 100644 index 000000000..d60c16e35 --- /dev/null +++ b/src/edit/navigation_ops.h @@ -0,0 +1,105 @@ +//-*-C++-*- + +#ifndef PDF_NAVIGATION_OPS_H +#define PDF_NAVIGATION_OPS_H + +#include +#include + +#include +#include +#include + +namespace pdflib +{ + // Maintain local destinations when a page leaves the page tree. Resolve + // names before removing their definitions, including legacy /Dests entries. + class pdf_navigation_ops + { + public: + static void drop_destinations_to(QPDF& qpdf, QPDFObjGen page); + + private: + static bool points_at(QPDFObjectHandle destination, + QPDFObjGen page, + QPDFOutlineDocumentHelper& resolver); + }; + + inline bool pdf_navigation_ops::points_at(QPDFObjectHandle destination, + QPDFObjGen page, + QPDFOutlineDocumentHelper& resolver) + { + if(destination.isName() or destination.isString()) + { + destination = resolver.resolveNamedDest(destination); + } + if(destination.isDictionary()) + { + destination = destination.getKey("/D"); + } + return destination.isArray() and destination.getArrayNItems() > 0 and + destination.getArrayItem(0).isIndirect() and + destination.getArrayItem(0).getObjGen() == page; + } + + inline void pdf_navigation_ops::drop_destinations_to(QPDF& qpdf, QPDFObjGen page) + { + QPDFOutlineDocumentHelper resolver(qpdf); + + // Links, bookmarks and the document open action can all use names. + // Inspect indirect dictionaries without decoding any content streams. + for(QPDFObjectHandle object : qpdf.getAllObjects()) + { + if(not object.isDictionary()) + { + continue; + } + if(points_at(object.getKey("/Dest"), page, resolver)) + { + object.removeKey("/Dest"); + } + for(const std::string key : {"/A", "/OpenAction"}) + { + QPDFObjectHandle action = object.getKey(key); + if((key == "/OpenAction" and points_at(action, page, resolver)) or + (action.isDictionary() and action.getKey("/S").isNameAndEquals("/GoTo") and + points_at(action.getKey("/D"), page, resolver))) + { + object.removeKey(key); + } + } + } + + QPDFObjectHandle root = qpdf.getRoot(); + QPDFObjectHandle legacy = root.getKey("/Dests"); + if(legacy.isDictionary()) + { + for(const std::string& name : legacy.getKeys()) + { + if(points_at(legacy.getKey(name), page, resolver)) + { + legacy.removeKey(name); + } + } + } + QPDFObjectHandle tree_object = root.getKey("/Names").getKey("/Dests"); + if(tree_object.isDictionary()) + { + QPDFNameTreeObjectHelper tree(tree_object, qpdf); + std::vector removed; + for(auto item = tree.begin(); item != tree.end(); ++item) + { + if(points_at(item->second, page, resolver)) + { + removed.push_back(item->first); + } + } + for(const std::string& name : removed) + { + tree.remove(name); + } + } + } +} + +#endif diff --git a/src/edit/object_json.h b/src/edit/object_json.h new file mode 100644 index 000000000..205be28fc --- /dev/null +++ b/src/edit/object_json.h @@ -0,0 +1,202 @@ +//-*-C++-*- + +#ifndef PDF_OBJECT_JSON_H +#define PDF_OBJECT_JSON_H + +#include +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include + +namespace pdflib +{ + // A detached, bounded JSON view of a PDF object, for inspection results + // whose shape the file decides (annotations, viewer preferences). Names + // keep their leading slash, strings are UTF-8, a stream is shown as its + // dictionary. The walk stops at `depth` levels and never follows the same + // indirect object twice on one path, so cyclic graphs terminate. + class pdf_object_json + { + public: + + static nlohmann::json to_json(QPDFObjectHandle object, int depth); + + static nlohmann::json to_json(QPDFObjectHandle object, + int depth, + const std::set& skipped_keys); + + // Zero-based index of every page of `qpdf`, by the page object's id. + static std::map page_indices(QPDF& qpdf); + + // The page a destination array [page /Kind ...] points at, or -1. + static int destination_page(QPDFObjectHandle destination, + const std::map& indices); + + // {"page": index or null, "kind": "/XYZ", "arguments": [...]}, or null + // when `destination` is not a destination array. + static nlohmann::json destination_to_json(QPDFObjectHandle destination, + const std::map& indices); + + private: + + static nlohmann::json walk(QPDFObjectHandle object, + int depth, + const std::set& skipped_keys, + std::set& path); + }; + + inline nlohmann::json pdf_object_json::to_json(QPDFObjectHandle object, int depth) + { + std::set skipped_keys; + return to_json(object, depth, skipped_keys); + } + + inline nlohmann::json pdf_object_json::to_json(QPDFObjectHandle object, + int depth, + const std::set& skipped_keys) + { + std::set path; + return walk(object, depth, skipped_keys, path); + } + + inline nlohmann::json pdf_object_json::walk(QPDFObjectHandle object, + int depth, + const std::set& skipped_keys, + std::set& path) + { + if(object.isNull()) { return nullptr; } + if(object.isBool()) { return object.getBoolValue(); } + if(object.isInteger()) { return object.getIntValue(); } + if(object.isReal()) { return object.getNumericValue(); } + if(object.isName()) { return object.getName(); } + if(object.isString()) { return object.getUTF8Value(); } + + bool is_container = (object.isArray() or object.isDictionary() or object.isStream()); + if(not is_container) + { + return object.unparse(); + } + + // An indirect container already on the path is a cycle (/Parent, /P ...). + QPDFObjGen identity = object.getObjGen(); + bool tracked = (object.isIndirect() and identity.getObj() != 0); + if(depth <= 0 or (tracked and path.count(identity) > 0)) + { + return object.isArray() ? nlohmann::json("[...]") : nlohmann::json("<<...>>"); + } + + if(tracked) + { + path.insert(identity); + } + + nlohmann::json result; + if(object.isArray()) + { + result = nlohmann::json::array(); + for(QPDFObjectHandle& item : object.getArrayAsVector()) + { + result.push_back(walk(item, depth - 1, skipped_keys, path)); + } + } + else + { + QPDFObjectHandle dictionary = object.isStream() ? object.getDict() : object; + + result = nlohmann::json::object(); + for(const std::string& key : dictionary.getKeys()) + { + if(skipped_keys.count(key) > 0) + { + continue; + } + result[key] = walk(dictionary.getKey(key), depth - 1, skipped_keys, path); + } + } + + if(tracked) + { + path.erase(identity); + } + + return result; + } + + inline std::map pdf_object_json::page_indices(QPDF& qpdf) + { + std::map indices; + + int index = 0; + for(const QPDFObjectHandle& page : qpdf.getAllPages()) + { + indices[page.getObjGen()] = index; + index += 1; + } + + return indices; + } + + inline int pdf_object_json::destination_page(QPDFObjectHandle destination, + const std::map& indices) + { + if(not destination.isArray() or destination.getArrayNItems() == 0) + { + return -1; + } + + QPDFObjectHandle page = destination.getArrayItem(0); + if(not page.isIndirect()) + { + return -1; + } + + auto itr = indices.find(page.getObjGen()); + return itr == indices.end() ? -1 : itr->second; + } + + inline nlohmann::json pdf_object_json::destination_to_json(QPDFObjectHandle destination, + const std::map& indices) + { + // A named destination's value is the array itself or a dictionary + // holding it under /D (ISO 32000-1, 12.3.2.3). + if(destination.isDictionary() and destination.hasKey("/D")) + { + destination = destination.getKey("/D"); + } + + if(not destination.isArray() or destination.getArrayNItems() == 0) + { + return nullptr; + } + + nlohmann::json result = nlohmann::json::object(); + + int page = destination_page(destination, indices); + result["page"] = (page < 0) ? nlohmann::json(nullptr) : nlohmann::json(page); + + result["kind"] = nullptr; + result["arguments"] = nlohmann::json::array(); + + int number_of_items = destination.getArrayNItems(); + if(number_of_items > 1 and destination.getArrayItem(1).isName()) + { + result["kind"] = destination.getArrayItem(1).getName(); + } + for(int index = 2; index < number_of_items; index++) + { + result["arguments"].push_back(to_json(destination.getArrayItem(index), 1)); + } + + return result; + } + +} + +#endif diff --git a/src/edit/outline_ops.h b/src/edit/outline_ops.h new file mode 100644 index 000000000..d9090e5de --- /dev/null +++ b/src/edit/outline_ops.h @@ -0,0 +1,828 @@ +//-*-C++-*- + +#ifndef PDF_OUTLINE_OPS_H +#define PDF_OUTLINE_OPS_H + +#include +#include +#include +#include +#include + +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include + +#include +#include +#include + +namespace pdflib +{ + // The document outline (bookmarks; ISO 32000-1, 12.3.3). qpdf reads + // outlines but has no way to create or change them, so the tree is built + // and repaired here, on the outline dictionaries themselves. + // + // An outline item is identified to callers by the object number of its + // dictionary; 0 stands for the outline root. + class pdf_outline_ops + { + public: + + // [{"id", "title", "page": index or null, "url": string or null, + // "open": bool, "children": [...]}, ...] + static nlohmann::json read(QPDF& qpdf); + + // Add an item as the last child of `parent` (0: top level) that opens + // `page` fitted to the window; page -1 makes an item without a + // destination. Returns the new item's id. + static int add_item(QPDF& qpdf, const std::string& title, int page, int parent); + + // Add an item described by `spec`: "title" (required), "parent" (id, 0 by + // default) and the entries update_item takes. Returns the new item's id. + static int add_item(QPDF& qpdf, const nlohmann::json& spec); + + // Change an item. Entries of `changes`, all optional: + // + // "title" text + // "page" index, or null for no target; with it "left", + // "top" and "zoom" (numbers or null) choose a + // position and magnification instead of fitting + // the page to the window + // "url" a URL to open instead of a page, or null + // "color" [red, green, blue] in 0..1, or null for default + // "bold", "italic" booleans + // "open" whether the item's children are shown + static void update_item(QPDF& qpdf, int id, const nlohmann::json& changes); + + // Remove an item and everything below it. + static void remove_item(QPDF& qpdf, int id); + + // Make an item the child of `parent` (0: top level) at position `index` + // among its siblings; a negative index puts it last. + static void move_item(QPDF& qpdf, int id, int parent, int index); + + // Remove the whole outline. + static void clear(QPDF& qpdf); + + // Recreate the outline of `source` in `destination` for the pages that + // were copied across: `page_map` gives, for a page of the source, the + // index it has in the destination. An item is kept when its own page or + // the page of one of its descendants was copied. Returns the number of + // items created under `parent`. + static int import(QPDF& destination, + QPDF& source, + const std::map& page_map, + int parent); + + // Remove every outline destination, and the open action, that points at + // this page: it is about to leave the page tree, and a destination that + // refers to it would keep the page alive in the file and lead nowhere. + static void drop_destinations_to(QPDF& qpdf, QPDFObjGen page); + + private: + + static const int MAX_DEPTH = 64; + + static nlohmann::json read_items(std::vector items, + const std::map& indices, + int depth); + + static QPDFObjectHandle outline_root(QPDF& qpdf); + static QPDFObjectHandle resolve_parent(QPDF& qpdf, int parent); + static QPDFObjectHandle resolve_item(QPDF& qpdf, int id); + + // The sibling list of `parent`: take `item` out of it, or put it in at + // `index` (negative: last). + static void unlink(QPDFObjectHandle item); + static void link(QPDFObjectHandle parent, QPDFObjectHandle item, int index); + + // Rewrite every /Count of the outline from its structure. An item keeps + // being open or closed; `closed` adds items to close, `opened` items to + // open. Returns the number of descendants visible below `item`. + static long long recount(QPDFObjectHandle item, + bool is_root, + const std::set& closed, + const std::set& opened, + std::set& visited, + int depth); + static void recount(QPDF& qpdf); + + static void apply(QPDF& qpdf, + QPDFObjectHandle item, + const nlohmann::json& changes, + std::set& closed, + std::set& opened); + + static std::optional number_or_null(const nlohmann::json& changes, const char* key); + + static int import_items(QPDF& destination, + std::vector items, + const std::map& page_map, + int parent, + int depth); + + static bool has_copied_page(QPDFOutlineObjectHelper& item, + const std::map& page_map, + int depth); + + static void drop_in_items(QPDFObjectHandle first, + QPDFObjGen page, + std::set& visited, + int depth); + + static bool points_at(QPDFObjectHandle destination, QPDFObjGen page); + }; + + inline nlohmann::json pdf_outline_ops::read(QPDF& qpdf) + { + QPDFOutlineDocumentHelper helper(qpdf); + if(not helper.hasOutlines()) + { + return nlohmann::json::array(); + } + + return read_items(helper.getTopLevelOutlines(), pdf_object_json::page_indices(qpdf), 0); + } + + inline nlohmann::json pdf_outline_ops::read_items(std::vector items, + const std::map& indices, + int depth) + { + nlohmann::json result = nlohmann::json::array(); + + for(QPDFOutlineObjectHelper& item : items) + { + nlohmann::json entry = nlohmann::json::object(); + + entry["id"] = item.getObjectHandle().getObjectID(); + entry["title"] = item.getTitle(); + + // getDestPage resolves /Dest, a /GoTo action and named destinations. + entry["page"] = nullptr; + QPDFObjectHandle page = item.getDestPage(); + if(page.isIndirect()) + { + auto itr = indices.find(page.getObjGen()); + if(itr != indices.end()) + { + entry["page"] = itr->second; + } + } + + QPDFObjectHandle dictionary = item.getObjectHandle(); + + entry["url"] = nullptr; + QPDFObjectHandle action = dictionary.getKey("/A"); + if(action.isDictionary() and + action.getKey("/S").isNameAndEquals("/URI") and + action.getKey("/URI").isString()) + { + entry["url"] = action.getKey("/URI").getUTF8Value(); + } + + // a negative /Count is an item whose children are hidden + QPDFObjectHandle count = dictionary.getKey("/Count"); + entry["open"] = not (count.isInteger() and count.getIntValue() < 0); + + entry["children"] = (depth < MAX_DEPTH) ? + read_items(item.getKids(), indices, depth + 1) : nlohmann::json::array(); + + result.push_back(entry); + } + + return result; + } + + inline QPDFObjectHandle pdf_outline_ops::outline_root(QPDF& qpdf) + { + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle outlines = root.getKey("/Outlines"); + if(not outlines.isDictionary()) + { + outlines = QPDFObjectHandle::newDictionary(); + outlines.replaceKey("/Type", QPDFObjectHandle::newName("/Outlines")); + outlines = qpdf.makeIndirectObject(outlines); + root.replaceKey("/Outlines", outlines); + } + else if(not outlines.isIndirect()) + { + // items refer to their parent, so the root has to be referable + outlines = qpdf.makeIndirectObject(outlines); + root.replaceKey("/Outlines", outlines); + } + + return outlines; + } + + inline QPDFObjectHandle pdf_outline_ops::resolve_parent(QPDF& qpdf, int parent) + { + if(parent == 0) + { + return outline_root(qpdf); + } + + QPDFObjectHandle item = qpdf.getObjectByID(parent, 0); + if(not (item.isDictionary() and item.hasKey("/Title"))) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "outline item " + std::to_string(parent) + " does not exist"); + } + + return item; + } + + inline QPDFObjectHandle pdf_outline_ops::resolve_item(QPDF& qpdf, int id) + { + QPDFObjectHandle item = (id > 0) ? qpdf.getObjectByID(id, 0) : QPDFObjectHandle::newNull(); + + // an outline item has a title and hangs below a parent + if(not (item.isDictionary() and item.hasKey("/Title") and item.getKey("/Parent").isDictionary())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "outline item " + std::to_string(id) + " does not exist"); + } + + return item; + } + + inline void pdf_outline_ops::unlink(QPDFObjectHandle item) + { + QPDFObjectHandle parent = item.getKey("/Parent"); + QPDFObjectHandle previous = item.getKey("/Prev"); + QPDFObjectHandle next = item.getKey("/Next"); + + // Siblings are a doubly linked list between the parent's /First and /Last. + if(previous.isDictionary()) + { + if(next.isDictionary()) { previous.replaceKey("/Next", next); } + else { previous.removeKey("/Next"); } + } + else if(parent.isDictionary()) + { + if(next.isDictionary()) { parent.replaceKey("/First", next); } + else { parent.removeKey("/First"); } + } + + if(next.isDictionary()) + { + if(previous.isDictionary()) { next.replaceKey("/Prev", previous); } + else { next.removeKey("/Prev"); } + } + else if(parent.isDictionary()) + { + if(previous.isDictionary()) { parent.replaceKey("/Last", previous); } + else { parent.removeKey("/Last"); } + } + + item.removeKey("/Prev"); + item.removeKey("/Next"); + item.removeKey("/Parent"); + } + + inline void pdf_outline_ops::link(QPDFObjectHandle parent, QPDFObjectHandle item, int index) + { + // The sibling the item goes in front of: the index-th, or none (last). + QPDFObjectHandle before = QPDFObjectHandle::newNull(); + if(index >= 0) + { + std::set visited; + before = parent.getKey("/First"); + for(int position = 0; position < index and before.isDictionary(); position++) + { + if(before.isIndirect() and not visited.insert(before.getObjGen()).second) + { + before = QPDFObjectHandle::newNull(); + break; + } + before = before.getKey("/Next"); + } + } + + item.replaceKey("/Parent", parent); + + if(before.isDictionary()) + { + QPDFObjectHandle previous = before.getKey("/Prev"); + + item.replaceKey("/Next", before); + before.replaceKey("/Prev", item); + + if(previous.isDictionary()) + { + previous.replaceKey("/Next", item); + item.replaceKey("/Prev", previous); + } + else + { + parent.replaceKey("/First", item); + } + return; + } + + QPDFObjectHandle last = parent.getKey("/Last"); + if(last.isDictionary()) + { + last.replaceKey("/Next", item); + item.replaceKey("/Prev", last); + } + else + { + parent.replaceKey("/First", item); + } + parent.replaceKey("/Last", item); + } + + inline long long pdf_outline_ops::recount(QPDFObjectHandle item, + bool is_root, + const std::set& closed, + const std::set& opened, + std::set& visited, + int depth) + { + // /Count (ISO 32000-1, tables 152 and 153): for an open item, the number + // of descendants a viewer shows below it; for a closed one, minus the + // number it would show if opened; absent without children. + long long shown = 0; + + QPDFObjectHandle kid = item.getKey("/First"); + while(kid.isDictionary() and depth < MAX_DEPTH) + { + if(kid.isIndirect() and not visited.insert(kid.getObjGen()).second) + { + break; + } + + shown += 1 + recount(kid, false, closed, opened, visited, depth + 1); + kid = kid.getKey("/Next"); + } + + bool is_closed = false; + if(not is_root) + { + QPDFObjectHandle count = item.getKey("/Count"); + is_closed = (count.isInteger() and count.getIntValue() < 0); + + if(item.isIndirect() and closed.count(item.getObjGen()) > 0) { is_closed = true; } + if(item.isIndirect() and opened.count(item.getObjGen()) > 0) { is_closed = false; } + } + + // without visible entries there is no /Count, for an item and for the + // outline root alike (ISO 32000-1, tables 152 and 153) + if(shown == 0 and (is_root or not is_closed)) + { + item.removeKey("/Count"); + return 0; + } + + item.replaceKey("/Count", QPDFObjectHandle::newInteger(is_closed ? -shown : shown)); + + // what a closed item holds is not visible further up + return is_closed ? 0 : shown; + } + + inline void pdf_outline_ops::recount(QPDF& qpdf) + { + QPDFObjectHandle outlines = qpdf.getRoot().getKey("/Outlines"); + if(not outlines.isDictionary()) + { + return; + } + + std::set none; + std::set visited; + recount(outlines, true, none, none, visited, 0); + } + + inline std::optional pdf_outline_ops::number_or_null(const nlohmann::json& changes, + const char* key) + { + auto itr = changes.find(key); + if(itr == changes.end() or itr->is_null()) + { + return std::nullopt; + } + if(not itr->is_number()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + std::string("outline item '") + key + "' must be a number"); + } + + return itr->get(); + } + + inline void pdf_outline_ops::apply(QPDF& qpdf, + QPDFObjectHandle item, + const nlohmann::json& changes, + std::set& closed, + std::set& opened) + { + if(not changes.is_object()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "outline item changes must be a dictionary"); + } + + if(changes.contains("title")) + { + if(not changes["title"].is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an outline item title must be text"); + } + item.replaceKey("/Title", QPDFObjectHandle::newUnicodeString(changes["title"].get())); + } + + bool has_url = (changes.contains("url") and not changes["url"].is_null()); + bool has_page = (changes.contains("page") and not changes["page"].is_null()); + + if(has_url and has_page) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an outline item opens a page or a URL, not both"); + } + + // Naming either one, even as null, replaces the item's target. + if(changes.contains("url") or changes.contains("page")) + { + item.removeKey("/Dest"); + item.removeKey("/A"); + } + + if(has_url) + { + if(not changes["url"].is_string()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an outline item URL must be text"); + } + + QPDFObjectHandle action = QPDFObjectHandle::newDictionary(); + action.replaceKey("/Type", QPDFObjectHandle::newName("/Action")); + action.replaceKey("/S", QPDFObjectHandle::newName("/URI")); + action.replaceKey("/URI", QPDFObjectHandle::newString(changes["url"].get())); + + item.replaceKey("/A", action); + } + else if(has_page) + { + if(not changes["page"].is_number_integer()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an outline item page must be a page index"); + } + + QPDFObjectHandle destination = + pdf_catalog_ops::fit_destination(qpdf, changes["page"].get()); + + // With a position or a magnification the destination is /XYZ, whose + // null entries mean "keep what the viewer has" (ISO 32000-1, table 151). + bool positioned = (changes.contains("left") or changes.contains("top") or changes.contains("zoom")); + if(positioned) + { + destination = QPDFObjectHandle::newArray(); + destination.appendItem(pdf_catalog_ops::fit_destination(qpdf, changes["page"].get()).getArrayItem(0)); + destination.appendItem(QPDFObjectHandle::newName("/XYZ")); + + for(const char* key : {"left", "top", "zoom"}) + { + std::optional value = number_or_null(changes, key); + destination.appendItem(value.has_value() ? + QPDFObjectHandle::newReal(QUtil::double_to_string(value.value(), 4, true)) : + QPDFObjectHandle::newNull()); + } + } + + item.replaceKey("/Dest", destination); + } + + if(changes.contains("color")) + { + const nlohmann::json& color = changes["color"]; + if(color.is_null()) + { + item.removeKey("/C"); + } + else + { + if(not (color.is_array() and color.size() == 3)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an outline item color is three numbers between 0 and 1"); + } + + QPDFObjectHandle components = QPDFObjectHandle::newArray(); + for(const nlohmann::json& component : color) + { + if(not component.is_number() or component.get() < 0.0 or component.get() > 1.0) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an outline item color is three numbers between 0 and 1"); + } + components.appendItem(QPDFObjectHandle::newReal(QUtil::double_to_string(component.get(), 4, true))); + } + item.replaceKey("/C", components); + } + } + + if(changes.contains("bold") or changes.contains("italic")) + { + // /F: bit 1 italic, bit 2 bold (ISO 32000-1, table 154) + long long flags = 0; + QPDFObjectHandle existing = item.getKey("/F"); + if(existing.isInteger()) + { + flags = existing.getIntValue(); + } + + for(const auto& style : {std::make_pair("italic", 1LL), std::make_pair("bold", 2LL)}) + { + if(not changes.contains(style.first)) + { + continue; + } + if(not changes[style.first].is_boolean()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + std::string("outline item '") + style.first + "' must be true or false"); + } + + flags = changes[style.first].get() ? (flags | style.second) : (flags & ~style.second); + } + + if(flags == 0) { item.removeKey("/F"); } + else { item.replaceKey("/F", QPDFObjectHandle::newInteger(flags)); } + } + + if(changes.contains("open")) + { + if(not changes["open"].is_boolean()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "outline item 'open' must be true or false"); + } + + (changes["open"].get() ? opened : closed).insert(item.getObjGen()); + } + } + + inline int pdf_outline_ops::add_item(QPDF& qpdf, const nlohmann::json& spec) + { + if(not (spec.is_object() and spec.contains("title") and spec["title"].is_string())) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an outline item needs a title"); + } + + int parent = 0; + if(spec.contains("parent") and not spec["parent"].is_null()) + { + if(not spec["parent"].is_number_integer()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an outline item parent is an item id"); + } + parent = spec["parent"].get(); + } + + QPDFObjectHandle parent_object = resolve_parent(qpdf, parent); + + QPDFObjectHandle item = qpdf.makeIndirectObject(QPDFObjectHandle::newDictionary()); + + // Everything that can be refused is checked before the item is linked in. + std::set closed; + std::set opened; + apply(qpdf, item, spec, closed, opened); + + link(parent_object, item, -1); + + std::set visited; + recount(qpdf.getRoot().getKey("/Outlines"), true, closed, opened, visited, 0); + + return item.getObjectID(); + } + + inline int pdf_outline_ops::add_item(QPDF& qpdf, const std::string& title, int page, int parent) + { + nlohmann::json spec = nlohmann::json::object(); + spec["title"] = title; + spec["parent"] = parent; + if(page >= 0) + { + spec["page"] = page; + } + + return add_item(qpdf, spec); + } + + inline void pdf_outline_ops::update_item(QPDF& qpdf, int id, const nlohmann::json& changes) + { + QPDFObjectHandle item = resolve_item(qpdf, id); + + std::set closed; + std::set opened; + apply(qpdf, item, changes, closed, opened); + + std::set visited; + recount(qpdf.getRoot().getKey("/Outlines"), true, closed, opened, visited, 0); + } + + inline void pdf_outline_ops::remove_item(QPDF& qpdf, int id) + { + QPDFObjectHandle item = resolve_item(qpdf, id); + + // Unlinked, the item and what hangs below it are unreachable, and the + // writer leaves unreachable objects out. + unlink(item); + recount(qpdf); + } + + inline void pdf_outline_ops::move_item(QPDF& qpdf, int id, int parent, int index) + { + QPDFObjectHandle item = resolve_item(qpdf, id); + QPDFObjectHandle parent_object = resolve_parent(qpdf, parent); + + // An item cannot go below itself: walk up from the new parent. + std::set visited; + QPDFObjectHandle ancestor = parent_object; + for(int depth = 0; depth < MAX_DEPTH and ancestor.isDictionary(); depth++) + { + if(ancestor.isIndirect() and ancestor.getObjGen() == item.getObjGen()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an outline item cannot be moved below itself"); + } + if(ancestor.isIndirect() and not visited.insert(ancestor.getObjGen()).second) + { + break; + } + ancestor = ancestor.getKey("/Parent"); + } + + unlink(item); + link(parent_object, item, index); + recount(qpdf); + } + + inline void pdf_outline_ops::clear(QPDF& qpdf) + { + qpdf.getRoot().removeKey("/Outlines"); + } + + inline bool pdf_outline_ops::has_copied_page(QPDFOutlineObjectHelper& item, + const std::map& page_map, + int depth) + { + QPDFObjectHandle page = item.getDestPage(); + if(page.isIndirect() and page_map.count(page.getObjGen()) > 0) + { + return true; + } + + if(depth >= MAX_DEPTH) + { + return false; + } + + for(QPDFOutlineObjectHelper& kid : item.getKids()) + { + if(has_copied_page(kid, page_map, depth + 1)) + { + return true; + } + } + + return false; + } + + inline int pdf_outline_ops::import_items(QPDF& destination, + std::vector items, + const std::map& page_map, + int parent, + int depth) + { + int created = 0; + + for(QPDFOutlineObjectHelper& item : items) + { + if(not has_copied_page(item, page_map, depth)) + { + continue; + } + + int page = -1; + QPDFObjectHandle source_page = item.getDestPage(); + if(source_page.isIndirect()) + { + auto itr = page_map.find(source_page.getObjGen()); + if(itr != page_map.end()) + { + page = itr->second; + } + } + + int id = add_item(destination, item.getTitle(), page, parent); + created += 1; + + if(depth < MAX_DEPTH) + { + import_items(destination, item.getKids(), page_map, id, depth + 1); + } + } + + return created; + } + + inline int pdf_outline_ops::import(QPDF& destination, + QPDF& source, + const std::map& page_map, + int parent) + { + QPDFOutlineDocumentHelper helper(source); + if(not helper.hasOutlines()) + { + return 0; + } + + return import_items(destination, helper.getTopLevelOutlines(), page_map, parent, 0); + } + + inline bool pdf_outline_ops::points_at(QPDFObjectHandle destination, QPDFObjGen page) + { + if(destination.isDictionary() and destination.hasKey("/D")) + { + destination = destination.getKey("/D"); + } + + if(not destination.isArray() or destination.getArrayNItems() == 0) + { + return false; + } + + QPDFObjectHandle target = destination.getArrayItem(0); + return (target.isIndirect() and target.getObjGen() == page); + } + + inline void pdf_outline_ops::drop_in_items(QPDFObjectHandle first, + QPDFObjGen page, + std::set& visited, + int depth) + { + QPDFObjectHandle item = first; + + while(item.isDictionary()) + { + // a damaged list may loop back on itself + if(item.isIndirect() and not visited.insert(item.getObjGen()).second) + { + break; + } + + if(points_at(item.getKey("/Dest"), page)) + { + item.removeKey("/Dest"); + } + + QPDFObjectHandle action = item.getKey("/A"); + if(action.isDictionary() and + action.getKey("/S").isNameAndEquals("/GoTo") and + points_at(action.getKey("/D"), page)) + { + item.removeKey("/A"); + } + + if(depth < MAX_DEPTH) + { + drop_in_items(item.getKey("/First"), page, visited, depth + 1); + } + + item = item.getKey("/Next"); + } + } + + inline void pdf_outline_ops::drop_destinations_to(QPDF& qpdf, QPDFObjGen page) + { + QPDFObjectHandle root = qpdf.getRoot(); + + QPDFObjectHandle outlines = root.getKey("/Outlines"); + if(outlines.isDictionary()) + { + std::set visited; + drop_in_items(outlines.getKey("/First"), page, visited, 0); + } + + QPDFObjectHandle open_action = root.getKey("/OpenAction"); + if(points_at(open_action, page)) + { + root.removeKey("/OpenAction"); + } + else if(open_action.isDictionary() and + open_action.getKey("/S").isNameAndEquals("/GoTo") and + points_at(open_action.getKey("/D"), page)) + { + root.removeKey("/OpenAction"); + } + } + +} + +#endif diff --git a/src/edit/page_ops.h b/src/edit/page_ops.h new file mode 100644 index 000000000..a67194c21 --- /dev/null +++ b/src/edit/page_ops.h @@ -0,0 +1,815 @@ +//-*-C++-*- + +#ifndef PDF_PAGE_OPS_H +#define PDF_PAGE_OPS_H + +#include +#include +#include +#include +#include +#include + +#define POINTERHOLDER_TRANSITION 0 // eliminate warnings from QPDF +#include +#include +#include +#include +#include +#include +#include + +#include + +namespace pdflib +{ + // The geometry of one page as the page tree defines it, with inherited + // attributes resolved (ISO 32000-1, 7.7.3.4) and the box fallbacks of + // 14.11.2 applied: /CropBox defaults to /MediaBox, the other three to + // /CropBox. Boxes are [llx, lly, urx, ury] in default user space units. + class pdf_page_info + { + public: + + typedef std::array box_type; + + pdf_page_info(); + + // Caller serializes access to the QPDF that owns `page`. + static pdf_page_info read(QPDFPageObjectHelper page); + + const box_type& get_media_box() const; + const box_type& get_crop_box() const; + const box_type& get_bleed_box() const; + const box_type& get_trim_box() const; + const box_type& get_art_box() const; + + int get_rotation() const; // /Rotate, normalized to 0, 90, 180 or 270 + double get_user_unit() const; // /UserUnit, 1.0 when absent + + private: + + static box_type to_box(QPDFObjectHandle handle, const box_type& fallback); + + private: + + box_type media_box; + box_type crop_box; + box_type bleed_box; + box_type trim_box; + box_type art_box; + + int rotation; + double user_unit; + }; + + // QPDF mechanics for single-page edits. Stateless; the caller owns the QPDF + // and serializes access to it. + class pdf_page_ops + { + public: + + // "media" | "crop" | "bleed" | "trim" | "art" -> "/MediaBox" ... + static std::string box_key(const std::string& name); + + static void set_box(QPDFPageObjectHelper page, + const std::string& name, + const pdf_page_info::box_type& box); + + // `angle` is a multiple of 90; relative adds to the current /Rotate. + static void rotate(QPDFPageObjectHelper page, int angle, bool relative); + + // A new, empty page object of the given size that is not yet in the page + // tree of `qpdf`. + static QPDFObjectHandle make_blank_page(QPDF& qpdf, double width, double height); + + // Apply the matrix [a b c d e f] to everything the page shows: its + // content, by concatenating the matrix to the CTM in front of it (ISO + // 32000-1, 8.3.4), and its annotations, whose rectangles and appearances + // are not part of the content stream. The page boxes are left alone. + static void transform(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::array& matrix); + + // Multiply every page boundary by (sx, sy), so the page changes size + // together with content transformed by the same scale. + static void scale_boxes(QPDFPageObjectHelper page, double sx, double sy); + + // Draw the form XObject `form` (already owned by `qpdf`) on the page, + // above its content or, with under, below it. + // + // fit=false: at the form's own coordinates transformed by `matrix`; + // with the identity the two pages are superimposed as if + // printed on the same sheet. + // fit=true: centered in the page's trim box, scaled down or up to + // fill it, and upright with respect to the page's /Rotate. + // `matrix` must be the identity. + static void overlay(QPDF& qpdf, + QPDFPageObjectHelper page, + QPDFObjectHandle form, + bool under, + bool fit, + const std::array& matrix); + + // ---- new content ---- + + // Add `content` (content stream operators) on top of what the page + // shows. The existing content is closed off first, so the new operators + // start from the default graphics state. + static void append_content(QPDF& qpdf, QPDFPageObjectHelper page, const std::string& content); + + // A font dictionary for one of the standard 14 fonts that take Latin + // text (ISO 32000-1, 9.6.2.2), with WinAnsiEncoding. These need no + // embedded font program: every viewer supplies them. + static QPDFObjectHandle make_standard_font(QPDF& qpdf, const std::string& base_font); + + // Register `resource` (an indirect object) in the page's own resources + // under a new name of the given kind ("/Font", "/XObject") and return + // that name. A resource already registered is reused. + static std::string add_resource(QPDFPageObjectHelper page, + const std::string& kind, + const std::string& prefix, + QPDFObjectHandle resource); + + // Draw `text` (UTF-8) with its baseline starting at (x, y), in `font` + // (from make_standard_font) at `size` points, filled with `color` + // (red, green, blue in 0..1). A line feed starts a new line 1.2 x size + // below. Text outside WinAnsiEncoding is an UNSUPPORTED error. + static void draw_text(QPDF& qpdf, + QPDFPageObjectHelper page, + QPDFObjectHandle font, + const std::string& text, + double x, + double y, + double size, + const std::array& color); + + // The text as a PDF literal string in WinAnsiEncoding, parentheses + // included. + static std::string win_ansi_literal(const std::string& text); + + // A page of page_width x page_height points showing one image in the + // rectangle `placement` (x, y, width, height). `data` is either a JPEG + // file (is_jpeg) or width x height x components 8-bit samples, row by + // row; `colorspace` is "gray", "rgb" or "cmyk". `alpha`, when not empty, + // is width x height 8-bit opacity samples. `invert` marks samples stored + // inverted, as Adobe applications write CMYK JPEGs. `rotate` becomes the + // page's /Rotate. The page is not yet in the page tree. + static QPDFObjectHandle make_image_page(QPDF& qpdf, + int width, + int height, + const std::string& colorspace, + const std::string& data, + bool is_jpeg, + bool invert, + const std::string& alpha, + double page_width, + double page_height, + const std::array& placement, + int rotate); + + // A number as written in a content stream. + static std::string number(double value); + + // Replace the page's /Rotate by an equivalent rotation of its content, + // boxes and annotations, so the page displays the same with /Rotate 0. + static void flatten_rotation(QPDF& qpdf, QPDFPageObjectHelper page); + + private: + + // Finite entries and a non-zero determinant, or INVALID_EDIT. + static void check_matrix(const std::array& matrix); + }; + + inline pdf_page_info::pdf_page_info(): + media_box({0.0, 0.0, 0.0, 0.0}), + crop_box({0.0, 0.0, 0.0, 0.0}), + bleed_box({0.0, 0.0, 0.0, 0.0}), + trim_box({0.0, 0.0, 0.0, 0.0}), + art_box({0.0, 0.0, 0.0, 0.0}), + rotation(0), + user_unit(1.0) + {} + + inline pdf_page_info::box_type pdf_page_info::to_box(QPDFObjectHandle handle, + const box_type& fallback) + { + if(not handle.isRectangle()) + { + return fallback; + } + + QPDFObjectHandle::Rectangle rect = handle.getArrayAsRectangle(); + + // A rectangle may be given by any two diagonally opposite corners + // (ISO 32000-1, 7.9.5): report it normalized. + return {std::min(rect.llx, rect.urx), + std::min(rect.lly, rect.ury), + std::max(rect.llx, rect.urx), + std::max(rect.lly, rect.ury)}; + } + + inline pdf_page_info pdf_page_info::read(QPDFPageObjectHelper page) + { + pdf_page_info result; + + // copy_if_shared=false: reading must not modify the document. + result.media_box = to_box(page.getAttribute("/MediaBox", false), result.media_box); + result.crop_box = to_box(page.getAttribute("/CropBox", false), result.media_box); + + QPDFObjectHandle page_object = page.getObjectHandle(); + + result.bleed_box = to_box(page_object.getKey("/BleedBox"), result.crop_box); + result.trim_box = to_box(page_object.getKey("/TrimBox"), result.crop_box); + result.art_box = to_box(page_object.getKey("/ArtBox"), result.crop_box); + + QPDFObjectHandle rotate = page.getAttribute("/Rotate", false); + if(rotate.isInteger()) + { + int angle = rotate.getIntValueAsInt() % 360; + result.rotation = (angle < 0) ? angle + 360 : angle; + } + + QPDFObjectHandle user_unit = page_object.getKey("/UserUnit"); + if(user_unit.isNumber()) + { + result.user_unit = user_unit.getNumericValue(); + } + + return result; + } + + inline const pdf_page_info::box_type& pdf_page_info::get_media_box() const { return media_box; } + + inline const pdf_page_info::box_type& pdf_page_info::get_crop_box() const { return crop_box; } + + inline const pdf_page_info::box_type& pdf_page_info::get_bleed_box() const { return bleed_box; } + + inline const pdf_page_info::box_type& pdf_page_info::get_trim_box() const { return trim_box; } + + inline const pdf_page_info::box_type& pdf_page_info::get_art_box() const { return art_box; } + + inline int pdf_page_info::get_rotation() const { return rotation; } + + inline double pdf_page_info::get_user_unit() const { return user_unit; } + + inline std::string pdf_page_ops::box_key(const std::string& name) + { + if(name == "media") { return "/MediaBox"; } + if(name == "crop") { return "/CropBox"; } + if(name == "bleed") { return "/BleedBox"; } + if(name == "trim") { return "/TrimBox"; } + if(name == "art") { return "/ArtBox"; } + + throw pdf_edit_error(edit_error::INVALID_EDIT, + "unknown page box '" + name + "': expected media, crop, bleed, trim or art"); + } + + inline void pdf_page_ops::set_box(QPDFPageObjectHelper page, + const std::string& name, + const pdf_page_info::box_type& box) + { + std::string key = box_key(name); + + if(not (box[0] < box[2] and box[1] < box[3])) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page box must have a positive width and height"); + } + + // Written on the page itself, never on a shared /Pages node: an inherited + // box stays untouched for the sibling pages. + QPDFObjectHandle::Rectangle rect(box[0], box[1], box[2], box[3]); + page.getObjectHandle().replaceKey(key, QPDFObjectHandle::newArray(rect)); + } + + inline void pdf_page_ops::rotate(QPDFPageObjectHelper page, int angle, bool relative) + { + // /Rotate shall be a multiple of 90 (ISO 32000-1, table 30). + if((angle % 90) != 0) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page rotation must be a multiple of 90 degrees"); + } + + page.rotatePage(angle, relative); + } + + inline QPDFObjectHandle pdf_page_ops::make_blank_page(QPDF& qpdf, double width, double height) + { + if(not (width > 0.0 and height > 0.0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a blank page needs a positive width and height"); + } + + // /Contents is optional (ISO 32000-1, table 30), but an empty content + // stream is the form other producers write for a blank page, so it is the + // form readers are certain to have seen. + QPDFObjectHandle page = QPDFObjectHandle::newDictionary(); + page.replaceKey("/Type", QPDFObjectHandle::newName("/Page")); + page.replaceKey("/MediaBox", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(0.0, 0.0, width, height))); + page.replaceKey("/Resources", QPDFObjectHandle::newDictionary()); + page.replaceKey("/Contents", qpdf.newStream(std::string(""))); + + return qpdf.makeIndirectObject(page); + } + + inline void pdf_page_ops::check_matrix(const std::array& matrix) + { + for(double value : matrix) + { + if(not std::isfinite(value)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a transformation matrix must have finite entries"); + } + } + + // A singular matrix collapses the page onto a line or a point. + double determinant = matrix[0]*matrix[3] - matrix[1]*matrix[2]; + if(std::abs(determinant) < 1.e-12) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a transformation matrix must be invertible"); + } + } + + inline void pdf_page_ops::flatten_rotation(QPDF& qpdf, QPDFPageObjectHelper page) + { + // qpdf rewrites the content, the boxes and, given the helper, the + // annotations and their form fields. + QPDFAcroFormDocumentHelper acroform(qpdf); + page.flattenRotation(&acroform); + } + + inline void pdf_page_ops::transform(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::array& matrix) + { + check_matrix(matrix); + + QPDFMatrix cm(matrix[0], matrix[1], matrix[2], matrix[3], matrix[4], matrix[5]); + + // q ... Q around the existing content: the matrix applies to all of it + // and to nothing drawn after it. Same construction as qpdf's + // QPDFPageObjectHelper::flattenRotation. + page.addPageContents(qpdf.newStream(std::string("q\n") + cm.unparse() + " cm\n"), true); + page.addPageContents(qpdf.newStream(std::string("\nQ\n")), false); + + QPDFObjectHandle page_object = page.getObjectHandle(); + QPDFObjectHandle annots = page_object.getKey("/Annots"); + if(annots.isArray() and annots.getArrayNItems() > 0) + { + std::vector new_annots; + std::vector new_fields; + std::set old_fields; + + // transformAnnotations returns transformed copies; the page then + // refers to the copies and the form to their fields, in place of + // the originals. + QPDFAcroFormDocumentHelper acroform(qpdf); + acroform.transformAnnotations(annots, new_annots, new_fields, old_fields, cm); + acroform.removeFormFields(old_fields); + for(const QPDFObjectHandle& field : new_fields) + { + acroform.addFormField(QPDFFormFieldObjectHelper(field)); + } + + page_object.replaceKey("/Annots", QPDFObjectHandle::newArray(new_annots)); + } + } + + inline void pdf_page_ops::scale_boxes(QPDFPageObjectHelper page, double sx, double sy) + { + if(not (sx > 0.0 and sy > 0.0 and std::isfinite(sx) and std::isfinite(sy))) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page scale factors must be positive"); + } + + QPDFObjectHandle page_object = page.getObjectHandle(); + + for(const char* key : {"/MediaBox", "/CropBox", "/BleedBox", "/TrimBox", "/ArtBox"}) + { + // /MediaBox and /CropBox may be inherited: the scaled value is + // written on this page, so sibling pages keep theirs. + std::string name(key); + bool inheritable = (name == "/MediaBox" or name == "/CropBox"); + + QPDFObjectHandle box = inheritable ? page.getAttribute(name, false) : page_object.getKey(name); + if(not box.isRectangle()) + { + continue; + } + + QPDFObjectHandle::Rectangle rect = box.getArrayAsRectangle(); + QPDFObjectHandle::Rectangle scaled(rect.llx*sx, rect.lly*sy, rect.urx*sx, rect.ury*sy); + + page_object.replaceKey(name, QPDFObjectHandle::newArray(scaled)); + } + } + + inline void pdf_page_ops::overlay(QPDF& qpdf, + QPDFPageObjectHelper page, + QPDFObjectHandle form, + bool under, + bool fit, + const std::array& matrix) + { + check_matrix(matrix); + + const std::array identity = {1.0, 0.0, 0.0, 1.0, 0.0, 0.0}; + if(fit and matrix != identity) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an overlay is either fitted to the page or placed with a matrix, not both"); + } + + // The page gets a /Resources dictionary of its own: adding a name to one + // inherited from /Pages would add it to every sibling page. + QPDFObjectHandle resources = page.getAttribute("/Resources", true); + if(not resources.isDictionary()) + { + resources = QPDFObjectHandle::newDictionary(); + page.getObjectHandle().replaceKey("/Resources", resources); + } + + int min_suffix = 1; + std::string name = resources.getUniqueResourceName("/Fx", min_suffix); + + std::string content; + if(fit) + { + QPDFObjectHandle trim_box = page.getTrimBox(false, false); + if(not trim_box.isRectangle()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the page has no usable boundary to fit an overlay into"); + } + + content = page.placeFormXObject(form, + name, + trim_box.getArrayAsRectangle(), + true, // invert_transformations + true, // allow_shrink + true); // allow_expand + if(content.empty()) + { + // qpdf's answer to a form without a usable /BBox + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the overlaid page has no usable boundary"); + } + } + else + { + QPDFMatrix cm(matrix[0], matrix[1], matrix[2], matrix[3], matrix[4], matrix[5]); + content = "q\n" + cm.unparse() + " cm\n" + name + " Do\nQ\n"; + } + + // mergeResources replaces a shared /XObject subdictionary by a copy + // before the name is added to it. + resources.mergeResources(QPDFObjectHandle::parse("<< /XObject << >> >>")); + QPDFObjectHandle xobjects = resources.getKey("/XObject"); + if(not xobjects.isDictionary()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the page's /XObject resources are not a dictionary"); + } + xobjects.replaceKey(name, form); + + if(under) + { + // Drawn first, in a graphics state of its own. + page.addPageContents(qpdf.newStream(content), true); + } + else + { + // The existing content may leave any graphics state behind: close it + // off before drawing on top. + page.addPageContents(qpdf.newStream(std::string("q\n")), true); + page.addPageContents(qpdf.newStream(std::string("\nQ\n") + content), false); + } + } + + inline std::string pdf_page_ops::number(double value) + { + if(not std::isfinite(value)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a coordinate must be a finite number"); + } + + return QUtil::double_to_string(value, 4, true); + } + + inline void pdf_page_ops::append_content(QPDF& qpdf, + QPDFPageObjectHelper page, + const std::string& content) + { + // q ... Q around what is there, then the new operators: same isolation + // as an overlay. + page.addPageContents(qpdf.newStream(std::string("q\n")), true); + page.addPageContents(qpdf.newStream(std::string("\nQ\n") + content), false); + } + + inline QPDFObjectHandle pdf_page_ops::make_standard_font(QPDF& qpdf, const std::string& base_font) + { + static const std::set fonts = { + "Helvetica", "Helvetica-Bold", "Helvetica-Oblique", "Helvetica-BoldOblique", + "Times-Roman", "Times-Bold", "Times-Italic", "Times-BoldItalic", + "Courier", "Courier-Bold", "Courier-Oblique", "Courier-BoldOblique"}; + + if(fonts.count(base_font) == 0) + { + std::string choices; + for(const std::string& choice : fonts) + { + choices += (choices.empty() ? "" : ", ") + choice; + } + throw pdf_edit_error(edit_error::INVALID_EDIT, + "'" + base_font + "' is not an available font: expected one of " + choices); + } + + QPDFObjectHandle font = QPDFObjectHandle::newDictionary(); + font.replaceKey("/Type", QPDFObjectHandle::newName("/Font")); + font.replaceKey("/Subtype", QPDFObjectHandle::newName("/Type1")); + font.replaceKey("/BaseFont", QPDFObjectHandle::newName("/" + base_font)); + font.replaceKey("/Encoding", QPDFObjectHandle::newName("/WinAnsiEncoding")); + + return qpdf.makeIndirectObject(font); + } + + inline std::string pdf_page_ops::add_resource(QPDFPageObjectHelper page, + const std::string& kind, + const std::string& prefix, + QPDFObjectHandle resource) + { + // A dictionary of the page's own, as in overlay(). + QPDFObjectHandle resources = page.getAttribute("/Resources", true); + if(not resources.isDictionary()) + { + resources = QPDFObjectHandle::newDictionary(); + page.getObjectHandle().replaceKey("/Resources", resources); + } + + resources.mergeResources(QPDFObjectHandle::parse("<< " + kind + " << >> >>")); + QPDFObjectHandle entries = resources.getKey(kind); + if(not entries.isDictionary()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the page's " + kind + " resources are not a dictionary"); + } + + for(const std::string& name : entries.getKeys()) + { + QPDFObjectHandle existing = entries.getKey(name); + if(existing.isIndirect() and existing.getObjGen() == resource.getObjGen()) + { + return name; + } + } + + int min_suffix = 1; + std::string name = resources.getUniqueResourceName(prefix, min_suffix); + entries.replaceKey(name, resource); + + return name; + } + + inline std::string pdf_page_ops::win_ansi_literal(const std::string& text) + { + std::string encoded; + if(not QUtil::utf8_to_win_ansi(text, encoded)) + { + throw pdf_edit_error(load_error::UNSUPPORTED, + "the text has characters outside WinAnsiEncoding (Latin-1 and a few more), " + "which is all the built-in fonts can show"); + } + + std::string literal = "("; + for(char character : encoded) + { + // the three characters with a meaning inside a literal string + if(character == '(' or character == ')' or character == '\\') + { + literal += '\\'; + } + literal += character; + } + literal += ")"; + + return literal; + } + + inline void pdf_page_ops::draw_text(QPDF& qpdf, + QPDFPageObjectHelper page, + QPDFObjectHandle font, + const std::string& text, + double x, + double y, + double size, + const std::array& color) + { + if(not (size > 0.0 and std::isfinite(size))) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the font size must be positive"); + } + for(double component : color) + { + if(not (component >= 0.0 and component <= 1.0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "a color is three numbers between 0 and 1"); + } + } + + // Encode every line before touching the page: a line that cannot be + // shown must leave the page as it was. + std::vector lines; + std::string::size_type start = 0; + while(true) + { + std::string::size_type end = text.find('\n', start); + std::string line = text.substr(start, end == std::string::npos ? std::string::npos : end - start); + if(not line.empty() and line.back() == '\r') + { + line.pop_back(); + } + lines.push_back(win_ansi_literal(line)); + + if(end == std::string::npos) + { + break; + } + start = end + 1; + } + + std::string font_name = add_resource(page, "/Font", "/F", font); + + std::string content = "q\nBT\n"; + content += font_name + " " + number(size) + " Tf\n"; + content += number(color[0]) + " " + number(color[1]) + " " + number(color[2]) + " rg\n"; + content += number(1.2 * size) + " TL\n"; + content += number(x) + " " + number(y) + " Td\n"; + for(std::size_t index = 0; index < lines.size(); index++) + { + if(index > 0) + { + content += "T*\n"; + } + content += lines[index] + " Tj\n"; + } + content += "ET\nQ\n"; + + append_content(qpdf, page, content); + } + + inline QPDFObjectHandle pdf_page_ops::make_image_page(QPDF& qpdf, + int width, + int height, + const std::string& colorspace, + const std::string& data, + bool is_jpeg, + bool invert, + const std::string& alpha, + double page_width, + double page_height, + const std::array& placement, + int rotate) + { + if((rotate % 90) != 0) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "page rotation must be a multiple of 90 degrees"); + } + + if(width <= 0 or height <= 0) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "an image needs a positive width and height"); + } + if(not (page_width > 0.0 and page_height > 0.0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "a page needs a positive width and height"); + } + if(not (placement[2] > 0.0 and placement[3] > 0.0)) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an image must be placed with a positive width and height"); + } + + std::size_t components = 0; + std::string device; + if(colorspace == "gray") { components = 1; device = "/DeviceGray"; } + else if(colorspace == "rgb") { components = 3; device = "/DeviceRGB"; } + else if(colorspace == "cmyk") { components = 4; device = "/DeviceCMYK"; } + else + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "an image colorspace is 'gray', 'rgb' or 'cmyk'"); + } + + std::size_t pixels = static_cast(width) * static_cast(height); + + if(data.empty()) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, "the image has no data"); + } + if(not is_jpeg and data.size() != pixels * components) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the image data does not match its size: expected " + + std::to_string(pixels * components) + " bytes, got " + + std::to_string(data.size())); + } + if(not alpha.empty() and alpha.size() != pixels) + { + throw pdf_edit_error(edit_error::INVALID_EDIT, + "the image's opacity samples do not match its size"); + } + + QPDFObjectHandle image = qpdf.newStream(); + if(is_jpeg) + { + // A JPEG file is the /DCTDecode stream data as it is: stored, not + // re-encoded. + image.replaceStreamData(data, + QPDFObjectHandle::newName("/DCTDecode"), + QPDFObjectHandle::newNull()); + } + else + { + // Raw samples; the writer compresses them. + image.replaceStreamData(data, QPDFObjectHandle::newNull(), QPDFObjectHandle::newNull()); + } + + QPDFObjectHandle image_dict = image.getDict(); + image_dict.replaceKey("/Type", QPDFObjectHandle::newName("/XObject")); + image_dict.replaceKey("/Subtype", QPDFObjectHandle::newName("/Image")); + image_dict.replaceKey("/Width", QPDFObjectHandle::newInteger(width)); + image_dict.replaceKey("/Height", QPDFObjectHandle::newInteger(height)); + image_dict.replaceKey("/ColorSpace", QPDFObjectHandle::newName(device)); + image_dict.replaceKey("/BitsPerComponent", QPDFObjectHandle::newInteger(8)); + + if(invert) + { + // one [1 0] pair per component maps each sample to its inverse + // (ISO 32000-1, 8.9.5.2) + QPDFObjectHandle decode = QPDFObjectHandle::newArray(); + for(std::size_t component = 0; component < components; component++) + { + decode.appendItem(QPDFObjectHandle::newInteger(1)); + decode.appendItem(QPDFObjectHandle::newInteger(0)); + } + image_dict.replaceKey("/Decode", decode); + } + + if(not alpha.empty()) + { + // Opacity is a second, grayscale image (ISO 32000-1, 11.6.5.3). + QPDFObjectHandle mask = qpdf.newStream(); + mask.replaceStreamData(alpha, QPDFObjectHandle::newNull(), QPDFObjectHandle::newNull()); + + QPDFObjectHandle mask_dict = mask.getDict(); + mask_dict.replaceKey("/Type", QPDFObjectHandle::newName("/XObject")); + mask_dict.replaceKey("/Subtype", QPDFObjectHandle::newName("/Image")); + mask_dict.replaceKey("/Width", QPDFObjectHandle::newInteger(width)); + mask_dict.replaceKey("/Height", QPDFObjectHandle::newInteger(height)); + mask_dict.replaceKey("/ColorSpace", QPDFObjectHandle::newName("/DeviceGray")); + mask_dict.replaceKey("/BitsPerComponent", QPDFObjectHandle::newInteger(8)); + + image_dict.replaceKey("/SMask", mask); + } + + // An image fills the unit square; the matrix maps that square onto the + // placement rectangle (ISO 32000-1, 8.9.4). + std::string content = "q\n"; + content += number(placement[2]) + " 0 0 " + number(placement[3]) + " " + + number(placement[0]) + " " + number(placement[1]) + " cm\n"; + content += "/Im0 Do\nQ\n"; + + QPDFObjectHandle xobjects = QPDFObjectHandle::newDictionary(); + xobjects.replaceKey("/Im0", image); + + QPDFObjectHandle resources = QPDFObjectHandle::newDictionary(); + resources.replaceKey("/XObject", xobjects); + + QPDFObjectHandle page = QPDFObjectHandle::newDictionary(); + page.replaceKey("/Type", QPDFObjectHandle::newName("/Page")); + page.replaceKey("/MediaBox", + QPDFObjectHandle::newArray(QPDFObjectHandle::Rectangle(0.0, 0.0, page_width, page_height))); + page.replaceKey("/Resources", resources); + page.replaceKey("/Contents", qpdf.newStream(content)); + + int normalized = ((rotate % 360) + 360) % 360; + if(normalized != 0) + { + page.replaceKey("/Rotate", QPDFObjectHandle::newInteger(normalized)); + } + + return qpdf.makeIndirectObject(page); + } + +} + +#endif diff --git a/src/edit/text_layout.h b/src/edit/text_layout.h new file mode 100644 index 000000000..8bf2880e8 --- /dev/null +++ b/src/edit/text_layout.h @@ -0,0 +1,153 @@ +//-*-C++-*- + +#ifndef PDF_TEXT_LAYOUT_H +#define PDF_TEXT_LAYOUT_H + +#include +#include +#include +#include +#include + +namespace pdflib +{ + // Lays text runs out on a character grid, so that the plain text keeps the + // page's columns, indentation and vertical spacing. This is the fixed-pitch + // approximation pypdf calls layout mode: one column is the page's typical + // character width, one row its typical line height. + class pdf_text_layout + { + public: + + typedef std::array box_type; // x0, y0, x1, y1; y grows upwards + + // `texts[i]` occupies `boxes[i]` and is `lengths[i]` characters long. + static std::string render(const std::vector& texts, + const std::vector& boxes, + const std::vector& lengths); + + private: + + // More blank lines than this between two rows say nothing more about the + // layout and only pad the output. + static constexpr int MAX_BLANK_LINES = 3; + + static double median(std::vector values, double fallback); + }; + + inline double pdf_text_layout::median(std::vector values, double fallback) + { + if(values.empty()) + { + return fallback; + } + + std::size_t middle = values.size() / 2; + std::nth_element(values.begin(), values.begin() + middle, values.end()); + + return values[middle]; + } + + inline std::string pdf_text_layout::render(const std::vector& texts, + const std::vector& boxes, + const std::vector& lengths) + { + std::size_t number_of_runs = texts.size(); + if(number_of_runs == 0) + { + return ""; + } + + std::vector char_widths; + std::vector line_heights; + double left = boxes[0][0]; + + for(std::size_t index = 0; index < number_of_runs; index++) + { + double width = boxes[index][2] - boxes[index][0]; + double height = boxes[index][3] - boxes[index][1]; + + if(lengths[index] > 0 and width > 0.0) + { + char_widths.push_back(width / lengths[index]); + } + if(height > 0.0) + { + line_heights.push_back(height); + } + + left = std::min(left, boxes[index][0]); + } + + // 6 x 12 points: a 10-point fixed-pitch face, when the page gives no measure + double char_width = median(char_widths, 6.0); + double line_height = median(line_heights, 12.0); + + // top to bottom, then left to right + std::vector order(number_of_runs); + for(std::size_t index = 0; index < number_of_runs; index++) + { + order[index] = index; + } + + auto center = [&boxes](std::size_t index) { + return 0.5 * (boxes[index][1] + boxes[index][3]); + }; + + std::stable_sort(order.begin(), order.end(), [¢er](std::size_t lhs, std::size_t rhs) { + return center(lhs) > center(rhs); + }); + + // Runs whose centers are within half a line of the row's first run share + // the row. + std::vector > rows; + std::vector row_centers; + + for(std::size_t index : order) + { + if(rows.empty() or (row_centers.back() - center(index)) > 0.5 * line_height) + { + rows.push_back({}); + row_centers.push_back(center(index)); + } + rows.back().push_back(index); + } + + std::string result; + + for(std::size_t row = 0; row < rows.size(); row++) + { + if(row > 0) + { + int blank_lines = static_cast(std::lround((row_centers[row - 1] - row_centers[row]) / line_height)) - 1; + blank_lines = std::max(0, std::min(blank_lines, MAX_BLANK_LINES)); + + result += std::string(static_cast(blank_lines) + 1, '\n'); + } + + std::vector& runs = rows[row]; + std::stable_sort(runs.begin(), runs.end(), [&boxes](std::size_t lhs, std::size_t rhs) { + return boxes[lhs][0] < boxes[rhs][0]; + }); + + int cursor = 0; // characters written on this row so far + for(std::size_t index : runs) + { + int column = static_cast(std::lround((boxes[index][0] - left) / char_width)); + + // Runs that the grid would overlap still stay apart by one space. + int padding = (column > cursor) ? (column - cursor) : ((cursor > 0) ? 1 : 0); + + result += std::string(static_cast(padding), ' '); + result += texts[index]; + + cursor += padding + lengths[index]; + } + } + + return result; + } + +} + +#endif diff --git a/src/parse/pdf_decoders/document.h b/src/parse/pdf_decoders/document.h index a5008395e..63597fedb 100644 --- a/src/parse/pdf_decoders/document.h +++ b/src/parse/pdf_decoders/document.h @@ -36,6 +36,19 @@ namespace pdflib std::string get_filename() { return filename; } + // The bytes this document was parsed from and the password it was opened + // with. Both are set once at load time and never change afterwards, so a + // second QPDF can be parsed from the same bytes without copying them + // (the editor clones and imports documents this way). + std::shared_ptr get_source_buffer() { return buffer; } + std::optional get_password() { return password; } + + // Run function(QPDF&) on the parsed document while holding the document + // mutex, which is what serializes every other use of that QPDF. The + // callable must not keep a QPDFObjectHandle beyond its own return. + template + decltype(auto) with_qpdf(function_type&& function); + // Why the last process_document_* call returned false: a category // from load_error and the message of the underlying failure. Both // are empty while no load has failed. @@ -186,6 +199,13 @@ namespace pdflib pdf_decoder::~pdf_decoder() {} + template + decltype(auto) pdf_decoder::with_qpdf(function_type&& function) + { + std::lock_guard lock(thread_safe_buffer_mutex); + return function(qpdf_document); + } + void pdf_decoder::ensure_annots_loaded() { // The first caller builds json_annots; every later caller returns as diff --git a/src/pybind/docling_editor.h b/src/pybind/docling_editor.h new file mode 100644 index 000000000..1e03d7a09 --- /dev/null +++ b/src/pybind/docling_editor.h @@ -0,0 +1,2115 @@ +//-*-C++-*- + +#ifndef PYBIND_PDF_EDITOR_H +#define PYBIND_PDF_EDITOR_H + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#include + +#include +#include + +namespace docling +{ + // Inspection, editing and writing of one PDF document. All functionality of + // PdfReader, PdfWriter and PdfEditor lives here; pdf_reader and pdf_writer + // only choose which of these operations they publish. + // + // States. An editor is closed, reading or editing: + // + // - reading: a source was opened and nothing was changed. The document is + // the inherited parser's decoder under SOURCE_KEY. + // - editing: the editor owns a destination QPDF. It gets one from + // create_empty(), or on the first mutating call after an open, which + // parses the source bytes a second time (a clone: the whole document + // survives, nothing is remapped). The source bytes are never modified. + // + // Thread safety. Not multi-threaded, but thread safe: every public method + // holds the inherited parser_mutex for its whole duration, so calls from + // several threads on one instance are serialized. Two editors never share a + // QPDF: what crosses between them is a pdf_source (immutable bytes), which + // the receiver parses for itself, so no operation takes two editors' locks. + // Nothing here touches Python; the binding releases the GIL around each + // call. + // + // Page handles. Page arguments are zero-based. Each takes the generation + // the caller last saw; a call with an outdated generation fails with + // edit_error::STALE_HANDLE instead of acting on whichever page now has that + // index. Pass ANY_GENERATION to skip the check. + // + // Errors. Every failure leaves as pdflib::pdf_edit_error (category plus + // message); open_* instead return false and record the reason, like the + // inherited load_document. + class docling_editor: public docling_parser + { + typedef pdflib::pdf_decoder document_decoder_type; + typedef std::shared_ptr document_decoder_ptr_type; + + typedef std::shared_ptr import_document_ptr_type; + + public: + + static constexpr std::int64_t ANY_GENERATION = -1; + + docling_editor(std::string loglevel = "fatal"); + ~docling_editor(); + + // ---- lifecycle ---- + + bool open_file(std::string filename, std::optional password); + bool open_buffer(std::shared_ptr buffer, std::optional password); + bool open_source(const pdflib::pdf_source& source); + + // {"category": ..., "message": ...} of the last failed open, or empty. + std::map take_open_error(); + + // Start an empty destination with no pages (assembly mode). + void create_empty(); + + bool is_open(); + bool is_editing(); + + void close(); + + // ---- inspection ---- + + int page_count(); + + // Changes whenever existing page indices may have changed meaning. + std::int64_t generation(); + + pdflib::pdf_document_info document_info(); + void validate_strict(); + pdflib::pdf_page_info page_info(int page, std::int64_t expected_generation); + + // The page's line cells in the order the parser emits them, joined by + // "\n"; or, with layout, placed on a character grid that keeps the page's + // columns, indentation and vertical spacing (pdf_text_layout). + std::string extract_text(int page, std::int64_t expected_generation, bool layout); + + // One-based page number, unlike the internal page indices used by the + // pypdf-compatible surfaces. Returns owned RGBA pixels and {height, width, 4}. + std::pair>, std::array> + render_page(int page_no, double scale); + + // A bounded JSON view of one object, for inspection: `id` is its object + // number, 0 the trailer, -1 the catalog. + nlohmann::json object_json(int id, int depth); + + // The images the page draws, in drawing order, with their encoded bytes. + std::vector page_images(int page, std::int64_t expected_generation); + + nlohmann::json outline(); + nlohmann::json annotations(); + + // Document-level content, read from the document as it currently is. + // The JSON shapes are documented on the pdf_*_ops functions they come + // from (src/edit). + nlohmann::json document_settings(); // pdf_catalog_ops::read_settings + std::vector page_labels(); + nlohmann::json named_destinations(); + nlohmann::json outline_tree(); // pdf_outline_ops::read + nlohmann::json form(); // pdf_form_ops::read + nlohmann::json page_annotations(int page, std::int64_t expected_generation); + nlohmann::json attachments(); // pdf_attachment_ops::read + std::string attachment_data(std::string name); + nlohmann::json javascript(); + + // The bytes this document can be re-parsed from: the opened source while + // reading, the serialized current state while editing. + pdflib::pdf_source get_source(); + + // Same, but fails with STALE_HANDLE when the page list is no longer the + // one a page handle of this document was taken from. Used when another + // editor is about to read one of this document's pages by index. + pdflib::pdf_source get_source(std::int64_t expected_generation); + + // ---- editing ---- + + void remove_page(int page, std::int64_t expected_generation, bool clean = false); + void move_page(int from, int to, std::int64_t expected_generation); + + void rotate_page(int page, std::int64_t expected_generation, int angle, bool relative); + void set_page_box(int page, + std::int64_t expected_generation, + std::string box, + std::array rectangle); + + // Concatenate [a b c d e f] to the page's content and annotations. + void transform_page(int page, + std::int64_t expected_generation, + std::array matrix); + + // Scale content, annotations and all page boundaries by (sx, sy). + void scale_page(int page, std::int64_t expected_generation, double sx, double sy); + + // Draw page `other_page` of another document on this page as vector + // content: above it, or with under below it. See pdf_page_ops::overlay + // for fit. The other page's annotations are not copied. + void overlay_page(int page, + std::int64_t expected_generation, + const pdflib::pdf_source& other, + int other_page, + bool under, + bool fit, + std::array matrix); + + // Turn the page's /Rotate into a rotation of its content. + void flatten_page_rotation(int page, std::int64_t expected_generation); + + // `at` is the index the first new page gets; negative appends at the end. + // All three return the index of the first new page. + int duplicate_page(int page, std::int64_t expected_generation, int at); + int insert_blank_page(int at, double width, double height); + + // A page showing one image; see pdf_page_ops::make_image_page. + int insert_image_page(int at, + int width, + int height, + std::string colorspace, + std::string data, + bool is_jpeg, + bool invert, + std::string alpha, + double page_width, + double page_height, + std::array placement, + int rotate); + + // Draw text on a page in one of the standard fonts; see + // pdf_page_ops::draw_text. + void draw_text(int page, + std::int64_t expected_generation, + std::string text, + double x, + double y, + double size, + std::string font, + std::array color); + // With import_outline, the other document's bookmarks that lead to a + // copied page are recreated at the top level of this document's outline. + int append_pages(const pdflib::pdf_source& other, + std::optional > pages, + int at, + bool import_outline); + + // ---- document-level editing ---- + + // Entries of /Info; a key without a value is removed. + void set_info(std::map > entries); + void set_xmp(std::optional packet); + + // Empty name removes the entry. + void set_page_layout(std::string name); + void set_page_mode(std::string name); + + // The new /ViewerPreferences dictionary in PDF syntax; empty removes it. + void set_viewer_preferences(std::string dictionary); + + // Page to show when the document is opened; -1 removes the open action. + void set_open_destination(int page); + + void set_page_label(int from, int to, std::string style, std::string prefix, int start); + void add_named_destination(std::string name, int page); + + // Returns the id of the new item, usable as `parent` of later items. + int add_outline_item(std::string title, int page, int parent); + + // Outline editing; the JSON entries are documented on + // pdf_outline_ops::add_item and update_item. + int add_outline_entry(nlohmann::json spec); + void update_outline_item(int id, nlohmann::json changes); + void remove_outline_item(int id); + void move_outline_item(int id, int parent, int index); + void clear_outline(); + + // ---- forms, annotations, attachments, scripts ---- + + int set_form_values(std::map values); + void set_need_appearances(bool value); + void flatten_annotations(); + + // Form fields; the JSON entries are documented on pdf_form_ops::add_field + // and update_field. + void add_form_field(int page, std::int64_t expected_generation, nlohmann::json spec); + void update_form_field(std::string name, nlohmann::json changes); + void remove_form_field(std::string name); + + // `dictionary` is the annotation in PDF syntax. + void add_annotation(int page, std::int64_t expected_generation, std::string dictionary); + void add_page_link(int page, + std::int64_t expected_generation, + std::array rectangle, + int target); + int remove_annotations(int page, + std::int64_t expected_generation, + std::set subtypes); + + void add_attachment(std::string name, + std::string bytes, + std::string description, + std::string mime_type); + bool remove_attachment(std::string name); + + void add_javascript(std::string name, std::string script); + int remove_javascript(); + + // ---- output ---- + + // Encrypt everything written from now on with AES-256 (ISO 32000-2, + // revision 6), the one password scheme PDF 2.0 retains. The user password + // opens the document; an empty one lets anyone open it. The owner + // password defaults to the user password. + void set_encryption(std::string user_password, + std::string owner_password, + pdflib::pdf_permissions permissions, + std::string algorithm = "AES-256"); + void clear_encryption(); + + // How the file is written. compress_streams: Flate-compress streams that + // are not compressed. object_streams: "preserve", "generate" (smaller + // files) or "disable". linearize: order the file for page-at-a-time + // loading over a network. + void set_output_options(bool compress_streams, std::string object_streams, bool linearize); + + // Full rewrite of the current state; unencrypted unless set_encryption + // was called, whatever the source was. The returned buffer is immutable + // and shared with later callers until the next edit. + std::shared_ptr write_to_memory(); + + // Writes a temporary sibling file and renames it over `filename`, so a + // failed write never leaves a truncated file behind. + void write_to_file(std::string filename); + + private: + + // All helpers below expect the caller to hold parser_mutex. + + template + decltype(auto) guarded(function_type&& function); + + template + decltype(auto) with_document(function_type&& function); + + void reset_state(); + + // The three shapes almost every operation has. Each takes the lock and + // translates errors; the editing ones also make sure there is a + // destination and mark the document as changed. + template + decltype(auto) read_document(function_type&& function); + + template + decltype(auto) edit_document(function_type&& function); + + template + decltype(auto) edit_page(int page, std::int64_t expected_generation, function_type&& function); + + void require_open(); + void check_generation(std::int64_t expected_generation); + void check_page(int page, int number_of_pages); + + document_decoder_ptr_type require_source_decoder(); + + // Clone the opened source into a destination, if there is none yet. + void ensure_destination(); + std::vector destination_pages(); + + void touch(bool page_list_changed); + + void ensure_snapshot(); + std::string decode_key(); + + // The password that opens the snapshot, if it is encrypted and needs one. + std::optional snapshot_password() const; + + // A fresh decode of one page with exactly this config. + std::shared_ptr > decode_page(int page, + const pdflib::decode_config& config); + + // Resolve an insertion index: returns the position, sets at_end. + int insertion_position(int at, int number_of_pages, bool& at_end); + + import_document_ptr_type find_or_create_import(const pdflib::pdf_source& other); + + QPDFObjectHandle find_or_create_overlay_form(const pdflib::pdf_source& other, + int other_page, + bool fit); + + static std::filesystem::path to_path(const std::string& filename); + static std::string random_suffix(); + + private: + + static constexpr const char* SOURCE_KEY = "docling-editor-source"; + static constexpr const char* SNAPSHOT_KEY = "docling-editor-snapshot"; + + // Decoded pages kept by the inherited cache; text extraction needs none + // of them once the text is returned. + static constexpr int PAGE_CACHE_SIZE = 4; + + // All guarded by the inherited parser_mutex; the editor adds no second lock. + + pdflib::pdf_source source; + + // Order matters: the destination reads lazily from destination_buffer + // (qpdf does not copy the bytes it parses) and from the imported + // documents (foreign stream data is copied at write time), so it is + // declared last and therefore destroyed first. + std::shared_ptr destination_buffer; + std::map imports; + std::unique_ptr destination; + + // Pages of imported documents already turned into form XObjects of the + // destination, by (source bytes, page, fit): a watermark stamped on every + // page is copied once. The handles point into the destination, so they + // are declared after it and released before it. + typedef std::tuple overlay_key_type; + std::map overlay_forms; + + // Standard font dictionaries already added to the destination, by name, + // so that text drawn on many pages shares one font object. + std::map standard_fonts; + + std::int64_t current_generation; // page-list identity, for page handles + std::int64_t current_revision; // any change, for the snapshot + + // The destination serialized at snapshot_revision. It backs write, text + // extraction and get_source(), so each edit is serialized at most once. + std::shared_ptr snapshot; + std::int64_t snapshot_revision; + bool snapshot_loaded; // registered with the parser under SNAPSHOT_KEY + + // Output encryption, off by default. The snapshot is the output, so it is + // encrypted too and read back with the user password. + bool output_encrypted; + std::string output_algorithm = "AES-256"; + std::string output_user_password; + std::string output_owner_password; + pdflib::pdf_permissions output_permissions; + + bool output_compress_streams; + qpdf_object_stream_e output_object_streams; + bool output_linearize; + }; + + inline docling_editor::docling_editor(std::string loglevel): + docling_parser(loglevel, PAGE_CACHE_SIZE), + source(), + destination_buffer(nullptr), + imports({}), + destination(nullptr), + overlay_forms({}), + standard_fonts({}), + current_generation(0), + current_revision(0), + snapshot(nullptr), + snapshot_revision(-1), + snapshot_loaded(false), + output_encrypted(false), + output_user_password(""), + output_owner_password(""), + output_permissions(), + output_compress_streams(true), + output_object_streams(qpdf_o_preserve), + output_linearize(false) + {} + + inline docling_editor::~docling_editor() + {} + + template + decltype(auto) docling_editor::guarded(function_type&& function) + { + try + { + return function(); + } + catch(const pdflib::pdf_edit_error&) + { + throw; + } + catch(const QPDFExc& exc) + { + throw pdflib::pdf_edit_error(pdflib::load_error::category_of(exc.getErrorCode()), + exc.what()); + } + catch(const pdflib::missing_page_object_error& exc) + { + throw pdflib::pdf_edit_error(pdflib::load_error::DAMAGED, exc.what()); + } + catch(const std::exception& exc) + { + throw pdflib::pdf_edit_error(pdflib::load_error::UNKNOWN, exc.what()); + } + } + + template + decltype(auto) docling_editor::with_document(function_type&& function) + { + if(destination != nullptr) + { + return function(*destination); + } + + // Reading: the decoder serializes this with its own page extraction. + return require_source_decoder()->with_qpdf(function); + } + + template + decltype(auto) docling_editor::read_document(function_type&& function) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, &function]() { + return with_document(function); + }); + } + + template + decltype(auto) docling_editor::edit_document(function_type&& function) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, &function]() { + ensure_destination(); + + // before the change: a failure half way still invalidates the snapshot + touch(false); + + return function(*destination); + }); + } + + template + decltype(auto) docling_editor::edit_page(int page, + std::int64_t expected_generation, + function_type&& function) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation, &function]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + touch(false); + + return function(*destination, pages.at(page)); + }); + } + + inline void docling_editor::reset_state() + { + source = pdflib::pdf_source(); + + // destination before what it reads from, as in the destructor + overlay_forms.clear(); + standard_fonts.clear(); + destination.reset(); + imports.clear(); + destination_buffer.reset(); + + snapshot.reset(); + snapshot_revision = -1; + snapshot_loaded = false; + + output_encrypted = false; + output_user_password.clear(); + output_owner_password.clear(); + output_permissions = pdflib::pdf_permissions(); + + output_compress_streams = true; + output_object_streams = qpdf_o_preserve; + output_linearize = false; + + // A reopened editor is a different document: outstanding page handles + // must not match it. + current_generation += 1; + current_revision += 1; + + unload_documents(); + } + + inline void docling_editor::require_open() + { + if(destination == nullptr and not source.is_valid()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "no document is open"); + } + } + + inline void docling_editor::check_generation(std::int64_t expected_generation) + { + if(expected_generation != ANY_GENERATION and expected_generation != current_generation) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::STALE_HANDLE, + "the page list changed since this page handle was obtained"); + } + } + + inline void docling_editor::check_page(int page, int number_of_pages) + { + if(page < 0 or page >= number_of_pages) + { + std::stringstream message; + message << "page index " << page << " is out of range for a document of " + << number_of_pages << " pages"; + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, message.str()); + } + } + + inline docling_editor::document_decoder_ptr_type docling_editor::require_source_decoder() + { + require_open(); + + document_decoder_ptr_type decoder = get_document_decoder(SOURCE_KEY); + if(decoder == nullptr) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "no document is open"); + } + + return decoder; + } + + inline void docling_editor::ensure_destination() + { + if(destination != nullptr) + { + return; + } + + require_open(); + + // Clone: a second parse of the same immutable bytes. Everything the file + // contains is carried over because nothing is copied object by object. + auto qpdf = std::make_unique(); + qpdf->setSuppressWarnings(true); + + const std::shared_ptr& buffer = source.get_buffer(); + if(source.get_password().has_value()) + { + qpdf->processMemoryFile("docling-editor clone", + buffer->c_str(), + buffer->size(), + source.get_password().value().c_str()); + } + else + { + qpdf->processMemoryFile("docling-editor clone", + buffer->c_str(), + buffer->size()); + } + + destination_buffer = buffer; + destination = std::move(qpdf); + + // The page list is the same, so page handles stay valid; from here on the + // destination is the document and the source decoder is not needed. + if(is_loaded(SOURCE_KEY)) + { + unload_document(SOURCE_KEY); + } + } + + inline std::vector docling_editor::destination_pages() + { + return QPDFPageDocumentHelper(*destination).getAllPages(); + } + + inline void docling_editor::touch(bool page_list_changed) + { + current_revision += 1; + + if(page_list_changed) + { + current_generation += 1; + } + } + + inline void docling_editor::ensure_snapshot() + { + ensure_destination(); + + if(snapshot != nullptr and snapshot_revision == current_revision) + { + return; + } + + try + { + QPDFWriter writer(*destination); + writer.setOutputMemory(); + + writer.setCompressStreams(output_compress_streams); + writer.setObjectStreamMode(output_object_streams); + writer.setLinearization(output_linearize); + + if(output_encrypted) + { + qpdf_r3_print_e print = qpdf_r3p_full; + if(output_permissions.get_print() == 1) { print = qpdf_r3p_low; } + if(output_permissions.get_print() >= 2) { print = qpdf_r3p_none; } + + if(output_algorithm == "RC4-40") + { + writer.setR2EncryptionParametersInsecure(output_user_password.c_str(), + output_owner_password.c_str(), output_permissions.get_print() != 2, + output_permissions.get_modify(), output_permissions.get_extract(), + output_permissions.get_annotate()); + } + else if(output_algorithm == "RC4-128") + { + writer.setR3EncryptionParametersInsecure(output_user_password.c_str(), + output_owner_password.c_str(), output_permissions.get_accessibility(), + output_permissions.get_extract(), output_permissions.get_assemble(), + output_permissions.get_annotate(), output_permissions.get_fill_forms(), + output_permissions.get_modify(), print); + } + else if(output_algorithm == "AES-128") + { + writer.setR4EncryptionParametersInsecure(output_user_password.c_str(), + output_owner_password.c_str(), output_permissions.get_accessibility(), + output_permissions.get_extract(), output_permissions.get_assemble(), + output_permissions.get_annotate(), output_permissions.get_fill_forms(), + output_permissions.get_modify(), print, true, true); + } + else if(output_algorithm == "AES-256-R5") + { + writer.setR5EncryptionParameters(output_user_password.c_str(), + output_owner_password.c_str(), output_permissions.get_accessibility(), + output_permissions.get_extract(), output_permissions.get_assemble(), + output_permissions.get_annotate(), output_permissions.get_fill_forms(), + output_permissions.get_modify(), print, true); + } + else + { + writer.setR6EncryptionParameters(output_user_password.c_str(), + output_owner_password.c_str(), + output_permissions.get_accessibility(), + output_permissions.get_extract(), + output_permissions.get_assemble(), + output_permissions.get_annotate(), + output_permissions.get_fill_forms(), + output_permissions.get_modify(), + print, + true); // encrypt_metadata_aes + } + } + else + { + // Output is unencrypted unless encryption was asked for: the + // encryption of the source is not carried over. + writer.setPreserveEncryption(false); + } + writer.write(); + + std::shared_ptr out = writer.getBufferSharedPointer(); + + snapshot = std::make_shared(reinterpret_cast(out->getBuffer()), + out->getSize()); + snapshot_revision = current_revision; + snapshot_loaded = false; + } + catch(const std::exception& exc) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::WRITE, exc.what()); + } + } + + inline std::string docling_editor::decode_key() + { + if(destination == nullptr) + { + require_source_decoder(); + return SOURCE_KEY; + } + + // Decoding reads a finished PDF, so an edited document is decoded from + // its serialized state. + ensure_snapshot(); + + if(not snapshot_loaded) + { + if(not load_document_from_buffer(SNAPSHOT_KEY, snapshot, snapshot_password())) + { + std::map error = take_load_error(SNAPSHOT_KEY); + throw pdflib::pdf_edit_error(pdflib::edit_error::WRITE, + "the edited document could not be read back: " + error["message"]); + } + snapshot_loaded = true; + } + + return SNAPSHOT_KEY; + } + + inline docling_editor::import_document_ptr_type + docling_editor::find_or_create_import(const pdflib::pdf_source& other) + { + // One parsed QPDF per distinct byte buffer: pages imported in several + // calls then share the objects qpdf already copied for the first one. + const std::string* identity = other.get_buffer().get(); + + auto itr = imports.find(identity); + if(itr != imports.end()) + { + return itr->second; + } + + auto document = std::make_shared(other, "docling-editor import"); + imports[identity] = document; + + return document; + } + + inline std::filesystem::path docling_editor::to_path(const std::string& filename) + { + // The filename is UTF-8; see pdf_decoder::process_document_from_file + // for why Windows needs the explicit conversion. +#ifdef _WIN32 + return std::filesystem::path(std::u8string(filename.begin(), filename.end())); +#else + return std::filesystem::path(filename); +#endif + } + + inline std::string docling_editor::random_suffix() + { + std::random_device device; + + std::stringstream stream; + stream << std::hex << device() << device(); + + return stream.str(); + } + + inline bool docling_editor::open_file(std::string filename, std::optional password) + { + std::lock_guard lock(parser_mutex); + + reset_state(); + + if(not load_document(SOURCE_KEY, filename, password)) + { + return false; + } + + document_decoder_ptr_type decoder = get_document_decoder(SOURCE_KEY); + source = pdflib::pdf_source(decoder->get_source_buffer(), decoder->get_password()); + + return true; + } + + inline bool docling_editor::open_buffer(std::shared_ptr buffer, + std::optional password) + { + std::lock_guard lock(parser_mutex); + + reset_state(); + + if(not load_document_from_buffer(SOURCE_KEY, buffer, password)) + { + return false; + } + + source = pdflib::pdf_source(buffer, password); + + return true; + } + + inline bool docling_editor::open_source(const pdflib::pdf_source& source_) + { + return open_buffer(source_.get_buffer(), source_.get_password()); + } + + inline std::map docling_editor::take_open_error() + { + return take_load_error(SOURCE_KEY); + } + + inline void docling_editor::create_empty() + { + std::lock_guard lock(parser_mutex); + + guarded([this]() { + reset_state(); + + auto qpdf = std::make_unique(); + qpdf->setSuppressWarnings(true); + qpdf->emptyPDF(); + + destination = std::move(qpdf); + }); + } + + inline bool docling_editor::is_open() + { + std::lock_guard lock(parser_mutex); + + return (destination != nullptr or source.is_valid()); + } + + inline bool docling_editor::is_editing() + { + std::lock_guard lock(parser_mutex); + + return (destination != nullptr); + } + + inline void docling_editor::close() + { + std::lock_guard lock(parser_mutex); + + reset_state(); + } + + inline int docling_editor::page_count() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() -> int { + if(destination != nullptr) + { + return static_cast(destination_pages().size()); + } + + return require_source_decoder()->get_number_of_pages(); + }); + } + + inline std::int64_t docling_editor::generation() + { + std::lock_guard lock(parser_mutex); + + return current_generation; + } + + inline pdflib::pdf_document_info docling_editor::document_info() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() { + pdflib::pdf_document_info info = with_document([](QPDF& qpdf) { + return pdflib::pdf_document_info::read(qpdf); + }); + + if(destination != nullptr) + { + // While editing, report the encryption of what will be written, + // not of what was opened: none by default, and with set_encryption + // exactly what the serialized document declares. + pdflib::pdf_encryption_info encryption; + if(output_encrypted) + { + document_decoder_ptr_type decoder = get_document_decoder(decode_key()); + if(decoder != nullptr) + { + encryption = decoder->with_qpdf([](QPDF& qpdf) { + return pdflib::pdf_encryption_info::read(qpdf); + }); + } + } + info.set_encryption(encryption); + } + + return info; + }); + } + + inline void docling_editor::validate_strict() + { + read_document([](QPDF& qpdf) { + if(qpdf.anyWarnings()) + { + throw pdflib::pdf_edit_error(pdflib::load_error::DAMAGED, "strict mode rejects a PDF that required repairs or produced structural warnings"); + } + }); + } + + inline pdflib::pdf_page_info docling_editor::page_info(int page, std::int64_t expected_generation) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation]() { + check_generation(expected_generation); + + return with_document([this, page](QPDF& qpdf) { + std::vector pages = QPDFPageDocumentHelper(qpdf).getAllPages(); + check_page(page, static_cast(pages.size())); + + return pdflib::pdf_page_info::read(pages.at(page)); + }); + }); + } + + inline nlohmann::json docling_editor::object_json(int id, int depth) + { + return read_document([id, depth](QPDF& qpdf) { + if(depth < 1 or depth > 32) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "the depth of an object view is between 1 and 32"); + } + + QPDFObjectHandle object = QPDFObjectHandle::newNull(); + if(id == 0) { object = qpdf.getTrailer(); } + else if(id == -1) { object = qpdf.getRoot(); } + else if(id > 0) { object = qpdf.getObjectByID(id, 0); } + + if(object.isNull()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "the document has no object " + std::to_string(id)); + } + + return pdflib::pdf_object_json::to_json(object, depth); + }); + } + + inline std::string docling_editor::extract_text(int page, + std::int64_t expected_generation, + bool layout) + { + // Held across the decode, unlike docling_parser::get_page_decoder on its + // own: the page index and the snapshot must stay the ones that were + // checked. Calls on one editor are serialized by contract. + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation, layout]() { + check_generation(expected_generation); + check_page(page, page_count()); + + // Text only: skip what the caller cannot ask for through this method. + pdflib::decode_config config; + config.keep_shapes = false; + config.keep_bitmaps = false; + config.create_word_cells = layout; + config.create_line_cells = true; + + auto page_decoder = decode_page(page, config); + + if(layout) + { + // Words, not lines: a line cell may already join runs that sit far + // apart on the page, and the distance between them is exactly + // what the grid is meant to keep. + auto& word_cells = page_decoder->get_word_cells(); + + std::vector texts; + std::vector boxes; + std::vector lengths; + + for(auto itr = word_cells.begin(); itr != word_cells.end(); ++itr) + { + texts.push_back(itr->text); + boxes.push_back({std::min(itr->x0, itr->x1), std::min(itr->y0, itr->y1), + std::max(itr->x0, itr->x1), std::max(itr->y0, itr->y1)}); + lengths.push_back(itr->number_of_chars()); + } + + return pdflib::pdf_text_layout::render(texts, boxes, lengths); + } + + auto& line_cells = page_decoder->get_line_cells(); + + std::string text; + + for(auto itr = line_cells.begin(); itr != line_cells.end(); ++itr) + { + if(not text.empty()) + { + text += "\n"; + } + text += itr->text; + } + + return text; + }); + } + + inline std::pair>, std::array> + docling_editor::render_page(int page_no, double scale) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, page_no, scale]() { + if(page_no < 1 or page_no > page_count()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "page_no must be between 1 and the number of pages"); + } + if(not std::isfinite(scale) or scale <= 0.0 or scale > std::numeric_limits::max()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "scale must be finite and positive"); + } + + pdflib::render_config render_config; + render_config.scale = static_cast(scale); + pdflib::validate_render_config(render_config); + + pdflib::decode_config decode_config; + decode_config.extract_font_programs = true; + decode_config.extract_bitmap_pixels = true; + decode_config.keep_shapes = true; + decode_config.keep_bitmaps = true; + decode_config.create_word_cells = false; + decode_config.create_line_cells = false; + decode_config.bitmap_target_pixels_per_unit = render_config.scale; + + auto page_decoder = decode_page(page_no - 1, decode_config); + pdflib::renderer renderer(render_config); + page_decoder->get_instructions().iterate_over_instructions(renderer); + return std::make_pair(renderer.get_canvas(), renderer.get_shape()); + }); + } + + inline std::shared_ptr > + docling_editor::decode_page(int page, const pdflib::decode_config& config) + { + std::string key = decode_key(); + + // The inherited cache is keyed by page only, not by config: a page + // decoded for its text must not be handed back when its images are asked + // for. The editor returns owned copies and keeps no decoded page, so the + // cached entry is dropped and the page decoded as asked. + unload_document_page(key, page); + + auto page_decoder = get_page_decoder(key, page, config); + if(page_decoder == nullptr) + { + throw pdflib::pdf_edit_error(pdflib::load_error::UNKNOWN, + "the page could not be decoded"); + } + + return page_decoder; + } + + inline std::vector + docling_editor::page_images(int page, std::int64_t expected_generation) + { + // Held across the decode, for the reason given in extract_text. + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation]() { + check_generation(expected_generation); + check_page(page, page_count()); + + // Images only: no derived text cells, no vector shapes. + pdflib::decode_config config; + config.keep_shapes = false; + config.keep_bitmaps = true; + config.extract_bitmap_pixels = true; + config.create_word_cells = false; + config.create_line_cells = false; + + auto page_decoder = decode_page(page, config); + + std::vector result; + + auto& images = page_decoder->get_page_images(); + for(auto itr = images.begin(); itr != images.end(); ++itr) + { + pdflib::pdf_exported_image::box_type bbox = {itr->x0, itr->y0, itr->x1, itr->y1}; + + result.emplace_back(itr->xobject_key, + bbox, + itr->image_width, + itr->image_height, + itr->get_image_format(), + itr->get_pil_mode(), + itr->get_image_as_bytes()); + } + + return result; + }); + } + + inline nlohmann::json docling_editor::outline() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() { + return get_table_of_contents(decode_key()); + }); + } + + inline nlohmann::json docling_editor::annotations() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() { + return get_annotations(decode_key()); + }); + } + + inline pdflib::pdf_source docling_editor::get_source() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() { + require_open(); + + if(destination == nullptr) + { + return source; + } + + ensure_snapshot(); + return pdflib::pdf_source(snapshot, snapshot_password()); + }); + } + + inline pdflib::pdf_source docling_editor::get_source(std::int64_t expected_generation) + { + std::lock_guard lock(parser_mutex); + + guarded([this, expected_generation]() { + check_generation(expected_generation); + }); + + return get_source(); + } + + inline int docling_editor::insertion_position(int at, int number_of_pages, bool& at_end) + { + if(at > number_of_pages) + { + check_page(at, number_of_pages); + } + + at_end = (at < 0 or at == number_of_pages); + + return at_end ? number_of_pages : at; + } + + inline QPDFObjectHandle docling_editor::find_or_create_overlay_form(const pdflib::pdf_source& other, + int other_page, + bool fit) + { + overlay_key_type key(other.get_buffer().get(), other_page, fit); + + auto itr = overlay_forms.find(key); + if(itr != overlay_forms.end()) + { + return itr->second; + } + + import_document_ptr_type import = find_or_create_import(other); + std::vector import_pages = import->get_pages(); + check_page(other_page, static_cast(import_pages.size())); + + // With fit, the form carries the other page's /Rotate and /UserUnit so it + // is placed the way that page is displayed; without, it is the page's + // content exactly as written. + QPDFObjectHandle form = + destination->copyForeignObject(import_pages.at(other_page).getFormXObjectForPage(fit)); + + overlay_forms[key] = form; + + return form; + } + + inline void docling_editor::transform_page(int page, + std::int64_t expected_generation, + std::array matrix) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, &matrix]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + touch(false); + pdflib::pdf_page_ops::transform(*destination, pages.at(page), matrix); + }); + } + + inline void docling_editor::scale_page(int page, + std::int64_t expected_generation, + double sx, + double sy) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, sx, sy]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + touch(false); + + // Boxes first: it validates the factors before anything is changed. + pdflib::pdf_page_ops::scale_boxes(pages.at(page), sx, sy); + pdflib::pdf_page_ops::transform(*destination, pages.at(page), {sx, 0.0, 0.0, sy, 0.0, 0.0}); + }); + } + + inline void docling_editor::overlay_page(int page, + std::int64_t expected_generation, + const pdflib::pdf_source& other, + int other_page, + bool under, + bool fit, + std::array matrix) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, &other, other_page, under, fit, &matrix]() { + check_generation(expected_generation); + + if(not other.is_valid()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "the document to overlay from is not open"); + } + + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + QPDFObjectHandle form = find_or_create_overlay_form(other, other_page, fit); + + touch(false); + pdflib::pdf_page_ops::overlay(*destination, pages.at(page), form, under, fit, matrix); + }); + } + + inline void docling_editor::flatten_page_rotation(int page, std::int64_t expected_generation) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + touch(false); + pdflib::pdf_page_ops::flatten_rotation(*destination, pages.at(page)); + }); + } + + inline int docling_editor::duplicate_page(int page, std::int64_t expected_generation, int at) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation, at]() -> int { + check_generation(expected_generation); + ensure_destination(); + + QPDFPageDocumentHelper helper(*destination); + std::vector pages = helper.getAllPages(); + int number_of_pages = static_cast(pages.size()); + + check_page(page, number_of_pages); + + bool at_end = false; + int position = insertion_position(at, number_of_pages, at_end); + + QPDFPageObjectHelper original = pages.at(page); + + // A new page object sharing the original's content and resources; an + // edit of either page then replaces what it changes on that page only. + QPDFPageObjectHelper copy = original.shallowCopyPage(); + + touch(not at_end); + + if(at_end) + { + helper.addPage(copy, false); + } + else + { + helper.addPageAt(copy, true, pages.at(position)); + } + + // The copy's /Annots still lists the original's annotation objects. + // Give it annotations and form fields of its own, as qpdf does for a + // page that appears twice in an assembled document. + QPDFObjectHandle annots = original.getObjectHandle().getKey("/Annots"); + if(annots.isArray() and annots.getArrayNItems() > 0) + { + QPDFAcroFormDocumentHelper acroform(*destination); + acroform.fixCopiedAnnotations(copy.getObjectHandle(), + original.getObjectHandle(), + acroform); + } + + return position; + }); + } + + inline void docling_editor::remove_page(int page, std::int64_t expected_generation, bool clean) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, clean]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + touch(true); + pdflib::pdf_navigation_ops::drop_destinations_to(*destination, + pages.at(page).getObjectHandle().getObjGen()); + // Bookmarks and an open action leading to the page would otherwise + // keep it in the file, unreachable and unlisted. + pdflib::pdf_outline_ops::drop_destinations_to(*destination, + pages.at(page).getObjectHandle().getObjGen()); + + QPDFPageDocumentHelper(*destination).removePage(pages.at(page)); + if(clean) + { + destination->replaceObject(pages.at(page).getObjectHandle().getObjGen(), QPDFObjectHandle::newNull()); + } + }); + } + + inline void docling_editor::move_page(int from, int to, std::int64_t expected_generation) + { + std::lock_guard lock(parser_mutex); + + guarded([this, from, to, expected_generation]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + int number_of_pages = static_cast(pages.size()); + + check_page(from, number_of_pages); + check_page(to, number_of_pages); + + if(from == to) + { + return; + } + + touch(true); + + QPDFPageDocumentHelper helper(*destination); + QPDFPageObjectHelper page = pages.at(from); + + // `to` is the index the page has afterwards: take it out, then put it + // back in front of whichever page now sits there. + helper.removePage(page); + + std::vector remaining = helper.getAllPages(); + if(to >= static_cast(remaining.size())) + { + helper.addPage(page, false); + } + else + { + helper.addPageAt(page, true, remaining.at(to)); + } + }); + } + + inline void docling_editor::rotate_page(int page, + std::int64_t expected_generation, + int angle, + bool relative) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, angle, relative]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + pdflib::pdf_page_ops::rotate(pages.at(page), angle, relative); + touch(false); + }); + } + + inline void docling_editor::set_page_box(int page, + std::int64_t expected_generation, + std::string box, + std::array rectangle) + { + std::lock_guard lock(parser_mutex); + + guarded([this, page, expected_generation, &box, &rectangle]() { + check_generation(expected_generation); + ensure_destination(); + + std::vector pages = destination_pages(); + check_page(page, static_cast(pages.size())); + + pdflib::pdf_page_ops::set_box(pages.at(page), box, rectangle); + touch(false); + }); + } + + inline int docling_editor::insert_blank_page(int at, double width, double height) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, at, width, height]() -> int { + ensure_destination(); + + QPDFPageDocumentHelper helper(*destination); + std::vector pages = helper.getAllPages(); + int number_of_pages = static_cast(pages.size()); + + bool at_end = false; + int position = insertion_position(at, number_of_pages, at_end); + + QPDFPageObjectHelper page(pdflib::pdf_page_ops::make_blank_page(*destination, width, height)); + + // Appending leaves every existing index as it was; inserting does not. + touch(not at_end); + + if(at_end) + { + helper.addPage(page, false); + } + else + { + helper.addPageAt(page, true, pages.at(position)); + } + + return position; + }); + } + + inline int docling_editor::append_pages(const pdflib::pdf_source& other, + std::optional > pages, + int at, + bool import_outline) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, &other, &pages, at, import_outline]() -> int { + if(not other.is_valid()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "the document to import from is not open"); + } + + ensure_destination(); + + import_document_ptr_type import = find_or_create_import(other); + std::vector import_pages = import->get_pages(); + int number_of_import_pages = static_cast(import_pages.size()); + + std::vector selection; + if(pages.has_value()) + { + selection = pages.value(); + } + else + { + for(int index = 0; index < number_of_import_pages; index++) + { + selection.push_back(index); + } + } + + for(int index : selection) + { + check_page(index, number_of_import_pages); + } + + QPDFPageDocumentHelper helper(*destination); + int number_of_pages = static_cast(helper.getAllPages().size()); + + bool at_end = false; + int first = insertion_position(at, number_of_pages, at_end); + + if(selection.empty()) + { + return first; + } + + // Before the first change: a failure half way must still invalidate + // the snapshot and, when inserting, the page handles. + touch(not at_end); + + // One helper for the whole call, as qpdf's own page assembly does; its + // constructor walks every form field of the destination. + std::unique_ptr destination_acroform = nullptr; + + std::map page_map; + + int position = first; + for(int index : selection) + { + QPDFPageObjectHelper import_page = import_pages.at(index); + + // where this page of the other document ends up here; a page + // copied twice is found at its first copy + page_map.emplace(import_page.getObjectHandle().getObjGen(), position); + + // qpdf copies a page of another QPDF into this one, and makes a + // shallow copy when the same page is added a second time. + std::vector current = helper.getAllPages(); + if(position >= static_cast(current.size())) + { + helper.addPage(import_page, false); + } + else + { + helper.addPageAt(import_page, true, current.at(position)); + } + + // Widgets were copied with the page, but their fields still belong + // to the other document's /AcroForm. Same repair, and same guard, + // as pdf_decoder::get_thread_safe_page_buffer. + QPDFObjectHandle annots = import_page.getObjectHandle().getKey("/Annots"); + if(annots.isArray() and annots.getArrayNItems() > 0) + { + if(destination_acroform == nullptr) + { + destination_acroform = std::make_unique(*destination); + } + + QPDFPageObjectHelper new_page = helper.getAllPages().at(position); + destination_acroform->fixCopiedAnnotations(new_page.getObjectHandle(), + import_page.getObjectHandle(), + import->get_acroform()); + } + + position += 1; + } + + if(import_outline) + { + pdflib::pdf_outline_ops::import(*destination, import->get_qpdf(), page_map, 0); + } + + return first; + }); + } + + inline std::optional docling_editor::snapshot_password() const + { + if(output_encrypted and not output_user_password.empty()) + { + return output_user_password; + } + + return std::nullopt; + } + + inline void docling_editor::set_encryption(std::string user_password, + std::string owner_password, + pdflib::pdf_permissions permissions, + std::string algorithm) + { + std::lock_guard lock(parser_mutex); + + guarded([this, &user_password, &owner_password, &permissions, &algorithm]() { + const std::set algorithms = {"RC4-40", "RC4-128", "AES-128", "AES-256-R5", "AES-256"}; + if(algorithms.count(algorithm) == 0) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, "unknown encryption algorithm: " + algorithm); + } + if(permissions.get_print() < 0 or permissions.get_print() > 2) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "the print permission is 0 (full), 1 (low resolution) or 2 (none)"); + } + + if(user_password.empty() and owner_password.empty()) + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "encryption needs a user password, an owner password, or both"); + } + + ensure_destination(); + + output_encrypted = true; + output_algorithm = algorithm; + output_user_password = user_password; + output_owner_password = owner_password.empty() ? user_password : owner_password; + output_permissions = permissions; + + touch(false); + }); + } + + inline void docling_editor::clear_encryption() + { + std::lock_guard lock(parser_mutex); + + guarded([this]() { + ensure_destination(); + + output_encrypted = false; + output_user_password.clear(); + output_owner_password.clear(); + + touch(false); + }); + } + + inline std::shared_ptr docling_editor::write_to_memory() + { + std::lock_guard lock(parser_mutex); + + return guarded([this]() { + ensure_snapshot(); + return snapshot; + }); + } + + inline void docling_editor::write_to_file(std::string filename) + { + // The bytes are immutable once produced, so the file is written without + // the lock: a slow disk does not stall other threads using this editor. + std::shared_ptr bytes = write_to_memory(); + + std::filesystem::path target = to_path(filename); + std::filesystem::path temporary = to_path(filename + ".tmp-" + random_suffix()); + + try + { + { + std::ofstream stream(temporary, std::ios::binary | std::ios::trunc); + if(not stream.is_open()) + { + throw std::runtime_error("could not open " + filename + " for writing"); + } + + stream.write(bytes->data(), static_cast(bytes->size())); + stream.close(); + + if(stream.fail()) + { + throw std::runtime_error("could not write " + filename); + } + } + + std::filesystem::rename(temporary, target); + } + catch(const std::exception& exc) + { + std::error_code ignored; + std::filesystem::remove(temporary, ignored); + + throw pdflib::pdf_edit_error(pdflib::edit_error::WRITE, exc.what()); + } + } + + // --------------------------------------------------------------------------- + // Document-level content: thin, locked entry points over src/edit/*_ops.h + // --------------------------------------------------------------------------- + + inline nlohmann::json docling_editor::document_settings() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_catalog_ops::read_settings(qpdf); + }); + } + + inline std::vector docling_editor::page_labels() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_catalog_ops::page_labels(qpdf); + }); + } + + inline nlohmann::json docling_editor::named_destinations() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_catalog_ops::named_destinations(qpdf); + }); + } + + inline nlohmann::json docling_editor::outline_tree() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_outline_ops::read(qpdf); + }); + } + + inline nlohmann::json docling_editor::form() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_form_ops::read(qpdf); + }); + } + + inline nlohmann::json docling_editor::page_annotations(int page, std::int64_t expected_generation) + { + std::lock_guard lock(parser_mutex); + + return guarded([this, page, expected_generation]() { + check_generation(expected_generation); + + return with_document([this, page](QPDF& qpdf) { + std::vector pages = QPDFPageDocumentHelper(qpdf).getAllPages(); + check_page(page, static_cast(pages.size())); + + return pdflib::pdf_annotation_ops::read(qpdf, pages.at(page)); + }); + }); + } + + inline nlohmann::json docling_editor::attachments() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_attachment_ops::read(qpdf); + }); + } + + inline std::string docling_editor::attachment_data(std::string name) + { + return read_document([&name](QPDF& qpdf) { + return pdflib::pdf_attachment_ops::data(qpdf, name); + }); + } + + inline nlohmann::json docling_editor::javascript() + { + return read_document([](QPDF& qpdf) { + return pdflib::pdf_attachment_ops::javascript(qpdf); + }); + } + + inline void docling_editor::set_info(std::map > entries) + { + edit_document([&entries](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_info(qpdf, entries); + }); + } + + inline void docling_editor::set_xmp(std::optional packet) + { + edit_document([&packet](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_xmp(qpdf, packet); + }); + } + + inline void docling_editor::set_page_layout(std::string name) + { + edit_document([&name](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_page_layout(qpdf, name); + }); + } + + inline void docling_editor::set_page_mode(std::string name) + { + edit_document([&name](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_page_mode(qpdf, name); + }); + } + + inline void docling_editor::set_viewer_preferences(std::string dictionary) + { + edit_document([&dictionary](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_viewer_preferences(qpdf, dictionary); + }); + } + + inline void docling_editor::set_open_destination(int page) + { + edit_document([page](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_open_destination(qpdf, page); + }); + } + + inline void docling_editor::set_page_label(int from, + int to, + std::string style, + std::string prefix, + int start) + { + edit_document([from, to, &style, &prefix, start](QPDF& qpdf) { + pdflib::pdf_catalog_ops::set_page_label(qpdf, from, to, style, prefix, start); + }); + } + + inline void docling_editor::add_named_destination(std::string name, int page) + { + edit_document([&name, page](QPDF& qpdf) { + pdflib::pdf_catalog_ops::add_named_destination(qpdf, name, page); + }); + } + + inline int docling_editor::add_outline_item(std::string title, int page, int parent) + { + return edit_document([&title, page, parent](QPDF& qpdf) { + return pdflib::pdf_outline_ops::add_item(qpdf, title, page, parent); + }); + } + + inline int docling_editor::set_form_values(std::map values) + { + return edit_document([&values](QPDF& qpdf) { + return pdflib::pdf_form_ops::set_values(qpdf, values); + }); + } + + inline void docling_editor::set_need_appearances(bool value) + { + edit_document([value](QPDF& qpdf) { + pdflib::pdf_form_ops::set_need_appearances(qpdf, value); + }); + } + + inline void docling_editor::flatten_annotations() + { + edit_document([](QPDF& qpdf) { + pdflib::pdf_form_ops::flatten(qpdf); + }); + } + + inline void docling_editor::add_annotation(int page, + std::int64_t expected_generation, + std::string dictionary) + { + edit_page(page, expected_generation, [&dictionary](QPDF& qpdf, QPDFPageObjectHelper target) { + pdflib::pdf_annotation_ops::add(qpdf, target, dictionary); + }); + } + + inline void docling_editor::add_page_link(int page, + std::int64_t expected_generation, + std::array rectangle, + int target) + { + edit_page(page, expected_generation, [&rectangle, target](QPDF& qpdf, QPDFPageObjectHelper source) { + pdflib::pdf_annotation_ops::add_page_link(qpdf, source, rectangle, target); + }); + } + + inline int docling_editor::remove_annotations(int page, + std::int64_t expected_generation, + std::set subtypes) + { + return edit_page(page, expected_generation, [&subtypes](QPDF& qpdf, QPDFPageObjectHelper target) { + return pdflib::pdf_annotation_ops::remove(qpdf, target, subtypes); + }); + } + + inline void docling_editor::add_attachment(std::string name, + std::string bytes, + std::string description, + std::string mime_type) + { + edit_document([&name, &bytes, &description, &mime_type](QPDF& qpdf) { + pdflib::pdf_attachment_ops::add(qpdf, name, bytes, description, mime_type); + }); + } + + inline bool docling_editor::remove_attachment(std::string name) + { + return edit_document([&name](QPDF& qpdf) { + return pdflib::pdf_attachment_ops::remove(qpdf, name); + }); + } + + inline void docling_editor::add_javascript(std::string name, std::string script) + { + edit_document([&name, &script](QPDF& qpdf) { + pdflib::pdf_attachment_ops::add_javascript(qpdf, name, script); + }); + } + + inline int docling_editor::remove_javascript() + { + return edit_document([](QPDF& qpdf) { + return pdflib::pdf_attachment_ops::remove_javascript(qpdf); + }); + } + + inline void docling_editor::set_output_options(bool compress_streams, + std::string object_streams, + bool linearize) + { + std::lock_guard lock(parser_mutex); + + guarded([this, compress_streams, &object_streams, linearize]() { + qpdf_object_stream_e mode = qpdf_o_preserve; + if(object_streams == "generate") { mode = qpdf_o_generate; } + else if(object_streams == "disable") { mode = qpdf_o_disable; } + else if(object_streams != "preserve") + { + throw pdflib::pdf_edit_error(pdflib::edit_error::INVALID_EDIT, + "object_streams is 'preserve', 'generate' or 'disable'"); + } + + ensure_destination(); + + output_compress_streams = compress_streams; + output_object_streams = mode; + output_linearize = linearize; + + touch(false); + }); + } + + inline int docling_editor::insert_image_page(int at, + int width, + int height, + std::string colorspace, + std::string data, + bool is_jpeg, + bool invert, + std::string alpha, + double page_width, + double page_height, + std::array placement, + int rotate) + { + std::lock_guard lock(parser_mutex); + + return guarded([&]() -> int { + ensure_destination(); + + QPDFPageDocumentHelper helper(*destination); + std::vector pages = helper.getAllPages(); + int number_of_pages = static_cast(pages.size()); + + bool at_end = false; + int position = insertion_position(at, number_of_pages, at_end); + + // built, and so checked, before the page list changes + QPDFPageObjectHelper page(pdflib::pdf_page_ops::make_image_page(*destination, + width, + height, + colorspace, + data, + is_jpeg, + invert, + alpha, + page_width, + page_height, + placement, + rotate)); + + touch(not at_end); + + if(at_end) + { + helper.addPage(page, false); + } + else + { + helper.addPageAt(page, true, pages.at(position)); + } + + return position; + }); + } + + inline void docling_editor::draw_text(int page, + std::int64_t expected_generation, + std::string text, + double x, + double y, + double size, + std::string font, + std::array color) + { + edit_page(page, expected_generation, [&](QPDF& qpdf, QPDFPageObjectHelper target) { + auto itr = standard_fonts.find(font); + if(itr == standard_fonts.end()) + { + itr = standard_fonts.emplace(font, pdflib::pdf_page_ops::make_standard_font(qpdf, font)).first; + } + + pdflib::pdf_page_ops::draw_text(qpdf, target, itr->second, text, x, y, size, color); + }); + } + + inline int docling_editor::add_outline_entry(nlohmann::json spec) + { + return edit_document([&spec](QPDF& qpdf) { + return pdflib::pdf_outline_ops::add_item(qpdf, spec); + }); + } + + inline void docling_editor::update_outline_item(int id, nlohmann::json changes) + { + edit_document([id, &changes](QPDF& qpdf) { + pdflib::pdf_outline_ops::update_item(qpdf, id, changes); + }); + } + + inline void docling_editor::remove_outline_item(int id) + { + edit_document([id](QPDF& qpdf) { + pdflib::pdf_outline_ops::remove_item(qpdf, id); + }); + } + + inline void docling_editor::move_outline_item(int id, int parent, int index) + { + edit_document([id, parent, index](QPDF& qpdf) { + pdflib::pdf_outline_ops::move_item(qpdf, id, parent, index); + }); + } + + inline void docling_editor::clear_outline() + { + edit_document([](QPDF& qpdf) { + pdflib::pdf_outline_ops::clear(qpdf); + }); + } + + inline void docling_editor::add_form_field(int page, + std::int64_t expected_generation, + nlohmann::json spec) + { + edit_page(page, expected_generation, [&spec](QPDF& qpdf, QPDFPageObjectHelper target) { + pdflib::pdf_form_ops::add_field(qpdf, target, spec); + }); + } + + inline void docling_editor::update_form_field(std::string name, nlohmann::json changes) + { + edit_document([&name, &changes](QPDF& qpdf) { + pdflib::pdf_form_ops::update_field(qpdf, name, changes); + }); + } + + inline void docling_editor::remove_form_field(std::string name) + { + edit_document([&name](QPDF& qpdf) { + pdflib::pdf_form_ops::remove_field(qpdf, name); + }); + } + +} + +#endif diff --git a/src/pybind/docling_parser.h b/src/pybind/docling_parser.h index 04bcb0f13..f92d3adc2 100644 --- a/src/pybind/docling_parser.h +++ b/src/pybind/docling_parser.h @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include @@ -48,6 +49,13 @@ namespace docling std::optional password, bool keep_qpdf_warnings = false); + // Load from bytes already owned by native code. Needs no Python object, + // so it may be called with the GIL released. + bool load_document_from_buffer(std::string key, + std::shared_ptr buffer, + std::optional password, + bool keep_qpdf_warnings = false); + bool unload_document(std::string key); bool unload_document_pages(std::string key); bool unload_document_page(std::string key, int page_num); @@ -65,11 +73,7 @@ namespace docling // Snapshot ownership while Python holds the GIL, before a binding releases // it for immutable/lazy document reads. Unload can then remove the map entry // without destroying an in-flight decoder. - doc_decoder_ptr_type get_document_decoder(const std::string& key) - { - auto it = doc_decoders.find(key); - return it == doc_decoders.end() ? nullptr : it->second; - } + doc_decoder_ptr_type get_document_decoder(const std::string& key); nlohmann::json get_meta_xml(std::string key); nlohmann::json get_table_of_contents(std::string key); @@ -98,7 +102,14 @@ namespace docling void remove_page_decoder(const std::string& key, int page); void trim_page_decoders(); - private: + protected: + + // Thread safety: every public method takes parser_mutex around its access + // to the members below, so one parser may be shared between threads. The + // mutex is recursive because docling_editor calls these methods while it + // already holds it. docling_parser itself never holds it across a page + // decode, and nothing may wait for the Python GIL while holding it. + mutable std::recursive_mutex parser_mutex; std::string pdf_resources_dir; @@ -156,8 +167,18 @@ namespace docling } } + docling_parser::doc_decoder_ptr_type docling_parser::get_document_decoder(const std::string& key) + { + std::lock_guard lock(parser_mutex); + + auto it = doc_decoders.find(key); + return it == doc_decoders.end() ? nullptr : it->second; + } + std::vector docling_parser::list_loaded_keys() { + std::lock_guard lock(parser_mutex); + std::vector keys={}; // Add the key (which is the first element of the pair) @@ -171,11 +192,15 @@ namespace docling bool docling_parser::is_loaded(std::string key) { + std::lock_guard lock(parser_mutex); + return (doc_decoders.count(key)==1); } std::map docling_parser::take_load_error(std::string key) { + std::lock_guard lock(parser_mutex); + std::map result; auto itr = load_errors.find(key); @@ -192,6 +217,8 @@ namespace docling const std::string& category, const std::string& message) { + std::lock_guard lock(parser_mutex); + load_errors[key] = {{"category", category}, {"message", message}}; } @@ -200,7 +227,10 @@ namespace docling std::optional password, bool keep_qpdf_warnings) { - load_errors.erase(key); + { + std::lock_guard lock(parser_mutex); + load_errors.erase(key); + } #ifdef _WIN32 // Convert UTF-8 string to UTF-16 wstring @@ -213,24 +243,30 @@ namespace docling if (std::filesystem::exists(path_filename)) { + // Read and parse outside parser_mutex: the new decoder is not visible + // to any other thread until it is registered below. + auto doc_decoder = std::make_shared(); + bool success = doc_decoder->process_document_from_file(filename, + password, + keep_qpdf_warnings); + + std::lock_guard lock(parser_mutex); + remove_page_decoders(key); - doc_decoders[key] = std::make_shared(); - bool success = doc_decoders.at(key)->process_document_from_file(filename, - password, - keep_qpdf_warnings); if(not success) { // do not keep a decoder that never parsed the document: it would // report is_loaded()=true and a number_of_pages of -1 record_load_error(key, - doc_decoders.at(key)->get_load_error_category(), - doc_decoders.at(key)->get_load_error_message()); + doc_decoder->get_load_error_category(), + doc_decoder->get_load_error_message()); doc_decoders.erase(key); LOG_S(ERROR) << "could not process document for key=" << key; return false; } + doc_decoders[key] = doc_decoder; return true; } @@ -253,7 +289,8 @@ namespace docling throw std::runtime_error("Expected a BytesIO object"); } - load_errors.erase(key); + // The Python calls below need the GIL, so they run before parser_mutex is + // taken: a thread must never wait for the GIL while holding that mutex. // Seek to the beginning of the BytesIO stream bytes_io.attr("seek")(0); @@ -264,32 +301,60 @@ namespace docling // Get the data into a shared buffer auto data_buffer = std::make_shared(data.cast()); + return load_document_from_buffer(key, data_buffer, password, keep_qpdf_warnings); + } + + bool docling_parser::load_document_from_buffer(std::string key, + std::shared_ptr buffer, + std::optional password, + bool keep_qpdf_warnings) + { + { + std::lock_guard lock(parser_mutex); + load_errors.erase(key); + } + + if(buffer == nullptr) + { + record_load_error(key, pdflib::load_error::IO, "no buffer provided"); + return false; + } + + auto doc_decoder = std::make_shared(); + try { + // Parse outside parser_mutex: the new decoder is not visible to any + // other thread until it is registered below. + std::string description = "parsing of " + key + " from bytesio"; + bool success = doc_decoder->process_document_from_bytesio(buffer, + password, + description, + keep_qpdf_warnings); + + std::lock_guard lock(parser_mutex); + remove_page_decoders(key); - doc_decoders[key] = std::make_shared(); - std::string description = "parsing of " + key + " from bytesio"; - bool success = doc_decoders.at(key)->process_document_from_bytesio(data_buffer, - password, - description, - keep_qpdf_warnings); if(not success) { // do not keep a decoder that never parsed the document: it would // report is_loaded()=true and a number_of_pages of -1 record_load_error(key, - doc_decoders.at(key)->get_load_error_category(), - doc_decoders.at(key)->get_load_error_message()); + doc_decoder->get_load_error_category(), + doc_decoder->get_load_error_message()); doc_decoders.erase(key); LOG_S(ERROR) << "could not decode bytesio object for key="< lock(parser_mutex); + record_load_error(key, pdflib::load_error::UNKNOWN, exc.what()); doc_decoders.erase(key); LOG_S(ERROR) << "could not decode bytesio object for key="< lock(parser_mutex); + if(doc_decoders.count(key)==1) { doc_decoders.erase(key); @@ -321,6 +388,8 @@ namespace docling bool docling_parser::unload_document_page(std::string key, int page_num) { + std::lock_guard lock(parser_mutex); + auto itr = doc_decoders.find(key); if(itr!=doc_decoders.end()) @@ -339,6 +408,8 @@ namespace docling bool docling_parser::unload_document_pages(std::string key) { + std::lock_guard lock(parser_mutex); + auto itr = doc_decoders.find(key); if(itr!=doc_decoders.end()) @@ -357,6 +428,8 @@ namespace docling void docling_parser::unload_documents() { + std::lock_guard lock(parser_mutex); + doc_decoders.clear(); page_decoders.clear(); total_processed_pages.store(0); @@ -426,6 +499,8 @@ namespace docling int docling_parser::number_of_pages(std::string key) { + std::lock_guard lock(parser_mutex); + auto itr = doc_decoders.find(key); if(itr!=doc_decoders.end()) @@ -444,45 +519,51 @@ namespace docling { LOG_S(INFO) << __FUNCTION__; - auto itr = doc_decoders.find(key); + // The decoder serializes its own lazy reads, so parser_mutex only covers + // the lookup. + doc_decoder_ptr_type doc_decoder = get_document_decoder(key); - if(itr==doc_decoders.end()) + if(doc_decoder==nullptr) { LOG_S(ERROR) << "key not found: " << key; return nlohmann::json::value_t::null; } - return (itr->second)->get_annotations(); + return doc_decoder->get_annotations(); } nlohmann::json docling_parser::get_meta_xml(std::string key) { LOG_S(INFO) << __FUNCTION__; - auto itr = doc_decoders.find(key); + // The decoder serializes its own lazy reads, so parser_mutex only covers + // the lookup. + doc_decoder_ptr_type doc_decoder = get_document_decoder(key); - if(itr==doc_decoders.end()) + if(doc_decoder==nullptr) { LOG_S(ERROR) << "key not found: " << key; return nlohmann::json::value_t::null; } - return (itr->second)->get_meta_xml(); + return doc_decoder->get_meta_xml(); } nlohmann::json docling_parser::get_table_of_contents(std::string key) { LOG_S(INFO) << __FUNCTION__; - auto itr = doc_decoders.find(key); + // The decoder serializes its own lazy reads, so parser_mutex only covers + // the lookup. + doc_decoder_ptr_type doc_decoder = get_document_decoder(key); - if(itr==doc_decoders.end()) + if(doc_decoder==nullptr) { LOG_S(ERROR) << "key not found: " << key; return nlohmann::json::value_t::null; } - return (itr->second)->get_table_of_contents(); + return doc_decoder->get_table_of_contents(); } std::shared_ptr> docling_parser::get_page_decoder(std::string key, @@ -491,20 +572,29 @@ namespace docling { LOG_S(INFO) << __FUNCTION__ << " for key: " << key << " and page: " << page; - auto itr = doc_decoders.find(key); - if(itr == doc_decoders.end()) - { - LOG_S(ERROR) << "key not found: " << key; - return nullptr; - } - - auto cached_page_decoder = find_page_decoder(key, page); - if(cached_page_decoder != nullptr) - { - return cached_page_decoder; - } + doc_decoder_ptr_type doc_decoder = nullptr; + { + std::lock_guard lock(parser_mutex); + + auto itr = doc_decoders.find(key); + if(itr == doc_decoders.end()) + { + LOG_S(ERROR) << "key not found: " << key; + return nullptr; + } + + auto cached_page_decoder = find_page_decoder(key, page); + if(cached_page_decoder != nullptr) + { + return cached_page_decoder; + } + + doc_decoder = itr->second; + } - auto& doc_decoder = itr->second; + // The decode runs without parser_mutex: it works on a standalone one-page + // copy that the document decoder hands out under its own mutex, so threads + // sharing this parser still decode different pages in parallel. auto page_decoder = doc_decoder->make_thread_safe_page_decoder( page, config.keep_qpdf_warnings); @@ -520,7 +610,28 @@ namespace docling page_decoder->create_line_cells(config); } - add_page_decoder(key, page, page_decoder); + { + std::lock_guard lock(parser_mutex); + + auto itr = doc_decoders.find(key); + if(itr != doc_decoders.end() and itr->second == doc_decoder) + { + // Another thread may have decoded the same page meanwhile; its + // result is already shared, so ours is dropped. + auto cached_page_decoder = find_page_decoder(key, page); + if(cached_page_decoder != nullptr) + { + page_decoder = cached_page_decoder; + } + else + { + add_page_decoder(key, page, page_decoder); + } + } + // else: the document was unloaded or replaced during the decode; the + // result is returned to this caller but not cached under the key. + } + maybe_release_native_memory(config); return page_decoder; } diff --git a/src/pybind/edit_bindings.h b/src/pybind/edit_bindings.h new file mode 100644 index 000000000..19a26bc0c --- /dev/null +++ b/src/pybind/edit_bindings.h @@ -0,0 +1,1029 @@ +//-*-C++-*- + +#ifndef PYBIND_EDIT_BINDINGS_H +#define PYBIND_EDIT_BINDINGS_H + +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include + +#include + +#include +#include +#include + +// Python bindings of docling_editor, pdf_reader and pdf_writer. +// +// The three classes are bound as unrelated Python types: pdf_reader and +// pdf_writer hide their base on purpose, so there is no Python inheritance to +// declare. The binding functions are templates over the bound class, which is +// what keeps one definition per operation. +// +// Every binding converts its arguments with the GIL held, releases the GIL for +// the native call, and builds the Python result after taking it back. Native +// code therefore never waits for the GIL while it holds the editor's mutex. + +namespace docling +{ + namespace edit_bindings + { + inline pybind11::tuple box_to_tuple(const pdflib::pdf_page_info::box_type& box) + { + return pybind11::make_tuple(box[0], box[1], box[2], box[3]); + } + + inline pybind11::dict document_info_to_dict(const pdflib::pdf_document_info& info) + { + pybind11::dict result; + + result["pdf_version"] = info.get_pdf_version(); + result["extension_level"] = info.get_extension_level(); + result["number_of_pages"] = info.get_number_of_pages(); + + pybind11::dict entries; + for(const auto& entry : info.get_info()) + { + entries[pybind11::str(entry.first)] = pybind11::str(entry.second); + } + result["info"] = entries; + + if(info.get_xmp().has_value()) + { + // XMP is a byte stream whose encoding its own header declares. + result["xmp"] = pybind11::bytes(info.get_xmp().value()); + } + else + { + result["xmp"] = pybind11::none(); + } + + const pdflib::pdf_encryption_info& encryption = info.get_encryption(); + if(encryption.is_encrypted()) + { + pybind11::dict values; + values["revision"] = encryption.get_revision(); + values["version"] = encryption.get_version(); + values["permissions"] = encryption.get_permissions(); + values["stream_method"] = encryption.get_stream_method(); + values["string_method"] = encryption.get_string_method(); + values["file_method"] = encryption.get_file_method(); + result["encryption"] = values; + } + else + { + result["encryption"] = pybind11::none(); + } + + return result; + } + + inline pybind11::dict page_info_to_dict(const pdflib::pdf_page_info& info) + { + pybind11::dict result; + + result["media_box"] = box_to_tuple(info.get_media_box()); + result["crop_box"] = box_to_tuple(info.get_crop_box()); + result["bleed_box"] = box_to_tuple(info.get_bleed_box()); + result["trim_box"] = box_to_tuple(info.get_trim_box()); + result["art_box"] = box_to_tuple(info.get_art_box()); + + result["rotation"] = info.get_rotation(); + result["user_unit"] = info.get_user_unit(); + + return result; + } + + inline pybind11::list images_to_list(const std::vector& images) + { + pybind11::list result; + + for(const pdflib::pdf_exported_image& image : images) + { + pybind11::dict item; + + item["name"] = image.get_name(); + item["bbox"] = box_to_tuple(image.get_bbox()); + item["width"] = image.get_width(); + item["height"] = image.get_height(); + item["format"] = image.get_format(); + item["mode"] = image.get_mode(); + + const std::vector& data = image.get_data(); + item["data"] = pybind11::bytes(reinterpret_cast(data.data()), data.size()); + + result.append(item); + } + + return result; + } + + // Lifecycle and inspection: bound on all three classes. + template + void bind_inspection(pybind11::class_& cls) + { + cls + .def(pybind11::init(), + pybind11::arg("loglevel") = "fatal") + + .def("open_file", + [](class_type& self, const std::string& filename, std::optional password) -> bool { + pybind11::gil_scoped_release release; + return self.open_file(filename, password); + }, + pybind11::arg("filename"), + pybind11::arg("password") = pybind11::none(), + "Open a PDF file. Returns False on failure; see take_open_error().") + + .def("open_bytes", + [](class_type& self, pybind11::bytes data, std::optional password) -> bool { + auto buffer = std::make_shared(data.cast()); + + pybind11::gil_scoped_release release; + return self.open_buffer(buffer, password); + }, + pybind11::arg("data"), + pybind11::arg("password") = pybind11::none(), + "Open a PDF held in a bytes object. Returns False on failure; see take_open_error().") + + .def("take_open_error", + [](class_type& self) -> std::map { + return self.take_open_error(); + }, + "Return and clear why the last open failed: {'category': ..., 'message': ...}.") + + .def("is_open", [](class_type& self) -> bool { return self.is_open(); }) + + .def("close", + [](class_type& self) -> void { + pybind11::gil_scoped_release release; + self.close(); + }) + + .def("page_count", + [](class_type& self) -> int { + pybind11::gil_scoped_release release; + return self.page_count(); + }) + + .def("generation", + [](class_type& self) -> std::int64_t { return self.generation(); }, + "Changes whenever existing page indices may have changed meaning.") + + .def("document_info", + [](class_type& self) -> pybind11::dict { + pdflib::pdf_document_info info; + { + pybind11::gil_scoped_release release; + info = self.document_info(); + } + return document_info_to_dict(info); + }) + + .def("page_info", + [](class_type& self, int page, std::int64_t generation) -> pybind11::dict { + pdflib::pdf_page_info info; + { + pybind11::gil_scoped_release release; + info = self.page_info(page, generation); + } + return page_info_to_dict(info); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION) + + .def("validate_strict", [](class_type& self) { + pybind11::gil_scoped_release release; + self.validate_strict(); + }) + + .def("extract_text", + [](class_type& self, int page, std::int64_t generation, bool layout) -> std::string { + pybind11::gil_scoped_release release; + return self.extract_text(page, generation, layout); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + pybind11::arg("layout") = false) + + .def("page_images", + [](class_type& self, int page, std::int64_t generation) -> pybind11::list { + std::vector images; + { + pybind11::gil_scoped_release release; + images = self.page_images(page, generation); + } + return images_to_list(images); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "The images the page draws, in drawing order, each as a dict with its bytes.") + + .def("document_settings", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.document_settings(); + } + return pyjson::from_json(result); + }, + "Page layout, page mode, viewer preferences and open destination.") + + .def("page_labels", + [](class_type& self) -> std::vector { + pybind11::gil_scoped_release release; + return self.page_labels(); + }, + "The label of every page, as a viewer shows it.") + + .def("named_destinations", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.named_destinations(); + } + return pyjson::from_json(result); + }, + "Named destinations: {name: {page, kind, arguments}}.") + + .def("outline_tree", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.outline_tree(); + } + return pyjson::from_json(result); + }, + "The outline as [{id, title, page, children}].") + + .def("form", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.form(); + } + return pyjson::from_json(result); + }, + "The interactive form: flags and fields.") + + .def("page_annotations", + [](class_type& self, int page, std::int64_t generation) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.page_annotations(page, generation); + } + return pyjson::from_json(result); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "The annotations of a page, one dict each.") + + .def("attachments", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.attachments(); + } + return pyjson::from_json(result); + }, + "Embedded files: [{name, filename, description, size, ...}].") + + .def("attachment_data", + [](class_type& self, const std::string& name) -> pybind11::bytes { + std::string data; + { + pybind11::gil_scoped_release release; + data = self.attachment_data(name); + } + return pybind11::bytes(data); + }, + pybind11::arg("name"), + "The bytes of one embedded file.") + + .def("javascript", + [](class_type& self) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.javascript(); + } + return pyjson::from_json(result); + }, + "Document-level scripts: {name: script}.") + + .def("outline", + [](class_type& self) -> pybind11::object { + nlohmann::json outline; + { + pybind11::gil_scoped_release release; + outline = self.outline(); + } + return pyjson::from_json(outline); + }); + } + + // open_source(other): one overload per kind of document that can be read + // from. The other document only hands over its immutable bytes. + template + void bind_open_source(pybind11::class_& cls) + { + cls.def("open_source", + [](class_type& self, other_type& other) -> bool { + pybind11::gil_scoped_release release; + return self.open_source(other.get_source()); + }, + pybind11::arg("other"), + "Open the document another reader, writer or editor currently holds."); + } + + template + void bind_append_pages(pybind11::class_& cls) + { + cls.def("append_pages", + [](class_type& self, + other_type& other, + std::optional > pages, + int at, + std::int64_t other_generation, + bool import_outline) -> int { + pybind11::gil_scoped_release release; + return self.append_pages(other.get_source(other_generation), + pages, + at, + import_outline); + }, + pybind11::arg("other"), + pybind11::arg("pages") = pybind11::none(), + pybind11::arg("at") = -1, + pybind11::arg("other_generation") = other_type::ANY_GENERATION, + pybind11::arg("import_outline") = false, + "Copy pages of another document into this one. Returns the index of the first new page."); + } + + // overlay_page(page, other, other_page, ...): one overload per kind of + // document the overlaid page can come from. + template + void bind_overlay_page(pybind11::class_& cls) + { + cls.def("overlay_page", + [](class_type& self, + int page, + other_type& other, + int other_page, + bool under, + bool fit, + std::array matrix, + std::int64_t generation, + std::int64_t other_generation) -> void { + pybind11::gil_scoped_release release; + self.overlay_page(page, + generation, + other.get_source(other_generation), + other_page, + under, + fit, + matrix); + }, + pybind11::arg("page"), + pybind11::arg("other"), + pybind11::arg("other_page"), + pybind11::arg("under") = false, + pybind11::arg("fit") = false, + pybind11::arg("matrix") = std::array{1.0, 0.0, 0.0, 1.0, 0.0, 0.0}, + pybind11::arg("generation") = class_type::ANY_GENERATION, + pybind11::arg("other_generation") = other_type::ANY_GENERATION, + "Draw a page of another document on this page, above or below its content."); + } + + // Editing and output: bound on the writer and the editor. + template + void bind_editing(pybind11::class_& cls) + { + cls + .def("create_empty", + [](class_type& self) -> void { + pybind11::gil_scoped_release release; + self.create_empty(); + }, + "Start an empty document with no pages.") + + .def("remove_page", + [](class_type& self, int page, std::int64_t generation, bool clean) -> void { + pybind11::gil_scoped_release release; + self.remove_page(page, generation, clean); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + pybind11::arg("clean") = false) + + .def("move_page", + [](class_type& self, int from, int to, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.move_page(from, to, generation); + }, + pybind11::arg("from_index"), + pybind11::arg("to_index"), + pybind11::arg("generation") = class_type::ANY_GENERATION) + + .def("rotate_page", + [](class_type& self, int page, int angle, bool relative, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.rotate_page(page, generation, angle, relative); + }, + pybind11::arg("page"), + pybind11::arg("angle"), + pybind11::arg("relative") = true, + pybind11::arg("generation") = class_type::ANY_GENERATION) + + .def("set_page_box", + [](class_type& self, + int page, + const std::string& box, + std::array rectangle, + std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.set_page_box(page, generation, box, rectangle); + }, + pybind11::arg("page"), + pybind11::arg("box"), + pybind11::arg("rectangle"), + pybind11::arg("generation") = class_type::ANY_GENERATION) + + .def("transform_page", + [](class_type& self, + int page, + std::array matrix, + std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.transform_page(page, generation, matrix); + }, + pybind11::arg("page"), + pybind11::arg("matrix"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Apply the matrix [a, b, c, d, e, f] to the page's content and annotations.") + + .def("scale_page", + [](class_type& self, int page, double sx, double sy, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.scale_page(page, generation, sx, sy); + }, + pybind11::arg("page"), + pybind11::arg("sx"), + pybind11::arg("sy"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Scale the page: content, annotations and all page boundaries.") + + .def("flatten_page_rotation", + [](class_type& self, int page, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.flatten_page_rotation(page, generation); + }, + pybind11::arg("page"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Turn the page's /Rotate into a rotation of its content.") + + .def("duplicate_page", + [](class_type& self, int page, int at, std::int64_t generation) -> int { + pybind11::gil_scoped_release release; + return self.duplicate_page(page, generation, at); + }, + pybind11::arg("page"), + pybind11::arg("at") = -1, + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Add a copy of a page. Returns the index of the copy.") + + .def("insert_blank_page", + [](class_type& self, double width, double height, int at) -> int { + pybind11::gil_scoped_release release; + return self.insert_blank_page(at, width, height); + }, + pybind11::arg("width"), + pybind11::arg("height"), + pybind11::arg("at") = -1) + + .def("set_info", + [](class_type& self, std::map > entries) -> void { + pybind11::gil_scoped_release release; + self.set_info(entries); + }, + pybind11::arg("entries"), + "Set entries of /Info; a None value removes the key.") + + .def("set_xmp", + [](class_type& self, std::optional packet) -> void { + std::optional data; + if(packet.has_value()) + { + data = packet.value().cast(); + } + + pybind11::gil_scoped_release release; + self.set_xmp(data); + }, + pybind11::arg("packet"), + "Replace the XMP metadata packet; None removes it.") + + .def("set_page_layout", + [](class_type& self, const std::string& name) -> void { + pybind11::gil_scoped_release release; + self.set_page_layout(name); + }, + pybind11::arg("name"), + "Set /PageLayout; an empty name removes it.") + + .def("set_page_mode", + [](class_type& self, const std::string& name) -> void { + pybind11::gil_scoped_release release; + self.set_page_mode(name); + }, + pybind11::arg("name"), + "Set /PageMode; an empty name removes it.") + + .def("set_viewer_preferences", + [](class_type& self, const std::string& dictionary) -> void { + pybind11::gil_scoped_release release; + self.set_viewer_preferences(dictionary); + }, + pybind11::arg("dictionary"), + "Replace /ViewerPreferences by a dictionary in PDF syntax; empty removes it.") + + .def("set_open_destination", + [](class_type& self, int page) -> void { + pybind11::gil_scoped_release release; + self.set_open_destination(page); + }, + pybind11::arg("page"), + "Page shown when the document opens; -1 removes the open action.") + + .def("set_page_label", + [](class_type& self, int from, int to, const std::string& style, const std::string& prefix, int start) -> void { + pybind11::gil_scoped_release release; + self.set_page_label(from, to, style, prefix, start); + }, + pybind11::arg("from_index"), + pybind11::arg("to_index"), + pybind11::arg("style") = "", + pybind11::arg("prefix") = "", + pybind11::arg("start") = 1, + "Label a range of pages.") + + .def("add_named_destination", + [](class_type& self, const std::string& name, int page) -> void { + pybind11::gil_scoped_release release; + self.add_named_destination(name, page); + }, + pybind11::arg("name"), + pybind11::arg("page"), + "Add or replace a named destination.") + + .def("add_outline_entry", + [](class_type& self, pybind11::dict spec) -> int { + nlohmann::json value = pyjson::to_json(spec); + + pybind11::gil_scoped_release release; + return self.add_outline_entry(value); + }, + pybind11::arg("spec"), + "Add a bookmark described by a dict; returns its id.") + + .def("update_outline_item", + [](class_type& self, int id, pybind11::dict changes) -> void { + nlohmann::json value = pyjson::to_json(changes); + + pybind11::gil_scoped_release release; + self.update_outline_item(id, value); + }, + pybind11::arg("id"), + pybind11::arg("changes"), + "Change a bookmark.") + + .def("remove_outline_item", + [](class_type& self, int id) -> void { + pybind11::gil_scoped_release release; + self.remove_outline_item(id); + }, + pybind11::arg("id"), + "Remove a bookmark and everything below it.") + + .def("move_outline_item", + [](class_type& self, int id, int parent, int index) -> void { + pybind11::gil_scoped_release release; + self.move_outline_item(id, parent, index); + }, + pybind11::arg("id"), + pybind11::arg("parent") = 0, + pybind11::arg("index") = -1, + "Move a bookmark below another one, or to the top level.") + + .def("clear_outline", + [](class_type& self) -> void { + pybind11::gil_scoped_release release; + self.clear_outline(); + }, + "Remove the whole outline.") + + .def("add_form_field", + [](class_type& self, int page, pybind11::dict spec, std::int64_t generation) -> void { + nlohmann::json value = pyjson::to_json(spec); + + pybind11::gil_scoped_release release; + self.add_form_field(page, generation, value); + }, + pybind11::arg("page"), + pybind11::arg("spec"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Create a form field on a page.") + + .def("update_form_field", + [](class_type& self, const std::string& name, pybind11::dict changes) -> void { + nlohmann::json value = pyjson::to_json(changes); + + pybind11::gil_scoped_release release; + self.update_form_field(name, value); + }, + pybind11::arg("name"), + pybind11::arg("changes"), + "Change a form field's name, rectangle, flags, tooltip or options.") + + .def("remove_form_field", + [](class_type& self, const std::string& name) -> void { + pybind11::gil_scoped_release release; + self.remove_form_field(name); + }, + pybind11::arg("name"), + "Remove a form field and its widgets.") + + .def("insert_image_page", + [](class_type& self, + int width, + int height, + const std::string& colorspace, + pybind11::bytes data, + bool is_jpeg, + double page_width, + double page_height, + std::array placement, + bool invert, + std::optional alpha, + int rotate, + int at) -> int { + std::string samples = data.cast(); + std::string opacity = alpha.has_value() ? alpha.value().cast() : std::string(); + + pybind11::gil_scoped_release release; + return self.insert_image_page(at, width, height, colorspace, samples, is_jpeg, invert, + opacity, page_width, page_height, placement, rotate); + }, + pybind11::arg("width"), + pybind11::arg("height"), + pybind11::arg("colorspace"), + pybind11::arg("data"), + pybind11::arg("is_jpeg"), + pybind11::arg("page_width"), + pybind11::arg("page_height"), + pybind11::arg("placement"), + pybind11::arg("invert") = false, + pybind11::arg("alpha") = pybind11::none(), + pybind11::arg("rotate") = 0, + pybind11::arg("at") = -1, + "Add a page that shows one image. Returns its index.") + + .def("draw_text", + [](class_type& self, + int page, + const std::string& text, + double x, + double y, + double size, + const std::string& font, + std::array color, + std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.draw_text(page, generation, text, x, y, size, font, color); + }, + pybind11::arg("page"), + pybind11::arg("text"), + pybind11::arg("x"), + pybind11::arg("y"), + pybind11::arg("size") = 12.0, + pybind11::arg("font") = "Helvetica", + pybind11::arg("color") = std::array{0.0, 0.0, 0.0}, + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Draw text on a page in a standard font.") + + .def("add_outline_item", + [](class_type& self, const std::string& title, int page, int parent) -> int { + pybind11::gil_scoped_release release; + return self.add_outline_item(title, page, parent); + }, + pybind11::arg("title"), + pybind11::arg("page") = -1, + pybind11::arg("parent") = 0, + "Add a bookmark; returns its id.") + + .def("set_form_values", + [](class_type& self, std::map values) -> int { + pybind11::gil_scoped_release release; + return self.set_form_values(values); + }, + pybind11::arg("values"), + "Set form field values by name; returns the number of fields set.") + + .def("set_need_appearances", + [](class_type& self, bool value) -> void { + pybind11::gil_scoped_release release; + self.set_need_appearances(value); + }, + pybind11::arg("value"), + "Set the form's /NeedAppearances flag.") + + .def("flatten_annotations", + [](class_type& self) -> void { + pybind11::gil_scoped_release release; + self.flatten_annotations(); + }, + "Draw annotations and form fields into the page content and remove them.") + + .def("add_annotation", + [](class_type& self, int page, const std::string& dictionary, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.add_annotation(page, generation, dictionary); + }, + pybind11::arg("page"), + pybind11::arg("dictionary"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Add an annotation given as a dictionary in PDF syntax.") + + .def("add_page_link", + [](class_type& self, int page, std::array rectangle, int target, std::int64_t generation) -> void { + pybind11::gil_scoped_release release; + self.add_page_link(page, generation, rectangle, target); + }, + pybind11::arg("page"), + pybind11::arg("rectangle"), + pybind11::arg("target"), + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Add a link to another page of the document.") + + .def("remove_annotations", + [](class_type& self, int page, std::set subtypes, std::int64_t generation) -> int { + pybind11::gil_scoped_release release; + return self.remove_annotations(page, generation, subtypes); + }, + pybind11::arg("page"), + pybind11::arg("subtypes") = std::set{}, + pybind11::arg("generation") = class_type::ANY_GENERATION, + "Remove annotations of a page by subtype; returns the number removed.") + + .def("add_attachment", + [](class_type& self, + const std::string& name, + pybind11::bytes data, + const std::string& description, + const std::string& mime_type) -> void { + std::string bytes = data.cast(); + + pybind11::gil_scoped_release release; + self.add_attachment(name, bytes, description, mime_type); + }, + pybind11::arg("name"), + pybind11::arg("data"), + pybind11::arg("description") = "", + pybind11::arg("mime_type") = "", + "Embed a file, replacing an attachment of the same name.") + + .def("remove_attachment", + [](class_type& self, const std::string& name) -> bool { + pybind11::gil_scoped_release release; + return self.remove_attachment(name); + }, + pybind11::arg("name"), + "Remove an embedded file; False if there is none of that name.") + + .def("add_javascript", + [](class_type& self, const std::string& name, const std::string& script) -> void { + pybind11::gil_scoped_release release; + self.add_javascript(name, script); + }, + pybind11::arg("name"), + pybind11::arg("script"), + "Register a document-level script.") + + .def("remove_javascript", + [](class_type& self) -> int { + pybind11::gil_scoped_release release; + return self.remove_javascript(); + }, + "Remove document-level scripts and scripted document actions.") + + .def("set_output_options", + [](class_type& self, bool compress_streams, const std::string& object_streams, bool linearize) -> void { + pybind11::gil_scoped_release release; + self.set_output_options(compress_streams, object_streams, linearize); + }, + pybind11::arg("compress_streams") = true, + pybind11::arg("object_streams") = "preserve", + pybind11::arg("linearize") = false, + "How the file is written.") + + .def("set_encryption", + [](class_type& self, + const std::string& user_password, + const std::string& owner_password, + int print, + bool modify, + bool extract, + bool annotate, + bool fill_forms, + bool accessibility, + bool assemble, + const std::string& algorithm) -> void { + pdflib::pdf_permissions permissions; + permissions.set_print(print); + permissions.set_modify(modify); + permissions.set_extract(extract); + permissions.set_annotate(annotate); + permissions.set_fill_forms(fill_forms); + permissions.set_accessibility(accessibility); + permissions.set_assemble(assemble); + + pybind11::gil_scoped_release release; + self.set_encryption(user_password, owner_password, permissions, algorithm); + }, + pybind11::arg("user_password"), + pybind11::arg("owner_password") = "", + pybind11::arg("print") = 0, + pybind11::arg("modify") = true, + pybind11::arg("extract") = true, + pybind11::arg("annotate") = true, + pybind11::arg("fill_forms") = true, + pybind11::arg("accessibility") = true, + pybind11::arg("assemble") = true, + pybind11::arg("algorithm") = "AES-256", + "Encrypt output with the requested PDF password algorithm.") + + .def("clear_encryption", + [](class_type& self) -> void { + pybind11::gil_scoped_release release; + self.clear_encryption(); + }, + "Write unencrypted output again.") + + .def("write_to_bytes", + [](class_type& self) -> pybind11::bytes { + std::shared_ptr data; + { + pybind11::gil_scoped_release release; + data = self.write_to_memory(); + } + return pybind11::bytes(*data); + }) + + .def("write_to_file", + [](class_type& self, const std::string& filename) -> void { + pybind11::gil_scoped_release release; + self.write_to_file(filename); + }, + pybind11::arg("filename")); + } + + // Operations with no pypdf counterpart: bound on the editor only. + inline void bind_editor_only(pybind11::class_& cls) + { + cls + .def("render_page", + [](docling_editor& self, int page_no, double scale) -> pybind11::tuple { + std::pair>, std::array> result; + { + pybind11::gil_scoped_release release; + result = self.render_page(page_no, scale); + } + const auto& pixels = result.first; + pybind11::bytes data = pixels ? pybind11::bytes( + reinterpret_cast(pixels->data()), pixels->size()) : pybind11::bytes(""); + return pybind11::make_tuple(data, result.second); + }, + pybind11::kw_only(), + pybind11::arg("page_no"), + pybind11::arg("scale") = 1.0, + "Render the current page to RGBA bytes and shape; page_no starts at 1.") + + .def("is_editing", [](docling_editor& self) -> bool { return self.is_editing(); }, + "True once the editor works on its own copy of the document.") + + .def("object_json", + [](docling_editor& self, int id, int depth) -> pybind11::object { + nlohmann::json result; + { + pybind11::gil_scoped_release release; + result = self.object_json(id, depth); + } + return pyjson::from_json(result); + }, + pybind11::arg("id"), + pybind11::arg("depth") = 3, + "A bounded view of one PDF object; id 0 is the trailer, -1 the catalog.") + + .def("annotations", + [](docling_editor& self) -> pybind11::object { + nlohmann::json annotations; + { + pybind11::gil_scoped_release release; + annotations = self.annotations(); + } + return pyjson::from_json(annotations); + }, + "Form, language, XMP, outline and structure of the current document state."); + } + + // pdf_edit_error -> Python exception with args (category, message). + inline void bind_edit_error(pybind11::module_& m) + { + // Kept for the lifetime of the interpreter; a translator cannot capture. + static pybind11::exception* edit_error_type = + new pybind11::exception(m, "pdf_edit_error", PyExc_RuntimeError); + + pybind11::register_exception_translator([](std::exception_ptr pointer) { + try + { + if(pointer) + { + std::rethrow_exception(pointer); + } + } + catch(const pdflib::pdf_edit_error& exc) + { + pybind11::tuple args = pybind11::make_tuple(exc.get_category(), std::string(exc.what())); + PyErr_SetObject(edit_error_type->ptr(), args.ptr()); + } + }); + } + } + + // Called once from the module definition in app/pybind_parse.cpp. + inline void register_edit_bindings(pybind11::module_& m) + { + edit_bindings::bind_edit_error(m); + + pybind11::class_ reader(m, "pdf_reader", + "Read-only PDF document; the native half of docling_parse.pdf_reader.PdfReader."); + pybind11::class_ writer(m, "pdf_writer", + "Writable PDF document; the native half of docling_parse.pdf_writer.PdfWriter."); + pybind11::class_ editor(m, "pdf_editor", + "Full PDF editor; the native half of docling_parse.pdf_editor.PdfEditor."); + + edit_bindings::bind_inspection(reader); + edit_bindings::bind_inspection(writer); + edit_bindings::bind_inspection(editor); + + edit_bindings::bind_open_source(reader); + edit_bindings::bind_open_source(reader); + edit_bindings::bind_open_source(reader); + + edit_bindings::bind_open_source(writer); + edit_bindings::bind_open_source(writer); + edit_bindings::bind_open_source(writer); + + edit_bindings::bind_open_source(editor); + edit_bindings::bind_open_source(editor); + edit_bindings::bind_open_source(editor); + + edit_bindings::bind_editing(writer); + edit_bindings::bind_editing(editor); + + edit_bindings::bind_append_pages(writer); + edit_bindings::bind_append_pages(writer); + edit_bindings::bind_append_pages(writer); + + edit_bindings::bind_append_pages(editor); + edit_bindings::bind_append_pages(editor); + edit_bindings::bind_append_pages(editor); + + edit_bindings::bind_overlay_page(writer); + edit_bindings::bind_overlay_page(writer); + edit_bindings::bind_overlay_page(writer); + + edit_bindings::bind_overlay_page(editor); + edit_bindings::bind_overlay_page(editor); + edit_bindings::bind_overlay_page(editor); + + edit_bindings::bind_editor_only(editor); + } + +} + +#endif diff --git a/src/pybind/pdf_reader.h b/src/pybind/pdf_reader.h new file mode 100644 index 000000000..6b646691d --- /dev/null +++ b/src/pybind/pdf_reader.h @@ -0,0 +1,55 @@ +//-*-C++-*- + +#ifndef PYBIND_PDF_READER_H +#define PYBIND_PDF_READER_H + +#include + +namespace docling +{ + // The read-only face of docling_editor. It implements nothing: protected + // inheritance hides the editor, and the using-declarations publish the + // operations that cannot change a document. Add logic to docling_editor, + // never here. + class pdf_reader: protected docling_editor + { + public: + + pdf_reader(std::string loglevel = "fatal"); + + using docling_editor::ANY_GENERATION; + + using docling_editor::open_file; + using docling_editor::open_buffer; + using docling_editor::open_source; + using docling_editor::take_open_error; + using docling_editor::is_open; + using docling_editor::close; + + using docling_editor::page_count; + using docling_editor::generation; + using docling_editor::document_info; + using docling_editor::validate_strict; + using docling_editor::page_info; + using docling_editor::extract_text; + using docling_editor::page_images; + using docling_editor::outline; + using docling_editor::get_source; + using docling_editor::document_settings; + using docling_editor::page_labels; + using docling_editor::named_destinations; + using docling_editor::outline_tree; + using docling_editor::form; + using docling_editor::page_annotations; + using docling_editor::attachments; + using docling_editor::attachment_data; + using docling_editor::javascript; + }; + + inline pdf_reader::pdf_reader(std::string loglevel): + docling_editor(loglevel) + {} + +} + +#endif diff --git a/src/pybind/pdf_writer.h b/src/pybind/pdf_writer.h new file mode 100644 index 000000000..2703d45fc --- /dev/null +++ b/src/pybind/pdf_writer.h @@ -0,0 +1,103 @@ +//-*-C++-*- + +#ifndef PYBIND_PDF_WRITER_H +#define PYBIND_PDF_WRITER_H + +#include + +namespace docling +{ + // The pypdf-shaped writing face of docling_editor. It implements nothing: + // protected inheritance hides the editor, and the using-declarations + // publish inspection plus the editing and output operations. Add logic to + // docling_editor, never here. + class pdf_writer: protected docling_editor + { + public: + + pdf_writer(std::string loglevel = "fatal"); + + using docling_editor::ANY_GENERATION; + + using docling_editor::open_file; + using docling_editor::open_buffer; + using docling_editor::open_source; + using docling_editor::take_open_error; + using docling_editor::create_empty; + using docling_editor::is_open; + using docling_editor::close; + + using docling_editor::page_count; + using docling_editor::generation; + using docling_editor::document_info; + using docling_editor::validate_strict; + using docling_editor::page_info; + using docling_editor::extract_text; + using docling_editor::page_images; + using docling_editor::outline; + using docling_editor::get_source; + using docling_editor::document_settings; + using docling_editor::page_labels; + using docling_editor::named_destinations; + using docling_editor::outline_tree; + using docling_editor::form; + using docling_editor::page_annotations; + using docling_editor::attachments; + using docling_editor::attachment_data; + using docling_editor::javascript; + + using docling_editor::remove_page; + using docling_editor::move_page; + using docling_editor::rotate_page; + using docling_editor::set_page_box; + using docling_editor::transform_page; + using docling_editor::scale_page; + using docling_editor::overlay_page; + using docling_editor::flatten_page_rotation; + using docling_editor::duplicate_page; + using docling_editor::insert_blank_page; + using docling_editor::insert_image_page; + using docling_editor::draw_text; + using docling_editor::append_pages; + + using docling_editor::set_info; + using docling_editor::set_xmp; + using docling_editor::set_page_layout; + using docling_editor::set_page_mode; + using docling_editor::set_viewer_preferences; + using docling_editor::set_open_destination; + using docling_editor::set_page_label; + using docling_editor::add_named_destination; + using docling_editor::add_outline_item; + using docling_editor::add_outline_entry; + using docling_editor::update_outline_item; + using docling_editor::remove_outline_item; + using docling_editor::move_outline_item; + using docling_editor::clear_outline; + using docling_editor::set_form_values; + using docling_editor::set_need_appearances; + using docling_editor::flatten_annotations; + using docling_editor::add_form_field; + using docling_editor::update_form_field; + using docling_editor::remove_form_field; + using docling_editor::add_annotation; + using docling_editor::add_page_link; + using docling_editor::remove_annotations; + using docling_editor::add_attachment; + using docling_editor::remove_attachment; + using docling_editor::add_javascript; + using docling_editor::remove_javascript; + using docling_editor::set_output_options; + using docling_editor::set_encryption; + using docling_editor::clear_encryption; + using docling_editor::write_to_memory; + using docling_editor::write_to_file; + }; + + inline pdf_writer::pdf_writer(std::string loglevel): + docling_editor(loglevel) + {} + +} + +#endif diff --git a/tests/rendering_regression.py b/tests/rendering_regression.py index fdb898bc9..4d2e7beee 100644 --- a/tests/rendering_regression.py +++ b/tests/rendering_regression.py @@ -1144,7 +1144,13 @@ def row_ink_profile( """Per-row ink pixel counts, top to bottom.""" mask = ink_mask(image, threshold=threshold) width = mask.width - data = list(mask.getdata()) + # get_flattened_data() requires Pillow 12.1.0; we still support Pillow 10. + # Remove the hasattr check and getdata() fallback when the minimum is >=12.1.0. + data = ( + mask.get_flattened_data() + if hasattr(mask, "get_flattened_data") + else list(mask.getdata()) + ) return [ sum(1 for value in data[y * width : (y + 1) * width] if value) for y in range(mask.height) @@ -1157,7 +1163,13 @@ def column_ink_profile( """Per-column ink pixel counts, left to right.""" mask = ink_mask(image, threshold=threshold) width, height = mask.size - data = list(mask.getdata()) + # get_flattened_data() requires Pillow 12.1.0; we still support Pillow 10. + # Remove the hasattr check and getdata() fallback when the minimum is >=12.1.0. + data = ( + mask.get_flattened_data() + if hasattr(mask, "get_flattened_data") + else list(mask.getdata()) + ) return [sum(1 for y in range(height) if data[y * width + x]) for x in range(width)] diff --git a/tests/test_unit_pdf_compat.py b/tests/test_unit_pdf_compat.py new file mode 100644 index 000000000..c89328e24 --- /dev/null +++ b/tests/test_unit_pdf_compat.py @@ -0,0 +1,175 @@ +"""The compatibility adapters preserve the pinned pypdf call signatures.""" + +import inspect +import re +from io import BytesIO + +import pypdf +import pytest + +from docling_parse import PdfEditor, PdfReader, PdfWriter +from docling_parse.pdf_errors import PdfLoadError +from tests.test_unit_pdf_editor import FORM, THREE, TWO + + +@pytest.mark.parametrize( + ("ours", "reference"), [(PdfReader, pypdf.PdfReader), (PdfWriter, pypdf.PdfWriter)] +) +def test_compatibility_method_signatures(ours, reference): + names = ["__init__"] + [ + name + for name, method in inspect.getmembers(ours, inspect.isfunction) + if not name.startswith("_") and callable(getattr(reference, name, None)) + ] + for name in names: + actual = inspect.signature(getattr(ours, name)).parameters + expected = inspect.signature(getattr(reference, name)).parameters + assert list(actual) == list(expected), name + for key, parameter in expected.items(): + other = actual[key] + assert other.kind == parameter.kind, (name, key) + if parameter.default is inspect.Parameter.empty: + assert other.default is inspect.Parameter.empty, (name, key) + elif parameter.default is None or isinstance( + parameter.default, (str, int, float, bool, tuple) + ): + assert other.default == parameter.default, (name, key) + elif hasattr(parameter.default, "fit_type"): + assert other.default.fit_type == parameter.default.fit_type + assert tuple(other.default.fit_args) == tuple( + parameter.default.fit_args + ) + else: + assert type(other.default) is type(parameter.default), (name, key) + + +def test_all_editor_parameters_are_keyword_only(): + for name, method in inspect.getmembers(PdfEditor, callable): + if name.startswith("_") and name != "__init__": + continue + for parameter in inspect.signature(method).parameters.values(): + if parameter.name not in ("self", "cls"): + assert parameter.kind == inspect.Parameter.KEYWORD_ONLY, ( + name, + parameter, + ) + + +def test_editor_rejects_positional_and_zero_page_arguments(): + with pytest.raises(TypeError): + getattr(PdfEditor, "__call__")(THREE) + with PdfEditor(source=THREE) as editor: + assert editor.get_page(page_no=1).extract_text() == "alpha" + assert editor.get_page_no(page=editor.pages[0]) == 1 + assert editor.pages[0].extract_text() == "alpha" + assert editor.get_page(page_no=3).extract_text() == "gamma" + for page_no in (0, -1, 4): + with pytest.raises(IndexError): + editor.get_page(page_no=page_no) + with pytest.raises(TypeError): + getattr(editor, "remove_page")(1) + + +def test_adapters_forward_named_editor_calls(monkeypatch): + with PdfReader(THREE) as reader, PdfWriter(THREE) as writer: + calls = [] + sentinel = object() + + def get_page(self, *, page_no): + calls.append((self._native, page_no)) + return sentinel + + monkeypatch.setattr(PdfEditor, "get_page", get_page) + assert reader.get_page(1) is sentinel + assert writer.get_page(0) is sentinel + assert calls == [(reader._native, 2), (writer._native, 1)] + + +@pytest.mark.parametrize("writer_class", [PdfWriter, pypdf.PdfWriter]) +def test_positional_pypdf_workflow(writer_class): + writer = writer_class() + writer.append(BytesIO(THREE), "Part", (0, 2)) + writer.merge(1, BytesIO(TWO), None, [1]) + writer.insert_blank_page(80, 90, 1) + writer.add_blank_page() + assert [float(page.mediabox.width) for page in writer.pages] == [ + 200, + 80, + 210, + 210, + 210, + ] + stream = BytesIO() + opened, output = writer.write(stream) + assert opened is False + assert output is stream and not output.closed + assert len(pypdf.PdfReader(BytesIO(stream.getvalue())).pages) == 5 + + +def test_writer_write_path_result(tmp_path): + writer = PdfWriter(THREE) + path = tmp_path / "out.pdf" + opened, stream = writer.write(path) + assert opened is True + assert stream.closed is True + assert str(stream.name) == str(path) + assert len(PdfReader(path).pages) == 3 + + +@pytest.mark.parametrize( + ("algorithm", "revision"), + [("RC4-40", 2), ("RC4-128", 3), ("AES-128", 4), ("AES-256-R5", 5), ("AES-256", 6)], +) +def test_compatibility_encryption_algorithms(algorithm, revision): + writer = PdfWriter(THREE) + writer.encrypt("secret", algorithm=algorithm) + data = writer.to_bytes() + reader = pypdf.PdfReader(BytesIO(data), password="secret") + assert reader.trailer["/Encrypt"]["/R"] == revision + assert len(reader.pages) == 3 + + +def test_encryption_defaults_differ_at_the_api_boundary(): + writer = PdfWriter(THREE) + writer.encrypt("secret") + with PdfReader(writer.to_bytes(), password="secret") as reader: + assert reader.encryption["revision"] == 3 + with PdfEditor(source=THREE) as editor: + editor.encrypt(user_password="secret") + with PdfReader(editor.to_bytes(), password="secret") as reader: + assert reader.encryption["revision"] == 6 + + +def test_strict_reader_rejects_repaired_input(): + damaged = re.sub(rb"startxref\n[0-9]+", b"startxref\n0", THREE) + assert len(PdfReader(damaged).pages) == 3 + with pytest.raises(PdfLoadError): + PdfReader(damaged, strict=True) + + +def test_get_pages_showing_field_accepts_returned_field_dictionary(): + with PdfReader(FORM) as reader: + field = reader.get_fields()["agree"] + assert reader.get_pages_showing_field(field)[0].index == 0 + + +@pytest.mark.parametrize("clean", [False, True]) +def test_remove_page_clean_controls_stray_references(clean): + source = pypdf.PdfWriter(clone_from=BytesIO(THREE)) + source.root_object[pypdf.generic.NameObject("/CustomPage")] = source.pages[ + 1 + ].indirect_reference + data = BytesIO() + source.write(data) + writer = PdfWriter(data) + writer.remove_page(1, clean=clean) + reader = pypdf.PdfReader(BytesIO(writer.to_bytes())) + target = ( + reader.trailer["/Root"] + .get("/CustomPage", pypdf.generic.NullObject()) + .get_object() + ) + if clean: + assert isinstance(target, pypdf.generic.NullObject) + else: + assert target["/Type"] == "/Page" diff --git a/tests/test_unit_pdf_editor.py b/tests/test_unit_pdf_editor.py new file mode 100644 index 000000000..b69d3c7f5 --- /dev/null +++ b/tests/test_unit_pdf_editor.py @@ -0,0 +1,2534 @@ +#!/usr/bin/env python +"""PdfReader, PdfWriter and PdfEditor over the native docling_editor. + +The three classes publish different subsets of one native implementation, so +the editing tests run against both PdfWriter and PdfEditor: a difference +between the two is a bug in the binding, not a feature. + +Every written document is read back, since "it wrote without raising" says +nothing about the file: always with our own reader and, where pypdf is +installed (it is in the `perf` dependency group, not `dev`), with pypdf as an +independent second opinion. The fixtures are built in memory so each page is +identifiable by its size and its text. +""" + +from __future__ import annotations + +import re +import subprocess +import sys +import threading +from io import BytesIO +from types import ModuleType + +import pytest + +from docling_parse.pdf_editor import PdfEditor +from docling_parse.pdf_errors import ( + PdfEditError, + PdfEditErrorCategory, + PdfLoadError, + PdfPasswordError, + PdfStaleHandleError, + PdfUnsupportedError, + PdfWriteError, +) +from docling_parse.pdf_reader import PdfReader +from docling_parse.pdf_writer import PdfWriter +from tests.outline_fixtures import build_destination_kinds +from tests.pdf_builder import simple_page_pdf +from tests.test_unit_acroform_widgets import _form_pdf +from tests.test_unit_structure_tree import _tagged_pdf + +pypdf: ModuleType | None +try: + import pypdf +except ImportError: # pragma: no cover - depends on the installed groups + pypdf = None + +GARBAGE = b"%PDF-1.4\nthis is not a valid pdf at all" + + +class _WriterEditor(PdfEditor): + """Run shared editor workflows against the restricted native writer too.""" + + _native_class = PdfWriter._native_class + + +EDITING_CLASSES = [pytest.param(_WriterEditor, id="PdfWriter-native"), PdfEditor] + + +def _test_page_no(index, document): + if index is None: + return None + return index + len(document.pages) + 1 if index < 0 else index + 1 + + +def _source_page_nos(source, selection): + with PdfReader(source) as reader: + count = len(reader.pages) + indices = ( + range(*selection.indices(count)) if isinstance(selection, slice) else selection + ) + return [index + count + 1 if index < 0 else index + 1 for index in indices] + + +def make_pdf( + labels: list[str], *, title: str = "fixture", rotate: int = 0, y: int = 150 +) -> bytes: + """One page per label. Page i is (200 + 10*i) x 300 and shows its label + at height `y`. + + Objects: 1 catalog, 2 page tree, 3 font, 4 info, then a page and its + content stream per label. + """ + first_page = 5 + kids = " ".join(f"{first_page + 2 * i} 0 R" for i in range(len(labels))) + rotate_entry = f" /Rotate {rotate}" if rotate else "" + + objects: list[str] = [ + "<< /Type /Catalog /Pages 2 0 R >>", + f"<< /Type /Pages /Kids [{kids}] /Count {len(labels)} >>", + "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>", + f"<< /Title ({title}) /Author (docling-parse tests) >>", + ] + for i, label in enumerate(labels): + content = f"BT /F1 24 Tf 20 {y} Td ({label}) Tj ET" + objects.append( + f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 {200 + 10 * i} 300]" + f"{rotate_entry} /Resources << /Font << /F1 3 0 R >> >> " + f"/Contents {first_page + 2 * i + 1} 0 R >>" + ) + objects.append(f"<< /Length {len(content)} >>\nstream\n{content}\nendstream") + + out = b"%PDF-1.7\n" + offsets = [] + for index, obj in enumerate(objects, start=1): + offsets.append(len(out)) + out += f"{index} 0 obj\n{obj}\nendobj\n".encode("latin-1") + + startxref = len(out) + out += f"xref\n0 {len(objects) + 1}\n".encode("latin-1") + out += b"0000000000 65535 f \n" + for offset in offsets: + out += f"{offset:010d} 00000 n \n".encode("latin-1") + out += ( + f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R /Info 4 0 R >>\n" + f"startxref\n{startxref}\n%%EOF" + ).encode("latin-1") + return out + + +def widths(document) -> list[float]: + return [page.mediabox.width for page in document.pages] + + +def written_widths(data: bytes) -> list[float]: + """Page widths of a written file, as both readers see them.""" + with PdfReader(data) as reader: + result = widths(reader) + if pypdf is not None: + pages = pypdf.PdfReader(BytesIO(data)).pages + assert [float(page.mediabox.width) for page in pages] == result + return result + + +def written_rotations(data: bytes) -> list[int]: + """Page rotations of a written file, as both readers see them.""" + with PdfReader(data) as reader: + result = [page.rotation for page in reader.pages] + if pypdf is not None: + pages = pypdf.PdfReader(BytesIO(data)).pages + assert [page.rotation for page in pages] == result + return result + + +def test_pypdf_is_available_as_second_reader(): + """Skipped, visibly, when the written files are checked by one reader only.""" + pytest.importorskip("pypdf") + + +THREE = make_pdf(["alpha", "beta", "gamma"]) +TWO = make_pdf(["delta", "epsilon"], title="second") + +# Text low on the page, so it shares no line with the labels of THREE. +STAMP = make_pdf(["STAMP"], y=40) + +# 2x2 uncompressed RGB samples: red, green / blue, white. +PIXELS = bytes([255, 0, 0, 0, 255, 0, 0, 0, 255, 255, 255, 255]) + + +def make_image_pdf() -> bytes: + """One 200x300 page drawing a 2x2 image into [20 30 120 130].""" + content = "q 100 0 0 100 20 30 cm /Im1 Do Q" + image = ( + b"<< /Type /XObject /Subtype /Image /Width 2 /Height 2 " + b"/ColorSpace /DeviceRGB /BitsPerComponent 8 /Length 12 >>\nstream\n" + + PIXELS + + b"\nendstream" + ) + objects: list[bytes] = [ + b"<< /Type /Catalog /Pages 2 0 R >>", + b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>", + b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 300] " + b"/Resources << /XObject << /Im1 5 0 R >> >> /Contents 4 0 R >>", + f"<< /Length {len(content)} >>\nstream\n{content}\nendstream".encode(), + image, + ] + + out = b"%PDF-1.7\n" + offsets = [] + for index, obj in enumerate(objects, start=1): + offsets.append(len(out)) + out += f"{index} 0 obj\n".encode() + obj + b"\nendobj\n" + + startxref = len(out) + out += f"xref\n0 {len(objects) + 1}\n".encode() + out += b"0000000000 65535 f \n" + for offset in offsets: + out += f"{offset:010d} 00000 n \n".encode() + out += ( + f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R >>\n" + f"startxref\n{startxref}\n%%EOF" + ).encode() + return out + + +IMAGE = make_image_pdf() + + +def lines(page) -> set[str]: + """The page's text lines, without relying on their order.""" + return set(page.extract_text().split("\n")) + + +# ---------------------------------------------------------------- reader + + +def test_reader_inspects_without_decoding(): + with PdfReader(THREE) as reader: + assert len(reader.pages) == 3 + assert reader.pdf_version == "1.7" + assert reader.is_encrypted is False + assert reader.encryption is None + assert reader.metadata == { + "Title": "fixture", + "Author": "docling-parse tests", + } + assert reader.xmp_metadata is None + assert widths(reader) == [200.0, 210.0, 220.0] + + +def test_reader_page_geometry(): + with PdfReader(make_pdf(["only"], rotate=90)) as reader: + page = reader.pages[0] + assert page.mediabox == (0.0, 0.0, 200.0, 300.0) + assert page.mediabox.height == 300.0 + # no /CropBox in the file: it defaults to the media box + assert page.cropbox == page.mediabox + assert page.trimbox == page.mediabox + assert page.rotation == 90 + assert page.user_unit == 1.0 + + +def test_reader_page_sequence(): + with PdfReader(THREE) as reader: + assert reader.pages[-1].index == 2 + assert [page.index for page in reader.pages[1:]] == [1, 2] + assert [page.index for page in reader.pages] == [0, 1, 2] + with pytest.raises(IndexError): + reader.pages[3] + + +def test_reader_extracts_text_per_page(): + with PdfReader(THREE) as reader: + assert [page.extract_text() for page in reader.pages] == [ + "alpha", + "beta", + "gamma", + ] + + +def test_layout_text_keeps_columns_and_spacing(): + content = ( + "BT /F1 12 Tf 20 250 Td (left) Tj ET " + "BT /F1 12 Tf 150 250 Td (right) Tj ET " + "BT /F1 12 Tf 100 150 Td (indented) Tj ET" + ) + pdf = simple_page_pdf( + content, + resources="/Font << /F1 5 0 R >>", + media_box="[0 0 300 300]", + extra_objects=["<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>"], + ) + + with PdfReader(pdf) as reader: + page = reader.pages[0] + plain = page.extract_text() + layout = page.extract_text(extraction_mode="layout") + + with pytest.raises(ValueError): + page.extract_text(extraction_mode="fancy") + + assert {"left", "right", "indented"} <= set(plain.split()) + + rows = layout.split("\n") + first, last = rows[0], rows[-1] + + # one row for the two runs that share a baseline, the gap between them kept + assert first.startswith("left") + assert first.rstrip().endswith("right") + assert first.index("right") - len("left") >= 5 + + # the lower run keeps its indentation and its distance from the first row + assert last.strip() == "indented" + assert last.startswith(" ") + assert len(rows) >= 3 and all(row == "" for row in rows[1:-1]) + + +@pytest.mark.parametrize("kind", ["bytes", "stream", "path", "reader"]) +def test_reader_sources(kind, tmp_path): + if kind == "bytes": + source = THREE + elif kind == "stream": + source = BytesIO(THREE) + elif kind == "path": + source = tmp_path / "three.pdf" + source.write_bytes(THREE) + else: + source = PdfReader(THREE) + + with PdfReader(source) as reader: + assert widths(reader) == [200.0, 210.0, 220.0] + + if kind == "stream": + # the stream is the caller's: read, not closed + assert not source.closed + + +def test_reader_reports_load_failure(tmp_path): + with pytest.raises(PdfLoadError): + PdfReader(GARBAGE) + with pytest.raises(PdfLoadError): + PdfReader(tmp_path / "missing.pdf") + + +def test_reader_has_no_editing_surface(): + with PdfReader(THREE) as reader: + for name in ("append", "write", "remove_page", "add_blank_page"): + assert not hasattr(reader, name) + assert not hasattr(reader.pages[0], "rotate") + with pytest.raises(TypeError): + del reader.pages[0] + for name in ("write_to_bytes", "remove_page", "append_pages", "create_empty"): + assert not hasattr(reader._native, name) + + +# ---------------------------------------------------------------- images + + +def test_reader_exports_page_images(): + with PdfReader(IMAGE) as reader: + images = reader.pages[0].images + + assert len(images) == 1 + image = images[0] + + assert "Im1" in image.name + assert (image.width, image.height) == (2, 2) + assert image.mode == "RGB" + assert image.format == "raw" + assert image.extension == ".bin" + assert image.data == PIXELS + assert image.bbox == pytest.approx((20.0, 30.0, 120.0, 130.0)) + assert image.bbox.width == pytest.approx(100.0) + + assert image.to_pil().size == (2, 2) + + +def test_image_export_saves_bytes(tmp_path): + with PdfReader(IMAGE) as reader: + image = reader.pages[0].images[0] + + target = tmp_path / f"image{image.extension}" + image.save(target) + assert target.read_bytes() == image.data + + +def test_text_and_images_of_one_page_do_not_shadow_each_other(): + """Both decode the page, with different settings: asking for one must not + hand back what was decoded for the other.""" + with PdfReader(IMAGE) as reader: + page = reader.pages[0] + assert page.extract_text() == "" + assert len(page.images) == 1 + assert page.extract_text() == "" + assert len(page.images) == 1 + + with PdfReader(THREE) as reader: + assert reader.pages[0].images == [] + assert reader.pages[0].extract_text() == "alpha" + + +# ---------------------------------------------------------------- writing + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_clone_round_trips_unchanged(cls): + document = cls(source=THREE) + data = document.to_bytes() + + assert written_widths(data) == [200.0, 210.0, 220.0] + with PdfReader(data) as reader: + assert reader.metadata["Title"] == "fixture" + assert [page.extract_text() for page in reader.pages] == [ + "alpha", + "beta", + "gamma", + ] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_remove_reorder_rotate(cls): + document = cls(source=THREE) + + document.pages[0].rotate(90) + document.pages[0].rotate(90) + del document.pages[1] + document.move_page( + page_no=_test_page_no(0, document), to_page_no=_test_page_no(1, document) + ) + + assert widths(document) == [220.0, 200.0] + assert [page.rotation for page in document.pages] == [0, 180] + + data = document.to_bytes() + assert written_widths(data) == [220.0, 200.0] + assert written_rotations(data) == [0, 180] + + # the source bytes are untouched + with PdfReader(THREE) as reader: + assert widths(reader) == [200.0, 210.0, 220.0] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_page_boxes_and_absolute_rotation(cls): + document = cls(source=THREE) + page = document.pages[2] + + page.cropbox = (10, 20, 110, 220) + page.rotation = 270 + + with PdfReader(document.to_bytes()) as reader: + written = reader.pages[2] + assert written.cropbox == (10.0, 20.0, 110.0, 220.0) + assert written.mediabox == (0.0, 0.0, 220.0, 300.0) + assert written.rotation == 270 + + with pytest.raises(PdfEditError) as excinfo: + page.rotate(45) + assert excinfo.value.category is PdfEditErrorCategory.INVALID_EDIT + + with pytest.raises(PdfEditError): + page.cropbox = (10, 10, 10, 50) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_assemble_from_several_sources(cls): + document = cls() + assert len(document.pages) == 0 + + document.append(source=THREE) + document.append( + source=PdfReader(TWO), page_nos=_source_page_nos(PdfReader(TWO), [1, 0]) + ) + document.append( + source=BytesIO(THREE), + page_nos=_source_page_nos(BytesIO(THREE), slice(0, 1)), + before_page_no=_test_page_no(0, document), + ) + blank = document.add_blank_page(width=100, height=150) + assert blank.mediabox == (0.0, 0.0, 100.0, 150.0) + document.insert_blank_page( + before_page_no=_test_page_no(1, document), width=50, height=60 + ) + + expected = [200.0, 50.0, 200.0, 210.0, 220.0, 210.0, 200.0, 100.0] + assert widths(document) == expected + + data = document.to_bytes() + assert written_widths(data) == expected + with PdfReader(data) as reader: + texts = [page.extract_text() for page in reader.pages] + assert texts == ["alpha", "", "alpha", "beta", "gamma", "epsilon", "delta", ""] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_pypdf_style_page_by_page_assembly(cls): + """The recipes people know: add_page in a loop, insert_page, merge.""" + reader = PdfReader(THREE) + + document = cls() + for page in reader.pages: + added = document.add_page(page=page) + assert added.page_number == len(document.pages) - 1 + document.insert_page( + page=PdfReader(TWO).pages[1], before_page_no=_test_page_no(0, document) + ) + document.merge( + before_page_no=_test_page_no(1, document), + fileobj=TWO, + page_nos=_source_page_nos(TWO, [0]), + ) + + assert document.get_num_pages() == 5 + assert widths(document) == [210.0, 200.0, 200.0, 210.0, 220.0] + assert document.get_page(page_no=_test_page_no(4, document)).mediabox.width == 220.0 + assert reader.pdf_header == "%PDF-1.7" + + other = cls(source=TWO) + stale = other.pages[1] + del other.pages[0] + with pytest.raises(PdfStaleHandleError): + document.add_page(page=stale) + + assert written_widths(document.to_bytes()) == [210.0, 200.0, 200.0, 210.0, 220.0] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_scale_to(cls): + document = cls(source=THREE) + document.pages[1].scale_to(105, 600) + + assert document.pages[1].mediabox == pytest.approx((0.0, 0.0, 105.0, 600.0)) + assert widths(document) == pytest.approx([200.0, 105.0, 220.0]) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_append_same_page_twice_gives_independent_pages(cls): + document = cls() + document.append(source=THREE, page_nos=_source_page_nos(THREE, [0, 0])) + document.pages[1].rotate(90) + + assert [page.rotation for page in document.pages] == [0, 90] + data = document.to_bytes() + assert written_rotations(data) == [0, 90] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_append_from_edited_document_and_from_itself(cls): + other = cls(source=TWO) + del other.pages[0] + + document = cls(source=THREE) + document.append(source=other) + document.append(source=document, page_nos=_source_page_nos(document, [0])) + + assert widths(document) == [200.0, 210.0, 220.0, 210.0, 200.0] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_text_of_edited_document(cls): + document = cls(source=THREE) + del document.pages[0] + document.append(source=TWO, page_nos=_source_page_nos(TWO, [0])) + + assert [page.extract_text() for page in document.pages] == [ + "beta", + "gamma", + "delta", + ] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_duplicate_page(cls): + document = cls(source=THREE) + + copy = document.duplicate_page(page_no=_test_page_no(0, document)) + assert copy.index == 3 + copy.rotate(90) + + front = document.duplicate_page( + page_no=_test_page_no(2, document), before_page_no=_test_page_no(0, document) + ) + assert front.index == 0 + + assert widths(document) == [220.0, 200.0, 210.0, 220.0, 200.0] + # the copy was rotated, the page it was copied from was not + assert [page.rotation for page in document.pages] == [0, 0, 0, 0, 90] + + data = document.to_bytes() + assert written_widths(data) == [220.0, 200.0, 210.0, 220.0, 200.0] + assert written_rotations(data) == [0, 0, 0, 0, 90] + with PdfReader(data) as reader: + assert reader.pages[4].extract_text() == "alpha" + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +@pytest.mark.parametrize("over", [True, False]) +def test_merge_page_draws_both_pages(cls, over): + stamp = PdfReader(STAMP).pages[0] + + document = cls(source=THREE) + result = document.pages[0].merge_page(stamp, over=over) + assert result.index == 0 + + assert lines(document.pages[0]) == {"alpha", "STAMP"} + assert lines(document.pages[1]) == {"beta"} + # merging draws on the page; it does not resize it + assert widths(document) == [200.0, 210.0, 220.0] + + data = document.to_bytes() + assert written_widths(data) == [200.0, 210.0, 220.0] + with PdfReader(data) as reader: + assert lines(reader.pages[0]) == {"alpha", "STAMP"} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_watermark_every_page(cls): + stamp = PdfReader(STAMP).pages[0] + + document = cls(source=THREE) + for page in document.pages: + page.merge_page(stamp, over=False) + + with PdfReader(document.to_bytes()) as reader: + assert [lines(page) for page in reader.pages] == [ + {"alpha", "STAMP"}, + {"beta", "STAMP"}, + {"gamma", "STAMP"}, + ] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_merge_page_fit_scales_into_the_page(cls): + """The 2x2 image fills [20 30 120 130] of a 200x300 page. Fitted onto a + 400x600 page, that page is drawn at twice the size.""" + document = cls() + document.add_blank_page(width=400, height=600) + document.pages[0].merge_page(PdfReader(IMAGE).pages[0], fit=True) + + image = document.pages[0].images[0] + assert image.bbox == pytest.approx((40.0, 60.0, 240.0, 260.0)) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_merge_page_from_own_document_and_twice(cls): + document = cls(source=THREE) + document.pages[0].merge_page(PdfReader(STAMP).pages[0]) + document.pages[0].merge_page(PdfReader(TWO).pages[1]) + document.pages[2].merge_page(document.pages[1]) + + assert lines(document.pages[0]) >= {"STAMP"} + assert len(document.to_bytes()) > 0 + assert written_widths(document.to_bytes()) == [200.0, 210.0, 220.0] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_merge_page_rejects_stale_and_closed_sources(cls): + other = cls(source=TWO) + handle = other.pages[1] + del other.pages[0] + + document = cls(source=THREE) + with pytest.raises(PdfStaleHandleError): + document.pages[0].merge_page(handle) + + reader = PdfReader(STAMP) + stamp = reader.pages[0] + reader.close() + with pytest.raises(PdfEditError): + document.pages[0].merge_page(stamp) + + # nothing was drawn by the failed calls + assert lines(document.pages[0]) == {"alpha"} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_scale_page(cls): + document = cls(source=IMAGE) + page = document.pages[0] + + page.scale(2, 0.5) + assert page.mediabox == pytest.approx((0.0, 0.0, 400.0, 150.0)) + assert page.cropbox == pytest.approx((0.0, 0.0, 400.0, 150.0)) + assert page.images[0].bbox == pytest.approx((40.0, 15.0, 240.0, 65.0)) + + page.scale_by(0.5) + assert page.mediabox == pytest.approx((0.0, 0.0, 200.0, 75.0)) + + with PdfReader(document.to_bytes()) as reader: + assert reader.pages[0].mediabox == pytest.approx((0.0, 0.0, 200.0, 75.0)) + assert reader.pages[0].images[0].bbox == pytest.approx((20.0, 7.5, 120.0, 32.5)) + + with pytest.raises(PdfEditError): + page.scale_by(0) + # the rejected call changed nothing + assert page.mediabox == pytest.approx((0.0, 0.0, 200.0, 75.0)) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_add_transformation(cls): + document = cls(source=IMAGE) + page = document.pages[0] + + page.add_transformation((1, 0, 0, 1, 10, 5)) + # content moves, the page boundary does not + assert page.mediabox == (0.0, 0.0, 200.0, 300.0) + assert page.images[0].bbox == pytest.approx((30.0, 35.0, 130.0, 135.0)) + + with pytest.raises(PdfEditError) as excinfo: + page.add_transformation((1, 2, 2, 4, 0, 0)) + assert excinfo.value.category is PdfEditErrorCategory.INVALID_EDIT + + with pytest.raises(ValueError): + page.add_transformation((1, 0, 0, 1)) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_stale_page_handle(cls): + document = cls(source=THREE) + first = document.pages[0] + last = document.pages[2] + + # in-place edits and appending at the end keep indices meaningful + first.rotate(90) + document.add_blank_page(width=10, height=10) + assert last.mediabox.width == 220.0 + + del document.pages[1] + + with pytest.raises(PdfStaleHandleError): + last.mediabox + with pytest.raises(PdfStaleHandleError): + first.rotate(90) + with pytest.raises(PdfStaleHandleError): + first.extract_text() + + assert document.pages[0].rotation == 90 + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_write_to_path_and_stream(cls, tmp_path): + document = cls(source=THREE) + del document.pages[0] + + target = tmp_path / "out.pdf" + target.write_bytes(b"previous content") + document.write(target=target) + assert written_widths(target.read_bytes()) == [210.0, 220.0] + assert [p.name for p in tmp_path.iterdir()] == ["out.pdf"] + + stream = BytesIO() + document.write(target=stream) + assert not stream.closed + assert stream.getvalue() == target.read_bytes() + + with pytest.raises(PdfWriteError): + document.write(target=tmp_path / "no-such-directory" / "out.pdf") + + +def test_write_over_the_source_path(tmp_path): + path = tmp_path / "document.pdf" + path.write_bytes(THREE) + + with PdfEditor(source=path) as editor: + del editor.pages[0] + editor.write(target=path) + + assert written_widths(path.read_bytes()) == [210.0, 220.0] + + +# ---------------------------------------------------------------- document level + + +def reread(document): + """What a fresh reader sees in the document as written.""" + return PdfReader(document.to_bytes()) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_write_metadata(cls): + document = cls(source=THREE) + document.add_metadata( + infos={"/Title": "New title", "Subject": "Ünïcode ✓", "Author": None} + ) + + expected = {"Title": "New title", "Subject": "Ünïcode ✓"} + assert document.metadata == expected + with reread(document) as reader: + assert reader.metadata == expected + + if pypdf is not None: + info = pypdf.PdfReader(BytesIO(document.to_bytes())).metadata + assert info.title == "New title" + assert info.subject == "Ünïcode ✓" + assert info.author is None + + with pytest.raises(PdfEditError): + document.add_metadata(infos={"": "nameless"}) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_write_xmp_metadata(cls): + packet = 'é' + + document = cls(source=THREE) + assert document.xmp_metadata is None + + document.set_xmp_metadata(packet=packet) + with reread(document) as reader: + assert reader.xmp_metadata == packet + + document.set_xmp_metadata(packet=None) + with reread(document) as reader: + assert reader.xmp_metadata is None + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_viewer_settings(cls): + document = cls(source=THREE) + assert document.page_layout is None + assert document.page_mode is None + assert document.viewer_preferences is None + assert document.open_destination is None + + document.set_page_layout(layout="/TwoColumnLeft") + document.set_page_mode(mode="UseOutlines") + document.set_viewer_preferences( + preferences={"/HideToolbar": True, "Direction": "/R2L"} + ) + document.set_open_destination(page_no=_test_page_no(2, document)) + + with reread(document) as reader: + assert reader.page_layout == "/TwoColumnLeft" + assert reader.page_mode == "/UseOutlines" + assert reader.viewer_preferences == {"/HideToolbar": True, "/Direction": "/R2L"} + assert reader.open_destination == {"page": 2, "kind": "/Fit", "arguments": []} + + with pytest.raises(PdfEditError) as excinfo: + document.set_page_layout(layout="/Sideways") + assert excinfo.value.category is PdfEditErrorCategory.INVALID_EDIT + + document.set_page_layout(layout=None) + document.set_page_mode(mode=None) + document.set_viewer_preferences(preferences=None) + document.set_open_destination(page_no=_test_page_no(None, document)) + + with reread(document) as reader: + assert reader.page_layout is None + assert reader.page_mode is None + assert reader.viewer_preferences is None + assert reader.open_destination is None + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_page_labels(cls): + document = cls(source=make_pdf([f"p{i}" for i in range(6)])) + assert document.page_labels == ["1", "2", "3", "4", "5", "6"] + + # front matter in roman numerals; the rest keeps counting 3, 4, ... + document.set_page_label( + first_page_no=_test_page_no(0, document), + last_page_no=_test_page_no(1, document), + style="/r", + ) + assert document.page_labels == ["i", "ii", "3", "4", "5", "6"] + + document.set_page_label( + first_page_no=_test_page_no(2, document), + last_page_no=_test_page_no(3, document), + style="/D", + prefix="A-", + start=5, + ) + assert document.page_labels == ["i", "ii", "A-5", "A-6", "5", "6"] + + document.set_page_label( + first_page_no=_test_page_no(5, document), + last_page_no=_test_page_no(5, document), + style="/A", + start=27, + ) + expected = ["i", "ii", "A-5", "A-6", "5", "AA"] + assert document.page_labels == expected + + data = document.to_bytes() + with PdfReader(data) as reader: + assert reader.page_labels == expected + if pypdf is not None: + assert pypdf.PdfReader(BytesIO(data)).page_labels == expected + + with pytest.raises(PdfEditError): + document.set_page_label( + first_page_no=_test_page_no(0, document), + last_page_no=_test_page_no(1, document), + style="/X", + ) + with pytest.raises(IndexError): + document.set_page_label( + first_page_no=_test_page_no(0, document), + last_page_no=_test_page_no(9, document), + style="/D", + ) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_named_destinations(cls): + document = cls(source=THREE) + assert document.named_destinations == {} + + document.add_named_destination( + title="chapter two", page_no=_test_page_no(1, document) + ) + document.add_named_destination(title="end", page_no=_test_page_no(-1, document)) + + with reread(document) as reader: + destinations = reader.named_destinations + assert destinations == { + "chapter two": {"page": 1, "kind": "/Fit", "arguments": []}, + "end": {"page": 2, "kind": "/Fit", "arguments": []}, + } + + +def flat_outline(items, depth: int = 0) -> list[tuple[int, str, int | None]]: + """(depth, title, page) of every outline item, in reading order.""" + result = [] + for item in items: + result.append((depth, item["title"], item["page"])) + result.extend(flat_outline(item["children"], depth + 1)) + return result + + +def pypdf_flat_outline(data: bytes) -> list[tuple[int, str, int | None]]: + assert pypdf is not None + reader = pypdf.PdfReader(BytesIO(data)) + + def walk(items, depth): + result = [] + for item in items: + if isinstance(item, list): + result.extend(walk(item, depth + 1)) + else: + result.append( + (depth, item.title, reader.get_destination_page_number(item)) + ) + return result + + return walk(reader.outline, 0) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_build_an_outline(cls): + document = cls(source=THREE) + assert document.outline == [] + + one = document.add_outline_item(title="One", page_no=_test_page_no(0, document)) + document.add_outline_item( + title="Sub ö", page_no=_test_page_no(1, document), parent=one + ) + document.add_outline_item( + title="Sub two", page_no=_test_page_no(2, document), parent=one + ) + document.add_outline_item(title="Two", page_no=_test_page_no(2, document)) + + expected = [(0, "One", 0), (1, "Sub ö", 1), (1, "Sub two", 2), (0, "Two", 2)] + assert flat_outline(document.outline) == expected + + data = document.to_bytes() + with PdfReader(data) as reader: + assert flat_outline(reader.outline) == expected + if pypdf is not None: + assert pypdf_flat_outline(data) == expected + + with pytest.raises(PdfEditError): + document.add_outline_item( + title="orphan", page_no=_test_page_no(0, document), parent=987654 + ) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_removing_a_page_unhooks_its_bookmarks(cls): + document = cls(source=THREE) + document.add_outline_item(title="One", page_no=_test_page_no(0, document)) + document.add_outline_item(title="Two", page_no=_test_page_no(1, document)) + document.add_outline_item(title="Three", page_no=_test_page_no(2, document)) + document.set_open_destination(page_no=_test_page_no(1, document)) + + del document.pages[1] + + # the bookmark stays as a heading; the ones behind it follow their pages + expected = [(0, "One", 0), (0, "Two", None), (0, "Three", 1)] + with reread(document) as reader: + assert flat_outline(reader.outline) == expected + assert reader.open_destination is None + assert len(reader.pages) == 2 + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_append_brings_the_outline_of_copied_pages(cls): + """build_destination_kinds: three pages, twelve bookmarks, eleven of them + on the first page and one without a destination.""" + source = build_destination_kinds() + with PdfReader(source) as reader: + titles = [item["title"] for item in reader.outline] + pages = [item["page"] for item in reader.outline] + assert len(titles) == 12 + assert pages == [0] * 11 + [None] + + document = cls(source=THREE) + document.append(source=source, page_nos=_source_page_nos(source, [1, 0])) + + # the first page of the source is now page 4 of the document + assert flat_outline(document.outline) == [(0, title, 4) for title in titles[:11]] + + without = cls(source=THREE) + without.append(source=source, page_nos=_source_page_nos(source, [1, 2])) + assert without.outline == [] + + declined = cls(source=THREE) + declined.append(source=source, import_outline=False) + assert declined.outline == [] + + +# ---------------------------------------------------------------- forms + + +def make_form_pdf() -> bytes: + """One 200x200 page with a text field "name" (value "Ada") and a + checkbox "agree" whose on state is /Yes, drawn as a black square.""" + on = "0 g 2 2 16 16 re f" + objects: list[str] = [ + "<< /Type /Catalog /Pages 2 0 R /AcroForm << /Fields [5 0 R 6 0 R] " + "/DA (/Helv 12 Tf 0 g) /DR << /Font << /Helv 3 0 R >> >> >> >>", + "<< /Type /Pages /Kids [4 0 R] /Count 1 >>", + "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica " + "/Encoding /WinAnsiEncoding >>", + "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] " + "/Resources << /Font << /Helv 3 0 R >> >> /Contents 9 0 R " + "/Annots [5 0 R 6 0 R] >>", + "<< /Type /Annot /Subtype /Widget /FT /Tx /T (name) /V (Ada) " + "/Rect [20 150 180 170] /P 4 0 R /F 4 /DA (/Helv 12 Tf 0 g) >>", + "<< /Type /Annot /Subtype /Widget /FT /Btn /T (agree) /V /Off /AS /Off " + "/Rect [20 100 40 120] /P 4 0 R /F 4 " + "/AP << /N << /Yes 7 0 R /Off 8 0 R >> >> >>", + f"<< /Type /XObject /Subtype /Form /BBox [0 0 20 20] /Length {len(on)} >>" + f"\nstream\n{on}\nendstream", + "<< /Type /XObject /Subtype /Form /BBox [0 0 20 20] /Length 0 >>" + "\nstream\n\nendstream", + "<< /Length 0 >>\nstream\n\nendstream", + ] + + out = b"%PDF-1.7\n" + offsets = [] + for index, obj in enumerate(objects, start=1): + offsets.append(len(out)) + out += f"{index} 0 obj\n{obj}\nendobj\n".encode("latin-1") + + startxref = len(out) + out += f"xref\n0 {len(objects) + 1}\n".encode("latin-1") + out += b"0000000000 65535 f \n" + for offset in offsets: + out += f"{offset:010d} 00000 n \n".encode("latin-1") + out += ( + f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R >>\n" + f"startxref\n{startxref}\n%%EOF" + ).encode("latin-1") + return out + + +FORM = make_form_pdf() + + +def test_reader_lists_form_fields(): + with PdfReader(FORM) as reader: + assert reader.has_form is True + assert reader.has_xfa is False + + fields = reader.get_fields() + assert set(fields) == {"name", "agree"} + + name = fields["name"] + assert (name["kind"], name["type"], name["value"]) == ("text", "/Tx", "Ada") + assert name["pages"] == [0] + assert name["read_only"] is False + + agree = fields["agree"] + assert (agree["kind"], agree["value"]) == ("checkbox", "/Off") + assert agree["states"] == ["/Yes"] + + assert reader.get_form_text_fields() == {"name": "Ada"} + + with PdfReader(THREE) as reader: + assert reader.has_form is False + assert reader.get_fields() == {} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_fill_form_fields(cls): + document = cls(source=FORM) + assert ( + document.update_form_field_values( + fields={"name": "Grace Hopper", "agree": True} + ) + == 2 + ) + + data = document.to_bytes() + with PdfReader(data) as reader: + fields = reader.get_fields() + assert fields["name"]["value"] == "Grace Hopper" + assert fields["agree"]["value"] == "/Yes" + # the widget shows the state its field has + widgets = [a for a in reader.pages[0].annotations if a["/Subtype"] == "/Widget"] + assert [w.get("/AS") for w in widgets if w.get("/T") == "agree"] == ["/Yes"] + + if pypdf is not None: + assert pypdf.PdfReader(BytesIO(data)).get_form_text_fields() == { + "name": "Grace Hopper" + } + + assert document.update_form_field_values(fields={"agree": False}) == 1 + with reread(document) as reader: + assert reader.get_fields()["agree"]["value"] == "/Off" + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_fill_form_rejects_what_it_cannot_set(cls): + document = cls(source=FORM) + + with pytest.raises(PdfEditError) as excinfo: + document.update_form_field_values(fields={"no such field": "x"}) + assert excinfo.value.category is PdfEditErrorCategory.INVALID_EDIT + + with pytest.raises(PdfEditError): + document.update_form_field_values(fields={"agree": "/Maybe"}) + + with pytest.raises(PdfEditError): + cls(source=THREE).update_form_field_values(fields={"name": "x"}) + + # nothing was changed by the rejected calls + with reread(document) as reader: + assert reader.get_form_text_fields() == {"name": "Ada"} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_flatten_form_into_page_content(cls): + document = cls(source=FORM) + document.update_form_field_values( + fields={"name": "Grace Hopper", "agree": True}, flatten=True + ) + + data = document.to_bytes() + with PdfReader(data) as reader: + assert reader.has_form is False + assert reader.pages[0].annotations == [] + # the value is ordinary page text now + assert "Grace Hopper" in reader.pages[0].extract_text() + + # the checkbox's on appearance fills [22 38] x [102 118] of the page + image = rendered(data) + assert color_at(image, 30, 110) == (0, 0, 0) + assert color_at(image, 100, 60) == WHITE + + +# ---------------------------------------------------------------- annotations + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_add_read_and_remove_annotations(cls): + document = cls(source=THREE) + assert document.pages[0].annotations == [] + + document.add_uri( + page_no=_test_page_no(0, document), + uri="https://example.org/a b", + rect=(10, 10, 60, 30), + ) + document.add_link( + page_no=_test_page_no(0, document), + rect=(10, 40, 60, 60), + target_page_no=_test_page_no(2, document), + ) + document.add_annotation( + page_no=_test_page_no(1, document), + annotation={ + "/Subtype": "/Text", + "/Rect": [50, 200, 70, 220], + "/Contents": "Nöte ✓", + }, + ) + + data = document.to_bytes() + with PdfReader(data) as reader: + first, second = reader.pages[0].annotations + assert first["/Subtype"] == "/Link" + assert first["/Rect"] == [10, 10, 60, 30] + assert first["/A"]["/URI"] == "https://example.org/a b" + assert "page" not in first + + assert second["/Subtype"] == "/Link" + assert second["page"] == 2 + + (note,) = reader.pages[1].annotations + assert note["/Subtype"] == "/Text" + assert note["/Contents"] == "Nöte ✓" + assert note["/Type"] == "/Annot" + + assert reader.pages[2].annotations == [] + + if pypdf is not None: + page = pypdf.PdfReader(BytesIO(data)).pages[0] + assert [a.get_object()["/Subtype"] for a in page["/Annots"]] == [ + "/Link", + "/Link", + ] + + assert document.remove_links() == 2 + assert document.pages[0].annotations == [] + assert len(document.pages[1].annotations) == 1 + + assert document.remove_annotations() == 1 + assert document.pages[1].annotations == [] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_add_annotation_validates_its_input(cls): + document = cls(source=THREE) + + with pytest.raises(PdfEditError): + document.add_annotation( + page_no=_test_page_no(0, document), annotation={"/Rect": [0, 0, 10, 10]} + ) + with pytest.raises(PdfEditError): + document.add_annotation( + page_no=_test_page_no(0, document), annotation={"/Subtype": "/Text"} + ) + with pytest.raises(IndexError): + document.add_annotation( + page_no=_test_page_no(7, document), + annotation={"/Subtype": "/Text", "/Rect": [0, 0, 1, 1]}, + ) + with pytest.raises(TypeError): + document.add_annotation( + page_no=_test_page_no(0, document), + annotation={"/Subtype": "/Text", "/Rect": object()}, + ) + + assert document.pages[0].annotations == [] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_removing_widgets_removes_their_fields(cls): + document = cls(source=FORM) + + # form fields are kept unless they are asked for by name + assert document.remove_annotations() == 0 + assert set(document.get_fields()) == {"name", "agree"} + + assert document.remove_annotations(subtypes="/Widget") == 2 + with reread(document) as reader: + assert reader.get_fields() == {} + assert reader.pages[0].annotations == [] + + +# ---------------------------------------------------------------- attachments + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_attachments(cls): + document = cls(source=THREE) + assert document.attachments == {} + + document.add_attachment( + filename="notes.txt", + data=b"hello", + description="a note", + mime_type="text/plain", + ) + document.add_attachment(filename="data ü.bin", data=bytes(range(256))) + document.add_attachment(filename="notes.txt", data="replaced") + + data = document.to_bytes() + with PdfReader(data) as reader: + assert reader.attachments == { + "data ü.bin": [bytes(range(256))], + "notes.txt": [b"replaced"], + } + assert reader.get_attachment("notes.txt") == b"replaced" + + info = {item["name"]: item for item in reader.attachment_info} + assert info["data ü.bin"]["size"] == 256 + assert info["notes.txt"]["size"] == len(b"replaced") + + with pytest.raises(PdfEditError): + reader.get_attachment("missing") + + if pypdf is not None: + assert pypdf.PdfReader(BytesIO(data)).attachments == { + "data ü.bin": [bytes(range(256))], + "notes.txt": [b"replaced"], + } + + assert document.remove_attachment(name="notes.txt") is True + assert document.remove_attachment(name="notes.txt") is False + with reread(document) as reader: + assert set(reader.attachments) == {"data ü.bin"} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_attachment_metadata(cls): + document = cls(source=THREE) + document.add_attachment( + filename="notes.txt", + data=b"hello", + description="a note", + mime_type="text/plain", + ) + + with reread(document) as reader: + (info,) = reader.attachment_info + assert info["filename"] == "notes.txt" + assert info["description"] == "a note" + assert info["mime_type"] == "text/plain" + assert info["creation_date"].startswith("D:") + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_document_scripts_are_stored_and_can_be_stripped(cls): + document = cls(source=THREE) + assert document.javascript == {} + + document.add_js(javascript="app.alert('one');") + document.add_js(javascript="app.alert('zwei ü');", name="second") + + with reread(document) as reader: + assert reader.javascript == { + "script-1": "app.alert('one');", + "second": "app.alert('zwei ü');", + } + + assert document.remove_javascript() == 2 + with reread(document) as reader: + assert reader.javascript == {} + + +# ---------------------------------------------------------------- output options + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_encrypt_with_permissions(cls): + document = cls(source=THREE) + document.encrypt( + user_password="user", + owner_password="owner", + allow_print=False, + allow_extract=False, + allow_modify=False, + ) + data = document.to_bytes() + + with PdfReader(data, password="user") as reader: + permissions = reader.permissions + assert permissions is not None + assert permissions["print"] is False + assert permissions["extract"] is False + assert permissions["modify"] is False + assert permissions["annotate"] is True + assert permissions["fill_forms"] is True + assert permissions["assemble"] is True + # reported, not enforced + assert reader.pages[0].extract_text() == "alpha" + + with PdfReader(THREE) as reader: + assert reader.permissions is None + + document.encrypt(user_password="user", allow_print="low") + with PdfReader(document.to_bytes(), password="user") as reader: + assert reader.permissions["print"] is True + assert reader.permissions["print_high_quality"] is False + + with pytest.raises(ValueError): + document.encrypt(user_password="user", allow_print="sometimes") + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_output_options(cls): + document = cls(source=THREE) + plain = document.to_bytes() + assert b"/Linearized" not in plain + + document.set_output_options(linearize=True) + linearized = document.to_bytes() + assert b"/Linearized" in linearized + assert written_widths(linearized) == [200.0, 210.0, 220.0] + + document.set_output_options(object_streams="generate") + packed = document.to_bytes() + assert b"/ObjStm" in packed + assert written_widths(packed) == [200.0, 210.0, 220.0] + + document.set_output_options(object_streams="disable", compress_streams=False) + loose = document.to_bytes() + assert b"/ObjStm" not in loose + # the page content is stored as written + assert b"(alpha) Tj" in loose + with PdfReader(loose) as reader: + assert reader.pages[0].extract_text() == "alpha" + + with pytest.raises(PdfEditError): + document.set_output_options(object_streams="sometimes") + + +def test_reader_has_no_document_level_editing(): + with PdfReader(FORM) as reader: + for name in ( + "add_metadata", + "set_page_label", + "add_outline_item", + "update_form_field_values", + "flatten_annotations", + "add_annotation", + "add_attachment", + "add_js", + "encrypt", + "set_output_options", + ): + assert not hasattr(reader, name) + for name in ( + "set_info", + "set_form_values", + "add_annotation", + "add_attachment", + "set_encryption", + ): + assert not hasattr(reader._native, name) + + +# ---------------------------------------------------------------- rendering + +RED = (255, 0, 0) +BLUE = (0, 0, 255) +WHITE = (255, 255, 255) + +# A red square over [50 150]^2 and a blue one over [100 180]^2, each on its +# own 200x200 page: they overlap in [100 150]^2. +RED_SQUARE = simple_page_pdf("1 0 0 rg 50 50 100 100 re f") +BLUE_SQUARE = simple_page_pdf("0 0 1 rg 100 100 80 80 re f") + + +def rendered(data: bytes, page_index: int = 0): + """The page as pypdfium2 draws it, one pixel per point: a renderer that + shares no code with docling-parse.""" + pdfium = pytest.importorskip("pypdfium2") + + document = pdfium.PdfDocument(data) + try: + return document[page_index].render(scale=1).to_pil().convert("RGB") + finally: + document.close() + + +def color_at(image, x: float, y: float) -> tuple[int, int, int]: + """The pixel at PDF coordinates (x, y), origin bottom-left.""" + return image.getpixel((int(x), image.height - 1 - int(y))) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +@pytest.mark.parametrize(("over", "overlap"), [(True, BLUE), (False, RED)]) +def test_merge_page_stacking_order_as_rendered(cls, over, overlap): + document = cls(source=RED_SQUARE) + document.pages[0].merge_page(PdfReader(BLUE_SQUARE).pages[0], over=over) + + image = rendered(document.to_bytes()) + + assert image.size == (200, 200) + assert color_at(image, 10, 10) == WHITE + assert color_at(image, 60, 60) == RED + assert color_at(image, 165, 165) == BLUE + # the only place where the order of the two pages is visible + assert color_at(image, 125, 125) == overlap + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_overlay_does_not_inherit_the_page_s_graphics_state(cls): + """The page ends with a scaled CTM and a green fill still in force. An + overlay drawn after it must not be scaled or recolored by them.""" + base = simple_page_pdf("0.5 0 0 0.5 0 0 cm 0 1 0 rg") + + document = cls(source=base) + document.pages[0].merge_page(PdfReader(BLUE_SQUARE).pages[0]) + + image = rendered(document.to_bytes()) + assert color_at(image, 165, 165) == BLUE + # where the square would be if the page's 0.5 scale had leaked into it + assert color_at(image, 60, 60) == WHITE + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_merge_transformed_pages_as_rendered(cls): + """The blue square covers [100 180]^2 of its page.""" + blue = PdfReader(BLUE_SQUARE).pages[0] + + document = cls() + for _ in range(4): + document.add_blank_page(width=200, height=200) + + # halved about the origin: [50 90]^2 + document.pages[0].merge_scaled_page(blue, 0.5) + # moved left and down by 100: [0 80]^2 + document.pages[1].merge_translated_page(blue, -100, -100) + # a quarter turn counter-clockwise takes (x, y) to (-y, x); moved right + # by 200 the square lands on x in [20 100], y in [100 180] + document.pages[2].merge_rotated_page(blue, 90) + document.pages[2].add_transformation((1, 0, 0, 1, 200, 0)) + # the same, as one matrix + document.pages[3].merge_transformed_page(blue, (0, 1, -1, 0, 200, 0)) + + data = document.to_bytes() + + scaled = rendered(data, 0) + assert color_at(scaled, 70, 70) == BLUE + assert color_at(scaled, 140, 140) == WHITE + + translated = rendered(data, 1) + assert color_at(translated, 40, 40) == BLUE + assert color_at(translated, 140, 140) == WHITE + + for index in (2, 3): + turned = rendered(data, index) + assert color_at(turned, 60, 140) == BLUE + assert color_at(turned, 140, 140) == WHITE + assert color_at(turned, 60, 60) == WHITE + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_transfer_rotation_to_content_keeps_the_picture(cls): + document = cls(source=RED_SQUARE) + page = document.pages[0] + page.cropbox = (50, 50, 200, 150) + page.rotate(90) + before = rendered(document.to_bytes()) + + page.transfer_rotation_to_content() + assert page.rotation == 0 + + after = rendered(document.to_bytes()) + assert after.size == before.size == (100, 150) + # Compared away from the square's edges, which lie on multiples of 50: + # the two files may antialias an edge differently, not move it. + points = [(x, y) for x in range(5, 100, 10) for y in range(5, 150, 10)] + assert [after.getpixel(p) for p in points] == [before.getpixel(p) for p in points] + assert {before.getpixel(p) for p in points} == {RED, WHITE} + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_scale_and_transformation_as_rendered(cls): + document = cls(source=RED_SQUARE) + document.pages[0].scale_by(0.5) + + image = rendered(document.to_bytes()) + assert image.size == (100, 100) + assert color_at(image, 50, 50) == RED + assert color_at(image, 10, 10) == WHITE + assert color_at(image, 90, 90) == WHITE + + document = cls(source=RED_SQUARE) + document.pages[0].add_transformation((1, 0, 0, 1, 40, 0)) + + image = rendered(document.to_bytes()) + assert image.size == (200, 200) + assert color_at(image, 60, 100) == WHITE + assert color_at(image, 180, 100) == RED + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_rotation_and_crop_as_rendered(cls): + document = cls(source=RED_SQUARE) + page = document.pages[0] + page.cropbox = (50, 50, 200, 150) + page.rotate(90) + + image = rendered(document.to_bytes()) + # a 150x100 crop, turned a quarter: 100 wide, 150 high + assert image.size == (100, 150) + + +# ---------------------------------------------------------------- bookmark editing + + +def pypdf_titles(data: bytes) -> list[str]: + """The outline titles as pypdf reads them, depth first.""" + assert pypdf is not None + + def walk(items): + titles = [] + for item in items: + titles.extend(walk(item) if isinstance(item, list) else [item.title]) + return titles + + return walk(pypdf.PdfReader(BytesIO(data)).outline) + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_edit_bookmarks(cls): + document = cls(source=make_pdf([f"p{i}" for i in range(5)])) + + one = document.add_outline_item(title="One", page_no=_test_page_no(0, document)) + two = document.add_outline_item(title="Two", page_no=_test_page_no(1, document)) + sub = document.add_outline_item( + title="Sub", page_no=_test_page_no(2, document), parent=one + ) + web = document.add_outline_item( + title="Web", page_no=_test_page_no(None, document), url="https://example.org" + ) + + document.update_outline_item( + item_id=two, title="Second", page_no=_test_page_no(3, document) + ) + document.move_outline_item(item_id=sub, parent=two) + document.move_outline_item(item_id=web, index=0) + + expected = [(0, "Web", None), (0, "One", 0), (0, "Second", 3), (1, "Sub", 2)] + assert flat_outline(document.outline) == expected + + data = document.to_bytes() + with PdfReader(data) as reader: + assert flat_outline(reader.outline) == expected + assert reader.outline[0]["url"] == "https://example.org" + assert reader.outline[1]["url"] is None + if pypdf is not None: + assert pypdf_titles(data) == ["Web", "One", "Second", "Sub"] + + # an item cannot go below itself or below its own children + with pytest.raises(PdfEditError): + document.move_outline_item(item_id=two, parent=sub) + with pytest.raises(PdfEditError): + document.move_outline_item(item_id=two, parent=two) + + document.remove_outline_item(item_id=one) + assert flat_outline(document.outline) == [ + (0, "Web", None), + (0, "Second", 3), + (1, "Sub", 2), + ] + + # removing the target leaves a heading + document.update_outline_item(item_id=two, page_no=_test_page_no(None, document)) + assert flat_outline(document.outline)[1] == (0, "Second", None) + + with pytest.raises(PdfEditError): + document.remove_outline_item(item_id=987654) + + document.clear_outline() + assert document.outline == [] + with reread(document) as reader: + assert reader.outline == [] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_bookmark_style_and_position(cls): + document = cls(source=THREE) + item = document.add_outline_item( + title="Styled", + page_no=_test_page_no(1, document), + color="#ff0000", + bold=True, + italic=True, + top=200, + zoom=2, + ) + document.add_outline_item( + title="Child", page_no=_test_page_no(2, document), parent=item + ) + document.update_outline_item(item_id=item, is_open=False) + + with PdfEditor(source=document.to_bytes()) as editor: + (entry,) = editor.outline + assert entry["open"] is False + assert entry["page"] == 1 + + raw = editor.get_object(object_id=entry["id"]) + assert raw["/C"] == [1, 0, 0] + assert raw["/F"] == 3 # italic and bold + assert raw["/Dest"][1:] == ["/XYZ", None, 200, 2] + # one child, folded away + assert raw["/Count"] == -1 + + document.update_outline_item(item_id=item, color=None, bold=False, italic=False) + with PdfEditor(source=document.to_bytes()) as editor: + raw = editor.get_object(object_id=editor.outline[0]["id"]) + assert "/C" not in raw + assert "/F" not in raw + + with pytest.raises(ValueError): + document.add_outline_item( + title="both", page_no=_test_page_no(0, document), url="https://example.org" + ) + with pytest.raises(ValueError): + document.add_outline_item( + title="position without page", page_no=_test_page_no(None, document), top=10 + ) + with pytest.raises(ValueError): + document.add_outline_item( + title="bad color", page_no=_test_page_no(0, document), color=(2, 0, 0) + ) + + +# ---------------------------------------------------------------- creating form fields + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_create_form_fields(cls): + document = cls(source=THREE) + document.add_text_field( + page_no=_test_page_no(0, document), + name="name", + rect=(20, 250, 180, 270), + value="Ada", + tooltip="Your name", + ) + document.add_text_field( + page_no=_test_page_no(0, document), + name="notes", + rect=(20, 180, 180, 240), + multiline=True, + ) + document.add_checkbox( + page_no=_test_page_no(0, document), + name="agree", + rect=(20, 150, 36, 166), + checked=True, + ) + document.add_choice_field( + page_no=_test_page_no(0, document), + name="country", + rect=(20, 120, 180, 140), + options=["Belgium", "Switzerland"], + value="Switzerland", + ) + document.add_radio_group( + page_no=_test_page_no(1, document), + name="plan", + buttons={"basic": (20, 250, 36, 266), "premium": (60, 250, 76, 266)}, + selected="premium", + ) + document.add_signature_field( + page_no=_test_page_no(2, document), name="signature", rect=(20, 20, 180, 60) + ) + + data = document.to_bytes() + with PdfReader(data) as reader: + fields = reader.get_fields() + assert {name: field["kind"] for name, field in fields.items()} == { + "name": "text", + "notes": "text", + "agree": "checkbox", + "country": "choice", + "plan": "radio", + "signature": "signature", + } + assert fields["name"]["value"] == "Ada" + assert fields["name"]["alternate_name"] == "Your name" + assert fields["name"]["rects"] == [[20, 250, 180, 270]] + assert fields["agree"]["value"] == "/Yes" + assert fields["country"]["value"] == "Switzerland" + assert fields["country"]["choices"] == ["Belgium", "Switzerland"] + assert fields["plan"]["value"] == "/premium" + assert fields["plan"]["states"] == ["/basic", "/premium"] + assert fields["plan"]["rects"] == [ + [20, 250, 36, 266], + [60, 250, 76, 266], + ] + assert fields["plan"]["pages"] == [1] + assert fields["signature"]["pages"] == [2] + + if pypdf is not None: + reader = pypdf.PdfReader(BytesIO(data)) + assert set(reader.get_fields()) == set(fields) + assert reader.get_form_text_fields()["name"] == "Ada" + + # the new fields are filled like any other + document.update_form_field_values( + fields={"name": "Grace", "agree": False, "country": "Belgium", "plan": "/basic"} + ) + with reread(document) as reader: + values = {name: field["value"] for name, field in reader.get_fields().items()} + assert values["name"] == "Grace" + assert values["agree"] == "/Off" + assert values["country"] == "Belgium" + assert values["plan"] == "/basic" + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_radio_group_update_and_remove(cls): + document = cls(source=THREE) + document.add_radio_group( + page_no=_test_page_no(1, document), + name="plan", + buttons={"basic": (20, 250, 36, 266), "premium": (60, 250, 76, 266)}, + ) + document.add_text_field( + page_no=_test_page_no(1, document), + name="keep", + rect=(20, 200, 180, 220), + value="Still here", + ) + + for selected in ("premium", "basic", "Off", "premium"): + assert document.update_form_field_values(fields={"plan": selected}) == 1 + with reread(document) as reader: + assert reader.get_fields()["plan"]["value"] == f"/{selected}" + widgets = [ + a + for a in reader.pages[1].annotations + if a["/Subtype"] == "/Widget" and "/AS" in a + ] + assert [a["/AS"] for a in widgets] == [ + "/basic" if selected == "basic" else "/Off", + "/premium" if selected == "premium" else "/Off", + ] + + # A group has two widgets, so a single replacement rectangle is invalid. + with pytest.raises(PdfEditError): + document.update_form_field(name="plan", rect=(20, 200, 36, 216)) + + document.update_form_field( + name="plan", new_name="subscription", read_only=True, tooltip="Choose a plan" + ) + with reread(document) as reader: + fields = reader.get_fields() + assert set(fields) == {"subscription", "keep"} + assert fields["subscription"]["states"] == ["/basic", "/premium"] + assert fields["subscription"]["read_only"] is True + assert fields["subscription"]["alternate_name"] == "Choose a plan" + + document.remove_form_field(name="subscription") + with reread(document) as reader: + assert set(reader.get_fields()) == {"keep"} + widgets = [a for a in reader.pages[1].annotations if a["/Subtype"] == "/Widget"] + assert len(widgets) == 1 + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_created_fields_render_and_flatten(cls): + document = cls(source=THREE) + document.add_text_field( + page_no=_test_page_no(0, document), + name="name", + rect=(20, 250, 180, 270), + value="Visible value", + ) + document.add_radio_group( + page_no=_test_page_no(0, document), + name="plan", + buttons={"basic": (20, 200, 36, 216), "premium": (60, 200, 76, 216)}, + selected="premium", + ) + document.flatten_annotations() + + data = document.to_bytes() + with PdfReader(data) as reader: + assert reader.has_form is False + assert "Visible value" in reader.pages[0].extract_text() + + image = rendered(data) + # the dot of the selected button, and none in the other one + assert color_at(image, 68, 208) == (0, 0, 0) + assert color_at(image, 28, 208) == WHITE + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_create_form_fields_rejects_bad_input(cls): + document = cls(source=FORM) + + # the existing form keeps its fields when new ones are added to it + document.add_text_field( + page_no=_test_page_no(0, document), name="city", rect=(20, 60, 180, 80) + ) + assert {"name", "agree", "city"} <= set(document.get_fields()) + + with pytest.raises(PdfEditError): + document.add_text_field( + page_no=_test_page_no(0, document), name="city", rect=(20, 30, 180, 50) + ) # taken + with pytest.raises(PdfEditError): + document.add_text_field( + page_no=_test_page_no(0, document), name="a.b", rect=(20, 30, 180, 50) + ) # a period + with pytest.raises(PdfEditError): + document.add_text_field( + page_no=_test_page_no(0, document), name="flat", rect=(20, 30, 20, 50) + ) # no width + with pytest.raises(PdfEditError): + document.add_choice_field( + page_no=_test_page_no(0, document), + name="pick", + rect=(20, 30, 180, 50), + options=["a", "b"], + value="c", + ) + with pytest.raises(PdfEditError): + document.add_radio_group( + page_no=_test_page_no(0, document), + name="group", + buttons={"a": (0, 0, 10, 10)}, + selected="z", + ) + with pytest.raises(PdfEditError): + document.add_radio_group( + page_no=_test_page_no(0, document), + name="group", + buttons={"Off": (0, 0, 10, 10)}, + ) + with pytest.raises(IndexError): + document.add_checkbox( + page_no=_test_page_no(9, document), name="box", rect=(0, 0, 10, 10) + ) + + # nothing half-made was left behind + assert set(document.get_fields()) == {"name", "agree", "city"} + + # a choice field that can be typed into takes other values + document.add_choice_field( + page_no=_test_page_no(0, document), + name="pick", + rect=(20, 30, 180, 50), + options=["a", "b"], + value="c", + editable=True, + ) + assert document.get_fields()["pick"]["value"] == "c" + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_update_and_remove_form_fields(cls): + document = cls(source=THREE) + document.add_text_field( + page_no=_test_page_no(0, document), + name="name", + rect=(20, 250, 180, 270), + value="Ada", + ) + document.add_checkbox( + page_no=_test_page_no(0, document), name="agree", rect=(20, 150, 36, 166) + ) + document.add_choice_field( + page_no=_test_page_no(0, document), + name="country", + rect=(20, 120, 180, 140), + options=["Belgium"], + ) + + document.update_form_field( + name="name", + new_name="full_name", + rect=(20, 200, 200, 230), + read_only=True, + required=True, + tooltip="Full name", + ) + document.update_form_field(name="country", options=["Belgium", "Italy"]) + + with reread(document) as reader: + fields = reader.get_fields() + assert "name" not in fields + renamed = fields["full_name"] + assert renamed["value"] == "Ada" + assert renamed["read_only"] is True + assert renamed["flags"] & 2 # required + assert renamed["rects"] == [[20, 200, 200, 230]] + assert renamed["alternate_name"] == "Full name" + assert fields["country"]["choices"] == ["Belgium", "Italy"] + + document.update_form_field(name="full_name", tooltip=None, read_only=False) + renamed = document.get_fields()["full_name"] + assert renamed["alternate_name"] == "full_name" + assert renamed["read_only"] is False + + with pytest.raises(PdfEditError): + document.update_form_field( + name="full_name", options=["a"] + ) # not a choice field + with pytest.raises(PdfEditError): + document.update_form_field(name="agree", new_name="full_name") # taken + with pytest.raises(PdfEditError): + document.update_form_field(name="missing", read_only=True) + + document.remove_form_field(name="agree") + with reread(document) as reader: + assert set(reader.get_fields()) == {"full_name", "country"} + widgets = [a for a in reader.pages[0].annotations if a["/Subtype"] == "/Widget"] + assert len(widgets) == 2 + + with pytest.raises(PdfEditError): + document.remove_form_field(name="agree") + + +# ---------------------------------------------------------------- drawing text + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_draw_text(cls): + document = cls(source=THREE) + page = document.pages[1] + + page.draw_text("Stamped (1) \\ ok", 20, 50, size=14, font="Times-Bold") + page.draw_text("Größe € one\nline two", 20, 100) + + with reread(document) as reader: + text = reader.pages[1].extract_text() + for expected in ("beta", "Stamped (1) \\ ok", "Größe € one", "line two"): + assert expected in text + + with pytest.raises(PdfUnsupportedError): + page.draw_text("日本語", 20, 20) + with pytest.raises(PdfEditError): + page.draw_text("x", 20, 20, font="Comic Sans") + with pytest.raises(PdfEditError): + page.draw_text("x", 20, 20, size=0) + + # the rejected calls left the page as it was + with reread(document) as reader: + assert "日本語" not in reader.pages[1].extract_text() + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_draw_text_color_as_rendered(cls): + document = cls() + page = document.add_blank_page(width=200, height=200) + page.draw_text("MM", 10, 40, size=120, font="Helvetica-Bold", color="#0000ff") + + image = rendered(document.to_bytes()) + # get_flattened_data() requires Pillow 12.1.0; we still support Pillow 10. + # Remove the hasattr check and getdata() fallback when the minimum is >=12.1.0. + pixels = ( + image.get_flattened_data() + if hasattr(image, "get_flattened_data") + else image.getdata() + ) + blue = [p for p in pixels if p[2] > 200 and p[0] < 60 and p[1] < 60] + assert len(blue) > 1000 + + +# ---------------------------------------------------------------- contents pages + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_table_of_contents_page(cls): + document = cls(source=make_pdf([f"p{i}" for i in range(4)])) + one = document.add_outline_item( + title="Introduction", page_no=_test_page_no(0, document) + ) + document.add_outline_item( + title="Scope", page_no=_test_page_no(1, document), parent=one + ) + document.add_outline_item(title="Results", page_no=_test_page_no(3, document)) + + pages = document.add_table_of_contents(page_size="A4") + assert [page.index for page in pages] == [0] + assert len(document.pages) == 5 + + # the bookmarks follow their pages behind the new one + assert flat_outline(document.outline) == [ + (0, "Introduction", 1), + (1, "Scope", 2), + (0, "Results", 4), + ] + + with reread(document) as reader: + contents = reader.pages[0] + assert contents.mediabox == pytest.approx((0, 0, 595.28, 841.89)) + text = contents.extract_text() + for expected in ("Contents", "Introduction", "Scope", "Results"): + assert expected in text + assert [a["page"] for a in contents.annotations] == [1, 2, 4] + + assert cls(source=THREE).add_table_of_contents() == [] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_table_of_contents_spans_pages_and_depth(cls): + document = cls(source=make_pdf([f"p{i}" for i in range(3)])) + for number in range(60): + parent = document.add_outline_item( + title=f"Chapter {number}", page_no=_test_page_no(number % 3, document) + ) + document.add_outline_item( + title=f"Section {number}.1", + page_no=_test_page_no(number % 3, document), + parent=parent, + ) + + pages = document.add_table_of_contents(page_size="A5", max_depth=0) + assert len(pages) > 1 + + links = [] + with reread(document) as reader: + for page in pages: + links.extend(a["page"] for a in reader.pages[page.index].annotations) + # one link per top-level bookmark, to the pages behind the contents + assert len(links) == 60 + assert set(links) == {len(pages), len(pages) + 1, len(pages) + 2} + + +# ---------------------------------------------------------------- pages from images + + +def image_bytes(mode: str, size, color, fmt: str, **options) -> bytes: + from PIL import Image + + out = BytesIO() + Image.new(mode, size, color).save(out, fmt, **options) + return out.getvalue() + + +def test_pdf_from_images(tmp_path): + jpeg = image_bytes("RGB", (300, 200), (200, 30, 30), "JPEG", dpi=(150, 150)) + png = image_bytes("RGBA", (100, 50), (0, 0, 255, 128), "PNG") + gray = tmp_path / "gray.png" + gray.write_bytes(image_bytes("L", (40, 40), 128, "PNG")) + + writer = PdfWriter.from_images([jpeg, BytesIO(png), gray]) + data = writer.to_bytes() + + with PdfReader(data) as reader: + boxes = [page.mediabox for page in reader.pages] + assert boxes[0] == pytest.approx((0, 0, 144, 96)) # 300 x 200 px at 150 dpi + assert boxes[1] == pytest.approx((0, 0, 100, 50)) # no resolution: 1 px = 1 pt + assert boxes[2] == pytest.approx((0, 0, 40, 40)) + + (photo,) = reader.pages[0].images + # the JPEG file is stored as it is + assert photo.format == "jpeg" + assert photo.data == jpeg + assert photo.bbox == pytest.approx((0, 0, 144, 96)) + + (shade,) = reader.pages[2].images + assert (shade.width, shade.height, shade.mode) == (40, 40, "L") + + # half-transparent blue over the white page + red, green, blue = color_at(rendered(data, 1), 50, 25) + assert blue > 200 and 100 < red < 160 and 100 < green < 160 + + if pypdf is not None: + assert len(pypdf.PdfReader(BytesIO(data)).pages) == 3 + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_image_on_a_fixed_page_size(cls): + jpeg = image_bytes("RGB", (300, 200), (30, 200, 30), "JPEG") + + document = cls(source=THREE) + (page,) = document.add_image( + image=jpeg, page_size="A4", margin=36, before_page_no=_test_page_no(1, document) + ) + assert page.index == 1 + assert len(document.pages) == 4 + + assert page.mediabox == pytest.approx((0, 0, 595.28, 841.89)) + (image,) = page.images + # 300 x 200 scaled to the 523.28 pt between the margins, centered + height = 523.28 * 200 / 300 + bottom = (841.89 - height) / 2 + assert image.bbox == pytest.approx((36, bottom, 559.28, bottom + height), abs=0.01) + + (landscape,) = document.add_image(image=jpeg, page_size=(842, 595)) + assert landscape.mediabox == pytest.approx((0, 0, 842, 595)) + + with pytest.raises(ValueError): + document.add_image(image=jpeg, page_size="B7") + with pytest.raises(ValueError): + document.add_image(image=jpeg, page_size="A4", margin=400) + + +def test_image_orientation_frames_and_cmyk(): + from PIL import Image + + exif = Image.Exif() + exif[0x0112] = 6 # stored turned: show it rotated a quarter clockwise + turned = image_bytes("RGB", (300, 200), (200, 30, 30), "JPEG", exif=exif.tobytes()) + + first = Image.new("RGB", (60, 40), (255, 0, 0)) + second = Image.new("RGB", (60, 40), (0, 0, 255)) + frames = BytesIO() + first.save(frames, "TIFF", save_all=True, append_images=[second]) + + cmyk = image_bytes("CMYK", (50, 50), (0, 255, 255, 0), "JPEG") + + writer = PdfWriter() + assert len(writer.add_image(turned)) == 1 + # one page per frame + assert len(writer.add_image(frames.getvalue())) == 2 + writer.add_image(cmyk) + + data = writer.to_bytes() + with PdfReader(data) as reader: + assert reader.pages[0].rotation == 90 + assert reader.pages[0].mediabox == pytest.approx((0, 0, 300, 200)) + assert len(reader.pages) == 4 + + # shown portrait, as the camera meant it + assert rendered(data, 0).size == (200, 300) + assert color_at(rendered(data, 1), 30, 20) == pytest.approx(RED, abs=8) + assert color_at(rendered(data, 2), 30, 20) == pytest.approx(BLUE, abs=8) + # a CMYK JPEG keeps its colors: no magenta-and-yellow cast inverted to cyan + red, green, blue = color_at(rendered(data, 3), 25, 25) + assert red > 180 and green < 90 and blue < 90 + + +def test_image_errors(): + writer = PdfWriter() + with pytest.raises(OSError): + writer.add_image(b"not an image") + with pytest.raises(TypeError): + writer.add_image(12345) + assert len(writer.pages) == 0 + + +def test_reader_cannot_create_content(): + with PdfReader(THREE) as reader: + for name in ( + "add_text_field", + "add_checkbox", + "update_form_field", + "remove_form_field", + "update_outline_item", + "remove_outline_item", + "add_table_of_contents", + "add_image", + "from_images", + ): + assert not hasattr(reader, name) + assert not hasattr(reader.pages[0], "draw_text") + for name in ( + "add_form_field", + "draw_text", + "insert_image_page", + "clear_outline", + ): + assert not hasattr(reader._native, name) + + +# ---------------------------------------------------------------- editor only + + +def test_editor_reads_until_first_change(): + with PdfEditor(source=THREE) as editor: + assert editor.is_modified is False + assert editor.pages[0].extract_text() == "alpha" + assert editor.is_modified is False + + editor.pages[0].rotate(90) + assert editor.is_modified is True + assert editor.pages[0].extract_text() == "alpha" + + assert isinstance(editor.annotations, dict) + + +OBJECT_REFERENCE = re.compile(r"^\d+ \d+( R)?$") + + +def text_leaves(value) -> list[str]: + """Every string in a JSON-like value, sorted, without object references. + + A rewrite renumbers the file's objects, so "6 0" before may be "9 0" + after; everything else a document says about itself must not change. + """ + found: list[str] = [] + + def walk(item) -> None: + if isinstance(item, str): + if not OBJECT_REFERENCE.match(item): + found.append(item) + elif isinstance(item, dict): + for key, child in item.items(): + found.append(str(key)) + walk(child) + elif isinstance(item, (list, tuple)): + for child in item: + walk(child) + + walk(value) + return sorted(found) + + +@pytest.mark.parametrize( + ("build", "marker"), + [ + (_tagged_pdf, "A grey square"), + (_form_pdf, "Ada Lovelace"), + (build_destination_kinds, "FitBV"), + ], + ids=["structure-tree", "acroform", "outline"], +) +def test_clone_keeps_document_level_content(build, marker): + """A clone is a second parse of the same bytes, so the structure tree, the + form and the outline survive an edit and a rewrite without remapping.""" + source = build() + + with PdfEditor(source=source) as editor: + before = text_leaves(editor.annotations) + assert marker in before + assert editor.is_modified is False + + # an edit that changes no geometry: make the default crop box explicit + page = editor.pages[0] + page.cropbox = page.mediabox + assert editor.is_modified is True + + assert text_leaves(editor.annotations) == before + data = editor.to_bytes() + + with PdfEditor(source=data) as reopened: + assert text_leaves(reopened.annotations) == before + + +def encrypted_pdf(password: str) -> bytes: + pypdf = pytest.importorskip("pypdf", reason="pypdf writes the encrypted fixture") + + writer = pypdf.PdfWriter(clone_from=BytesIO(THREE)) + writer.encrypt(password) + out = BytesIO() + writer.write(out) + return out.getvalue() + + +def test_encrypted_source_needs_its_password(): + data = encrypted_pdf("secret") + + with pytest.raises(PdfPasswordError) as excinfo: + PdfReader(data) + assert excinfo.value.password_supplied is False + + with pytest.raises(PdfPasswordError) as excinfo: + PdfReader(data, password="wrong") + assert excinfo.value.password_supplied is True + + with PdfReader(data, password="secret") as reader: + assert reader.is_encrypted is True + encryption = reader.encryption + assert encryption is not None + assert {"revision", "version", "permissions", "stream_method"} <= set( + encryption + ) + assert reader.pages[1].extract_text() == "beta" + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_encrypted_source_is_written_in_the_clear(cls): + """The documented default: output is unencrypted unless asked otherwise.""" + document = cls(source=encrypted_pdf("secret"), password="secret") + del document.pages[0] + + with PdfReader(document.to_bytes()) as reader: + assert reader.is_encrypted is False + assert [page.extract_text() for page in reader.pages] == ["beta", "gamma"] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_pages_of_an_encrypted_document_can_be_imported(cls): + document = cls() + document.append( + source=encrypted_pdf("secret"), + page_nos=[3], + password="secret", + ) + stamp = PdfReader(STAMP).pages[0] + document.pages[0].merge_page(stamp) + + with PdfReader(document.to_bytes()) as reader: + assert reader.is_encrypted is False + assert lines(reader.pages[0]) == {"gamma", "STAMP"} + assert widths(reader) == [220.0] + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_encrypt_output(cls): + document = cls(source=THREE) + document.encrypt(user_password="secret") + data = document.to_bytes() + + with pytest.raises(PdfPasswordError): + PdfReader(data) + + with PdfReader(data, password="secret") as reader: + assert reader.is_encrypted is True + encryption = reader.encryption + assert encryption is not None + assert encryption["revision"] == 6 + assert encryption["stream_method"] == "aesv3" + assert [page.extract_text() for page in reader.pages] == [ + "alpha", + "beta", + "gamma", + ] + + # the encrypted state is still readable and reusable by its owner + assert document.pages[2].extract_text() == "gamma" + assert document.is_encrypted is True + other = cls() + other.append(source=document, page_nos=_source_page_nos(document, [1])) + assert other.pages[0].extract_text() == "beta" + assert other.is_encrypted is False + + document.remove_encryption() + with PdfReader(document.to_bytes()) as reader: + assert reader.is_encrypted is False + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_encrypt_with_owner_password_only(cls): + document = cls(source=THREE) + document.encrypt(user_password="", owner_password="owner") + + # no user password: anyone can open it, and it is still encrypted + with PdfReader(document.to_bytes()) as reader: + assert reader.is_encrypted is True + assert reader.pages[0].extract_text() == "alpha" + + with pytest.raises(PdfEditError) as excinfo: + document.encrypt(user_password="") + assert excinfo.value.category is PdfEditErrorCategory.INVALID_EDIT + + +def test_editor_shows_raw_objects(): + with PdfEditor(source=THREE) as editor: + trailer = editor.trailer + assert trailer["/Size"] > 0 + assert "/Root" in trailer + + catalog = editor.root_object + assert catalog["/Type"] == "/Catalog" + assert catalog["/Pages"]["/Count"] == 3 + + # object 3 of the fixture is its font + assert editor.get_object(object_id=3) == { + "/Type": "/Font", + "/Subtype": "/Type1", + "/BaseFont": "/Helvetica", + } + + with pytest.raises(PdfEditError): + editor.get_object(object_id=9999) + with pytest.raises(ValueError): + editor.get_object(object_id=0) + + # reading objects is not an edit + assert editor.is_modified is False + + +def test_page_lookups(): + with PdfReader(FORM) as reader: + page = reader.pages[0] + assert reader.get_page_number(page) == 0 + assert [p.index for p in reader.get_pages_showing_field("agree")] == [0] + with pytest.raises(KeyError): + reader.get_pages_showing_field("missing") + with pytest.raises(ValueError): + reader.get_page_number(PdfReader(THREE).pages[0]) + + +def test_writer_does_not_expose_editor_only_operations(): + writer = PdfWriter(THREE) + assert not hasattr(writer, "annotations") + assert not hasattr(writer._native, "annotations") + + +# ---------------------------------------------------------------- threading + + +def test_one_editor_shared_between_threads(): + """Thread safe, not parallel: mixed calls on one instance are serialized + and leave a document that still writes and reads back.""" + editor = PdfEditor(source=make_pdf([f"page{i}" for i in range(12)])) + errors: list[BaseException] = [] + + def work(seed: int) -> None: + try: + for step in range(25): + kind = (seed + step) % 5 + try: + if kind == 0: + editor.add_blank_page(width=50 + seed, height=50) + elif kind == 1: + editor.pages[0].rotate(90) + elif kind == 2: + editor.pages[0].extract_text() + elif kind == 3: + editor.to_bytes() + else: + editor.append( + source=TWO, + page_nos=_source_page_nos(TWO, [0]), + before_page_no=_test_page_no(0, editor), + ) + except PdfStaleHandleError: + # another thread changed the page list between taking the + # handle and using it: the documented outcome + pass + except BaseException as exc: + errors.append(exc) + + threads = [threading.Thread(target=work, args=(seed,)) for seed in range(6)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + + assert errors == [] + + data = editor.to_bytes() + assert len(written_widths(data)) == len(editor.pages) + + +def test_two_writers_appending_to_each_other(): + left = PdfWriter(THREE) + right = PdfWriter(TWO) + errors: list[BaseException] = [] + + def work(target: PdfWriter, source: PdfWriter) -> None: + try: + for _ in range(10): + target.append(source, pages=[0]) + except BaseException as exc: + errors.append(exc) + + threads = [ + threading.Thread(target=work, args=(left, right)), + threading.Thread(target=work, args=(right, left)), + ] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + + assert errors == [] + assert len(left.pages) == 13 + assert len(right.pages) == 12 + + +# ---------------------------------------------------------------- packaging + + +def test_imports_stay_free_of_heavy_dependencies(): + """The reader, writer and editor must not pull in docling-core, pydantic + or PIL: they are importable in a process that has none of them loaded.""" + script = ( + "import sys\n" + "import docling_parse\n" + "from docling_parse import PdfReader, PdfWriter, PdfEditor\n" + "heavy = [m for m in ('docling_core', 'pydantic', 'PIL', " + "'docling_parse.pdf_parser') if m in sys.modules]\n" + "print(','.join(heavy))\n" + ) + result = subprocess.run( + [sys.executable, "-c", script], capture_output=True, text=True, check=True + ) + assert result.stdout.strip() == "" + + +def test_load_errors_are_the_parser_s_classes(): + from docling_parse import pdf_parser + + assert pdf_parser.PdfLoadError is PdfLoadError diff --git a/tests/test_unit_pdf_editor_navigation.py b/tests/test_unit_pdf_editor_navigation.py new file mode 100644 index 000000000..e7036d5d7 --- /dev/null +++ b/tests/test_unit_pdf_editor_navigation.py @@ -0,0 +1,51 @@ +"""Navigation must never retain a target outside the document's page tree.""" + +from io import BytesIO + +import pypdf +import pytest + +from tests.test_unit_pdf_editor import EDITING_CLASSES, THREE, _test_page_no + + +@pytest.mark.parametrize("cls", EDITING_CLASSES) +def test_remove_page_clears_explicit_and_named_destinations(cls): + document = cls(source=THREE) + document.add_named_destination(title="gone", page_no=_test_page_no(1, document)) + document.add_named_destination(title="keep", page_no=_test_page_no(2, document)) + document.add_outline_item(title="Gone", page_no=_test_page_no(1, document)) + document.set_open_destination(page_no=_test_page_no(1, document)) + document.add_link( + page_no=_test_page_no(0, document), + rect=(10, 10, 20, 20), + target_page_no=_test_page_no(1, document), + ) + document.add_annotation( + page_no=_test_page_no(0, document), + annotation={"/Subtype": "/Link", "/Rect": [30, 10, 40, 20], "/Dest": "gone"}, + ) + document.add_annotation( + page_no=_test_page_no(0, document), + annotation={ + "/Subtype": "/Link", + "/Rect": [50, 10, 60, 20], + "/A": {"/S": "/GoTo", "/D": "gone"}, + }, + ) + document.add_link( + page_no=_test_page_no(0, document), + rect=(70, 10, 80, 20), + target_page_no=_test_page_no(2, document), + ) + document.remove_page(page_no=_test_page_no(1, document)) + reader = pypdf.PdfReader(BytesIO(document.to_bytes())) + assert set(reader.named_destinations) == {"keep"} + assert reader.get_destination_page_number(reader.named_destinations["keep"]) == 1 + assert "/OpenAction" not in reader.trailer["/Root"] + assert document.outline[0]["page"] is None + links = [reference.get_object() for reference in reader.pages[0]["/Annots"]] + assert len(links) == 4 + for link in links[:3]: + assert "/Dest" not in link + assert "/A" not in link + assert reader.get_page_number(links[3]["/Dest"][0].get_object()) == 1 diff --git a/tests/test_unit_pdf_editor_render.py b/tests/test_unit_pdf_editor_render.py new file mode 100644 index 000000000..8f0e31f6a --- /dev/null +++ b/tests/test_unit_pdf_editor_render.py @@ -0,0 +1,50 @@ +"""Single-page rendering uses the current editor state and one-based page numbers.""" + +import pytest + +from docling_parse.pdf_editor import PdfEditor +from docling_parse.pdf_errors import PdfEditError +from tests.pdf_builder import simple_page_pdf +from tests.test_unit_pdf_editor import THREE + + +def test_render_page_uses_one_based_page_numbers(): + with PdfEditor(source=THREE) as editor: + assert editor.render_page(page_no=1, scale=2.0).size == (400, 600) + assert editor.render_page(page_no=3).size == (220, 300) + assert editor.is_modified is False + with pytest.raises(PdfEditError): + editor.render_page(page_no=4) + + +def test_render_page_includes_unsaved_changes_and_owns_its_pixels(): + source = simple_page_pdf("1 0 0 rg 20 20 40 40 re f") + with PdfEditor(source=source) as editor: + before = editor.render_page(page_no=1) + assert before.getpixel((30, 170)) == (255, 0, 0, 255) + editor.pages[0].rotate(90) + after = editor.render_page(page_no=1) + assert after.getpixel((30, 30)) == (255, 0, 0, 255) + assert after.getpixel((30, 170)) == (255, 255, 255, 255) + assert before.getpixel((30, 170)) == (255, 0, 0, 255) + + +@pytest.mark.parametrize("page_no", [0, -1]) +def test_render_page_rejects_invalid_page_numbers(page_no): + with PdfEditor(source=THREE) as editor, pytest.raises(ValueError): + editor.render_page(page_no=page_no) + + +@pytest.mark.parametrize("scale", [0, -1, float("inf"), float("nan")]) +def test_render_page_rejects_invalid_scales(scale): + with PdfEditor(source=THREE) as editor, pytest.raises(ValueError): + editor.render_page(page_no=1, scale=scale) + + +def test_render_page_requires_named_arguments_and_integer_page_number(): + with PdfEditor(source=THREE) as editor: + with pytest.raises(TypeError): + getattr(editor, "render_page")(1) + for page_no in (True, 1.5, "1"): + with pytest.raises(TypeError): + getattr(editor, "render_page")(page_no=page_no) diff --git a/uv.lock b/uv.lock index d243fbd24..686bcbc1e 100644 --- a/uv.lock +++ b/uv.lock @@ -944,6 +944,8 @@ dev = [ { name = "huggingface-hub" }, { name = "mypy" }, { name = "pre-commit" }, + { name = "pypdf" }, + { name = "pypdfium2" }, { name = "pytest" }, { name = "pytest-xdist" }, { name = "python-semantic-release" }, @@ -987,6 +989,8 @@ dev = [ { name = "huggingface-hub", specifier = ">=1.11.0" }, { name = "mypy", specifier = ">=1.13.0,<2.0.0" }, { name = "pre-commit", specifier = ">=3.7.1,<4.0.0" }, + { name = "pypdf", specifier = "==6.21.1" }, + { name = "pypdfium2", specifier = "==5.14.0" }, { name = "pytest", specifier = ">=9.0.3,<10.0.0" }, { name = "pytest-xdist", specifier = ">=3.8.0,<4.0.0" }, { name = "python-semantic-release", specifier = ">=7.32.2,<8.0.0" },