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

PyPDFForm/widgets/dropdown.py

@@ -1,27 +1,23 @@
 # -*- coding: utf-8 -*-
-"""Provides dropdown widget creation functionality for PDF forms.
-
-This module contains the DropdownWidget class which handles creation of:
-- Interactive dropdown/combobox fields
-- Option list management
-- Visual styling inheritance from text fields
-- Form field integration
+"""
+This module defines the DropdownWidget class, which is a subclass of the
+TextWidget class. It represents a dropdown form field in a PDF document.
 """
 
 from .text import TextWidget
 
 
 class DropdownWidget(TextWidget):
-    """Creates and configures PDF dropdown widgets.
+    """
+    Represents a dropdown widget in a PDF form.
 
-    Extends TextWidget to support dropdown/combobox functionality including:
-    - Option list management
-    - Initial value selection
-    - All inherited text field styling options
+    Inherits from the base TextWidget class and adds specific parameters for
+    dropdown styling, such as options.
 
-    Class Attributes:
-        NONE_DEFAULTS: Empty list - dropdowns require options
-        ACRO_FORM_FUNC: Uses underlying text field creation function
+    Attributes:
+        NONE_DEFAULTS (list): A list of parameters that default to None.
+        ACRO_FORM_FUNC (str): The name of the AcroForm function to use for
+            creating the dropdown.
     """
 
     NONE_DEFAULTS = []
@@ -35,19 +31,16 @@ class DropdownWidget(TextWidget):
         y: float,
         **kwargs,
     ) -> None:
-        """Initializes a new dropdown widget with options.
+        """
+        Initializes a DropdownWidget object.
 
         Args:
-            name: Field name/key for the dropdown
-            page_number: Page number to place widget on (1-based)
-            x: X coordinate for widget position
-            y: Y coordinate for widget position
-            **kwargs: Additional widget parameters including:
-                width/height: Field dimensions
-                font/font_size: Text styling
-                options: List of dropdown choices
+            name (str): Name of the widget.
+            page_number (int): Page number of the widget.
+            x (float): X coordinate of the widget.
+            y (float): Y coordinate of the widget.
+            **kwargs: Additional keyword arguments.
         """
-
         self.USER_PARAMS = super().USER_PARAMS[:-1] + [
             ("options", "options"),
         ]

PyPDFForm/widgets/image.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """
-This module provides the ImageWidget class for creating and customizing
-image fields in PDF forms. It extends SignatureWidget to enable placement
-of image widgets on specified pages and coordinates, using an image field
-template instead of a signature field template.
+This module defines the ImageWidget class, which is a subclass of the
+SignatureWidget class. It represents an image field in a PDF document.
+The ImageWidget leverages the SignatureWidget's functionality to handle
+image insertion into PDF forms.
 """
 
 from .signature import SignatureWidget
@@ -11,14 +11,16 @@ from .signature import SignatureWidget
 
 class ImageWidget(SignatureWidget):
     """
-    A widget for adding an image field to a PDF form.
+    Represents an image widget in a PDF form.
 
-    Inherits from SignatureWidget, but uses an image widget template
-    instead of a signature field template. All initialization parameters
-    and methods are inherited from SignatureWidget.
+    This class inherits from the SignatureWidget and is specifically designed
+    for handling image fields in PDF forms. It reuses the signature widget's
+    infrastructure for positioning and rendering, but instead of capturing
+    a signature, it inserts a provided image.
 
     Attributes:
-        BEDROCK_WIDGET_TO_COPY (str): The widget type to copy from the bedrock template ("image").
+        BEDROCK_WIDGET_TO_COPY (str): The name of the bedrock widget to copy,
+            set to "image".
     """
 
     BEDROCK_WIDGET_TO_COPY = "image"

PyPDFForm/widgets/radio.py

@@ -1,14 +1,8 @@
 # -*- coding: utf-8 -*-
-"""Provides radio button widget creation functionality for PDF forms.
-
-This module contains the RadioWidget class which handles creation of:
-- Interactive radio button fields for mutually exclusive selections
-- Custom button styles and color styling
-- Size adjustments
-- PDF form field integration
-
-Supports all standard PDF radio button properties and integrates with both
-AcroForm and non-AcroForm PDF documents.
+"""
+This module defines the RadioWidget class, which is a subclass of the
+CheckBoxWidget class. It represents a radio button form field in a PDF
+document.
 """
 
 from typing import List
@@ -19,15 +13,16 @@ from .checkbox import CheckBoxWidget
 
 
 class RadioWidget(CheckBoxWidget):
-    """Creates and configures PDF radio button widgets.
+    """
+    Represents a radio button widget in a PDF form.
 
-    Supports all standard radio button properties including:
-    - Mutually exclusive selection handling
-    - Button style customization and color styling
-    - Size adjustments
-    - PDF form field integration
+    This class inherits from the CheckBoxWidget and is designed for handling
+    radio button fields in PDF forms. Radio buttons allow the user to select
+    only one option from a predefined set of choices.
 
-    Inherits from CheckBoxWidget, adding radio-specific parameters and logic.
+    Attributes:
+        ACRO_FORM_FUNC (str): The name of the AcroForm function to use for
+            creating the radio button, set to "radio".
     """
 
     ACRO_FORM_FUNC = "radio"
@@ -40,35 +35,30 @@ class RadioWidget(CheckBoxWidget):
         y: List[float],
         **kwargs,
     ) -> None:
-        """Initializes a new radio button widget with options.
+        """
+        Initializes a RadioWidget object.
 
         Args:
-            name: Field name/key for the radio group.
-            page_number: Page number to place widget on (1-based).
-            x: List of X coordinates for each radio button.
-            y: List of Y coordinates for each radio button.
-            **kwargs: Additional widget parameters including:
-                width/height: Field dimensions.
-                font/font_size: Text styling.
-                options: List of radio button choices.
-                shape: Button style (e.g., circle, check, cross, etc.).
-                color: Button color and border styling.
+            name (str): Name of the widget.
+            page_number (int): Page number of the widget.
+            x (List[float]): List of X coordinates for each radio button.
+            y (List[float]): List of Y coordinates for each radio button.
+            **kwargs: Additional keyword arguments.
         """
-
         self.USER_PARAMS.append(("shape", "shape"))
         super().__init__(name, page_number, x, y, **kwargs)
 
     def canvas_operations(self, canvas: Canvas) -> None:
-        """Draws all radio button options on the provided PDF canvas.
+        """
+        Performs canvas operations for the radio button widget.
 
-        Iterates over each (x, y) coordinate pair for the radio button group,
-        sets the value for each option, and calls the AcroForm radio function
-        to render each button on the canvas.
+        This method iterates through the X and Y coordinates of each radio button
+        and draws it on the PDF canvas. It also sets the value of the radio button
+        based on its index in the list of coordinates.
 
         Args:
-            canvas: The ReportLab Canvas object to draw the radio buttons on.
+            canvas (Canvas): Canvas object to operate on.
         """
-
         for i, x in enumerate(self.acro_form_params["x"]):
             y = self.acro_form_params["y"][i]
             new_acro_form_params = self.acro_form_params.copy()

PyPDFForm/widgets/signature.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 """
-This module provides the SignatureWidget class for creating and customizing
-signature fields in PDF forms. It enables placement of signature widgets
-on specified pages and coordinates, and generates watermark overlays for
-PDF documents to visually represent signature fields.
+This module defines the SignatureWidget class, which is responsible for
+representing signature fields in a PDF form. It handles the creation and
+rendering of signature widgets, as well as the integration of signatures
+into the PDF document.
 """
 
 from io import BytesIO
@@ -21,26 +21,17 @@ from .bedrock import BEDROCK_PDF
 
 class SignatureWidget:
     """
-    A widget for adding a digital signature field to a PDF form.
+    Represents a signature widget in a PDF form.
 
-    This class allows you to specify the name, page number, position (x, y),
-    and size (width, height) of a signature field to be placed on a PDF page.
-    The widget is based on a bedrock template and can generate a watermark
-    overlay for the specified page, updating the annotation's name and rectangle
-    to match the provided parameters.
+    This class is responsible for handling the creation, rendering, and
+    integration of signature fields in a PDF document. It inherits from
+    the base Widget class and provides specific functionality for handling
+    signatures.
 
     Attributes:
-        BEDROCK_WIDGET_TO_COPY (str): The widget type to copy from the bedrock template.
-        name (str): The name of the signature field.
-        page_number (int): The 1-based page number where the signature field will appear.
-        x (float): The x-coordinate of the lower-left corner of the signature field.
-        y (float): The y-coordinate of the lower-left corner of the signature field.
-        optional_params (dict): Optional parameters for widget customization (e.g., width, height).
-
-    Methods:
-        watermarks(stream: bytes) -> List[bytes]:
-            Generates a list of watermark overlays, with the signature field
-            applied to the specified page.
+        OPTIONAL_PARAMS (list): A list of tuples, where each tuple contains the
+            parameter name and its default value.
+        BEDROCK_WIDGET_TO_COPY (str): The name of the bedrock widget to copy.
     """
 
     OPTIONAL_PARAMS = [
@@ -58,20 +49,17 @@ class SignatureWidget:
         **kwargs,
     ) -> None:
         """
-        Initialize a SignatureWidget.
+        Initializes a SignatureWidget object.
 
         Args:
             name (str): The name of the signature widget.
-            page_number (int): The page number where the widget will be placed (1-based).
-            x (float): The x-coordinate of the widget's lower-left corner.
-            y (float): The y-coordinate of the widget's lower-left corner.
-            width (float, optional): The width of the widget. Defaults to 160 if not provided.
-            height (float, optional): The height of the widget. Defaults to 90 if not provided.
-            **kwargs: Additional optional parameters for widget customization.
+            page_number (int): The page number of the signature widget.
+            x (float): The x coordinate of the signature widget.
+            y (float): The y coordinate of the signature widget.
+            **kwargs: Additional keyword arguments.
         """
-
         super().__init__()
-        self.non_acro_form_params = []
+        self.hook_params = []
 
         self.page_number = page_number
         self.name = name
@@ -83,22 +71,23 @@ class SignatureWidget:
 
     def watermarks(self, stream: bytes) -> List[bytes]:
         """
-        Generate watermark overlays for the signature widget on the specified PDF page.
+        Generates watermarks for the signature widget.
 
-        This method creates a list of watermark overlays for each page in the input PDF.
-        Only the page corresponding to `page_number` contains the signature widget overlay,
-        which is generated by copying and customizing a signature annotation from a bedrock
-        template PDF. All other pages in the returned list are empty byte strings.
+        This method takes a PDF stream as input, reads a "bedrock" PDF, and
+        creates a new PDF with the signature widget added as a watermark on the
+        specified page. The signature's name and rectangle are then added to the
+        new PDF.
 
         Args:
-            stream (bytes): The PDF file as a byte stream.
+            stream (bytes): The PDF stream.
 
         Returns:
-            List[bytes]: A list of byte streams, one for each page in the input PDF.
-                         Only the page corresponding to `page_number` contains the
-                         signature widget overlay; other pages are empty byte strings.
+            List[bytes]: A list of watermarks for the signature widget. Each
+            element in the list represents a page in the PDF. If the current
+            page matches the signature's page number, the corresponding element
+            will contain the watermark data. Otherwise, the element will be an
+            empty byte string.
         """
-
         input_pdf = PdfReader(stream_to_io(stream))
         page_count = len(input_pdf.pages)
         pdf = PdfReader(stream_to_io(BEDROCK_PDF))

PyPDFForm/widgets/text.py

@@ -1,33 +1,34 @@
 # -*- coding: utf-8 -*-
-"""Provides text field widget creation functionality for PDF forms.
-
-This module contains the TextWidget class which handles creation of:
-- Standard text input fields
-- Multiline text fields
-- Font and color styling
-- Field size and length constraints
+"""
+This module defines the TextWidget class, which is a subclass of the
+Widget class. It represents a text field in a PDF document.
 """
 
 from .base import Widget
 
 
 class TextWidget(Widget):
-    """Creates and configures PDF text field widgets.
+    """
+    Represents a text widget in a PDF form.
 
-    Supports all standard text field properties including:
-    - Font styling (family, size, color)
-    - Background and border colors
-    - Width/height dimensions
-    - Maximum length constraints
-    - Alignment and multiline options
+    This class inherits from the base Widget class and provides specific
+    parameters for text field styling, such as width, height, font size,
+    font color, background color, border color, border width, and maximum
+    length.
 
-    Inherits from Widget base class adding text-specific parameters.
+    Attributes:
+        USER_PARAMS (list): A list of tuples, where each tuple contains the
+            user-facing parameter name and the corresponding AcroForm parameter name.
+        COLOR_PARAMS (list): A list of user-facing parameter names that represent colors.
+        ALLOWED_HOOK_PARAMS (list): A list of allowed hook parameters.
+        NONE_DEFAULTS (list): A list of parameters that default to None.
+        ACRO_FORM_FUNC (str): The name of the AcroForm function to use for
+            creating the text field.
     """
 
     USER_PARAMS = [
         ("width", "width"),
         ("height", "height"),
-        ("font", "fontName"),
         ("font_size", "fontSize"),
         ("font_color", "textColor"),
         ("bg_color", "fillColor"),
@@ -36,6 +37,6 @@ class TextWidget(Widget):
         ("max_length", "maxlen"),
     ]
     COLOR_PARAMS = ["font_color", "bg_color", "border_color"]
-    ALLOWED_NON_ACRO_FORM_PARAMS = ["alignment", "multiline"]
+    ALLOWED_HOOK_PARAMS = ["alignment", "multiline", "comb", "font"]
     NONE_DEFAULTS = ["max_length"]
     ACRO_FORM_FUNC = "textfield"