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

PyPDFForm/hooks.py

@@ -1,9 +1,11 @@
 # -*- coding: utf-8 -*-
-"""Module containing hook functions for PDF form widget manipulation.
+"""
+This module defines widget hooks that allow for dynamic modification of PDF form fields.
 
-This module provides functions to apply various transformations and modifications
-to PDF form widgets through a hook system. It allows dynamic modification of
-widget properties like font sizes and other attributes.
+It provides functions to trigger these hooks, enabling changes to text field properties
+like font, font size, color, alignment, and multiline settings, as well as the size
+of checkbox and radio button widgets. These hooks are triggered during the PDF form
+filling process, allowing for customization of the form's appearance and behavior.
 """
 
 import sys
@@ -15,7 +17,7 @@ from pypdf.generic import (ArrayObject, DictionaryObject, FloatObject,
                            NameObject, NumberObject, TextStringObject)
 
 from .constants import (COMB, DA, FONT_COLOR_IDENTIFIER, FONT_SIZE_IDENTIFIER,
-                        MULTILINE, Annots, Ff, Parent, Q, Rect)
+                        MULTILINE, Annots, Ff, Opt, Parent, Q, Rect)
 from .template import get_widget_key
 from .utils import stream_to_io
 
@@ -25,21 +27,26 @@ def trigger_widget_hooks(
     widgets: dict,
     use_full_widget_name: bool,
 ) -> bytes:
-    """Apply all registered widget hooks to a PDF document.
+    """
+    Triggers widget hooks to apply dynamic changes to PDF form fields.
+
+    This function iterates through the annotations on each page of the PDF and,
+    if a widget is associated with an annotation and has hooks to trigger,
+    it executes those hooks. Hooks are functions defined in this module that
+    modify the annotation dictionary, allowing for dynamic changes to the form field's
+    appearance or behavior.
 
     Args:
-        pdf: The input PDF document as bytes
-        widgets: Dictionary mapping widget names to widget objects
-        use_full_widget_name: Whether to use full widget names including parent hierarchy
+        pdf (bytes): The PDF file data as bytes.
+        widgets (dict): A dictionary of widgets, where keys are widget identifiers
+            and values are widget objects containing information about the widget
+            and its associated hooks.
+        use_full_widget_name (bool): Whether to use the full widget name when
+            looking up widgets in the widgets dictionary.
 
     Returns:
-        The modified PDF document as bytes
-
-    Note:
-        This function processes all pages and annotations in the PDF, applying
-        any hooks registered in the widget objects.
+        bytes: The modified PDF data as bytes, with the widget hooks applied.
     """
-
     pdf_file = PdfReader(stream_to_io(pdf))
     output = PdfWriter()
     output.append(pdf_file)
@@ -65,18 +72,45 @@ def trigger_widget_hooks(
         return f.read()
 
 
-def update_text_field_font_size(annot: DictionaryObject, val: float) -> None:
-    """Update the font size of a text field widget.
+def update_text_field_font(annot: DictionaryObject, val: str) -> None:
+    """
+    Updates the font of a text field annotation.
+
+    This function modifies the appearance string (DA) in the annotation dictionary
+    to change the font used for the text field.
 
     Args:
-        annot: The PDF annotation (widget) dictionary object
-        val: The new font size value to apply
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (str): The new font name to use for the text field.
+    """
+    if Parent in annot and DA not in annot:
+        text_appearance = annot[Parent][DA]
+    else:
+        text_appearance = annot[DA]
+
+    text_appearance = text_appearance.split(" ")
+    text_appearance[0] = val
+    new_text_appearance = " ".join(text_appearance)
+
+    if Parent in annot and DA not in annot:
+        annot[NameObject(Parent)][NameObject(DA)] = TextStringObject(
+            new_text_appearance
+        )
+    else:
+        annot[NameObject(DA)] = TextStringObject(new_text_appearance)
+
 
-    Note:
-        Handles both direct font size specification and inherited font sizes
-        from parent objects. Modifies the DA (default appearance) string.
+def update_text_field_font_size(annot: DictionaryObject, val: float) -> None:
     """
+    Updates the font size of a text field annotation.
+
+    This function modifies the appearance string (DA) in the annotation dictionary
+    to change the font size used for the text field.
 
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (float): The new font size to use for the text field.
+    """
     if Parent in annot and DA not in annot:
         text_appearance = annot[Parent][DA]
     else:
@@ -101,18 +135,16 @@ def update_text_field_font_size(annot: DictionaryObject, val: float) -> None:
 
 
 def update_text_field_font_color(annot: DictionaryObject, val: tuple) -> None:
-    """Update the font color of a text field widget.
+    """
+    Updates the font color of a text field annotation.
 
-    Args:
-        annot: The PDF annotation (widget) dictionary object
-        val: Tuple containing RGB color values (e.g. (1, 0, 0) for red)
+    This function modifies the appearance string (DA) in the annotation dictionary
+    to change the font color used for the text field.
 
-    Note:
-        Handles both direct font color specification and inherited font colors
-        from parent objects. Modifies the DA (default appearance) string to
-        include the new color values after the font size identifier.
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (tuple): The new font color as an RGB tuple (e.g., (1, 0, 0) for red).
     """
-
     if Parent in annot and DA not in annot:
         text_appearance = annot[Parent][DA]
     else:
@@ -141,76 +173,84 @@ def update_text_field_font_color(annot: DictionaryObject, val: tuple) -> None:
 
 
 def update_text_field_alignment(annot: DictionaryObject, val: int) -> None:
-    """Update text alignment for text field annotations.
+    """
+    Updates the text alignment of a text field annotation.
 
-    Modifies the alignment (Q) field of a text field annotation to set the
-    specified text alignment.
+    This function modifies the Q entry in the annotation dictionary to change
+    the text alignment of the text field.
 
     Args:
-        annot: PDF text field annotation dictionary to modify
-        val: Alignment value to set (typically 0=left, 1=center, 2=right)
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (int): The new alignment value (0=Left, 1=Center, 2=Right).
     """
-
     annot[NameObject(Q)] = NumberObject(val)
 
 
 def update_text_field_multiline(annot: DictionaryObject, val: bool) -> None:
-    """Update multiline flag for text field annotations.
+    """
+    Updates the multiline property of a text field annotation.
 
-    Modifies the field flags (Ff) of a text field annotation to set or
-    clear the multiline flag based on the input value.
+    This function modifies the Ff (flags) entry in the annotation dictionary to
+    enable or disable the multiline property of the text field.
 
     Args:
-        annot: PDF text field annotation dictionary to modify
-        val: Whether to enable multiline (True) or disable (False)
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (bool): True to enable multiline, False to disable.
     """
-
     if val:
         annot[NameObject(Ff)] = NumberObject(int(annot[NameObject(Ff)]) | MULTILINE)
 
 
 def update_text_field_comb(annot: DictionaryObject, val: bool) -> None:
-    """Update comb formatting flag for text field annotations.
+    """
+    Updates the comb property of a text field annotation.
 
-    Modifies the field flags (Ff) of a text field annotation to set or
-    clear the comb flag which enables/disables comb formatting.
+    This function modifies the Ff (flags) entry in the annotation dictionary to
+    enable or disable the comb property of the text field, which limits the
+    number of characters that can be entered in each line.
 
     Args:
-        annot: PDF text field annotation dictionary to modify
-        val: Whether to enable comb formatting (True) or disable (False)
+        annot (DictionaryObject): The annotation dictionary for the text field.
+        val (bool): True to enable comb, False to disable.
     """
-
     if val:
         annot[NameObject(Ff)] = NumberObject(int(annot[NameObject(Ff)]) | COMB)
 
 
 def update_check_radio_size(annot: DictionaryObject, val: float) -> None:
-    """Update the size of a checkbox or radio button widget while maintaining center position.
+    """
+    Updates the size of a check box or radio button annotation.
 
-    Args:
-        annot: PDF annotation dictionary containing the widget to modify
-        val: New size value (width and height) for the widget
+    This function modifies the Rect entry in the annotation dictionary to change
+    the size of the check box or radio button.
 
-    Note:
-        The widget will be resized symmetrically around its center point,
-        maintaining the same center position while changing its dimensions.
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the check box or
+            radio button.
+        val (float): The new size (width and height) for the check box or radio button.
     """
-
     rect = annot[Rect]
-    center_x = (rect[0] + rect[2]) / 2
-    center_y = (rect[1] + rect[3]) / 2
+    # scale from bottom left
     new_rect = [
-        FloatObject(center_x - val / 2),
-        FloatObject(center_y - val / 2),
-        FloatObject(center_x + val / 2),
-        FloatObject(center_y + val / 2),
+        rect[0],
+        rect[1],
+        FloatObject(rect[0] + val),
+        FloatObject(rect[1] + val),
     ]
     annot[NameObject(Rect)] = ArrayObject(new_rect)
 
 
-# TODO: remove this and switch to hooks
-NON_ACRO_FORM_PARAM_TO_FUNC = {
-    ("TextWidget", "alignment"): update_text_field_alignment,
-    ("TextWidget", "multiline"): update_text_field_multiline,
-    ("TextWidget", "comb"): update_text_field_comb,
-}
+def update_dropdown_choices(annot: DictionaryObject, val: list) -> None:
+    """
+    Updates the choices in a dropdown field annotation.
+
+    This function modifies the Opt entry in the annotation dictionary to change
+    the available choices in the dropdown field.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the dropdown field.
+        val (list): A list of strings representing the new choices for the dropdown.
+    """
+    annot[NameObject(Opt)] = ArrayObject(
+        [ArrayObject([TextStringObject(each), TextStringObject(each)]) for each in val]
+    )

PyPDFForm/image.py

@@ -1,12 +1,10 @@
 # -*- coding: utf-8 -*-
-"""Provides image processing utilities for PDF forms.
-
-This module contains functions for:
-- Rotating images while maintaining quality
-- Extracting image dimensions
-- Handling image streams and formats
+"""
+This module provides functionalities for handling images within PyPDFForm.
 
-Supports common image formats including JPEG, PNG, and others supported by PIL.
+It includes functions for rotating images, retrieving image dimensions, and
+calculating the resolutions for drawing an image on a PDF page, taking into
+account whether to preserve the aspect ratio.
 """
 
 from io import BytesIO
@@ -14,21 +12,26 @@ from typing import Tuple, Union
 
 from PIL import Image
 
+from .constants import Rect
+
 
 def rotate_image(image_stream: bytes, rotation: Union[float, int]) -> bytes:
-    """Rotates an image while maintaining original quality and format.
+    """
+    Rotates an image by a specified angle in degrees.
+
+    This function takes an image stream as bytes and rotates it using the PIL library.
+    The rotation is performed around the center of the image, and the expand=True
+    parameter ensures that the entire rotated image is visible, even if it extends
+    beyond the original image boundaries.
 
     Args:
-        image_stream: Input image as bytes
-        rotation: Rotation angle in degrees (can be a float for precise angles)
+        image_stream (bytes): The image data as bytes.
+        rotation (Union[float, int]): The rotation angle in degrees. Positive values
+            rotate the image counterclockwise, while negative values rotate it clockwise.
 
     Returns:
-        bytes: Rotated image as bytes in the original format
-
-    Note:
-        Automatically expands the canvas to prevent cropping during rotation.
+        bytes: The rotated image data as bytes.
     """
-
     buff = BytesIO()
     buff.write(image_stream)
     buff.seek(0)
@@ -48,18 +51,18 @@ def rotate_image(image_stream: bytes, rotation: Union[float, int]) -> bytes:
 
 
 def get_image_dimensions(image_stream: bytes) -> Tuple[float, float]:
-    """Extracts width and height from an image stream.
+    """
+    Retrieves the width and height of an image from its byte stream.
+
+    This function uses the PIL library to open the image from the provided byte stream
+    and returns its dimensions (width and height) as a tuple of floats.
 
     Args:
-        image_stream: Input image as bytes
+        image_stream (bytes): The image data as bytes.
 
     Returns:
-        Tuple[float, float]: (width, height) in pixels
-
-    Note:
-        Works with any image format supported by PIL (Pillow)
+        Tuple[float, float]: The width and height of the image in pixels.
     """
-
     buff = BytesIO()
     buff.write(image_stream)
     buff.seek(0)
@@ -67,3 +70,50 @@ def get_image_dimensions(image_stream: bytes) -> Tuple[float, float]:
     image = Image.open(buff)
 
     return image.size
+
+
+def get_draw_image_resolutions(
+    widget: dict,
+    preserve_aspect_ratio: bool,
+    image_width: float,
+    image_height: float,
+) -> Tuple[float, float, float, float]:
+    """
+    Calculates the position and dimensions for drawing an image on a PDF page.
+
+    This function determines the x, y coordinates, width, and height for drawing an
+    image within a specified widget area on a PDF page. It takes into account whether
+    the aspect ratio of the image should be preserved and adjusts the dimensions
+    accordingly.
+
+    Args:
+        widget (dict): A dictionary containing the widget's rectangle coordinates
+            (x1, y1, x2, y2) under the key "Rect".
+        preserve_aspect_ratio (bool): Whether to preserve the aspect ratio of the image.
+            If True, the image will be scaled to fit within the widget area while
+            maintaining its original aspect ratio.
+        image_width (float): The width of the image in pixels.
+        image_height (float): The height of the image in pixels.
+
+    Returns:
+        Tuple[float, float, float, float]: A tuple containing the x, y coordinates,
+            width, and height of the image to be drawn on the PDF page.
+    """
+    x = float(widget[Rect][0])
+    y = float(widget[Rect][1])
+    width = abs(float(widget[Rect][0]) - float(widget[Rect][2]))
+    height = abs(float(widget[Rect][1]) - float(widget[Rect][3]))
+
+    if preserve_aspect_ratio:
+        ratio = max(image_width / width, image_height / height)
+
+        new_width = image_width / ratio
+        new_height = image_height / ratio
+
+        x += abs(new_width - width) / 2
+        y += abs(new_height - height) / 2
+
+        width = new_width
+        height = new_height
+
+    return x, y, width, height

PyPDFForm/middleware/base.py

@@ -1,29 +1,24 @@
 # -*- coding: utf-8 -*-
-"""Provides base widget middleware for PDF form elements.
-
-This module contains the Widget base class that defines common functionality
-and properties for all PDF form widgets, including:
-- Name and value management
-- Styling properties (borders, colors)
-- Schema generation
-- Basic validation
+"""
+Module containing base classes for middleware.
+
+This module defines the base class for form widgets, which are used to
+represent form fields in a PDF document. The Widget class provides
+common attributes and methods for all form widgets, such as name, value,
+and schema definition.
 """
 
 from typing import Any
 
 
 class Widget:
-    """Abstract base class for all PDF form widget middleware.
-
-    Provides common interface and functionality for:
-    - Managing widget names and values
-    - Handling visual properties (borders, colors)
-    - Generating JSON schema definitions
-    - Providing sample values
+    """
+    Base class for form widget.
 
-    Subclasses must implement:
-    - sample_value property
-    - Any widget-specific functionality
+    The Widget class provides a base implementation for form widgets,
+    which are used to represent form fields in a PDF document. It
+    defines common attributes and methods for all form widgets, such
+    as name, value, and schema definition.
     """
 
     SET_ATTR_TRIGGER_HOOK_MAP = {}
@@ -33,87 +28,76 @@ class Widget:
         name: str,
         value: Any = None,
     ) -> None:
-        """Initializes a new widget with basic properties.
+        """
+        Initialize a new widget.
 
         Args:
-            name: Field name/key for the widget
-            value: Initial value for the widget (default: None)
+            name (str): The name of the widget.
+            value (Any): The initial value of the widget. Defaults to None.
         """
-
         super().__init__()
         self._name = name
         self._value = value
         self.desc = None
-        self.border_color = None
-        self.background_color = None
-        self.border_width = None
-        self.border_style = None
-        self.dash_array = None
-        self.render_widget = None
         self.hooks_to_trigger = []
 
     def __setattr__(self, name: str, value: Any) -> None:
-        """Sets an attribute on the widget with special handling for hook-triggering attributes.
+        """
+        Set an attribute on the widget.
 
-        For attributes listed in SET_ATTR_TRIGGER_HOOK_MAP, when set to non-None values,
-        adds a hook to hooks_to_trigger list with the mapped hook name and value.
-        All other attributes are set normally via the standard object.__setattr__.
+        This method overrides the default __setattr__ method to
+        trigger hooks when certain attributes are set.
 
         Args:
-            name: Name of the attribute to set
-            value: Value to set the attribute to
-
-        Note:
-            The hook triggering only occurs when:
-            1. The attribute is in SET_ATTR_TRIGGER_HOOK_MAP
-            2. The value being set is not None
+            name (str): The name of the attribute.
+            value (Any): The value of the attribute.
         """
-
         if name in self.SET_ATTR_TRIGGER_HOOK_MAP and value is not None:
             self.hooks_to_trigger.append((self.SET_ATTR_TRIGGER_HOOK_MAP[name], value))
         super().__setattr__(name, value)
 
     @property
     def name(self) -> str:
-        """Gets the widget's field name/key.
+        """
+        Get the name of the widget.
 
         Returns:
-            str: The widget's name as it appears in the PDF form
+            str: The name of the widget.
         """
-
         return self._name
 
     @property
     def value(self) -> Any:
-        """Gets the widget's current value.
+        """
+        Get the value of the widget.
 
         Returns:
-            Any: The widget's current value (type depends on widget type)
+            Any: The value of the widget.
         """
-
         return self._value
 
     @value.setter
     def value(self, value: Any) -> None:
-        """Sets the widget's value.
+        """
+        Set the value of the widget.
 
         Args:
-            value: New value for the widget (type depends on widget type)
+            value (Any): The value to set.
         """
-
         self._value = value
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the widget.
+        """
+        Get the schema definition of the widget.
+
+        This method returns a dictionary that defines the schema
+        for the widget. The schema definition is used to validate
+        the widget's value.
 
         Returns:
-            dict: Schema properties including:
-                - description (if available)
-                - type constraints
-                - other widget-specific properties
+            dict: The schema definition of the widget.
         """
-
         result = {}
 
         if self.desc is not None:
@@ -123,12 +107,10 @@ class Widget:
 
     @property
     def sample_value(self) -> Any:
-        """Generates a sample value appropriate for the widget type.
-
-        Returns:
-            Any: A representative value demonstrating the widget's expected input
+        """
+        Get a sample value for the widget.
 
         Raises:
-            NotImplementedError: Must be implemented by subclasses
+            NotImplementedError: This method must be implemented by subclasses.
         """
         raise NotImplementedError