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

PyPDFForm/watermark.py

@@ -1,18 +1,42 @@
 # -*- 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 .utils import stream_to_io
+from .constants import Annots
+from .patterns import WIDGET_KEY_PATTERNS
+from .utils import extract_widget_property, 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 +97,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 +124,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 +151,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 +178,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 +214,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 +254,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()
@@ -216,9 +306,17 @@ def create_watermarks_and_draw(
 
 def merge_watermarks_with_pdf(
     pdf: bytes,
-    watermarks: list,
+    watermarks: List[bytes],
 ) -> 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 +332,57 @@ def merge_watermarks_with_pdf(
     output.write(result)
     result.seek(0)
     return result.read()
+
+
+def copy_watermark_widgets(
+    pdf: bytes, watermarks: List[bytes], keys: List[str]
+) -> bytes:
+    """
+    Copies annotation widgets (form fields) from watermark PDFs onto the corresponding pages of a base PDF,
+    including only those widgets whose key matches an entry in the provided keys list.
+
+    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, but only if their key
+    matches one of the specified keys.
+
+    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.
+        keys: List of widget keys (str). Only widgets whose key is in this list will be copied.
+
+    Returns:
+        bytes: The resulting PDF document with selected 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
+                key = extract_widget_property(
+                    annot.get_object(), WIDGET_KEY_PATTERNS, None, str
+                )
+                if key in keys:
+                    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
+                if Annots in page
+                else ArrayObject(widgets_to_copy[i])
+            )
+
+    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()