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

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,95 +1,103 @@
 # -*- 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 = {}
+
     def __init__(
         self,
         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:
+        """
+        Set an attribute on the widget.
+
+        This method overrides the default __setattr__ method to
+        trigger hooks when certain attributes are set.
+
+        Args:
+            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:
@@ -99,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

PyPDFForm/middleware/checkbox.py

@@ -1,11 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF checkbox widgets.
+"""
+Module representing a checkbox widget.
 
-This module contains the Checkbox class which handles:
-- Checkbox state management (checked/unchecked)
-- Button style customization
-- Value validation and conversion
-- Schema generation for form validation
+This module defines the Checkbox class, which is a subclass of the
+Widget class. It represents a checkbox form field in a PDF document.
 """
 
 from typing import Union
@@ -14,21 +12,16 @@ from .base import Widget
 
 
 class Checkbox(Widget):
-    """Middleware for PDF checkbox widgets.
-
-    Handles all aspects of checkbox processing including:
-    - State management (checked/unchecked)
-    - Button style customization (check, cross, circle)
-    - Value validation
-    - PDF form field integration
+    """
+    Represents a checkbox widget.
 
-    Inherits from Widget base class and extends it with checkbox-specific features.
+    The Checkbox class provides a concrete implementation for
+    checkbox form fields. It inherits from the Widget class and
+    implements the schema_definition and sample_value properties.
     """
 
-    BUTTON_STYLE_MAPPING = {
-        "check": "4",
-        "cross": "5",
-        "circle": "l",
+    SET_ATTR_TRIGGER_HOOK_MAP = {
+        "size": "update_check_radio_size",
     }
 
     def __init__(
@@ -36,62 +29,42 @@ class Checkbox(Widget):
         name: str,
         value: bool = None,
     ) -> None:
-        """Initializes a new checkbox widget.
+        """
+        Initializes a checkbox widget.
 
         Args:
-            name: Field name/key for the checkbox
-            value: Initial checked state (default: None)
-        """
+            name (str): The name of the checkbox.
+            value (bool): The initial value of the checkbox. Defaults to None.
 
+        Attributes:
+            size (int): The size of the checkbox. Defaults to None.
+        """
         super().__init__(name, value)
 
         self.size = None
-        self._button_style = self.BUTTON_STYLE_MAPPING["check"]
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the checkbox.
+        """
+        Returns the schema definition for the checkbox.
+
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the checkbox value.
 
         Returns:
-            dict: Schema properties including:
-                - type: boolean
-                - description (if available from base class)
+            dict: A dictionary representing the schema definition.
         """
-
         return {"type": "boolean", **super().schema_definition}
 
     @property
     def sample_value(self) -> Union[bool, int]:
-        """Generates a sample value for the checkbox.
-
-        Returns:
-            Union[bool, int]: Always returns True as the sample checked state
         """
+        Returns a sample value for the checkbox.
 
-        return True
-
-    @property
-    def button_style(self) -> Union[str, None]:
-        """Gets the current button style identifier.
+        The sample value is used to generate example data for the
+        checkbox field.
 
         Returns:
-            Union[str, None]: The button style code used in PDF form fields
+            Union[bool, int]: A sample value for the checkbox.
         """
-
-        return self._button_style
-
-    @button_style.setter
-    def button_style(self, value) -> None:
-        """Sets the button style for the checkbox.
-
-        Accepts either style names ('check', 'cross', 'circle') or
-        direct PDF button style codes ('4', '5', 'l').
-
-        Args:
-            value: Button style name or code to set
-        """
-
-        if value in self.BUTTON_STYLE_MAPPING:
-            self._button_style = self.BUTTON_STYLE_MAPPING[value]
-        elif value in self.BUTTON_STYLE_MAPPING.values():
-            self._button_style = value
+        return True

PyPDFForm/middleware/dropdown.py

@@ -1,58 +1,68 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF dropdown/combobox widgets.
+"""
+Module representing a dropdown widget.
 
-This module contains the Dropdown class which handles:
-- Dropdown option management
-- Selection index tracking
-- Value validation
-- Schema generation for form validation
+This module defines the Dropdown class, which is a subclass of the
+Widget class. It represents a dropdown form field in a PDF document.
 """
 
 from .base import Widget
 
 
 class Dropdown(Widget):
-    """Middleware for PDF dropdown/combobox widgets.
+    """
+    Represents a dropdown widget in a PDF form.
+
+    Inherits from the Widget class and provides specific functionality
+    for handling dropdown form fields.
 
-    Handles all aspects of dropdown processing including:
-    - Option list management
-    - Selection index validation
-    - Value conversion
-    - PDF form field integration
+    Key attributes:
+        font (str): The font of the dropdown field.
+        choices (List[str]): The list of available options in the dropdown.
+        value (int): The index of the selected choice in the choices list.
 
-    Inherits from Widget base class and extends it with dropdown-specific features.
+    Methods:
+        schema_definition: Returns a schema definition for the dropdown's value.
+        sample_value: Returns a sample value for the dropdown.
     """
 
+    SET_ATTR_TRIGGER_HOOK_MAP = {
+        "font": "update_text_field_font",
+        "choices": "update_dropdown_choices",
+    }
+
     def __init__(
         self,
         name: str,
         value: int = None,
     ) -> None:
-        """Initializes a new dropdown widget.
+        """
+        Initializes a dropdown widget.
 
         Args:
-            name: Field name/key for the dropdown
-            value: Initial selected option index (default: None)
-        """
+            name (str): The name of the dropdown.
+            value (int): The initial value of the dropdown. Defaults to None.
 
+        Attributes:
+            font (str): The font of the dropdown field.
+            choices (List[str]): The list of choices for the dropdown.
+        """
         super().__init__(name, value)
 
-        self.choices = []
-        self.desc = None
+        self.font = None
+        self.choices = None
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the dropdown.
+        """
+        Returns the schema definition for the dropdown.
 
-        Includes:
-        - Type constraint (integer)
-        - Maximum valid option index
-        - Any inherited schema properties
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the dropdown value.
 
         Returns:
-            dict: Complete JSON schema definition
+            dict: A dictionary representing the schema definition.
         """
-
         return {
             "type": "integer",
             "maximum": len(self.choices) - 1,
@@ -61,12 +71,13 @@ class Dropdown(Widget):
 
     @property
     def sample_value(self) -> int:
-        """Generates a sample value for the dropdown.
+        """
+        Returns a sample value for the dropdown.
 
-        Returns the index of the last option by default.
+        The sample value is used to generate example data for the
+        dropdown field.
 
         Returns:
-            int: Index of the last option in the dropdown
+            int: A sample value for the dropdown.
         """
-
         return len(self.choices) - 1

PyPDFForm/middleware/image.py

@@ -1,34 +1,22 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF image field widgets.
-
-This module contains the Image class which handles:
-- Image field processing for common formats (JPEG, PNG)
-- Aspect ratio preservation when scaling
-- PDF form field integration
-- Image rotation and positioning
-
-Supports image data from:
-- Raw bytes
-- File paths
-- File-like objects
+"""
+Module representing an image widget.
 
-Note: Inherits core functionality from Signature middleware since
-PDF image fields are technically signature fields with images.
+This module defines the Image class, which is a subclass of the
+Signature class. It represents an image form field in a PDF document,
+allowing users to add images to the form.
 """
 
 from .signature import Signature
 
 
 class Image(Signature):
-    """Middleware for PDF image field widgets.
-
-    Handles all aspects of image field processing including:
-    - Image data handling
-    - Aspect ratio control
-    - PDF form field integration
+    """
+    Represents an image widget.
 
-    Inherits from Signature class and extends it with image-specific features.
+    The Image class provides a concrete implementation for
+    image form fields. It inherits from the Signature class and
+    sets the preserve_aspect_ratio attribute to False by default.
     """
 
     preserve_aspect_ratio = False
-    """Whether to preserve the original image's aspect ratio when scaling."""

PyPDFForm/middleware/radio.py

@@ -1,26 +1,22 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF radio button widgets.
+"""
+Module representing a radio button widget.
 
-This module contains the Radio class which handles:
-- Radio button group state management
-- Option selection tracking
-- Value validation and conversion
-- Schema generation for form validation
+This module defines the Radio class, which is a subclass of the
+Checkbox class. It represents a radio button form field in a PDF
+document, allowing users to select one option from a group of choices.
 """
 
 from .checkbox import Checkbox
 
 
 class Radio(Checkbox):
-    """Middleware for PDF radio button widgets.
-
-    Handles all aspects of radio button processing including:
-    - Group selection management
-    - Option counting and validation
-    - Button style customization
-    - PDF form field integration
+    """
+    Represents a radio button widget.
 
-    Inherits from Checkbox class and extends it with radio-specific features.
+    The Radio class provides a concrete implementation for radio button
+    form fields. It inherits from the Checkbox class and implements
+    the schema_definition and sample_value properties.
     """
 
     def __init__(
@@ -28,32 +24,33 @@ class Radio(Checkbox):
         name: str,
         value: int = None,
     ) -> None:
-        """Initializes a new radio button widget.
+        """
+        Initializes a radio button widget.
 
         Args:
-            name: Field name/key for the radio button group
-            value: Initial selected option index (default: None)
-        """
+            name (str): The name of the radio button.
+            value (int): The initial value of the radio button. Defaults to None.
 
+        Attributes:
+            number_of_options (int): The number of options for the radio button.
+        """
         super().__init__(name, value)
 
-        self.size = None
         self.number_of_options = 0
-        self._button_style = self.BUTTON_STYLE_MAPPING["circle"]
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the radio button group.
+        """
+        Returns the schema definition for the radio button.
 
-        Includes:
-        - Type constraint (integer)
-        - Maximum valid option index
-        - Any inherited schema properties
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the radio button value,
+        which is expected to be an integer representing the index
+        of the selected option.
 
         Returns:
-            dict: Complete JSON schema definition
+            dict: A dictionary representing the schema definition.
         """
-
         return {
             "maximum": self.number_of_options - 1,
             **super().schema_definition,
@@ -62,12 +59,14 @@ class Radio(Checkbox):
 
     @property
     def sample_value(self) -> int:
-        """Generates a sample value for the radio button group.
+        """
+        Returns a sample value for the radio button.
 
-        Returns the index of the last option by default.
+        The sample value is used to generate example data for the
+        radio button field. It returns the index of the last option
+        in the group.
 
         Returns:
-            int: Index of the last option in the group
+            int: A sample value for the radio button.
         """
-
         return self.number_of_options - 1