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

PyPDFForm/watermark.py

@@ -1,12 +1,11 @@
 # -*- coding: utf-8 -*-
-"""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
+"""
+Module related to adding watermarks to a PDF.
+
+This module provides functionalities to add watermarks to existing PDF documents.
+It supports drawing text, lines, and images as watermarks.
+The module also includes functions to merge these watermarks with the original PDF content
+and to copy specific widgets from the watermarks to the original PDF.
 """
 
 from io import BytesIO
@@ -23,208 +22,77 @@ from .utils import stream_to_io
 
 
 def draw_text(canvas: Canvas, **kwargs) -> None:
-    """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
+    """
+    Draws a text string on the given canvas using the specified font, size, and color.
+    Supports multiline text by splitting the input string by newline characters.
 
     Args:
-        canvas: Canvas object to draw on
-        **kwargs: Additional arguments including:
-            widget: Text widget with content and properties
-            x: X coordinate for drawing
-            y: Y coordinate for drawing
-    """
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the text's properties and coordinates.
+            - widget: The widget object containing font, font_size, font_color, and value.
+            - x (float): The x-coordinate of the text's starting point.
+            - y (float): The y-coordinate of the text's starting point.
 
+    Returns:
+        None
+    """
     widget = kwargs["widget"]
     coordinate_x = kwargs["x"]
     coordinate_y = kwargs["y"]
 
     text_to_draw = widget.value
-
-    if not text_to_draw:
-        text_to_draw = ""
-
-    if widget.max_length is not None:
-        text_to_draw = text_to_draw[: widget.max_length]
-
     canvas.setFont(widget.font, widget.font_size)
     canvas.setFillColorRGB(
         widget.font_color[0], widget.font_color[1], widget.font_color[2]
     )
+    text_obj = canvas.beginText(coordinate_x, coordinate_y)
+    for line in text_to_draw.split("\n"):
+        text_obj.textLine(line)
+    canvas.drawText(text_obj)
 
-    if widget.comb is True:
-        for i, char in enumerate(text_to_draw):
-            canvas.drawString(
-                coordinate_x + widget.character_paddings[i],
-                coordinate_y,
-                char,
-            )
-    elif (
-        widget.text_wrap_length is None or len(text_to_draw) < widget.text_wrap_length
-    ) and widget.text_lines is None:
-        canvas.drawString(
-            coordinate_x,
-            coordinate_y,
-            text_to_draw,
-        )
-    else:
-        text_obj = canvas.beginText(0, 0)
-        for i, line in enumerate(widget.text_lines):
-            cursor_moved = False
-            if (
-                widget.text_line_x_coordinates is not None
-                and widget.text_line_x_coordinates[i] - coordinate_x != 0
-            ):
-                text_obj.moveCursor(widget.text_line_x_coordinates[i] - coordinate_x, 0)
-                cursor_moved = True
-            text_obj.textLine(line)
-            if cursor_moved:
-                text_obj.moveCursor(
-                    -1 * (widget.text_line_x_coordinates[i] - coordinate_x), 0
-                )
-
-        canvas.saveState()
-        canvas.translate(
-            coordinate_x,
-            coordinate_y,
-        )
-        canvas.drawText(text_obj)
-        canvas.restoreState()
-
-
-def draw_rect(canvas: Canvas, **kwargs) -> None:
-    """Draws a rectangle onto a watermark canvas.
 
-    Args:
-        canvas: Canvas object to draw on
-        **kwargs: Additional arguments including:
-            x: X coordinate of bottom-left corner
-            y: Y coordinate of bottom-left corner
-            width: Width of rectangle
-            height: Height of rectangle
-            border_color: Border color
-            background_color: Background color
-            border_width: Border width
-            dash_array: Dash pattern for border
+def draw_line(canvas: Canvas, **kwargs) -> None:
     """
-
-    x = kwargs["x"]
-    y = kwargs["y"]
-    width = kwargs["width"]
-    height = kwargs["height"]
-
-    canvas.saveState()
-    stroke, fill = set_border_and_background_styles(canvas, **kwargs)
-    canvas.rect(x, y, width, height, stroke=stroke, fill=fill)
-    canvas.restoreState()
-
-
-def draw_ellipse(canvas: Canvas, **kwargs) -> None:
-    """Draws an ellipse onto a watermark canvas.
+    Draws a line on the given canvas with the specified source and destination coordinates, and color.
 
     Args:
-        canvas: Canvas object to draw on
-        **kwargs: Additional arguments including:
-            x1: X coordinate of first bounding point
-            y1: Y coordinate of first bounding point
-            x2: X coordinate of second bounding point
-            y2: Y coordinate of second bounding point
-            border_color: Border color
-            background_color: Background color
-            border_width: Border width
-            dash_array: Dash pattern for border
-    """
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the line's properties and coordinates.
+            - src_x (float): The x-coordinate of the line's starting point.
+            - src_y (float): The y-coordinate of the line's starting point.
+            - dest_x (float): The x-coordinate of the line's ending point.
+            - dest_y (float): The y-coordinate of the line's ending point.
+            - color (tuple): A tuple representing the RGB color of the line.
 
-    x1 = kwargs["x1"]
-    y1 = kwargs["y1"]
-    x2 = kwargs["x2"]
-    y2 = kwargs["y2"]
-
-    canvas.saveState()
-    stroke, fill = set_border_and_background_styles(canvas, **kwargs)
-    canvas.ellipse(x1, y1, x2, y2, stroke=stroke, fill=fill)
-    canvas.restoreState()
-
-
-def draw_line(canvas: Canvas, **kwargs) -> None:
-    """Draws a line onto a watermark canvas.
-
-    Args:
-        canvas: Canvas object to draw on
-        **kwargs: Additional arguments including:
-            src_x: X coordinate of start point
-            src_y: Y coordinate of start point
-            dest_x: X coordinate of end point
-            dest_y: Y coordinate of end point
-            border_color: Line color
-            border_width: Line width
-            dash_array: Dash pattern for line
+    Returns:
+        None
     """
-
     src_x = kwargs["src_x"]
     src_y = kwargs["src_y"]
     dest_x = kwargs["dest_x"]
     dest_y = kwargs["dest_y"]
+    color = kwargs["color"]
 
-    canvas.saveState()
-    set_border_and_background_styles(canvas, **kwargs)
+    canvas.setStrokeColorRGB(*(color))
     canvas.line(src_x, src_y, dest_x, dest_y)
-    canvas.restoreState()
 
 
-def set_border_and_background_styles(canvas: Canvas, **kwargs) -> tuple:
-    """Configures stroke and fill styles for drawing operations.
+def draw_image(canvas: Canvas, **kwargs) -> None:
+    """
+    Draws an image on the given canvas, scaling it to fit within the specified width and height.
 
     Args:
-        canvas: Canvas object to configure
-        **kwargs: Additional arguments including:
-            border_color: Border color
-            background_color: Background color
-            border_width: Border width
-            dash_array: Dash pattern for border
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the image's properties and coordinates.
+            - stream (bytes): The image data as a byte stream.
+            - x (float): The x-coordinate of the image's bottom-left corner.
+            - y (float): The y-coordinate of the image's bottom-left corner.
+            - width (float): The desired width of the image.
+            - height (float): The desired height of the image.
 
     Returns:
-        tuple: (stroke_flag, fill_flag) indicating which styles were set
+        None
     """
-
-    border_color = kwargs["border_color"]
-    background_color = kwargs["background_color"]
-    border_width = kwargs["border_width"]
-    dash_array = kwargs["dash_array"]
-
-    stroke = 0
-    fill = 0
-    if border_color is not None and border_width:
-        canvas.setStrokeColor(border_color)
-        canvas.setLineWidth(border_width)
-        stroke = 1
-    if background_color is not None:
-        canvas.setFillColor(background_color)
-        fill = 1
-
-    if dash_array is not None:
-        canvas.setDash(array=dash_array)
-
-    return stroke, fill
-
-
-def draw_image(canvas: Canvas, **kwargs) -> None:
-    """Draws an image onto a watermark canvas.
-
-    Args:
-        canvas: Canvas object to draw on
-        **kwargs: Additional arguments including:
-            stream: Image data as bytes
-            x: X coordinate for drawing
-            y: Y coordinate for drawing
-            width: Width of drawn image
-            height: Height of drawn image
-    """
-
     image_stream = kwargs["stream"]
     coordinate_x = kwargs["x"]
     coordinate_y = kwargs["y"]
@@ -253,18 +121,22 @@ def create_watermarks_and_draw(
     action_type: str,
     actions: List[dict],
 ) -> List[bytes]:
-    """Creates watermarks for each page with specified drawing operations.
+    """
+    Creates watermarks for a specific page in the PDF based on the provided actions and draws them.
+
+    This function takes a PDF file, a page number, an action type, and a list of actions as input.
+    It then creates a watermark for the specified page by drawing the specified actions on a Canvas object.
 
     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
+        pdf (bytes): The PDF file as a byte stream.
+        page_number (int): The page number to which the watermark should be applied (1-indexed).
+        action_type (str): The type of action to perform when creating the watermark (e.g., "image", "text", "line").
+        actions (List[dict]): A list of dictionaries, where each dictionary represents an action to be performed on the watermark.
 
     Returns:
-        List[bytes]: Watermark data for each page (empty for non-target pages)
+        List[bytes]: A list of byte streams, where the element at index (page_number - 1) contains the watermark for the specified page,
+                     and all other elements are empty byte streams.
     """
-
     pdf_file = PdfReader(stream_to_io(pdf))
     buff = BytesIO()
 
@@ -280,8 +152,6 @@ def create_watermarks_and_draw(
         "image": draw_image,
         "text": draw_text,
         "line": draw_line,
-        "rect": draw_rect,
-        "ellipse": draw_ellipse,
     }
 
     if action_type_to_func.get(action_type):
@@ -303,16 +173,19 @@ def merge_watermarks_with_pdf(
     pdf: bytes,
     watermarks: List[bytes],
 ) -> bytes:
-    """Combines watermarks with their corresponding PDF pages.
+    """
+    Merges the generated watermarks with the original PDF content.
+
+    This function takes a PDF file and a list of watermarks as input.
+    It then merges each watermark with its corresponding page in the PDF.
 
     Args:
-        pdf: Original PDF document as bytes
-        watermarks: List of watermark data for each page
+        pdf (bytes): The PDF file as a byte stream.
+        watermarks (List[bytes]): A list of byte streams, where each element represents the watermark for a specific page.
 
     Returns:
-        bytes: Merged PDF document with watermarks applied
+        bytes: A byte stream representing the merged PDF with watermarks applied.
     """
-
     result = BytesIO()
     pdf_file = PdfReader(stream_to_io(pdf))
     output = PdfWriter()
@@ -335,32 +208,26 @@ def copy_watermark_widgets(
     keys: Union[List[str], None],
     page_num: Union[int, None],
 ) -> bytes:
-    """Copies annotation widgets (form fields) from watermark PDFs onto the corresponding pages of a base PDF.
-
-    This function selectively copies annotation widgets (form fields) from watermark PDFs to a base PDF.
-    It allows specifying which widgets to copy based on their keys, and optionally restricts the operation
-    to a specific page number.
+    """
+    Copies specific widgets from the watermarks to the original PDF.
 
-    The function can handle either a list of watermarks (one per page) or a single watermark PDF applied to all pages.
-    Widgets are only copied if their key is present in the provided keys list.
+    This function allows you to selectively copy widgets (e.g., form fields) from the watermarks to the original PDF.
+    You can specify which widgets to copy by providing a list of keys.
 
     Args:
-        pdf: The original PDF document as bytes.
-        watermarks: Either a list of watermark PDF data (as bytes, one per page) or a single watermark PDF as bytes.
-                   Empty or None entries are skipped.
-        keys: List of widget keys (str). Only widgets whose key is in this list will be copied.
-              If None, all widgets will be copied.
-        page_num: Optional page number (0-based) to restrict widget copying to. If None, widgets are copied
-                  across all pages.
+        pdf (bytes): The PDF file as a byte stream.
+        watermarks (Union[List[bytes], bytes]): A list of byte streams, where each element represents the watermark for a specific page.
+        keys (Union[List[str], None]): A list of keys identifying the widgets to copy from the watermarks. If None, all widgets are copied.
+        page_num (Union[int, None]): The page number to copy the widgets from. If None, widgets are copied from all pages.
 
     Returns:
-        bytes: The resulting PDF document with selected annotation widgets from watermarks copied onto their respective pages.
+        bytes: A byte stream representing the modified PDF with the specified widgets copied from the watermarks.
     """
-
     pdf_file = PdfReader(stream_to_io(pdf))
     out = PdfWriter()
     out.append(pdf_file)
 
+    # TODO: refactor duplicate logic with merge_two_pdfs
     widgets_to_copy_watermarks = {}
     widgets_to_copy_pdf = {}
 
@@ -382,6 +249,8 @@ def copy_watermark_widgets(
             widgets_to_copy_pdf[j] = []
             for annot in page.get(Annots, []):
                 key = get_widget_key(annot.get_object(), False)
+
+                # cannot be watermarks when page_num not None
                 if (keys is None or key in keys) and (
                     page_num is None or page_num == j
                 ):

PyPDFForm/widgets/base.py

@@ -1,46 +1,42 @@
 # -*- coding: utf-8 -*-
-"""Provides base widget class and utilities for PDF form field creation.
+"""
+This module defines the base class for all widgets in PyPDFForm.
 
-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
+It provides a common interface for interacting with different types of form fields,
+such as text fields, checkboxes, and radio buttons. The Widget class handles
+basic properties like name, page number, and coordinates, and provides methods
+for rendering the widget on a PDF page.
 """
 
 from io import BytesIO
-from typing import List, Union, cast
+from typing import List, Union
 
-from pypdf import PdfReader, PdfWriter
-from pypdf.generic import DictionaryObject
+from pypdf import PdfReader
 from reportlab.lib.colors import Color
 from reportlab.pdfgen.canvas import Canvas
 
-from ..constants import Annots
-from ..patterns import NON_ACRO_FORM_PARAM_TO_FUNC
-from ..template import get_widget_key
 from ..utils import stream_to_io
 
 
 class Widget:
-    """Abstract base class for all PDF form widget creators.
+    """
+    Base class for all widgets in PyPDFForm.
 
-    Provides common functionality for:
-    - Managing widget parameters
-    - Generating watermarks for form fields
-    - Handling both AcroForm and non-AcroForm parameters
-    - PDF page integration
+    This class provides a common interface for interacting with different types of
+    form fields. It handles basic properties like name, page number, and
+    coordinates, and provides methods for rendering the widget on a PDF page.
 
     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 (list): List of user-defined parameters for the widget.
+        COLOR_PARAMS (list): List of color-related parameters for the widget.
+        ALLOWED_HOOK_PARAMS (list): List of allowed hook parameters for the widget.
+        NONE_DEFAULTS (list): List of parameters that default to None.
+        ACRO_FORM_FUNC (str): Name of the AcroForm function to use for rendering the widget.
     """
 
     USER_PARAMS = []
     COLOR_PARAMS = []
-    ALLOWED_NON_ACRO_FORM_PARAMS = []
+    ALLOWED_HOOK_PARAMS = []
     NONE_DEFAULTS = []
     ACRO_FORM_FUNC = ""
 
@@ -52,16 +48,23 @@ class Widget:
         y: Union[float, List[float]],
         **kwargs,
     ) -> None:
-        """Initializes a new widget with position and parameters.
+        """
+        Initializes a Widget object.
+
+        This method sets up the basic properties of the widget, such as its name,
+        page number, and coordinates. It also handles user-defined parameters,
+        color parameters, and hook 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
-        """
+            name (str): Name of the widget.
+            page_number (int): Page number of the widget.
+            x (Union[float, List[float]]): X coordinate(s) of the widget. Can be a single float or a list of floats.
+            y (Union[float, List[float]]): Y coordinate(s) of the widget. Can be a single float or a list of floats.
+            **kwargs: Additional keyword arguments for customizing the widget.
 
+        Returns:
+            None
+        """
         super().__init__()
         self.page_number = page_number
         self.acro_form_params = {
@@ -69,7 +72,7 @@ class Widget:
             "x": x,
             "y": y,
         }
-        self.non_acro_form_params = []
+        self.hook_params = []
 
         for each in self.USER_PARAMS:
             user_input, param = each
@@ -86,34 +89,44 @@ class Widget:
             elif user_input in self.NONE_DEFAULTS:
                 self.acro_form_params[param] = None
 
-        for each in self.ALLOWED_NON_ACRO_FORM_PARAMS:
+        for each in self.ALLOWED_HOOK_PARAMS:
             if each in kwargs:
-                self.non_acro_form_params.append(
-                    ((type(self).__name__, each), kwargs.get(each))
-                )
+                self.hook_params.append((each, kwargs.get(each)))
 
     def canvas_operations(self, canvas: Canvas) -> None:
-        """Draws the widget on the provided PDF canvas using AcroForm.
+        """
+        Performs canvas operations for the widget.
 
-        Calls the appropriate AcroForm function on the canvas to create the widget
-        with the parameters specified in self.acro_form_params.
+        This method uses the ReportLab library to draw the widget on the PDF canvas.
+        It retrieves the appropriate AcroForm function from the canvas and calls it
+        with the widget's parameters.
 
         Args:
-            canvas: The ReportLab Canvas object to draw the widget on.
-        """
+            canvas (Canvas): Canvas object to operate on.
 
+        Returns:
+            None
+        """
         getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
 
     def watermarks(self, stream: bytes) -> List[bytes]:
-        """Generates watermarks containing the widget for each page.
+        """
+        Generates watermarks for the widget.
+
+        This method takes a PDF stream as input and generates watermarks for each
+        page of the PDF. The watermark is created by drawing the widget on a
+        ReportLab canvas and then embedding the canvas as a watermark on the
+        specified page.
 
         Args:
-            stream: PDF document as bytes to add widget to
+            stream (bytes): PDF stream.
 
         Returns:
-            List[bytes]: Watermark data for each page (empty for non-target pages)
+            List[bytes]: List of watermarks for each page. Each element in the list
+                         is a byte stream representing the watermark for that page.
+                         If a page does not need a watermark, the corresponding
+                         element will be an empty byte string.
         """
-
         pdf = PdfReader(stream_to_io(stream))
         page_count = len(pdf.pages)
         watermark = BytesIO()
@@ -136,35 +149,3 @@ class Widget:
             watermark.read() if i == self.page_number - 1 else b""
             for i in range(page_count)
         ]
-
-
-def handle_non_acro_form_params(pdf: bytes, key: str, params: list) -> bytes:
-    """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()
-    out.append(pdf_file)
-
-    for page in out.pages:
-        for annot in page.get(Annots, []):
-            annot = cast(DictionaryObject, annot.get_object())
-            _key = get_widget_key(annot.get_object(), False)
-
-            if _key == key:
-                for param in params:
-                    if param[0] in NON_ACRO_FORM_PARAM_TO_FUNC:
-                        NON_ACRO_FORM_PARAM_TO_FUNC[param[0]](annot, param[1])
-
-    with BytesIO() as f:
-        out.write(f)
-        f.seek(0)
-        return f.read()

PyPDFForm/widgets/checkbox.py

@@ -1,34 +1,30 @@
 # -*- coding: utf-8 -*-
-"""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.
+"""
+This module defines the CheckBoxWidget class, which is a subclass of the
+Widget class. It represents a checkbox form field in a PDF document.
 """
 
 from .base import Widget
 
 
 class CheckBoxWidget(Widget):
-    """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.
+    """
+    Represents a checkbox widget in a PDF form.
+
+    Inherits from the base Widget class and adds specific parameters for
+    checkbox styling, such as button style, tick color, background color,
+    border color, and border width.
+
+    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.
+        ACRO_FORM_FUNC (str): The name of the AcroForm function to use for
+            creating the checkbox.
     """
 
     USER_PARAMS = [
-        ("size", "size"),
         ("button_style", "buttonStyle"),
         ("tick_color", "textColor"),
         ("bg_color", "fillColor"),
@@ -36,4 +32,5 @@ class CheckBoxWidget(Widget):
         ("border_width", "borderWidth"),
     ]
     COLOR_PARAMS = ["tick_color", "bg_color", "border_color"]
+    ALLOWED_HOOK_PARAMS = ["size"]
     ACRO_FORM_FUNC = "checkbox"