PyPDFForm 3.2.0__tar.gz → 3.3.0__tar.gz

{pypdfform-3.2.0 → pypdfform-3.3.0}/PKG-INFO

@@ -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 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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-3.2.0 → pypdfform-3.3.0}/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 → pypdfform-3.3.0}/PyPDFForm.egg-info/PKG-INFO

@@ -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 → pypdfform-3.3.0}/tests/test_create_widget.py

@@ -1161,3 +1161,148 @@ def test_create_image_default_filled_flatten(
 
         assert len(obj.read()) == len(expected)
         assert obj.read() == expected
+
+
+def test_create_required_fields(pdf_samples, request):
+    expected_path = os.path.join(
+        pdf_samples, "widget", "test_create_required_fields.pdf"
+    )
+    with open(expected_path, "rb+") as f:
+        obj = (
+            PdfWrapper(os.path.join(pdf_samples, "dummy.pdf"))
+            .create_widget("text", "new_text", 1, 100, 100, required=True)
+            .create_widget("checkbox", "new_check", 1, 100, 200, required=True)
+            .create_widget(
+                "radio",
+                "new_radio_group",
+                1,
+                [300, 350, 400],
+                [100, 150, 200],
+                required=True,
+            )
+            .create_widget(
+                "dropdown",
+                "new_dropdown",
+                1,
+                400,
+                400,
+                required=True,
+                options=["apple", "banana", "cherry"],
+            )
+            .create_widget(
+                "image",
+                "new_image",
+                1,
+                300,
+                600,
+                required=True,
+            )
+            .create_widget("signature", "new_signature", 1, 100, 600, required=True)
+        )
+
+        request.config.results["expected_path"] = expected_path
+        request.config.results["stream"] = obj.read()
+
+        expected = f.read()
+
+        assert len(obj.read()) == len(expected)
+        assert obj.read() == expected
+
+
+def test_create_not_required_fields(pdf_samples, request):
+    expected_path = os.path.join(
+        pdf_samples, "widget", "test_create_not_required_fields.pdf"
+    )
+    with open(expected_path, "rb+") as f:
+        obj = (
+            PdfWrapper(os.path.join(pdf_samples, "dummy.pdf"))
+            .create_widget("text", "new_text", 1, 100, 100, required=False)
+            .create_widget("checkbox", "new_check", 1, 100, 200, required=False)
+            .create_widget(
+                "radio",
+                "new_radio_group",
+                1,
+                [300, 350, 400],
+                [100, 150, 200],
+                required=False,
+            )
+            .create_widget(
+                "dropdown",
+                "new_dropdown",
+                1,
+                400,
+                400,
+                required=False,
+                options=["apple", "banana", "cherry"],
+            )
+            .create_widget(
+                "image",
+                "new_image",
+                1,
+                300,
+                600,
+                required=False,
+            )
+            .create_widget("signature", "new_signature", 1, 100, 600, required=False)
+        )
+
+        request.config.results["expected_path"] = expected_path
+        request.config.results["stream"] = obj.read()
+
+        expected = f.read()
+
+        assert len(obj.read()) == len(expected)
+        assert obj.read() == expected
+
+
+def test_create_fields_with_tooltips(pdf_samples, request):
+    expected_path = os.path.join(
+        pdf_samples, "widget", "test_create_fields_with_tooltips.pdf"
+    )
+    with open(expected_path, "rb+") as f:
+        obj = (
+            PdfWrapper(os.path.join(pdf_samples, "dummy.pdf"))
+            .create_widget("text", "new_text", 1, 100, 100, tooltip="new_text")
+            .create_widget("checkbox", "new_check", 1, 100, 200, tooltip="new_checkbox")
+            .create_widget(
+                "radio",
+                "new_radio_group",
+                1,
+                [300, 350, 400],
+                [100, 150, 200],
+                tooltip="new_radio_group",
+            )
+            .create_widget(
+                "dropdown",
+                "new_dropdown",
+                1,
+                400,
+                400,
+                options=["apple", "banana", "cherry"],
+                tooltip="new_dropdown",
+            )
+            .create_widget(
+                "image",
+                "new_image",
+                1,
+                300,
+                600,
+                tooltip="new_image",
+            )
+            .create_widget(
+                "signature",
+                "new_signature",
+                1,
+                100,
+                600,
+                tooltip="new_signature",
+            )
+        )
+
+        request.config.results["expected_path"] = expected_path
+        request.config.results["stream"] = obj.read()
+
+        expected = f.read()
+
+        assert len(obj.read()) == len(expected)
+        assert obj.read() == expected