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

PyPDFForm/constants.py

@@ -95,6 +95,7 @@ XFA = "/XFA"
 
 # Field flag bits
 READ_ONLY = 1 << 0
+REQUIRED = 1 << 1
 MULTILINE = 1 << 12
 COMB = 1 << 24
 

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,48 @@ 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.
+    """
+    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/checkbox.py

@@ -25,6 +25,7 @@ class CheckBoxWidget(Widget):
     """
 
     USER_PARAMS = [
+        ("tooltip", "tooltip"),
         ("button_style", "buttonStyle"),
         ("tick_color", "textColor"),
         ("bg_color", "fillColor"),
@@ -32,5 +33,5 @@ class CheckBoxWidget(Widget):
         ("border_width", "borderWidth"),
     ]
     COLOR_PARAMS = ["tick_color", "bg_color", "border_color"]
-    ALLOWED_HOOK_PARAMS = ["size"]
+    ALLOWED_HOOK_PARAMS = ["required", "size"]
     ACRO_FORM_FUNC = "checkbox"

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,7 @@ class TextWidget(Widget):
     """
 
     USER_PARAMS = [
+        ("tooltip", "tooltip"),
         ("width", "width"),
         ("height", "height"),
         ("font_size", "fontSize"),
@@ -37,6 +38,6 @@ class TextWidget(Widget):
         ("max_length", "maxlen"),
     ]
     COLOR_PARAMS = ["font_color", "bg_color", "border_color"]
-    ALLOWED_HOOK_PARAMS = ["alignment", "multiline", "comb", "font"]
+    ALLOWED_HOOK_PARAMS = ["required", "alignment", "multiline", "comb", "font"]
     NONE_DEFAULTS = ["max_length"]
     ACRO_FORM_FUNC = "textfield"

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

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

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

@@ -1,10 +1,10 @@
-PyPDFForm/__init__.py,sha256=MdhapOSXGvZvnL2gmvBhLy8__hBxfCI3beVkrNljOcg,925
+PyPDFForm/__init__.py,sha256=ToO1r5zbCDJutiMz36Y_5mpA35NPoRtwTAsABtKUGEQ,925
 PyPDFForm/adapter.py,sha256=LBxHth0qJFB6rdByRJbsn4x0dftCOAolKVutZeFZm9E,2634
-PyPDFForm/constants.py,sha256=GU0LcNbN-ttYQVVoFGQLysKByJYF4lKoMideU65z_wI,2523
+PyPDFForm/constants.py,sha256=Y5l1qIZGPsSoMl55bOsXaHf3yAY36_b-8KRxTLxXGmk,2541
 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=3ugnhnrB4nFsGL6fc1TtT5Nf_J2QOtM5ZQsm6WVpErY,14279
 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
@@ -22,14 +22,14 @@ PyPDFForm/middleware/text.py,sha256=GLKuYvG4BUtNvj-3NkDeIlV1jcouhn7gAqfm9TBWduQ,
 PyPDFForm/widgets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 PyPDFForm/widgets/base.py,sha256=vudfjwlybj82pxQhy6K8Qds9osFqn219Ze3yMs8QQuU,5786
 PyPDFForm/widgets/bedrock.py,sha256=j6beU04kaQzpAIFZHI5VJLaDT5RVAAa6LzkU1luJpN8,137660
-PyPDFForm/widgets/checkbox.py,sha256=s4a0a1pAemQyrz3SpZHzIPoVLvJZAV72KEfxKp15dyk,1281
+PyPDFForm/widgets/checkbox.py,sha256=5Cg07d3SmRehkSiROtkK2vl0WKITxmv9BAKVnem8keM,1325
 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=GjPwajoP20dZMlJGhJrQtwOa4VHGInjYkjUYmLwtRWs,1584
+pypdfform-3.3.0.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
+pypdfform-3.3.0.dist-info/METADATA,sha256=K7q2yHg1rUw5hwO4gnmgNB8fR-UjPWce-z-0YY7gbWU,4538
+pypdfform-3.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pypdfform-3.3.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
+pypdfform-3.3.0.dist-info/RECORD,,