PyPDFForm 3.2.0__py3-none-any.whl → 3.3.1__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.2.0"
+__version__ = "3.3.1"
 
 from .middleware.text import Text  # exposing for setting global font attrs
 from .wrapper import PdfWrapper

PyPDFForm/constants.py

@@ -95,9 +95,14 @@ XFA = "/XFA"
 
 # Field flag bits
 READ_ONLY = 1 << 0
+REQUIRED = 1 << 1
 MULTILINE = 1 << 12
 COMB = 1 << 24
 
+# reportlab acroform func
+fieldFlags = "fieldFlags"
+required = "required"
+
 FONT_SIZE_IDENTIFIER = "Tf"
 FONT_COLOR_IDENTIFIER = " rg"
 DEFAULT_FONT = "Helvetica"

PyPDFForm/hooks.py

@@ -22,7 +22,8 @@ from pypdf.generic import (ArrayObject, DictionaryObject, FloatObject,
                            NameObject, NumberObject, TextStringObject)
 
 from .constants import (COMB, DA, FONT_COLOR_IDENTIFIER, FONT_SIZE_IDENTIFIER,
-                        MULTILINE, READ_ONLY, Annots, Ff, Opt, Parent, Q, Rect)
+                        MULTILINE, READ_ONLY, REQUIRED, TU, Annots, Ff, Opt,
+                        Parent, Q, Rect)
 from .template import get_widget_key
 from .utils import stream_to_io
 
@@ -329,3 +330,49 @@ def flatten_generic(annot: DictionaryObject, val: bool) -> None:
                 else int(annot.get(NameObject(Ff), 0)) & ~READ_ONLY
             )
         )
+
+
+def update_field_tooltip(annot: DictionaryObject, val: str) -> None:
+    """
+    Updates the tooltip (alternate field name) of a form field annotation.
+
+    This function sets the 'TU' entry in the annotation dictionary, which
+    provides a text string that can be used as a tooltip for the field.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (str): The new tooltip string for the field.
+    """
+    if val:
+        annot[NameObject(TU)] = TextStringObject(val)
+
+
+def update_field_required(annot: DictionaryObject, val: bool) -> None:
+    """
+    Updates the 'Required' flag of a form field annotation.
+
+    This function modifies the Ff (flags) entry in the annotation dictionary
+    (or its parent if applicable) to set or unset the 'Required' flag,
+    making the field mandatory or optional.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (bool): True to set the field as required, False to make it optional.
+    """
+    # TODO: add a test case when supporting edit required
+    # if Parent in annot and Ff not in annot:
+    #     annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
+    #         (
+    #             int(annot.get(NameObject(Ff), 0)) | REQUIRED
+    #             if val
+    #             else int(annot.get(NameObject(Ff), 0)) & ~REQUIRED
+    #         )
+    #     )
+    # else:
+    annot[NameObject(Ff)] = NumberObject(
+        (
+            int(annot.get(NameObject(Ff), 0)) | REQUIRED
+            if val
+            else int(annot.get(NameObject(Ff), 0)) & ~REQUIRED
+        )
+    )

PyPDFForm/middleware/base.py

@@ -23,6 +23,8 @@ class Widget:
 
     SET_ATTR_TRIGGER_HOOK_MAP = {
         "readonly": "flatten_generic",
+        "required": "update_field_required",
+        "tooltip": "update_field_tooltip",
     }
 
     def __init__(
@@ -41,7 +43,9 @@ class Widget:
         self._name = name
         self._value = value
         self.desc: str = None
+        self.tooltip: str = None  # TODO: sync tooltip and desc
         self.readonly: bool = None
+        self.required: bool = None
         self.hooks_to_trigger: list = []
 
     def __setattr__(self, name: str, value: Any) -> None:

PyPDFForm/widgets/base.py

@@ -10,6 +10,7 @@ for rendering the widget on a PDF page.
 # 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 inspect import signature
 from io import BytesIO
 from typing import List, Union
 
@@ -17,6 +18,7 @@ from pypdf import PdfReader
 from reportlab.lib.colors import Color
 from reportlab.pdfgen.canvas import Canvas
 
+from ..constants import fieldFlags, required
 from ..utils import stream_to_io
 
 
@@ -95,6 +97,39 @@ class Widget:
             if each in kwargs:
                 self.hook_params.append((each, kwargs.get(each)))
 
+    def _required_handler(self, canvas: Canvas) -> None:
+        """
+        Handles the 'Required' flag for the widget's AcroForm field.
+
+        This method inspects the default flags of the AcroForm function associated
+        with the widget and modifies them based on the widget's 'required' parameter.
+        If the widget is marked as required, the 'required' flag is added to the
+        AcroForm field flags; otherwise, it is removed. This ensures the PDF form
+        field's required status is correctly reflected.
+
+        Args:
+            canvas (Canvas): The ReportLab canvas object used for PDF operations.
+        """
+        default_flags = signature(
+            getattr(canvas.acroForm, self.ACRO_FORM_FUNC)
+        ).parameters.get(fieldFlags)
+        default_flags = (
+            default_flags.default.split(" ")
+            if default_flags and default_flags.default
+            else []
+        )
+
+        if self.acro_form_params.get(required):
+            default_flags.append(required)
+        else:
+            if required in default_flags:
+                default_flags.remove(required)
+
+        default_flags = " ".join(list(set(default_flags)))
+        self.acro_form_params[fieldFlags] = default_flags
+        if required in self.acro_form_params:
+            del self.acro_form_params[required]
+
     def canvas_operations(self, canvas: Canvas) -> None:
         """
         Performs canvas operations for the widget.
@@ -141,6 +176,7 @@ class Widget:
             ),
         )
 
+        self._required_handler(canvas)
         self.canvas_operations(canvas)
 
         canvas.showPage()

PyPDFForm/widgets/checkbox.py

@@ -25,6 +25,8 @@ class CheckBoxWidget(Widget):
     """
 
     USER_PARAMS = [
+        ("required", "required"),
+        ("tooltip", "tooltip"),
         ("button_style", "buttonStyle"),
         ("tick_color", "textColor"),
         ("bg_color", "fillColor"),

PyPDFForm/widgets/signature.py

@@ -34,6 +34,8 @@ class SignatureWidget:
     Attributes:
         OPTIONAL_PARAMS (list): A list of tuples, where each tuple contains the
             parameter name and its default value.
+        ALLOWED_HOOK_PARAMS (list): A list of parameter names that can be
+            used as hooks to trigger dynamic modifications.
         BEDROCK_WIDGET_TO_COPY (str): The name of the bedrock widget to copy.
     """
 
@@ -41,6 +43,7 @@ class SignatureWidget:
         ("width", 160),
         ("height", 90),
     ]
+    ALLOWED_HOOK_PARAMS = ["required", "tooltip"]
     BEDROCK_WIDGET_TO_COPY = "signature"
 
     def __init__(
@@ -71,6 +74,9 @@ class SignatureWidget:
         self.optional_params = {
             each[0]: kwargs.get(each[0], each[1]) for each in self.OPTIONAL_PARAMS
         }
+        for each in self.ALLOWED_HOOK_PARAMS:
+            if each in kwargs:
+                self.hook_params.append((each, kwargs.get(each)))
 
     def watermarks(self, stream: bytes) -> List[bytes]:
         """

PyPDFForm/widgets/text.py

@@ -27,6 +27,8 @@ class TextWidget(Widget):
     """
 
     USER_PARAMS = [
+        ("required", "required"),
+        ("tooltip", "tooltip"),
         ("width", "width"),
         ("height", "height"),
         ("font_size", "fontSize"),

{pypdfform-3.2.0.dist-info → pypdfform-3.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 3.2.0
+Version: 3.3.1
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-3.2.0.dist-info → pypdfform-3.3.1.dist-info}/RECORD

@@ -1,10 +1,10 @@
-PyPDFForm/__init__.py,sha256=MdhapOSXGvZvnL2gmvBhLy8__hBxfCI3beVkrNljOcg,925
+PyPDFForm/__init__.py,sha256=kzlOedFQykVQ-7y-ntC2MDQNY0fFVu8B86etcEa60yY,925
 PyPDFForm/adapter.py,sha256=LBxHth0qJFB6rdByRJbsn4x0dftCOAolKVutZeFZm9E,2634
-PyPDFForm/constants.py,sha256=GU0LcNbN-ttYQVVoFGQLysKByJYF4lKoMideU65z_wI,2523
+PyPDFForm/constants.py,sha256=rxE9KyygdMkuPfpO6PRV6DasvIta0sZqadVPtX9Q_1U,2616
 PyPDFForm/coordinate.py,sha256=veYOlRyFKIvzLISYA_f-drNBiKOzFwr0EIFCaUAzGgo,4428
 PyPDFForm/filler.py,sha256=fqGIxT3FR3cWo3SMTDYud6Ocs9SZBmSpFv5yg1v19Wk,8450
 PyPDFForm/font.py,sha256=opZjAacsIRFcERXWegPXkOSpmnRrv4y_50yD0_BjWPM,10273
-PyPDFForm/hooks.py,sha256=lXw3nNxYmgRp_IYe3aEXPeGCQxO_l6ruFzjmSeqfvIc,12659
+PyPDFForm/hooks.py,sha256=E-KVXQGIcyJfCOJpIIf8otgZw1eQ6FqifBZ92kPze5o,14327
 PyPDFForm/image.py,sha256=P1P3Ejm8PVPQwpJFGAesjtwS5hxnVItrj75TE3WnFhM,4607
 PyPDFForm/patterns.py,sha256=HbTqzFllQ1cW3CqyNEfVh0qUMeFerbvOd0-HQnkifQQ,9765
 PyPDFForm/template.py,sha256=Jvx99HjLcEG8fZQeGSPZEFcITa4jauPSvenj3XgAf3c,11046
@@ -12,7 +12,7 @@ PyPDFForm/utils.py,sha256=JavhAO4HmYRdujlsPXcZWGXTf7wDXzj4uU1XGRFsAaA,13257
 PyPDFForm/watermark.py,sha256=BJ8NeZLKf-MuJ2XusHiALaQpoqE8j6hHGbWcNhpjxN0,11299
 PyPDFForm/wrapper.py,sha256=KTFou6cXrHtLHVKwngoIr4Pwu4vOfjXY0cWRNNDlW0U,28866
 PyPDFForm/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyPDFForm/middleware/base.py,sha256=zBO9YP01dAEfFKoHKDg10XcpXEuYdFd-pb5wSFmJJj0,3091
+PyPDFForm/middleware/base.py,sha256=ZmJFh3nSxj6PFjqBqsLih0pXKtcm1o-ctJVWn0v6bbI,3278
 PyPDFForm/middleware/checkbox.py,sha256=OCSZEFD8wQG_Y9qO7Os6VXTaxJCpkRYTxI4wDgG0GZc,1870
 PyPDFForm/middleware/dropdown.py,sha256=pfiMuAOr3ze7eboCB55UKaSR89oLNhvHGvNmDGWHVS0,3855
 PyPDFForm/middleware/image.py,sha256=eKM7anU56jbaECnK6rq0jGsBRY3HW_fM86fgA3hq7xA,585
@@ -20,16 +20,16 @@ PyPDFForm/middleware/radio.py,sha256=PuGDJ8RN1C-MkL9Jf14ABWYV67cN18R66dI4nR-03DU
 PyPDFForm/middleware/signature.py,sha256=P6Mg9AZP5jML7GawsteVZjDaunKb9Yazu5iy0qF60bo,2432
 PyPDFForm/middleware/text.py,sha256=GLKuYvG4BUtNvj-3NkDeIlV1jcouhn7gAqfm9TBWduQ,3936
 PyPDFForm/widgets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyPDFForm/widgets/base.py,sha256=vudfjwlybj82pxQhy6K8Qds9osFqn219Ze3yMs8QQuU,5786
+PyPDFForm/widgets/base.py,sha256=iWsZ4LDtFVmrVUwvG_ORnH8fd614saI6wfNN4LrgOjQ,7230
 PyPDFForm/widgets/bedrock.py,sha256=j6beU04kaQzpAIFZHI5VJLaDT5RVAAa6LzkU1luJpN8,137660
-PyPDFForm/widgets/checkbox.py,sha256=s4a0a1pAemQyrz3SpZHzIPoVLvJZAV72KEfxKp15dyk,1281
+PyPDFForm/widgets/checkbox.py,sha256=gqqulFdjrLd6Ry-BM4sHwGu0QogfKnG_6v3RcYLeYMo,1347
 PyPDFForm/widgets/dropdown.py,sha256=6zZwt6eU9Hgwl-57QfyT3G6c37FkQTJ-XSsXGluWevs,1459
 PyPDFForm/widgets/image.py,sha256=aSD-3MEZFIRL7HYVuO6Os8irfSUOLHA_rHGkqcEIPPA,855
 PyPDFForm/widgets/radio.py,sha256=oFw8Um4g414UH93QJv6dZHRxpq0yuYog09B2W3eE8wo,2612
-PyPDFForm/widgets/signature.py,sha256=vk9w9YmUpABvRhRcvllXw_Wr2SvKyCXDVQEFsR77ugM,4820
-PyPDFForm/widgets/text.py,sha256=gtheE6_w0vQPRJJ9oj_l9FaMDEGnPtvVR6_axsrmxKI,1540
-pypdfform-3.2.0.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
-pypdfform-3.2.0.dist-info/METADATA,sha256=qjn9PkGilefmwJ0MocWv3DI8hvEDnJjh6buHCWzVpqA,4538
-pypdfform-3.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pypdfform-3.2.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
-pypdfform-3.2.0.dist-info/RECORD,,
+PyPDFForm/widgets/signature.py,sha256=L4Et6pxtrEh7U-lnnLZrnvb_dKwGNpI6TZ11HCD0lvY,5147
+PyPDFForm/widgets/text.py,sha256=rmI0EYUTVf06AKsnxsVqewdTjt_mhBASEHyj5nAvYjE,1606
+pypdfform-3.3.1.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
+pypdfform-3.3.1.dist-info/METADATA,sha256=zbqEKsATFK12_iuYaAfc3p1K7MDw4lripco_cyGFKj8,4538
+pypdfform-3.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pypdfform-3.3.1.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
+pypdfform-3.3.1.dist-info/RECORD,,