PyPDFForm 3.5.1__py3-none-any.whl → 4.2.0__py3-none-any.whl

PyPDFForm/watermark.py

@@ -7,14 +7,8 @@ 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.
 """
-# TODO: In `draw_image`, `ImageReader(image_buff)` is created for each image. If the same image is drawn multiple times, consider caching `ImageReader` objects or passing pre-processed image data to avoid redundant processing.
-# TODO: In `create_watermarks_and_draw`, `PdfReader(stream_to_io(pdf))` is called, which re-parses the PDF. If this function is called repeatedly for the same PDF, consider passing the `PdfReader` object directly to avoid redundant parsing.
-# TODO: In `create_watermarks_and_draw`, the function returns a list of watermarks where only one element is populated. This can be inefficient for memory if there are many pages but only one watermark is created. Consider returning only the created watermark and its page number, and let the caller handle placement.
-# TODO: In `merge_watermarks_with_pdf`, `PdfReader(stream_to_io(pdf))` and `PdfReader(stream_to_io(watermarks[i]))` are called in a loop. This leads to repeated parsing of the base PDF and each watermark. It would be more efficient to parse the base PDF once and then merge watermark pages directly into the existing `PdfWriter` object.
-# TODO: In `copy_watermark_widgets`, the function reads the PDF and watermarks multiple times. Similar to `merge_watermarks_with_pdf`, optimize by parsing the base PDF and watermarks once and then manipulating the `PdfWriter` object.
-# TODO: The `copy_watermark_widgets` function has a `TODO: refactor duplicate logic with merge_two_pdfs` comment. This indicates a potential for code duplication and inefficiency. Refactoring this to a shared helper function would improve maintainability and potentially performance.
-# TODO: In `copy_watermark_widgets`, the nested loops iterating through `watermarks`, `watermark_file.pages`, and `page.get(Annots, [])` can be very inefficient for large numbers of watermarks, pages, or annotations. Consider creating a lookup structure for annotations by key to avoid repeated linear scans.
 
+from collections import defaultdict
 from io import BytesIO
 from typing import List, Union
 
@@ -84,6 +78,112 @@ def draw_line(canvas: Canvas, **kwargs) -> None:
     canvas.line(src_x, src_y, dest_x, dest_y)
 
 
+def draw_rect(canvas: Canvas, **kwargs) -> None:
+    """
+    Draws a rectangle on the given canvas with the specified coordinates, dimensions, and color.
+
+    Args:
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the rectangle's properties and coordinates.
+            - x (float): The x-coordinate of the rectangle's bottom-left corner.
+            - y (float): The y-coordinate of the rectangle's bottom-left corner.
+            - width (float): The width of the rectangle.
+            - height (float): The height of the rectangle.
+            - color (tuple): A tuple representing the RGB color of the rectangle's outline.
+            - fill_color (tuple): A tuple representing the RGB color of the rectangle's fill.
+
+    Returns:
+        None
+    """
+    x = kwargs["x"]
+    y = kwargs["y"]
+    width = kwargs["width"]
+    height = kwargs["height"]
+    color = kwargs["color"]
+    fill_color = kwargs["fill_color"]
+
+    canvas.setStrokeColorRGB(*(color))
+
+    fill = 0
+    canvas.saveState()
+    if fill_color:
+        canvas.setFillColorRGB(*(fill_color))
+        fill = 1
+
+    canvas.rect(x, y, width, height, fill=fill)
+    canvas.restoreState()
+
+
+def draw_circle(canvas: Canvas, **kwargs) -> None:
+    """
+    Draws a circle on the given canvas with the specified center coordinates, radius, and color.
+
+    Args:
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the circle's properties and coordinates.
+            - center_x (float): The x-coordinate of the circle's center.
+            - center_y (float): The y-coordinate of the circle's center.
+            - radius (float): The radius of the circle.
+            - color (tuple): A tuple representing the RGB color of the circle's outline.
+            - fill_color (tuple): A tuple representing the RGB color of the circle's fill.
+
+    Returns:
+        None
+    """
+    center_x = kwargs["center_x"]
+    center_y = kwargs["center_y"]
+    radius = kwargs["radius"]
+    color = kwargs["color"]
+    fill_color = kwargs["fill_color"]
+
+    canvas.setStrokeColorRGB(*(color))
+
+    fill = 0
+    canvas.saveState()
+    if fill_color:
+        canvas.setFillColorRGB(*(fill_color))
+        fill = 1
+
+    canvas.circle(center_x, center_y, radius, fill=fill)
+    canvas.restoreState()
+
+
+def draw_ellipse(canvas: Canvas, **kwargs) -> None:
+    """
+    Draws an ellipse on the given canvas defined by its bounding box coordinates and color.
+
+    Args:
+        canvas (Canvas): The ReportLab Canvas object to draw on.
+        **kwargs: Keyword arguments containing the ellipse's properties and coordinates.
+            - x1 (float): The x-coordinate of the first corner of the bounding box.
+            - y1 (float): The y-coordinate of the first corner of the bounding box.
+            - x2 (float): The x-coordinate of the second corner of the bounding box.
+            - y2 (float): The y-coordinate of the second corner of the bounding box.
+            - color (tuple): A tuple representing the RGB color of the ellipse's outline.
+            - fill_color (tuple): A tuple representing the RGB color of the ellipse's fill.
+
+    Returns:
+        None
+    """
+    x1 = kwargs["x1"]
+    y1 = kwargs["y1"]
+    x2 = kwargs["x2"]
+    y2 = kwargs["y2"]
+    color = kwargs["color"]
+    fill_color = kwargs["fill_color"]
+
+    canvas.setStrokeColorRGB(*(color))
+
+    fill = 0
+    canvas.saveState()
+    if fill_color:
+        canvas.setFillColorRGB(*(fill_color))
+        fill = 1
+
+    canvas.ellipse(x1, y1, x2, y2, fill=fill)
+    canvas.restoreState()
+
+
 def draw_image(canvas: Canvas, **kwargs) -> None:
     """
     Draws an image on the given canvas, scaling it to fit within the specified width and height.
@@ -122,58 +222,67 @@ def draw_image(canvas: Canvas, **kwargs) -> None:
     image_buff.close()
 
 
-def create_watermarks_and_draw(
-    pdf: bytes,
-    page_number: int,
-    action_type: str,
-    actions: List[dict],
-) -> List[bytes]:
+def create_watermarks_and_draw(pdf: bytes, to_draw: List[dict]) -> List[bytes]:
     """
-    Creates watermarks for a specific page in the PDF based on the provided actions and draws them.
+    Creates a watermark PDF for each page of the input PDF based on the drawing instructions.
 
-    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.
+    This function reads the input PDF to determine page sizes, then uses ReportLab
+    to create a separate, single-page PDF (a watermark) for each page that has
+    drawing instructions.
 
     Args:
-        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.
+        pdf (bytes): The original PDF file as a byte stream.
+        to_draw (List[dict]): A list of drawing instructions, where each dictionary
+            must contain a "page_number" key (1-based) and a "type" key ("image", "text", or "line")
+            along with type-specific parameters.
 
     Returns:
-        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.
+        List[bytes]: A list of watermark PDF byte streams. An empty byte string (b"")
+            is used for pages without any drawing instructions.
     """
-    pdf_file = PdfReader(stream_to_io(pdf))
-    buff = BytesIO()
-
-    canvas = Canvas(
-        buff,
-        pagesize=(
-            float(pdf_file.pages[page_number - 1].mediabox[2]),
-            float(pdf_file.pages[page_number - 1].mediabox[3]),
-        ),
-    )
-
-    action_type_to_func = {
+    type_to_func = {
         "image": draw_image,
         "text": draw_text,
         "line": draw_line,
+        "rect": draw_rect,
+        "circle": draw_circle,
+        "ellipse": draw_ellipse,
     }
 
-    if action_type_to_func.get(action_type):
-        for each in actions:
-            action_type_to_func[action_type](canvas, **each)
+    result = []
+
+    page_to_to_draw = defaultdict(list)
+    for each in to_draw:
+        page_to_to_draw[each["page_number"]].append(each)
+
+    pdf_file = PdfReader(stream_to_io(pdf))
+    buff = BytesIO()
+
+    for i, page in enumerate(pdf_file.pages):
+        elements = page_to_to_draw[i + 1]
+        if not elements:
+            result.append(b"")
+            continue
+
+        buff.seek(0)
+        buff.flush()
+
+        canvas = Canvas(
+            buff,
+            pagesize=(
+                float(page.mediabox[2]),
+                float(page.mediabox[3]),
+            ),
+        )
 
-    canvas.save()
-    buff.seek(0)
+        for element in elements:
+            type_to_func[element["type"]](canvas, **element)
 
-    watermark = buff.read()
-    buff.close()
+        canvas.save()
+        buff.seek(0)
+        result.append(buff.read())
 
-    return [
-        watermark if i == page_number - 1 else b"" for i in range(len(pdf_file.pages))
-    ]
+    return result
 
 
 def merge_watermarks_with_pdf(

PyPDFForm/widgets/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 The `widgets` package provides a collection of classes representing various types of PDF form fields (widgets).
 

PyPDFForm/widgets/base.py

@@ -12,8 +12,7 @@ Classes:
       functionality for rendering and manipulation.
 """
 
-# TODO: In `watermarks`, `PdfReader(stream_to_io(stream))` is called, which re-parses the PDF for each widget. If multiple widgets are being processed, consider passing the `PdfReader` object directly to avoid redundant parsing.
-# TODO: In `watermarks`, the list comprehension `[watermark.read() if i == self.page_number - 1 else b"" for i in range(page_count)]` creates a new `BytesIO` object and reads from it for each widget. If many widgets are created, this could be optimized by creating the `BytesIO` object once and passing it around, or by directly returning the watermark bytes and its page number.
+from __future__ import annotations
 
 from dataclasses import dataclass
 from inspect import signature
@@ -28,35 +27,6 @@ from ..constants import fieldFlags, required
 from ..utils import stream_to_io
 
 
-@dataclass
-class Field:
-    """
-    Base dataclass for all PDF form fields.
-
-    This class defines the common properties that all types of form fields
-    (e.g., text fields, checkboxes, radio buttons) share. Specific field types
-    will extend this class to add their unique attributes.
-
-    Attributes:
-        name (str): The name of the form field. This is used to identify the
-            field within the PDF document.
-        page_number (int): The 1-based page number on which the field is located.
-        x (float): The x-coordinate of the field's position on the page.
-        y (float): The y-coordinate of the field's position on the page.
-        required (Optional[bool]): Indicates whether the field is required to be
-            filled by the user. Defaults to None, meaning not explicitly set.
-        tooltip (Optional[str]): A tooltip message that appears when the user
-            hovers over the field. Defaults to None.
-    """
-
-    name: str
-    page_number: int
-    x: float
-    y: float
-    required: Optional[bool] = None
-    tooltip: Optional[str] = None
-
-
 class Widget:
     """
     Base class for all widgets in PyPDFForm.
@@ -106,6 +76,7 @@ class Widget:
         """
         super().__init__()
         self.page_number = page_number
+        self.name = name
         self.acro_form_params = {
             "name": name,
             "x": x,
@@ -181,44 +152,93 @@ class Widget:
         """
         getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
 
-    def watermarks(self, stream: bytes) -> List[bytes]:
+    @staticmethod
+    def bulk_watermarks(widgets: List[Widget], stream: bytes) -> List[bytes]:
         """
-        Generates watermarks for the widget.
+        Generates watermarks for multiple widgets in bulk.
 
-        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.
+        This static method processes a list of widgets and a PDF stream to create
+        a list of watermark streams, one for each page of the PDF. Widgets are
+        grouped by their page number, and all widgets for a given page are drawn
+        onto a single ReportLab canvas, which is then returned as the watermark
+        stream for that page. This is more efficient than generating watermarks
+        for each widget individually.
 
         Args:
-            stream (bytes): PDF stream.
+            widgets (List[Widget]): A list of Widget objects to be watermarked.
+            stream (bytes): The PDF stream to be watermarked.
 
         Returns:
-            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.
+            List[bytes]: A list of watermark streams (bytes), where the index
+                         corresponds to the 0-based page index of the original PDF.
+                         Each element is a byte stream representing the combined
+                         watermark for that page. Pages without any widgets will
+                         have an empty byte string (b"").
         """
+        result = []
+
         pdf = PdfReader(stream_to_io(stream))
-        page_count = len(pdf.pages)
         watermark = BytesIO()
 
-        canvas = Canvas(
-            watermark,
-            pagesize=(
-                float(pdf.pages[self.page_number - 1].mediabox[2]),
-                float(pdf.pages[self.page_number - 1].mediabox[3]),
-            ),
-        )
+        widgets_by_page = {}
+        for widget in widgets:
+            if widget.page_number not in widgets_by_page:
+                widgets_by_page[widget.page_number] = []
+            widgets_by_page[widget.page_number].append(widget)
+
+        for i, page in enumerate(pdf.pages):
+            page_num = i + 1
+            if page_num not in widgets_by_page:
+                result.append(b"")
+                continue
 
-        self._required_handler(canvas)
-        self.canvas_operations(canvas)
+            watermark.seek(0)
+            watermark.flush()
 
-        canvas.showPage()
-        canvas.save()
-        watermark.seek(0)
+            canvas = Canvas(
+                watermark,
+                pagesize=(
+                    float(page.mediabox[2]),
+                    float(page.mediabox[3]),
+                ),
+            )
 
-        return [
-            watermark.read() if i == self.page_number - 1 else b""
-            for i in range(page_count)
-        ]
+            for widget in widgets_by_page[page_num]:
+                getattr(widget, "_required_handler")(canvas)
+                widget.canvas_operations(canvas)
+
+            canvas.showPage()
+            canvas.save()
+            watermark.seek(0)
+            result.append(watermark.read())
+
+        return result
+
+
+@dataclass
+class Field:
+    """
+    Base dataclass for all PDF form fields.
+
+    This class defines the common properties that all types of form fields
+    (e.g., text fields, checkboxes, radio buttons) share. Specific field types
+    will extend this class to add their unique attributes.
+
+    Attributes:
+        name (str): The name of the form field. This is used to identify the
+            field within the PDF document.
+        page_number (int): The 1-based page number on which the field is located.
+        x (float): The x-coordinate of the field's position on the page.
+        y (float): The y-coordinate of the field's position on the page.
+        required (Optional[bool]): Indicates whether the field is required to be
+            filled by the user. Defaults to None, meaning not explicitly set.
+        tooltip (Optional[str]): A tooltip message that appears when the user
+            hovers over the field. Defaults to None.
+    """
+
+    name: str
+    page_number: int
+    x: float
+    y: float
+    required: Optional[bool] = None
+    tooltip: Optional[str] = None

PyPDFForm/widgets/checkbox.py

@@ -11,40 +11,11 @@ functionality for interacting with checkbox form fields in PDFs.
 """
 
 from dataclasses import dataclass
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Type
 
 from .base import Field, Widget
 
 
-@dataclass
-class CheckBoxField(Field):
-    """
-    Represents a checkbox field in a PDF document.
-
-    This dataclass extends the `Field` base class and defines the specific
-    attributes that can be configured for a checkbox field.
-
-    Attributes:
-        _field_type (str): The type of the field, fixed as "checkbox".
-        size (Optional[float]): The size of the checkbox.
-        button_style (Optional[str]): The visual style of the checkbox button
-            (e.g., "check", "circle", "cross").
-        tick_color (Optional[Tuple[float, ...]]): The color of the checkmark or tick.
-        bg_color (Optional[Tuple[float, ...]]): The background color of the checkbox.
-        border_color (Optional[Tuple[float, ...]]): The color of the checkbox's border.
-        border_width (Optional[float]): The width of the checkbox's border.
-    """
-
-    _field_type: str = "checkbox"
-
-    size: Optional[float] = None
-    button_style: Optional[str] = None
-    tick_color: Optional[Tuple[float, ...]] = None
-    bg_color: Optional[Tuple[float, ...]] = None
-    border_color: Optional[Tuple[float, ...]] = None
-    border_width: Optional[float] = None
-
-
 class CheckBoxWidget(Widget):
     """
     Represents a checkbox widget in a PDF form.
@@ -74,3 +45,32 @@ class CheckBoxWidget(Widget):
     COLOR_PARAMS = ["tick_color", "bg_color", "border_color"]
     ALLOWED_HOOK_PARAMS = ["size"]
     ACRO_FORM_FUNC = "checkbox"
+
+
+@dataclass
+class CheckBoxField(Field):
+    """
+    Represents a checkbox field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a checkbox field.
+
+    Attributes:
+        _widget_class (Type[Widget]): The widget class associated with this field type.
+        size (Optional[float]): The size of the checkbox.
+        button_style (Optional[str]): The visual style of the checkbox button
+            (e.g., "check", "circle", "cross").
+        tick_color (Optional[Tuple[float, ...]]): The color of the checkmark or tick.
+        bg_color (Optional[Tuple[float, ...]]): The background color of the checkbox.
+        border_color (Optional[Tuple[float, ...]]): The color of the checkbox's border.
+        border_width (Optional[float]): The width of the checkbox's border.
+    """
+
+    _widget_class: Type[Widget] = CheckBoxWidget
+
+    size: Optional[float] = None
+    button_style: Optional[str] = None
+    tick_color: Optional[Tuple[float, ...]] = None
+    bg_color: Optional[Tuple[float, ...]] = None
+    border_color: Optional[Tuple[float, ...]] = None
+    border_width: Optional[float] = None

PyPDFForm/widgets/dropdown.py

@@ -11,49 +11,12 @@ specific functionality for interacting with dropdown form fields in PDFs.
 """
 
 from dataclasses import dataclass
-from typing import List, Optional, Tuple, Union
+from typing import List, Optional, Tuple, Type, Union
 
-from .base import Field
+from .base import Field, Widget
 from .text import TextWidget
 
 
-@dataclass
-class DropdownField(Field):
-    """
-    Represents a dropdown field in a PDF document.
-
-    This dataclass extends the `Field` base class and defines the specific
-    attributes that can be configured for a dropdown selection field.
-
-    Attributes:
-        _field_type (str): The type of the field, fixed as "dropdown".
-        options (Optional[List[Union[str, Tuple[str, str]]]]): A list of options
-            available in the dropdown. Each option can be a string (display value)
-            or a tuple of strings (display value, export value).
-        width (Optional[float]): The width of the dropdown field.
-        height (Optional[float]): The height of the dropdown field.
-        font (Optional[str]): The font to use for the dropdown text.
-        font_size (Optional[float]): The font size for the dropdown text.
-        font_color (Optional[Tuple[float, ...]]): The color of the font as an RGB or RGBA tuple.
-        bg_color (Optional[Tuple[float, ...]]): The background color of the dropdown field.
-        border_color (Optional[Tuple[float, ...]]): The color of the dropdown's border.
-        border_width (Optional[float]): The width of the dropdown's border.
-    """
-
-    _field_type: str = "dropdown"
-
-    options: Optional[List[Union[str, Tuple[str, str]]]] = None
-    width: Optional[float] = None
-    height: Optional[float] = None
-    # pylint: disable=R0801
-    font: Optional[str] = None
-    font_size: Optional[float] = None
-    font_color: Optional[Tuple[float, ...]] = None
-    bg_color: Optional[Tuple[float, ...]] = None
-    border_color: Optional[Tuple[float, ...]] = None
-    border_width: Optional[float] = None
-
-
 class DropdownWidget(TextWidget):
     """
     Represents a dropdown widget in a PDF form.
@@ -93,4 +56,43 @@ class DropdownWidget(TextWidget):
         ]
         super().__init__(name, page_number, x, y, **kwargs)
         self.acro_form_params["wkind"] = "choice"
-        self.acro_form_params["value"] = self.acro_form_params["options"][0]
+        self.acro_form_params["value"] = (
+            self.acro_form_params["options"][0] or " "  # reportlab bug
+        )
+
+
+@dataclass
+class DropdownField(Field):
+    """
+    Represents a dropdown field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a dropdown selection field.
+
+    Attributes:
+        _widget_class (Type[Widget]): The widget class associated with this field type.
+        options (Optional[List[Union[str, Tuple[str, str]]]]): A list of options
+            available in the dropdown. Each option can be a string (display value)
+            or a tuple of strings (display value, export value).
+        width (Optional[float]): The width of the dropdown field.
+        height (Optional[float]): The height of the dropdown field.
+        font (Optional[str]): The font to use for the dropdown text.
+        font_size (Optional[float]): The font size for the dropdown text.
+        font_color (Optional[Tuple[float, ...]]): The color of the font as an RGB or RGBA tuple.
+        bg_color (Optional[Tuple[float, ...]]): The background color of the dropdown field.
+        border_color (Optional[Tuple[float, ...]]): The color of the dropdown's border.
+        border_width (Optional[float]): The width of the dropdown's border.
+    """
+
+    _widget_class: Type[Widget] = DropdownWidget
+
+    options: Optional[List[Union[str, Tuple[str, str]]]] = None
+    width: Optional[float] = None
+    height: Optional[float] = None
+    # pylint: disable=R0801
+    font: Optional[str] = None
+    font_size: Optional[float] = None
+    font_color: Optional[Tuple[float, ...]] = None
+    bg_color: Optional[Tuple[float, ...]] = None
+    border_color: Optional[Tuple[float, ...]] = None
+    border_width: Optional[float] = None

PyPDFForm/widgets/image.py

@@ -12,26 +12,11 @@ leveraging the existing infrastructure for positioning and rendering.
 """
 
 from dataclasses import dataclass
+from typing import Type
 
 from .signature import SignatureField, SignatureWidget
 
 
-@dataclass
-class ImageField(SignatureField):
-    """
-    Represents an image field in a PDF document.
-
-    This dataclass extends the `SignatureField` base class and defines the
-    specific attributes for an image input field. It inherits `width` and
-    `height` from `SignatureField` as images also have dimensions.
-
-    Attributes:
-        _field_type (str): The type of the field, fixed as "image".
-    """
-
-    _field_type: str = "image"
-
-
 class ImageWidget(SignatureWidget):
     """
     Represents an image widget in a PDF form.
@@ -47,3 +32,19 @@ class ImageWidget(SignatureWidget):
     """
 
     BEDROCK_WIDGET_TO_COPY = "image"
+
+
+@dataclass
+class ImageField(SignatureField):
+    """
+    Represents an image field in a PDF document.
+
+    This dataclass extends the `SignatureField` base class and defines the
+    specific attributes for an image input field. It inherits `width` and
+    `height` from `SignatureField` as images also have dimensions.
+
+    Attributes:
+        _widget_class (Type[ImageWidget]): The widget class associated with this field type.
+    """
+
+    _widget_class: Type[ImageWidget] = ImageWidget