PyPDFForm 3.5.5__py3-none-any.whl → 3.6.0__py3-none-any.whl

PyPDFForm/__init__.py

@@ -20,7 +20,7 @@ The library supports various PDF form features, including:
 PyPDFForm aims to simplify PDF form manipulation, making it accessible to developers of all skill levels.
 """
 
-__version__ = "3.5.5"
+__version__ = "3.6.0"
 
 from .middleware.text import Text  # exposing for setting global font attrs
 from .widgets import Fields

PyPDFForm/widgets/__init__.py

@@ -21,6 +21,12 @@ from .text import TextField
 FieldTypes = Union[
     TextField, CheckBoxField, RadioGroup, DropdownField, SignatureField, ImageField
 ]
+BulkFieldTypes = Union[
+    TextField,
+    CheckBoxField,
+    RadioGroup,
+    DropdownField,
+]
 
 
 @dataclass

PyPDFForm/widgets/base.py

@@ -12,6 +12,8 @@ Classes:
       functionality for rendering and manipulation.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from inspect import signature
 from io import BytesIO
@@ -191,6 +193,68 @@ class Widget:
             for i in range(page_count)
         ]
 
+    @staticmethod
+    def bulk_watermarks(widgets: List[Widget], stream: bytes) -> List[bytes]:
+        """
+        Generates watermarks for multiple widgets in bulk.
+
+        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:
+            widgets (List[Widget]): A list of Widget objects to be watermarked.
+            stream (bytes): The PDF stream to be watermarked.
+
+        Returns:
+            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))
+        watermark = BytesIO()
+
+        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
+
+            watermark.seek(0)
+            watermark.flush()
+
+            canvas = Canvas(
+                watermark,
+                pagesize=(
+                    float(page.mediabox[2]),
+                    float(page.mediabox[3]),
+                ),
+            )
+
+            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:

PyPDFForm/widgets/checkbox.py

@@ -11,7 +11,7 @@ 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
 
@@ -57,6 +57,7 @@ class CheckBoxField(Field):
 
     Attributes:
         _field_type (str): The type of the field, fixed as "checkbox".
+        _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").
@@ -67,6 +68,7 @@ class CheckBoxField(Field):
     """
 
     _field_type: str = "checkbox"
+    _widget_class: Type[Widget] = CheckBoxWidget
 
     size: Optional[float] = None
     button_style: Optional[str] = None

PyPDFForm/widgets/dropdown.py

@@ -11,9 +11,9 @@ 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
 
 
@@ -69,6 +69,7 @@ class DropdownField(Field):
 
     Attributes:
         _field_type (str): The type of the field, fixed as "dropdown".
+        _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).
@@ -83,6 +84,7 @@ class DropdownField(Field):
     """
 
     _field_type: str = "dropdown"
+    _widget_class: Type[Widget] = DropdownWidget
 
     options: Optional[List[Union[str, Tuple[str, str]]]] = None
     width: Optional[float] = None

PyPDFForm/widgets/radio.py

@@ -11,10 +11,11 @@ specific functionality for interacting with radio button form fields in PDFs.
 """
 
 from dataclasses import dataclass
-from typing import List, Optional
+from typing import List, Optional, Type
 
 from reportlab.pdfgen.canvas import Canvas
 
+from .base import Widget
 from .checkbox import CheckBoxField, CheckBoxWidget
 
 
@@ -86,6 +87,7 @@ class RadioGroup(CheckBoxField):
 
     Attributes:
         _field_type (str): The type of the field, fixed as "radio".
+        _widget_class (Type[Widget]): The widget class associated with this field type.
         x (List[float]): A list of x-coordinates for each radio button in the group.
         y (List[float]): A list of y-coordinates for each radio button in the group.
         shape (Optional[str]): The shape of the radio button. Valid values are
@@ -93,6 +95,7 @@ class RadioGroup(CheckBoxField):
     """
 
     _field_type: str = "radio"
+    _widget_class: Type[Widget] = RadioWidget
 
     x: List[float]
     y: List[float]

PyPDFForm/widgets/text.py

@@ -11,7 +11,7 @@ functionality for interacting with text form fields in PDFs.
 """
 
 from dataclasses import dataclass
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Type
 
 from .base import Field, Widget
 
@@ -63,6 +63,7 @@ class TextField(Field):
 
     Attributes:
         _field_type (str): The type of the field, fixed as "text".
+        _widget_class (Type[Widget]): The widget class associated with this field type.
         width (Optional[float]): The width of the text field.
         height (Optional[float]): The height of the text field.
         max_length (Optional[int]): The maximum number of characters allowed in the text field.
@@ -79,6 +80,7 @@ class TextField(Field):
     """
 
     _field_type: str = "text"
+    _widget_class: Type[Widget] = TextWidget
 
     width: Optional[float] = None
     height: Optional[float] = None

PyPDFForm/wrapper.py

@@ -18,6 +18,7 @@ underlying PDF manipulation.
 
 from __future__ import annotations
 
+from collections import defaultdict
 from dataclasses import asdict
 from functools import cached_property
 from typing import TYPE_CHECKING, BinaryIO, Dict, List, Sequence, Tuple, Union
@@ -41,6 +42,8 @@ from .utils import (enable_adobe_mode, generate_unique_suffix,
                     get_page_streams, merge_two_pdfs, remove_all_widgets)
 from .watermark import (copy_watermark_widgets, create_watermarks_and_draw,
                         merge_watermarks_with_pdf)
+from .widgets import CheckBoxField
+from .widgets.base import Widget
 from .widgets.checkbox import CheckBoxWidget
 from .widgets.dropdown import DropdownWidget
 from .widgets.image import ImageWidget
@@ -49,7 +52,7 @@ from .widgets.signature import SignatureWidget
 from .widgets.text import TextWidget
 
 if TYPE_CHECKING:
-    from .widgets import FieldTypes
+    from .widgets import BulkFieldTypes, FieldTypes
 
 
 class PdfWrapper:
@@ -451,6 +454,91 @@ class PdfWrapper:
 
         return self
 
+    def bulk_create_fields(self, fields: List[BulkFieldTypes]) -> PdfWrapper:
+        """
+        Creates multiple new form fields (widgets) on the PDF in a single operation.
+
+        This method takes a list of field definition objects (`BulkFieldTypes`),
+        groups them by type (if necessary for specific widget handling, like CheckBoxField),
+        and then delegates the creation to the internal `_bulk_create_fields` method.
+        This is the preferred method for creating multiple fields as it minimizes
+        PDF manipulation overhead.
+
+        Args:
+            fields (List[BulkFieldTypes]): A list of field definition objects
+                (e.g., `TextField`, `CheckBoxField`, etc.) to be created.
+
+        Returns:
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
+        """
+
+        needs_separate_creation = [CheckBoxField]
+        needs_separate_creation_dict = defaultdict(list)
+        general_creation = []
+
+        for each in fields:
+            if type(each) in needs_separate_creation:
+                needs_separate_creation_dict[type(each)].append(each)
+            else:
+                general_creation.append(each)
+
+        for each in needs_separate_creation_dict.values():
+            self._bulk_create_fields(each)
+        self._bulk_create_fields(general_creation)
+
+        return self
+
+    def _bulk_create_fields(self, fields: List[BulkFieldTypes]) -> PdfWrapper:
+        """
+        Internal method to create multiple new form fields (widgets) on the PDF in a single operation.
+
+        This method takes a list of field definition objects (`BulkFieldTypes`),
+        converts them into `Widget` objects, and efficiently draws them onto the
+        PDF using bulk watermarking. It is designed to be called by the public
+        `bulk_create_fields` method after fields have been grouped for creation.
+
+        Args:
+            fields (List[BulkFieldTypes]): A list of field definition objects
+                (e.g., `TextField`, `CheckBoxField`, etc.) to be created.
+
+        Returns:
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
+        """
+
+        widgets = []
+        for field in fields:
+            field_dict = asdict(field)
+            widget_class = getattr(field, "_widget_class")
+            name = field_dict.pop("name")
+            page_number = field_dict.pop("page_number")
+            x = field_dict.pop("x")
+            y = field_dict.pop("y")
+            widgets.append(
+                widget_class(
+                    name=name,
+                    page_number=page_number,
+                    x=x,
+                    y=y,
+                    **{k: v for k, v in field_dict.items() if v is not None},
+                )
+            )
+
+        watermarks = Widget.bulk_watermarks(widgets, self.read())
+        self._stream = copy_watermark_widgets(
+            self.read(),
+            watermarks,
+            [widget.acro_form_params["name"] for widget in widgets],
+            None,
+        )
+
+        self._init_helper()
+
+        for widget in widgets:
+            for k, v in widget.hook_params:
+                self.widgets[widget.acro_form_params["name"]].__setattr__(k, v)
+
+        return self
+
     def create_field(
         self,
         field: FieldTypes,

{pypdfform-3.5.5.dist-info → pypdfform-3.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 3.5.5
+Version: 3.6.0
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -49,7 +49,7 @@ Dynamic: license-file
     <a href="https://github.com/chinapandaman/PyPDFForm/actions/workflows/python-package.yml"><img src="https://img.shields.io/badge/coverage-100%25-green"></a>
     <a href="https://github.com/chinapandaman/PyPDFForm/raw/master/LICENSE"><img src="https://img.shields.io/github/license/chinapandaman/pypdfform?label=license&color=orange"></a>
     <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/pypi/pyversions/pypdfform?label=python&color=gold"></a>
-    <a href="https://pypistats.org/packages/pypdfform"><img src="https://img.shields.io/pypi/dm/pypdfform?color=blue"></a>
+    <a href="https://pepy.tech/projects/pypdfform"><img src="https://static.pepy.tech/badge/pypdfform/month"></a>
 </p>
 
 ## Introduction

{pypdfform-3.5.5.dist-info → pypdfform-3.6.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-PyPDFForm/__init__.py,sha256=NSu4wjk8XAx0SA5LJIMstL6UlHQa7AuvZnFXjjYYco4,963
+PyPDFForm/__init__.py,sha256=CC5j1ui603ZNCwB7vhfBoSkfUothfptPDO9jrhWLbMs,963
 PyPDFForm/adapter.py,sha256=0OTZBzGYzOerfXzUPvNq2HNVcMmkRnxNHQ1-Ys2VjYA,2427
 PyPDFForm/constants.py,sha256=tFtomm4bSsghxRqKaMP6Tln7ug9W_72e-AAU3sEU_no,2917
 PyPDFForm/coordinate.py,sha256=VMVkqa-VAGJSGVvetZwOxeMzIgQtQdvtn_DI_qSecCE,3876
@@ -10,7 +10,7 @@ PyPDFForm/patterns.py,sha256=Xhdsef7pPEIVEYhQRyOzonld3z1wk6WZ3TTjnj-RvpU,9573
 PyPDFForm/template.py,sha256=GSNMH5meKk5B62sj_UXxiJgs4SOVDcQCNISvARmXJZ0,10004
 PyPDFForm/utils.py,sha256=hLSVUG6qnE0iTMB-yPNQQIhmm3R69X7fcnbCTDvSUQs,11001
 PyPDFForm/watermark.py,sha256=9p1tjaIqicXngTNai_iOEkCoXRYnR66azB4s7wNsZUw,9349
-PyPDFForm/wrapper.py,sha256=ayqL-p7Ftwg0txMpK8sNxQ0aIoUrPtyPwJEIgej_Ofo,27598
+PyPDFForm/wrapper.py,sha256=8kYjgd18F_27QJXRJnxcZQ6RLyRmpXJHb0BAdtwUviw,30951
 PyPDFForm/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 PyPDFForm/middleware/base.py,sha256=YQNVhjoDV2E3WYSQrahHkD6_Zdfxpcnr9ONKeB7hcgM,3223
 PyPDFForm/middleware/checkbox.py,sha256=OCSZEFD8wQG_Y9qO7Os6VXTaxJCpkRYTxI4wDgG0GZc,1870
@@ -19,17 +19,17 @@ PyPDFForm/middleware/image.py,sha256=eKM7anU56jbaECnK6rq0jGsBRY3HW_fM86fgA3hq7xA
 PyPDFForm/middleware/radio.py,sha256=PuGDJ8RN1C-MkL9Jf14ABWYV67cN18R66dI4nR-03DU,2211
 PyPDFForm/middleware/signature.py,sha256=a2IfD36zpEWXWNNWRvtJ6nG6TszkF6Wil82Szsbjfns,2149
 PyPDFForm/middleware/text.py,sha256=WLK6Ae9zT3uUu1AzcWUhR-hs5rm0z9Ydz-fL8Qu-44o,3997
-PyPDFForm/widgets/__init__.py,sha256=TvMMWGtrTC4xRPRokr4Pl8ZtvfYXRPUDgfHd3pnbPE8,1304
-PyPDFForm/widgets/base.py,sha256=KoYSGkN35iU0RnWT1ZhGQ0I_q_NSFXBvvKculRPSmsc,7876
+PyPDFForm/widgets/__init__.py,sha256=gVJzqdpj6NRltqXrvCeHJO28snlIwHydbftWCnLZnvI,1399
+PyPDFForm/widgets/base.py,sha256=FCFMJPMeqE1z0zNe_IK6kEu8M_sYFy7Tu8SyAMDJ14M,10195
 PyPDFForm/widgets/bedrock.py,sha256=j6beU04kaQzpAIFZHI5VJLaDT5RVAAa6LzkU1luJpN8,137660
-PyPDFForm/widgets/checkbox.py,sha256=BhCKjjh2VP4s6OqW-VrUdfrIcUYhahxeZBYKeVe4MOA,2870
-PyPDFForm/widgets/dropdown.py,sha256=A55KfFR2Tqh2EvV0P2G1_KYYDeQ0KGMP8tGm4OHAKws,3528
+PyPDFForm/widgets/checkbox.py,sha256=QQH9MURhyASDss83uWRvD8R7uyZ1D9fxtLnpNCVFc10,3013
+PyPDFForm/widgets/dropdown.py,sha256=jIRefrCqUZy9MJxeMlAnreclnSeai6YflsNDuRzim-o,3679
 PyPDFForm/widgets/image.py,sha256=t-nHD38hF_wgHCAeBliqedbHX94k331L4HtKYhxkOaY,1628
-PyPDFForm/widgets/radio.py,sha256=za7vwYC-1JnUhnpro3xqOqRDzdBQfKuSOBvZyOoog54,3581
+PyPDFForm/widgets/radio.py,sha256=ip1imdGQhbQ6GO57Z8HNrzQkQH7SEq6K-azS949lMkU,3746
 PyPDFForm/widgets/signature.py,sha256=-hc3bvU0zLPnla0CLzrnMAkJkPo_Nce_VO8UdeDUH90,5247
-PyPDFForm/widgets/text.py,sha256=n5kvI4u1wg1NWSyaSw450pkv4lR6-ZFg2of9OobZZpE,3836
-pypdfform-3.5.5.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
-pypdfform-3.5.5.dist-info/METADATA,sha256=mKDGDNLtjyQZ2yFehUHdOLXcEYFTY_VpGTfUvQiWOeY,4278
-pypdfform-3.5.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pypdfform-3.5.5.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
-pypdfform-3.5.5.dist-info/RECORD,,
+PyPDFForm/widgets/text.py,sha256=RJXPLCopmuayKJSvVeDVaiMRvqOjFoFwqiEzgyydIhg,3975
+pypdfform-3.6.0.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
+pypdfform-3.6.0.dist-info/METADATA,sha256=3w5_arGBmdkCiaWFjWYwLlDv-E3D8XFY5N2sh2_KtM4,4269
+pypdfform-3.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pypdfform-3.6.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
+pypdfform-3.6.0.dist-info/RECORD,,