PyPDFForm 2.5.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

PyPDFForm/filler.py

@@ -1,106 +1,60 @@
 # -*- coding: utf-8 -*-
-"""Provides core functionality for filling PDF form fields.
-
-This module handles:
-- Drawing text, images, borders and other elements onto PDF forms
-- Managing widget states and appearances
-- Supporting different filling modes (simple vs watermark-based)
-- Handling special cases like checkboxes, radio buttons and signatures
+"""
+Module containing functions to fill PDF forms.
 
-The main functions are:
-- fill(): Uses watermark technique for complex form filling
-- simple_fill(): Directly modifies form fields for simpler cases
+This module provides the core functionality for filling PDF forms programmatically.
+It includes functions for handling various form field types, such as text fields,
+checkboxes, radio buttons, dropdowns, images, and signatures. The module also
+supports flattening the filled form to prevent further modifications.
 """
 
 from io import BytesIO
-from typing import Dict, Tuple, Union, cast
+from typing import Dict, Union, cast
 
 from pypdf import PdfReader, PdfWriter
-from pypdf.generic import (ArrayObject, BooleanObject, DictionaryObject,
-                           IndirectObject, NameObject)
+from pypdf.generic import DictionaryObject
 
-from .constants import (BUTTON_STYLES, DEFAULT_RADIO_STYLE, WIDGET_TYPES,
-                        AcroForm, Annots, Fields, NeedAppearances, Root, U)
-from .coordinate import (get_draw_border_coordinates,
-                         get_draw_checkbox_radio_coordinates,
-                         get_draw_image_coordinates_resolutions,
-                         get_draw_text_coordinates,
-                         get_text_line_x_coordinates)
-from .font import checkbox_radio_font_size
-from .image import get_image_dimensions
+from .constants import WIDGET_TYPES, Annots
+from .image import get_draw_image_resolutions, get_image_dimensions
 from .middleware.checkbox import Checkbox
 from .middleware.dropdown import Dropdown
 from .middleware.image import Image
 from .middleware.radio import Radio
 from .middleware.signature import Signature
 from .middleware.text import Text
-from .patterns import (simple_flatten_generic, simple_flatten_radio,
-                       simple_update_checkbox_value,
-                       simple_update_dropdown_value, simple_update_radio_value,
-                       simple_update_text_value)
-from .template import get_widget_key, get_widgets_by_page
-from .utils import checkbox_radio_to_draw, stream_to_io
+from .patterns import (flatten_generic, flatten_radio, update_checkbox_value,
+                       update_dropdown_value, update_radio_value,
+                       update_text_value)
+from .template import get_widget_key
+from .utils import stream_to_io
 from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
 
 
-def check_radio_handler(
-    widget: dict, middleware: Union[Checkbox, Radio], radio_button_tracker: dict
-) -> Tuple[Text, Union[float, int], Union[float, int], bool]:
-    """Calculates drawing parameters for checkbox and radio button widgets.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect coordinates
-        middleware: Checkbox or Radio middleware instance
-        radio_button_tracker: Dictionary tracking radio button group states
-
-    Returns:
-        Tuple containing:
-        - Text: Prepared text object for drawing the symbol
-        - float/int: x coordinate for drawing
-        - float/int: y coordinate for drawing
-        - bool: Whether the symbol needs to be drawn
-    """
-
-    font_size = (
-        checkbox_radio_font_size(widget) if middleware.size is None else middleware.size
-    )
-    to_draw = checkbox_radio_to_draw(middleware, font_size)
-    x, y = get_draw_checkbox_radio_coordinates(
-        widget, to_draw, border_width=middleware.border_width
-    )
-    text_needs_to_be_drawn = False
-    if type(middleware) is Checkbox and middleware.value:
-        text_needs_to_be_drawn = True
-    elif isinstance(middleware, Radio):
-        if middleware.name not in radio_button_tracker:
-            radio_button_tracker[middleware.name] = 0
-        radio_button_tracker[middleware.name] += 1
-        if middleware.value == radio_button_tracker[middleware.name] - 1:
-            text_needs_to_be_drawn = True
-
-    return to_draw, x, y, text_needs_to_be_drawn
-
-
 def signature_image_handler(
     widget: dict, middleware: Union[Signature, Image], images_to_draw: list
 ) -> bool:
-    """Prepares image data for signature and image widgets.
+    """Handles signature and image widgets by extracting image data and preparing it for drawing.
+
+    This function processes signature and image widgets found in a PDF form. It extracts the
+    image data from the widget's middleware and prepares it for drawing on the form. The
+    function calculates the position and dimensions of the image based on the widget's
+    properties and the `preserve_aspect_ratio` setting. The image data is then stored in a
+    list for later drawing.
 
     Args:
-        widget: PDF form widget dictionary containing Rect coordinates
-        middleware: Signature or Image middleware instance
-        images_to_draw: List to append image drawing parameters to
+        widget (dict): The widget dictionary representing the signature or image field.
+        middleware (Union[Signature, Image]): The middleware object containing the image data and properties.
+        images_to_draw (list): A list to store image data for drawing.
 
     Returns:
-        bool: True if an image needs to be drawn, False otherwise
+        bool: True if any image is to be drawn, False otherwise.
     """
-
     stream = middleware.stream
     any_image_to_draw = False
     if stream is not None:
         any_image_to_draw = True
         image_width, image_height = get_image_dimensions(stream)
-        x, y, width, height = get_draw_image_coordinates_resolutions(
+        x, y, width, height = get_draw_image_resolutions(
             widget, middleware.preserve_aspect_ratio, image_width, image_height
         )
         images_to_draw.append(
@@ -116,95 +70,23 @@ def signature_image_handler(
     return any_image_to_draw
 
 
-def text_handler(
-    widget: dict, middleware: Text
-) -> Tuple[Text, Union[float, int], Union[float, int], bool]:
-    """Prepares text field drawing parameters.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect and properties
-        middleware: Text middleware instance with text properties
-
-    Returns:
-        Tuple containing:
-        - Text: The text middleware to draw
-        - float/int: x coordinate for drawing
-        - float/int: y coordinate for drawing
-        - bool: Always True for text fields (they always need drawing)
-    """
-
-    middleware.text_line_x_coordinates = get_text_line_x_coordinates(widget, middleware)
-    x, y = get_draw_text_coordinates(widget, middleware)
-    to_draw = middleware
-    text_needs_to_be_drawn = True
-
-    return to_draw, x, y, text_needs_to_be_drawn
-
-
-def border_handler(
-    widget: dict,
-    middleware: WIDGET_TYPES,
-    rect_borders_to_draw: list,
-    ellipse_borders_to_draw: list,
-    line_borders_to_draw: list,
-) -> None:
-    """Prepares border drawing parameters for widgets.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect coordinates
-        middleware: Any widget middleware instance
-        rect_borders_to_draw: List to append rectangle border parameters to
-        ellipse_borders_to_draw: List to append ellipse border parameters to
-        line_borders_to_draw: List to append line border parameters to
-    """
-
-    if (
-        isinstance(middleware, Radio)
-        and BUTTON_STYLES.get(middleware.button_style) == DEFAULT_RADIO_STYLE
-    ):
-        list_to_append = ellipse_borders_to_draw
-        shape = "ellipse"
-    elif middleware.border_style == U:
-        list_to_append = line_borders_to_draw
-        shape = "line"
-    else:
-        list_to_append = rect_borders_to_draw
-        shape = "rect"
-
-    list_to_append.append(
-        {
-            **get_draw_border_coordinates(widget, shape),
-            "border_color": middleware.border_color,
-            "background_color": middleware.background_color,
-            "border_width": middleware.border_width,
-            "dash_array": middleware.dash_array,
-        }
-    )
-
-    if shape == "line":
-        rect_borders_to_draw.append(
-            {
-                **get_draw_border_coordinates(widget, "rect"),
-                "border_color": None,
-                "background_color": middleware.background_color,
-                "border_width": 0,
-                "dash_array": None,
-            }
-        )
-
-
 def get_drawn_stream(to_draw: dict, stream: bytes, action: str) -> bytes:
-    """Applies drawing operations to a PDF stream.
+    """Applies watermarks to specific pages of a PDF based on the provided drawing instructions.
+
+    This function takes a dictionary of drawing instructions and applies watermarks to the
+    specified pages of a PDF. It iterates through the drawing instructions, creates watermarks
+    for each page, and merges the watermarks with the original PDF content. The function
+    supports various drawing actions, such as adding images or text.
 
     Args:
-        to_draw: Dictionary mapping page numbers to drawing parameters
-        stream: Input PDF as bytes
-        action: Type of drawing operation ('text', 'image', 'rect', etc.)
+        to_draw (dict): A dictionary containing page numbers as keys and lists of drawing instructions as values.
+                         Each drawing instruction specifies the type of drawing, position, dimensions, and content.
+        stream (bytes): The PDF content as bytes.
+        action (str): The type of action to perform (e.g., "image", "text").
 
     Returns:
-        bytes: Modified PDF with drawings applied
+        bytes: The modified PDF content with watermarks applied.
     """
-
     watermark_list = []
     for page, stuffs in to_draw.items():
         watermark_list.append(b"")
@@ -217,184 +99,78 @@ def get_drawn_stream(to_draw: dict, stream: bytes, action: str) -> bytes:
 
 
 def fill(
-    template_stream: bytes,
-    widgets: Dict[str, WIDGET_TYPES],
-    use_full_widget_name: bool,
-) -> bytes:
-    """Fills a PDF form using watermark technique for complex rendering.
-
-    This method:
-    - Handles text, images, borders for all widget types
-    - Preserves original form fields while adding visual elements
-    - Supports complex cases like multiline text and image scaling
-
-    Args:
-        template_stream: Input PDF form as bytes
-        widgets: Dictionary mapping field names to widget middleware
-        use_full_widget_name: If True, uses the full widget name as the key in the widgets dictionary
-
-    Returns:
-        bytes: Filled PDF form as bytes
-    """
-
-    texts_to_draw = {}
-    images_to_draw = {}
-    rect_borders_to_draw = {}
-    ellipse_borders_to_draw = {}
-    line_borders_to_draw = {}
-    any_image_to_draw = False
-
-    radio_button_tracker = {}
-
-    for page, widget_dicts in get_widgets_by_page(template_stream).items():
-        texts_to_draw[page] = []
-        images_to_draw[page] = []
-        rect_borders_to_draw[page] = []
-        ellipse_borders_to_draw[page] = []
-        line_borders_to_draw[page] = []
-        for widget_dict in widget_dicts:
-            key = get_widget_key(widget_dict, use_full_widget_name)
-            text_needs_to_be_drawn = False
-            to_draw = x = y = None
-
-            if widgets[key].render_widget:
-                border_handler(
-                    widget_dict,
-                    widgets[key],
-                    rect_borders_to_draw[page],
-                    ellipse_borders_to_draw[page],
-                    line_borders_to_draw[page],
-                )
-
-            if isinstance(widgets[key], (Checkbox, Radio)):
-                to_draw, x, y, text_needs_to_be_drawn = check_radio_handler(
-                    widget_dict, widgets[key], radio_button_tracker
-                )
-            elif isinstance(widgets[key], (Signature, Image)):
-                any_image_to_draw |= signature_image_handler(
-                    widget_dict, widgets[key], images_to_draw[page]
-                )
-            else:
-                to_draw, x, y, text_needs_to_be_drawn = text_handler(
-                    widget_dict, widgets[key]
-                )
-
-            if all(
-                [
-                    text_needs_to_be_drawn,
-                    to_draw is not None,
-                    x is not None,
-                    y is not None,
-                ]
-            ):
-                texts_to_draw[page].append(
-                    {
-                        "widget": to_draw,
-                        "x": x,
-                        "y": y,
-                    }
-                )
-
-    result = template_stream
-    result = get_drawn_stream(rect_borders_to_draw, result, "rect")
-    result = get_drawn_stream(ellipse_borders_to_draw, result, "ellipse")
-    result = get_drawn_stream(line_borders_to_draw, result, "line")
-    result = get_drawn_stream(texts_to_draw, result, "text")
-
-    if any_image_to_draw:
-        result = get_drawn_stream(images_to_draw, result, "image")
-
-    return result
-
-
-def enable_adobe_mode(reader: PdfReader, writer: PdfWriter, adobe_mode: bool) -> None:
-    """Configures the PDF for Adobe Acrobat compatibility by setting the NeedAppearances flag
-    and ensuring the AcroForm structure is properly initialized.
-
-    Args:
-        reader: PdfReader instance of the PDF
-        writer: PdfWriter instance to configure
-        adobe_mode: If True, enables Adobe Acrobat compatibility mode
-    """
-
-    if not adobe_mode:
-        return
-
-    # https://stackoverflow.com/questions/47288578/pdf-form-filled-with-pypdf2-does-not-show-in-print
-    if AcroForm in reader.trailer[Root]:
-        reader.trailer[Root][AcroForm].update(
-            {NameObject(NeedAppearances): BooleanObject(True)}
-        )
-
-    if AcroForm not in writer.root_object:
-        writer.root_object.update(
-            {NameObject(AcroForm): IndirectObject(len(writer.root_object), 0, writer)}
-        )
-    writer.root_object[AcroForm][NameObject(NeedAppearances)] = BooleanObject(True)
-    writer.root_object[AcroForm][NameObject(Fields)] = ArrayObject()
-
-
-def simple_fill(
     template: bytes,
     widgets: Dict[str, WIDGET_TYPES],
     use_full_widget_name: bool,
     flatten: bool = False,
-    adobe_mode: bool = False,
-) -> bytes:
-    """Fills a PDF form by directly modifying form fields.
+) -> tuple:
+    """Fills a PDF template with the given widgets.
 
-    This method:
-    - Updates field values directly in the PDF
-    - Supports flattening to make fields read-only
-    - Works with Adobe Acrobat compatibility mode
+    This function fills a PDF template with the provided widget values. It iterates through the
+    widgets on each page of the PDF and updates their values based on the provided `widgets`
+    dictionary. The function supports various widget types, including text fields, checkboxes,
+    radio buttons, dropdowns, images, and signatures. It also supports flattening the filled
+    form to prevent further modifications.
 
     Args:
-        template: Input PDF form as bytes
-        widgets: Dictionary mapping field names to widget middleware
-        use_full_widget_name: If True, uses the full widget name as the key in the widgets dictionary
-        flatten: If True, makes form fields read-only
-        adobe_mode: If True, enables Adobe Acrobat compatibility
+        template (bytes): The PDF template as bytes.
+        widgets (Dict[str, WIDGET_TYPES]): A dictionary of widgets to fill, where the keys are the
+                                            widget names and the values are the widget objects.
+        use_full_widget_name (bool): Whether to use the full widget name when looking up widgets
+                                      in the `widgets` dictionary.
+        flatten (bool): Whether to flatten the filled PDF. Defaults to False.
 
     Returns:
-        bytes: Filled PDF form as bytes
+        tuple: A tuple containing the filled PDF as bytes and the image drawn stream as bytes, if any.
+               The image drawn stream is only returned if there are any image or signature widgets
+               in the form.
     """
-
     pdf = PdfReader(stream_to_io(template))
     out = PdfWriter()
-    enable_adobe_mode(pdf, out, adobe_mode)
     out.append(pdf)
 
     radio_button_tracker = {}
+    images_to_draw = {}
+    any_image_to_draw = False
 
-    for page in out.pages:
+    for page_num, page in enumerate(out.pages):
+        images_to_draw[page_num + 1] = []
         for annot in page.get(Annots, []):
             annot = cast(DictionaryObject, annot.get_object())
             key = get_widget_key(annot.get_object(), use_full_widget_name)
 
             widget = widgets.get(key)
-            if widget is None or widget.value is None:
+            if widget is None:
+                continue
+
+            # flatten all
+            if flatten:
+                (flatten_radio if isinstance(widget, Radio) else flatten_generic)(annot)
+            if widget.value is None:
                 continue
 
-            if type(widget) is Checkbox:
-                simple_update_checkbox_value(annot, widget.value)
+            if isinstance(widgets[key], (Signature, Image)):
+                any_image_to_draw |= signature_image_handler(
+                    annot, widgets[key], images_to_draw[page_num + 1]
+                )
+            elif type(widget) is Checkbox:
+                update_checkbox_value(annot, widget.value)
             elif isinstance(widget, Radio):
                 if key not in radio_button_tracker:
                     radio_button_tracker[key] = 0
                 radio_button_tracker[key] += 1
                 if widget.value == radio_button_tracker[key] - 1:
-                    simple_update_radio_value(annot)
+                    update_radio_value(annot)
             elif isinstance(widget, Dropdown):
-                simple_update_dropdown_value(annot, widget)
+                update_dropdown_value(annot, widget)
             elif isinstance(widget, Text):
-                simple_update_text_value(annot, widget)
-
-            if flatten:
-                if isinstance(widget, Radio):
-                    simple_flatten_radio(annot)
-                else:
-                    simple_flatten_generic(annot)
+                update_text_value(annot, widget)
 
     with BytesIO() as f:
         out.write(f)
         f.seek(0)
-        return f.read()
+        result = f.read()
+
+    return result, (
+        get_drawn_stream(images_to_draw, result, "image") if any_image_to_draw else None
+    )