PyPDFForm 2.0.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

PyPDFForm/watermark.py

@@ -1,18 +1,41 @@
 # -*- coding: utf-8 -*-
-"""Contains helpers for watermark."""
+"""Provides watermark generation, annotation copying, and merging functionality for PDF forms.
+
+This module handles:
+- Drawing text, images, shapes, and lines onto PDF watermarks
+- Managing watermark styles and properties
+- Merging watermarks with PDF documents
+- Copying annotation widgets (form fields) from watermark PDFs onto base PDFs
+- Supporting various drawing operations needed for form filling
+"""
 
 from io import BytesIO
 from typing import List
 
 from pypdf import PdfReader, PdfWriter
+from pypdf.generic import ArrayObject, NameObject
 from reportlab.lib.utils import ImageReader
 from reportlab.pdfgen.canvas import Canvas
 
+from .constants import Annots
 from .utils import stream_to_io
 
 
 def draw_text(*args) -> None:
-    """Draws a text on the watermark."""
+    """Draws text onto a watermark canvas with proper formatting.
+
+    Handles:
+    - Comb fields (fixed character spacing)
+    - Multiline text with wrapping
+    - Font and color styling
+    - Text alignment
+
+    Args:
+        args[0]: Canvas object to draw on
+        args[1]: Text widget with content and properties
+        args[2]: X coordinate for drawing
+        args[3]: Y coordinate for drawing
+    """
 
     canvas = args[0]
     widget = args[1]
@@ -73,7 +96,19 @@ def draw_text(*args) -> None:
 
 
 def draw_rect(*args) -> None:
-    """Draws a rectangle on the watermark."""
+    """Draws a rectangle onto a watermark canvas.
+
+    Args:
+        args[0]: Canvas object to draw on
+        args[1]: X coordinate of bottom-left corner
+        args[2]: Y coordinate of bottom-left corner
+        args[3]: Width of rectangle
+        args[4]: Height of rectangle
+        args[5]: Border color
+        args[6]: Background color
+        args[7]: Border width
+        args[8]: Dash pattern for border
+    """
 
     canvas = args[0]
     x = args[1]
@@ -88,7 +123,19 @@ def draw_rect(*args) -> None:
 
 
 def draw_ellipse(*args) -> None:
-    """Draws an ellipse on the watermark."""
+    """Draws an ellipse onto a watermark canvas.
+
+    Args:
+        args[0]: Canvas object to draw on
+        args[1]: X coordinate of first bounding point
+        args[2]: Y coordinate of first bounding point
+        args[3]: X coordinate of second bounding point
+        args[4]: Y coordinate of second bounding point
+        args[5]: Border color
+        args[6]: Background color
+        args[7]: Border width
+        args[8]: Dash pattern for border
+    """
 
     canvas = args[0]
     x1 = args[1]
@@ -103,7 +150,19 @@ def draw_ellipse(*args) -> None:
 
 
 def draw_line(*args) -> None:
-    """Draws a line on the watermark."""
+    """Draws a line onto a watermark canvas.
+
+    Args:
+        args[0]: Canvas object to draw on
+        args[1]: X coordinate of start point
+        args[2]: Y coordinate of start point
+        args[3]: X coordinate of end point
+        args[4]: Y coordinate of end point
+        args[5]: Line color
+        args[6]: Unused (kept for consistency)
+        args[7]: Line width
+        args[8]: Dash pattern for line
+    """
 
     canvas = args[0]
     src_x = args[1]
@@ -118,7 +177,18 @@ def draw_line(*args) -> None:
 
 
 def set_border_and_background_styles(*args) -> tuple:
-    """Sets colors for both border and background before drawing."""
+    """Configures stroke and fill styles for drawing operations.
+
+    Args:
+        args[0]: Canvas object to configure
+        args[5]: Border color
+        args[6]: Background color
+        args[7]: Border width
+        args[8]: Dash pattern for border
+
+    Returns:
+        tuple: (stroke_flag, fill_flag) indicating which styles were set
+    """
 
     canvas = args[0]
     border_color = args[5]
@@ -143,7 +213,16 @@ def set_border_and_background_styles(*args) -> tuple:
 
 
 def draw_image(*args) -> None:
-    """Draws an image on the watermark."""
+    """Draws an image onto a watermark canvas.
+
+    Args:
+        args[0]: Canvas object to draw on
+        args[1]: Image data as bytes
+        args[2]: X coordinate for drawing
+        args[3]: Y coordinate for drawing
+        args[4]: Width of drawn image
+        args[5]: Height of drawn image
+    """
 
     canvas = args[0]
     image_stream = args[1]
@@ -174,7 +253,17 @@ def create_watermarks_and_draw(
     action_type: str,
     actions: List[list],
 ) -> List[bytes]:
-    """Creates a canvas watermark and draw some stuffs on it."""
+    """Creates watermarks for each page with specified drawing operations.
+
+    Args:
+        pdf: PDF document as bytes
+        page_number: Page number to create watermark for (1-based)
+        action_type: Type of drawing operation ('text', 'image', 'line', etc.)
+        actions: List of drawing operations to perform
+
+    Returns:
+        List[bytes]: Watermark data for each page (empty for non-target pages)
+    """
 
     pdf_file = PdfReader(stream_to_io(pdf))
     buff = BytesIO()
@@ -218,7 +307,15 @@ def merge_watermarks_with_pdf(
     pdf: bytes,
     watermarks: list,
 ) -> bytes:
-    """Merges watermarks with PDF."""
+    """Combines watermarks with their corresponding PDF pages.
+
+    Args:
+        pdf: Original PDF document as bytes
+        watermarks: List of watermark data for each page
+
+    Returns:
+        bytes: Merged PDF document with watermarks applied
+    """
 
     result = BytesIO()
     pdf_file = PdfReader(stream_to_io(pdf))
@@ -234,3 +331,48 @@ def merge_watermarks_with_pdf(
     output.write(result)
     result.seek(0)
     return result.read()
+
+
+def copy_watermark_widgets(
+    pdf: bytes,
+    watermarks: list,
+) -> bytes:
+    """Copies annotation widgets from watermark PDFs onto the corresponding pages of a base PDF.
+
+    For each watermark in the provided list, any annotation widgets (such as form fields)
+    are cloned and appended to the annotations of the corresponding page in the base PDF.
+
+    Args:
+        pdf: The original PDF document as bytes.
+        watermarks: List of watermark PDF data (as bytes), one per page. Empty or None entries are skipped.
+
+    Returns:
+        bytes: The resulting PDF document with annotation widgets from watermarks copied onto their respective pages.
+    """
+
+    pdf_file = PdfReader(stream_to_io(pdf))
+    out = PdfWriter()
+    out.append(pdf_file)
+
+    widgets_to_copy = {}
+
+    for i, watermark in enumerate(watermarks):
+        if not watermark:
+            continue
+
+        widgets_to_copy[i] = []
+        watermark_file = PdfReader(stream_to_io(watermark))
+        for page in watermark_file.pages:
+            for annot in page.get(Annots, []):  # noqa
+                widgets_to_copy[i].append(annot.clone(out))
+
+    for i, page in enumerate(out.pages):
+        if i in widgets_to_copy:
+            page[NameObject(Annots)] = page[NameObject(Annots)] + ArrayObject(
+                widgets_to_copy[i]
+            )  # noqa
+
+    with BytesIO() as f:
+        out.write(f)
+        f.seek(0)
+        return f.read()

PyPDFForm/widgets/base.py

@@ -1,8 +1,14 @@
 # -*- coding: utf-8 -*-
-"""Contains base class for all widgets to create."""
+"""Provides base widget class and utilities for PDF form field creation.
+
+This module contains:
+- Widget base class with core form field creation functionality
+- Watermark generation for form fields
+- Parameter handling for both AcroForm and non-AcroForm fields
+"""
 
 from io import BytesIO
-from typing import List, cast
+from typing import List, Union, cast
 
 from pypdf import PdfReader, PdfWriter
 from pypdf.generic import DictionaryObject
@@ -15,7 +21,21 @@ from ..utils import extract_widget_property, stream_to_io
 
 
 class Widget:
-    """Base class for all widgets to create."""
+    """Abstract base class for all PDF form widget creators.
+
+    Provides common functionality for:
+    - Managing widget parameters
+    - Generating watermarks for form fields
+    - Handling both AcroForm and non-AcroForm parameters
+    - PDF page integration
+
+    Attributes:
+        USER_PARAMS: List of (user_name, pdf_param) mappings
+        COLOR_PARAMS: List of color parameters to convert
+        ALLOWED_NON_ACRO_FORM_PARAMS: Supported non-AcroForm parameters
+        NONE_DEFAULTS: Parameters that should default to None
+        ACRO_FORM_FUNC: Name of AcroForm function for widget creation
+    """
 
     USER_PARAMS = []
     COLOR_PARAMS = []
@@ -27,11 +47,19 @@ class Widget:
         self,
         name: str,
         page_number: int,
-        x: float,
-        y: float,
+        x: Union[float, List[float]],
+        y: Union[float, List[float]],
         **kwargs,
     ) -> None:
-        """Sets acro form parameters."""
+        """Initializes a new widget with position and parameters.
+
+        Args:
+            name: Field name/key for the widget
+            page_number: Page number to place widget on (1-based)
+            x: X coordinate(s) for widget position
+            y: Y coordinate(s) for widget position
+            **kwargs: Additional widget-specific parameters
+        """
 
         super().__init__()
         self.page_number = page_number
@@ -63,8 +91,27 @@ class Widget:
                     ((type(self).__name__, each), kwargs.get(each))
                 )
 
+    def canvas_operations(self, canvas: Canvas) -> None:
+        """Draws the widget on the provided PDF canvas using AcroForm.
+
+        Calls the appropriate AcroForm function on the canvas to create the widget
+        with the parameters specified in self.acro_form_params.
+
+        Args:
+            canvas: The ReportLab Canvas object to draw the widget on.
+        """
+
+        getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
+
     def watermarks(self, stream: bytes) -> List[bytes]:
-        """Returns a list of watermarks after creating the widget."""
+        """Generates watermarks containing the widget for each page.
+
+        Args:
+            stream: PDF document as bytes to add widget to
+
+        Returns:
+            List[bytes]: Watermark data for each page (empty for non-target pages)
+        """
 
         pdf = PdfReader(stream_to_io(stream))
         page_count = len(pdf.pages)
@@ -78,7 +125,7 @@ class Widget:
             ),
         )
 
-        getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
+        self.canvas_operations(canvas)
 
         canvas.showPage()
         canvas.save()
@@ -91,7 +138,16 @@ class Widget:
 
 
 def handle_non_acro_form_params(pdf: bytes, key: str, params: list) -> bytes:
-    """Handles non acro form parameters when creating a widget."""
+    """Processes non-AcroForm parameters for a widget.
+
+    Args:
+        pdf: PDF document as bytes to modify
+        key: Field name/key of the widget to update
+        params: List of (parameter_name, value) tuples to set
+
+    Returns:
+        bytes: Modified PDF with updated parameters
+    """
 
     pdf_file = PdfReader(stream_to_io(pdf))
     out = PdfWriter()

PyPDFForm/widgets/checkbox.py

@@ -1,11 +1,31 @@
 # -*- coding: utf-8 -*-
-"""Contains checkbox widget to create."""
+"""Provides checkbox widget creation functionality for PDF forms.
+
+This module contains the CheckBoxWidget class which handles creation of:
+- Interactive checkbox fields with three states (checked, unchecked, read-only)
+- Custom button styles (check, cross, circle)
+- Color styling for tick, background and border
+- Size adjustments
+- PDF form field integration
+
+Supports all standard PDF checkbox properties and integrates with both
+AcroForm and non-AcroForm PDF documents.
+"""
 
 from .base import Widget
 
 
 class CheckBoxWidget(Widget):
-    """Checkbox widget to create."""
+    """Creates and configures PDF checkbox widgets.
+
+    Supports all standard checkbox properties including:
+    - Button style customization (check, cross, circle)
+    - Tick, background and border colors
+    - Size adjustments
+    - PDF form field integration
+
+    Inherits from Widget base class adding checkbox-specific parameters.
+    """
 
     USER_PARAMS = [
         ("size", "size"),

PyPDFForm/widgets/dropdown.py

@@ -1,11 +1,28 @@
 # -*- coding: utf-8 -*-
-"""Contains dropdown widget to create."""
+"""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
+"""
 
 from .text import TextWidget
 
 
 class DropdownWidget(TextWidget):
-    """Dropdown widget to create."""
+    """Creates and configures PDF dropdown widgets.
+
+    Extends TextWidget to support dropdown/combobox functionality including:
+    - Option list management
+    - Initial value selection
+    - All inherited text field styling options
+
+    Class Attributes:
+        NONE_DEFAULTS: Empty list - dropdowns require options
+        ACRO_FORM_FUNC: Uses underlying text field creation function
+    """
 
     NONE_DEFAULTS = []
     ACRO_FORM_FUNC = "_textfield"
@@ -18,7 +35,18 @@ class DropdownWidget(TextWidget):
         y: float,
         **kwargs,
     ) -> None:
-        """Sets acro form parameters."""
+        """Initializes a new dropdown widget with options.
+
+        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
+        """
 
         self.USER_PARAMS = super().USER_PARAMS[:-1] + [
             ("options", "options"),

PyPDFForm/widgets/radio.py

@@ -0,0 +1,78 @@
+# -*- 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.
+"""
+
+from typing import List
+
+from reportlab.pdfgen.canvas import Canvas
+
+from .checkbox import CheckBoxWidget
+
+
+class RadioWidget(CheckBoxWidget):
+    """Creates and configures PDF radio button widgets.
+
+    Supports all standard radio button properties including:
+    - Mutually exclusive selection handling
+    - Button style customization and color styling
+    - Size adjustments
+    - PDF form field integration
+
+    Inherits from CheckBoxWidget, adding radio-specific parameters and logic.
+    """
+
+    ACRO_FORM_FUNC = "radio"
+
+    def __init__(
+        self,
+        name: str,
+        page_number: int,
+        x: List[float],
+        y: List[float],
+        **kwargs,
+    ) -> None:
+        """Initializes a new radio button widget with options.
+
+        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.
+        """
+
+        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.
+
+        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.
+
+        Args:
+            canvas: The ReportLab Canvas object to draw the radio buttons 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()
+            new_acro_form_params["x"] = x
+            new_acro_form_params["y"] = y
+            new_acro_form_params["value"] = str(i)
+            getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**new_acro_form_params)

PyPDFForm/widgets/text.py

@@ -1,11 +1,28 @@
 # -*- coding: utf-8 -*-
-"""Contains text field widget to create."""
+"""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
+"""
 
 from .base import Widget
 
 
 class TextWidget(Widget):
-    """Text field widget to create."""
+    """Creates and configures PDF text field widgets.
+
+    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
+
+    Inherits from Widget base class adding text-specific parameters.
+    """
 
     USER_PARAMS = [
         ("width", "width"),