PyPDFForm 3.5.3__py3-none-any.whl → 4.2.0__py3-none-any.whl

PyPDFForm/raw/image.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=R0801
+"""
+Contains the RawImage class, which represents an image that can be drawn
+directly onto a PDF page at a specified position and size.
+"""
+
+from typing import BinaryIO, Union
+
+from ..adapter import fp_or_f_obj_or_stream_to_stream
+from ..image import rotate_image
+
+
+class RawImage:
+    """
+    Represents an image object intended for direct drawing onto a specific page
+    of a PDF document at specified coordinates, size, and rotation.
+
+    This class handles converting various input types for the image (file path, bytes,
+    or stream) into a standardized stream format, applying rotation if necessary.
+    """
+
+    def __init__(
+        self,
+        image: Union[bytes, str, BinaryIO],
+        page_number: int,
+        x: float,
+        y: float,
+        width: float,
+        height: float,
+        rotation: float = 0,
+    ) -> None:
+        """
+        Initializes a raw image object for drawing.
+
+        Args:
+            image: The image source, which can be a path (str), raw bytes (bytes),
+                   or a file stream (BinaryIO).
+            page_number: The 1-based index of the page where the image should be drawn.
+            x: The x-coordinate (horizontal position) of the bottom-left corner of the image.
+            y: The y-coordinate (vertical position) of the bottom-left corner of the image.
+            width: The desired width of the image when drawn on the PDF.
+            height: The desired height of the image when drawn on the PDF.
+            rotation: The rotation angle in degrees (defaults to 0, no rotation).
+        """
+        super().__init__()
+
+        self.image = image
+        self.page_number = page_number
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+        self.rotation = rotation
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw image object into a dictionary format ready for drawing.
+
+        The image is converted to a stream and rotated if necessary before being included in the dictionary.
+
+        Returns:
+            A dictionary containing drawing parameters: page number, object type ("image"),
+            the image stream (BinaryIO), coordinates (x, y), and dimensions (width, height).
+        """
+        image = fp_or_f_obj_or_stream_to_stream(self.image)
+        if self.rotation:
+            image = rotate_image(image, self.rotation)
+
+        return {
+            "page_number": self.page_number,
+            "type": "image",
+            "stream": image,
+            "x": self.x,
+            "y": self.y,
+            "width": self.width,
+            "height": self.height,
+        }

PyPDFForm/raw/line.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""
+Contains the RawLine class, which represents a line that can be drawn
+directly onto a PDF page at specified coordinates.
+"""
+
+from ..constants import DEFAULT_FONT_COLOR
+
+
+class RawLine:
+    """
+    Represents a line object intended for direct drawing onto a specific page
+    of a PDF document defined by starting and ending coordinates.
+
+    This class encapsulates the necessary information (start point, end point,
+    page number, and color) to render a straight line on a PDF page.
+    """
+
+    def __init__(
+        self,
+        page_number: int,
+        src_x: float,
+        src_y: float,
+        dest_x: float,
+        dest_y: float,
+        color: tuple = DEFAULT_FONT_COLOR,
+    ) -> None:
+        """
+        Initializes a raw line object for drawing.
+
+        Args:
+            page_number: The 1-based index of the page where the line should be drawn.
+            src_x: The x-coordinate (horizontal position) of the starting point.
+            src_y: The y-coordinate (vertical position) of the starting point.
+            dest_x: The x-coordinate (horizontal position) of the ending point.
+            dest_y: The y-coordinate (vertical position) of the ending point.
+            color: The color of the line as an RGB tuple (0-1 for each channel).
+        """
+        super().__init__()
+
+        self.page_number = page_number
+        self.src_x = src_x
+        self.src_y = src_y
+        self.dest_x = dest_x
+        self.dest_y = dest_y
+        self.color = color
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw line object into a dictionary format ready for drawing.
+
+        Returns:
+            A dictionary containing drawing parameters: page number, object type ("line"),
+            start and end coordinates, and color.
+        """
+        return {
+            "page_number": self.page_number,
+            "type": "line",
+            "src_x": self.src_x,
+            "src_y": self.src_y,
+            "dest_x": self.dest_x,
+            "dest_y": self.dest_y,
+            "color": self.color,
+        }

PyPDFForm/raw/rect.py

@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=R0801
+"""
+Contains the RawRectangle class, which represents a rectangle that can be drawn
+directly onto a PDF page at specified coordinates and dimensions.
+"""
+
+from ..constants import DEFAULT_FONT_COLOR
+
+
+class RawRectangle:
+    """
+    Represents a rectangle object intended for direct drawing onto a specific page
+    of a PDF document at specified coordinates and size.
+
+    This class encapsulates the necessary information (position, size, color,
+    and fill color) to render a rectangle on a PDF page.
+    """
+
+    def __init__(
+        self,
+        page_number: int,
+        x: float,
+        y: float,
+        width: float,
+        height: float,
+        color: tuple = DEFAULT_FONT_COLOR,
+        fill_color: tuple = None,
+    ) -> None:
+        """
+        Initializes a raw rectangle object for drawing.
+
+        Args:
+            page_number: The 1-based index of the page where the rectangle should be drawn.
+            x: The x-coordinate (horizontal position) of the bottom-left corner of the rectangle.
+            y: The y-coordinate (vertical position) of the bottom-left corner of the rectangle.
+            width: The width of the rectangle.
+            height: The height of the rectangle.
+            color: The color of the rectangle's outline as an RGB tuple (0-1 for each channel).
+            fill_color: The fill color of the rectangle as an RGB tuple (0-1 for each channel).
+        """
+        super().__init__()
+
+        self.page_number = page_number
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+        self.color = color
+        self.fill_color = fill_color
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw rectangle object into a dictionary format ready for drawing.
+
+        Returns:
+            A dictionary containing drawing parameters: page number, object type ("rect"),
+            coordinates, dimensions, outline color, and fill color.
+        """
+        return {
+            "page_number": self.page_number,
+            "type": "rect",
+            "x": self.x,
+            "y": self.y,
+            "width": self.width,
+            "height": self.height,
+            "color": self.color,
+            "fill_color": self.fill_color,
+        }

PyPDFForm/raw/text.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""
+Contains the RawText class, which represents a text annotation
+that can be drawn directly onto a PDF page without relying on existing form fields.
+"""
+
+from ..constants import DEFAULT_FONT, DEFAULT_FONT_COLOR, DEFAULT_FONT_SIZE
+from ..middleware.text import Text
+
+
+class RawText:
+    """
+    Represents a text object intended for direct drawing onto a specific page
+    of a PDF document at specified coordinates.
+
+    This class encapsulates all necessary information (text content, position,
+    font, size, and color) to render text on a PDF page outside of traditional
+    form fields.
+    """
+
+    def __init__(
+        self,
+        text: str,
+        page_number: int,
+        x: float,
+        y: float,
+        font: str = DEFAULT_FONT,
+        font_size: float = DEFAULT_FONT_SIZE,
+        font_color: tuple = DEFAULT_FONT_COLOR,
+    ) -> None:
+        """
+        Initializes a raw text object for drawing.
+
+        Args:
+            text: The string content of the text to be drawn.
+            page_number: The 1-based index of the page where the text should be drawn.
+            x: The x-coordinate (horizontal position) of the text.
+            y: The y-coordinate (vertical position) of the text.
+            font: The name of the font to use for the text (defaults to DEFAULT_FONT).
+            font_size: The size of the font (defaults to DEFAULT_FONT_SIZE).
+            font_color: The color of the text as an RGB tuple (0-255 for each channel).
+        """
+        super().__init__()
+
+        self.text = text
+        self.page_number = page_number
+        self.x = x
+        self.y = y
+        self.font = font
+        self.font_size = font_size
+        self.font_color = font_color
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw text object to a dict ready for drawing.
+
+        Returns:
+            A dictionary containing the page number, object type, an initialized Text widget,
+            and the coordinates for drawing.
+        """
+        widget = Text("new", self.text)
+        widget.font = self.font
+        widget.font_size = self.font_size
+        widget.font_color = self.font_color
+
+        return {
+            "page_number": self.page_number,
+            "type": "text",
+            "widget": widget,
+            "x": self.x,
+            "y": self.y,
+        }

PyPDFForm/template.py

@@ -7,29 +7,25 @@ in PDF form templates. It leverages the pypdf library for PDF manipulation
 and defines specific patterns for identifying and constructing different
 types of widgets.
 """
-# TODO: In `build_widgets`, the `get_widgets_by_page` function is called, which then iterates through pages and annotations. For very large PDFs, this initial parsing and iteration can be a bottleneck. Consider optimizing the widget extraction process if possible, perhaps by using a more direct method to access annotations if `pypdf` allows.
-# TODO: The `construct_widget` function iterates through `WIDGET_TYPE_PATTERNS` for each widget. If there are many patterns or many widgets, this repeated iteration could be optimized by pre-compiling patterns or using a more efficient lookup mechanism.
-# TODO: In `get_widget_key`, the recursive call for `Parent` can lead to deep recursion for deeply nested widgets, potentially impacting performance or hitting recursion limits for extremely complex forms. Consider an iterative approach if deep nesting is common.
-# TODO: In `update_widget_keys`, the nested loops iterating through `old_keys`, `out.pages`, and `page.get(Annots, [])` can be very inefficient for large numbers of keys, pages, or annotations. Consider creating a lookup structure for annotations by key to avoid repeated linear scans.
-# TODO: In `update_widget_keys`, `PdfReader(stream_to_io(template))` and `out.append(pdf)` involve re-parsing and appending the PDF. For large PDFs, passing `PdfReader` and `PdfWriter` objects directly could reduce overhead.
 
 from functools import lru_cache
 from io import BytesIO
 from typing import Dict, List, Tuple, Union, cast
 
 from pypdf import PdfReader, PdfWriter
-from pypdf.generic import DictionaryObject
+from pypdf.generic import DictionaryObject, NameObject, TextStringObject
 
-from .constants import WIDGET_TYPES, Annots, MaxLen, Parent, T
+from .constants import (JS, WIDGET_TYPES, Annots, JavaScript, MaxLen,
+                        OpenAction, Parent, S, T, Title)
 from .middleware.checkbox import Checkbox
 from .middleware.dropdown import Dropdown
 from .middleware.radio import Radio
 from .middleware.text import Text
 from .patterns import (DROPDOWN_CHOICE_PATTERNS, WIDGET_DESCRIPTION_PATTERNS,
                        WIDGET_KEY_PATTERNS, WIDGET_TYPE_PATTERNS,
-                       get_checkbox_value, get_dropdown_value, get_radio_value,
-                       get_text_field_multiline, get_text_value,
-                       update_annotation_name)
+                       get_checkbox_value, get_dropdown_value, get_field_rect,
+                       get_radio_value, get_text_field_multiline,
+                       get_text_value, update_annotation_name)
 from .utils import extract_widget_property, find_pattern_match, stream_to_io
 
 
@@ -62,10 +58,13 @@ def build_widgets(
             key = get_widget_key(widget, use_full_widget_name)
             _widget = construct_widget(widget, key)
             if _widget is not None:
-                _widget.desc = extract_widget_property(
+                _widget.__dict__["tooltip"] = extract_widget_property(
                     widget, WIDGET_DESCRIPTION_PATTERNS, None, str
                 )
 
+                field_rect = get_field_rect(widget)
+                _widget.x, _widget.y, _widget.width, _widget.height = field_rect
+
                 if isinstance(_widget, Text):
                     # mostly for schema for now
                     # doesn't trigger hook
@@ -84,11 +83,20 @@ def build_widgets(
 
                 if isinstance(_widget, Radio):
                     if key not in results:
+                        _widget.x = []
+                        _widget.y = []
+                        _widget.width = []
+                        _widget.height = []
                         results[key] = _widget
 
                     # for schema
                     results[key].number_of_options += 1
 
+                    results[key].x.append(field_rect[0])
+                    results[key].y.append(field_rect[1])
+                    results[key].width.append(field_rect[2])
+                    results[key].height.append(field_rect[3])
+
                     if get_radio_value(widget):
                         results[key].value = results[key].number_of_options - 1
                     continue
@@ -225,13 +233,107 @@ def get_dropdown_choices(widget: dict) -> Union[Tuple[str, ...], None]:
         Union[Tuple[str, ...], None]: A tuple of strings representing the choices in the dropdown, or None if the choices are not specified.
     """
     return tuple(
-        (each if isinstance(each, str) else str(each[1]))
+        (
+            each.get_object()
+            if isinstance(each.get_object(), str)
+            else str(each.get_object()[1])
+        )
         for each in extract_widget_property(
             widget, DROPDOWN_CHOICE_PATTERNS, None, None
         )
     )
 
 
+def get_on_open_javascript(pdf: bytes) -> Union[str, None]:
+    """
+    Retrieves the JavaScript that runs when the PDF is opened.
+
+    Args:
+        pdf (bytes): The PDF file content as a bytes stream.
+
+    Returns:
+        Union[str, None]: The JavaScript that runs when the PDF is opened, or None if it's not present.
+    """
+    reader = PdfReader(stream_to_io(pdf))
+    try:
+        return reader.root_object[OpenAction][JS]
+    except KeyError:
+        return None
+
+
+def set_on_open_javascript(pdf: bytes, script: str) -> bytes:
+    """
+    Sets the JavaScript that runs when the PDF is opened.
+
+    Args:
+        pdf (bytes): The PDF file content as a bytes stream.
+        script (str): The JavaScript to run when the PDF is opened.
+
+    Returns:
+        bytes: The modified PDF content as a bytes stream.
+    """
+    if not script:
+        return pdf
+
+    reader = PdfReader(stream_to_io(pdf))
+    writer = PdfWriter()
+    writer.append(reader)
+
+    open_action = DictionaryObject()
+    open_action[NameObject(S)] = NameObject(JavaScript)
+    open_action[NameObject(JS)] = TextStringObject(script)
+
+    writer._root_object.update({NameObject(OpenAction): open_action})  # type: ignore # noqa: SLF001 # # pylint: disable=W0212
+
+    with BytesIO() as f:
+        writer.write(f)
+        f.seek(0)
+        return f.read()
+
+
+def get_pdf_title(pdf: bytes) -> Union[str, None]:
+    """
+    Retrieves the title of a PDF from its metadata.
+
+    Args:
+        pdf (bytes): The PDF file content as a bytes stream.
+
+    Returns:
+        Union[str, None]: The title of the PDF, or None if it's not present.
+    """
+    reader = PdfReader(stream_to_io(pdf))
+    return (reader.metadata or {}).get(Title)
+
+
+def set_pdf_title(pdf: bytes, title: str) -> bytes:
+    """
+    Sets the title of a PDF in its metadata.
+
+    Args:
+        pdf (bytes): The PDF file content as a bytes stream.
+        title (str): The new title for the PDF.
+
+    Returns:
+        bytes: The modified PDF content as a bytes stream.
+    """
+    if not title:
+        return pdf
+
+    reader = PdfReader(stream_to_io(pdf))
+    writer = PdfWriter()
+    writer.append(reader)
+
+    metadata = reader.metadata or {}
+    metadata[NameObject(Title)] = TextStringObject(title)
+
+    writer.add_metadata(metadata)
+
+    with BytesIO() as f:
+        writer.write(f)
+        f.seek(0)
+        return f.read()
+
+
 def update_widget_keys(
     template: bytes,
     widgets: Dict[str, WIDGET_TYPES],

PyPDFForm/types.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""
+A module for custom type definitions used throughout the PyPDFForm library.
+
+This includes specialized container types like PdfWrapperList, which extends
+the standard list to provide custom behavior for slicing operations, particularly
+for merging PdfWrapper objects.
+"""
+
+from typing import Any, Union
+
+
+class PdfWrapperList(list):
+    """
+    A specialized list subclass designed to hold PdfWrapper objects.
+
+    When sliced, this list automatically merges the contained PdfWrapper
+    objects using the PdfWrapper.__add__ method, returning a single
+    merged PdfWrapper object. If the slice is empty, it returns an empty list.
+    For non-slice indexing, it behaves like a standard list.
+    """
+
+    def __getitem__(self, key: Any) -> Union[list, Any]:
+        """
+        Retrieves an item or a slice of items from the list.
+
+        If the key is a slice, it merges the PdfWrapper objects in the slice
+        and returns a single merged PdfWrapper.
+        If the key is an index, it returns the PdfWrapper at that index.
+
+        Args:
+            key (Union[int, slice]): The index or slice to retrieve.
+
+        Returns:
+            Union[PdfWrapper, list, Any]: A single merged PdfWrapper if sliced,
+                                          or the item at the index if indexed.
+        """
+
+        if isinstance(key, slice):
+            result = None
+            wrappers = super().__getitem__(key)
+            for each in wrappers:
+                if not result:
+                    result = each
+                else:
+                    result += each
+
+            return result
+        return super().__getitem__(key)

PyPDFForm/utils.py

@@ -10,16 +10,8 @@ It includes functions for:
 - Finding and traversing patterns within PDF widgets.
 - Extracting widget properties based on defined patterns.
 - Generating unique suffixes for internal use.
-- Enabling Adobe-specific settings in the PDF to ensure proper rendering of form fields.
+- Setting the `NeedAppearances` flag in the PDF to ensure proper rendering of form fields.
 """
-# TODO: In `enable_adobe_mode`, `PdfReader(stream_to_io(pdf))` and `writer.append(reader)` involve re-parsing and appending the PDF. For large PDFs, passing `PdfReader` and `PdfWriter` objects directly could reduce overhead.
-# TODO: In `remove_all_widgets`, `PdfReader(stream_to_io(pdf))` and iterating through pages to add them to a new writer can be inefficient for large PDFs. Consider if `pypdf` offers a more direct way to remove annotations without reconstructing the entire PDF.
-# TODO: In `get_page_streams`, `PdfReader(stream_to_io(pdf))` and then creating a new `PdfWriter` for each page can be very inefficient. It would be more performant to iterate through the pages of a single `PdfReader` and extract their content streams directly if possible, or to use a single `PdfWriter` to extract multiple pages.
-# TODO: In `merge_two_pdfs`, the function reads and writes PDFs multiple times (`PdfReader`, `PdfWriter`, `remove_all_widgets`, then another `PdfReader` and `PdfWriter`). This is highly inefficient. The PDF objects should be passed around and modified in-place as much as possible, with a single final write operation.
-# TODO: The `merge_two_pdfs` function has a `TODO: refactor duplicate logic with copy_watermark_widgets` comment. This indicates a potential for code duplication and inefficiency. Refactoring this to a shared helper function would improve maintainability and potentially performance.
-# TODO: In `find_pattern_match` and `traverse_pattern`, the recursive nature and repeated dictionary lookups (`widget.items()`, `value.get_object()`) can be slow for deeply nested or complex widget structures. Consider optimizing these traversals, perhaps by pre-flattening the widget dictionary or using a more direct access method if `pypdf` allows.
-# TODO: In `extract_widget_property`, the loop iterates through `patterns` and calls `traverse_pattern` for each. If `patterns` is long or `traverse_pattern` is expensive, this could be a bottleneck. Consider optimizing the pattern matching or lookup.
-# TODO: `generate_unique_suffix` uses `choice` in a loop. While generally fast, for extremely high call volumes, pre-generating a pool of characters or using a faster random string generation method might offer minor improvements.
 
 from collections.abc import Callable
 from functools import lru_cache
@@ -31,7 +23,7 @@ from typing import Any, BinaryIO, List, Union
 from pypdf import PdfReader, PdfWriter
 from pypdf.generic import ArrayObject, DictionaryObject, NameObject
 
-from .constants import SLASH, UNIQUE_SUFFIX_LENGTH, XFA, AcroForm, Annots, Root
+from .constants import SLASH, UNIQUE_SUFFIX_LENGTH, Annots
 
 
 @lru_cache
@@ -58,37 +50,6 @@ def stream_to_io(stream: bytes) -> BinaryIO:
     return result
 
 
-@lru_cache
-def enable_adobe_mode(pdf: bytes) -> bytes:
-    """Enables Adobe-specific settings in the PDF to ensure proper rendering of form fields.
-
-    This function modifies the PDF's AcroForm dictionary to include the `NeedAppearances` flag,
-    which forces Adobe Reader to generate appearance streams for form fields. It also handles
-    XFA (XML Forms Architecture) forms by removing the XFA entry from the AcroForm dictionary
-    if it exists, ensuring compatibility and proper rendering. This ensures that the form fields
-    are rendered correctly in Adobe Reader, especially when the form is filled programmatically.
-
-    Args:
-        pdf (bytes): The PDF content as bytes.
-
-    Returns:
-        bytes: The modified PDF content with Adobe mode enabled.
-    """
-    reader = PdfReader(stream_to_io(pdf))
-    writer = PdfWriter()
-
-    if AcroForm in reader.trailer[Root] and XFA in reader.trailer[Root][AcroForm]:
-        del reader.trailer[Root][AcroForm][XFA]
-
-    writer.append(reader)
-    writer.set_need_appearances_writer()
-
-    with BytesIO() as f:
-        writer.write(f)
-        f.seek(0)
-        return f.read()
-
-
 @lru_cache
 def remove_all_widgets(pdf: bytes) -> bytes:
     """
@@ -144,6 +105,35 @@ def get_page_streams(pdf: bytes) -> List[bytes]:
     return result
 
 
+def merge_pdfs(pdf_list: list[bytes]) -> bytes:
+    """
+    Merges a list of PDF byte streams into a single PDF byte stream.
+
+    This function uses a pairwise merging strategy (similar to a merge sort's merge phase)
+    to combine multiple PDF files efficiently. Instead of iteratively merging the result
+    with the next PDF (O(n^2) complexity where n is the number of pages), this approach
+    merges all available PDFs in pairs in a single pass. This process repeats until
+    only a single merged PDF remains, offering better performance for large lists of
+    PDFs.
+
+    Args:
+        pdf_list (list[bytes]): A list of PDF files as byte streams to be merged.
+
+    Returns:
+        bytes: The merged PDF file as a single byte stream.
+    """
+    while len(pdf_list) > 2:
+        groups = [pdf_list[i : i + 2] for i in range(0, len(pdf_list), 2)]
+        pdf_list = []
+        for each in groups:
+            if len(each) == 2:
+                pdf_list.append(merge_two_pdfs(each[0], each[1]))
+            else:
+                pdf_list += each
+
+    return merge_two_pdfs(pdf_list[0], pdf_list[1])
+
+
 def merge_two_pdfs(pdf: bytes, other: bytes) -> bytes:
     """
     Merges two PDF files into a single PDF file.