PyPDFForm 5.5.2__tar.gz → 5.5.3__tar.gz

{pypdfform-5.5.2 → pypdfform-5.5.3}/PKG-INFO

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

{pypdfform-5.5.2 → pypdfform-5.5.3}/PyPDFForm/__init__.py

@@ -18,7 +18,7 @@ from Python code or from the command line.
 
 import logging
 
-__version__ = "5.5.2"
+__version__ = "5.5.3"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

{pypdfform-5.5.2 → pypdfform-5.5.3}/PyPDFForm/lib/constants.py

@@ -47,6 +47,10 @@ Annots = "/Annots"
 Annot = "/Annot"
 Contents = "/Contents"
 Widget = "/Widget"
+XObject = "/XObject"
+Form = "/Form"
+BBox = "/BBox"
+Matrix = "/Matrix"
 T = "/T"
 TU = "/TU"
 Rect = "/Rect"
@@ -59,6 +63,7 @@ V = "/V"
 AP = "/AP"
 I = "/I"  # noqa: E741
 N = "/N"
+R = "/R"
 Sig = "/Sig"
 DA = "/DA"
 DR = "/DR"
@@ -71,6 +76,13 @@ Opt = "/Opt"
 AS = "/AS"
 Yes = "/Yes"
 Off = "/Off"
+MK = "/MK"
+BC = "/BC"
+BS = "/BS"
+W = "/W"
+H = "/H"
+TP = "/TP"
+IF = "/IF"
 
 # javascript
 A = "/A"
@@ -144,7 +156,7 @@ DEFAULT_FONT = "Helvetica"
 DEFAULT_FONT_SIZE = 12
 DEFAULT_FONT_COLOR = (0, 0, 0)
 
-IMAGE_FIELD_IDENTIFIER = "event.target.buttonImportIcon();"
+IMAGE_IMPORT_JAVASCRIPT = "event.target.buttonImportIcon();"
 
 COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO = DEFAULT_FONT_SIZE / 100
 UNIQUE_SUFFIX_LENGTH = 20

{pypdfform-5.5.2 → pypdfform-5.5.3}/PyPDFForm/lib/egress.py

@@ -119,8 +119,8 @@ def rebuild_acroform_fields(
                     fields.append(field_ref)
                     seen_fields.add(field_key)
 
-    # if not seen_fields:
-    #     return pdf
+    if not seen_fields:
+        return pdf
 
     if AcroForm not in root:
         root[NameObject(AcroForm)] = DictionaryObject({})

{pypdfform-5.5.2 → pypdfform-5.5.3}/PyPDFForm/lib/patterns.py

@@ -24,7 +24,7 @@ from .constants import (
     DV,
     FT,
     HIDDEN,
-    IMAGE_FIELD_IDENTIFIER,
+    IMAGE_IMPORT_JAVASCRIPT,
     JS,
     SLASH,
     TU,
@@ -61,7 +61,7 @@ WIDGET_TYPE_PATTERNS = [
     (
         (
             {Subtype: Widget},
-            {A: {JS: IMAGE_FIELD_IDENTIFIER}},
+            {A: {JS: IMAGE_IMPORT_JAVASCRIPT}},
         ),
         Image,
     ),

{pypdfform-5.5.2 → pypdfform-5.5.3}/PyPDFForm/lib/widgets/base.py

@@ -18,7 +18,7 @@ from dataclasses import dataclass
 from functools import lru_cache
 from inspect import signature
 from io import BytesIO
-from typing import List, Optional
+from typing import Any, List, Optional
 
 from pypdf import PdfReader
 from reportlab.lib.colors import Color
@@ -172,6 +172,27 @@ class Widget:
         """
         getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
 
+    @staticmethod
+    def create_watermark_canvas(page: Any) -> tuple[BytesIO, Canvas]:
+        """
+        Creates a PDF canvas sized to a source page.
+
+        Args:
+            page (Any): The source PDF page whose media box defines the canvas size.
+
+        Returns:
+            tuple[BytesIO, Canvas]: The in-memory stream and its PDF canvas.
+        """
+        watermark = BytesIO()
+        canvas = Canvas(
+            watermark,
+            pagesize=(
+                float(page.mediabox[2]),
+                float(page.mediabox[3]),
+            ),
+        )
+        return watermark, canvas
+
     @staticmethod
     def bulk_watermarks(widgets: List[Widget], stream: bytes) -> List[bytes]:
         """
@@ -209,18 +230,10 @@ class Widget:
             if page_num not in widgets_by_page:
                 continue
 
+            page = pdf.pages[page_num - 1]
             # Use a fresh buffer per page to avoid stale trailing bytes
             # when the current page watermark is smaller than a previous page.
-            watermark = BytesIO()
-            page = pdf.pages[page_num - 1]
-
-            canvas = Canvas(
-                watermark,
-                pagesize=(
-                    float(page.mediabox[2]),
-                    float(page.mediabox[3]),
-                ),
-            )
+            watermark, canvas = Widget.create_watermark_canvas(page)
 
             for widget in widgets_by_page[page_num]:
                 getattr(widget, "_required_handler")(canvas)

pypdfform-5.5.3/PyPDFForm/lib/widgets/image.py

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the `ImageField` and `ImageWidget` classes, which are used
+to describe and construct image-import form fields.
+
+`ImageField` inherits the signature field's sizing properties. `ImageWidget`
+reuses the signature widget's placement and carrier-PDF infrastructure while
+constructing a push-button annotation with an Acrobat JavaScript image-import
+action.
+"""
+
+from dataclasses import dataclass
+from typing import Any, List, Type
+
+from pypdf import PdfWriter
+from pypdf.generic import (
+    ArrayObject,
+    DictionaryObject,
+    FloatObject,
+    NameObject,
+    NumberObject,
+    TextStringObject,
+)
+
+from ..constants import (
+    AP,
+    BC,
+    BS,
+    DA,
+    FT,
+    IF,
+    IMAGE_IMPORT_JAVASCRIPT,
+    JS,
+    MK,
+    TP,
+    A,
+    Action,
+    Annot,
+    Btn,
+    D,
+    F,
+    Ff,
+    JavaScript,
+    Matrix,
+    N,
+    R,
+    Rect,
+    S,
+    Subtype,
+    T,
+    W,
+    Widget,
+)
+from ..constants import Type as PdfType
+from .signature import SignatureField, SignatureWidget
+
+
+class ImageWidget(SignatureWidget):
+    """
+    Represents an image widget in a PDF form.
+
+    The widget inherits signature-field placement, dimensions, and deferred
+    hooks, but constructs a push-button annotation identified by its
+    `buttonImportIcon()` JavaScript action.
+    """
+
+    @staticmethod
+    def _build_annotation(out: PdfWriter, widget: SignatureWidget) -> Any:
+        """
+        Constructs an image-import widget annotation owned by a PDF writer.
+
+        This method creates a border-only Form XObject, reuses it for the normal,
+        rollover, and pressed appearances, and builds a push-button `/Btn` widget
+        whose JavaScript action invokes `buttonImportIcon()`. It registers the
+        appearance and annotation with the same writer and implements the
+        annotation-builder callback used by `build_widget_watermarks`.
+
+        Args:
+            out (PdfWriter): The writer that will own the appearance stream and
+                widget annotation.
+            widget (SignatureWidget): The normalized image widget definition to
+                convert into a PDF annotation.
+
+        Returns:
+            Any: The writer-owned indirect reference to the widget annotation.
+        """
+        width = float(widget.optional_parameters["width"])
+        height = float(widget.optional_parameters["height"])
+        border_color = (0.1, 0.1, 0.1)
+
+        appearance_stream = ImageWidget._build_border_appearance(
+            width, height, border_color
+        )
+        appearance_stream[NameObject(Matrix)] = ArrayObject(
+            [
+                FloatObject(1),
+                FloatObject(0),
+                FloatObject(0),
+                FloatObject(1),
+                FloatObject(0),
+                FloatObject(0),
+            ]
+        )
+        appearance = out._add_object(  # type: ignore # noqa: SLF001 # pylint: disable=W0212
+            appearance_stream.flate_encode()
+        )
+
+        annotation = DictionaryObject(
+            {
+                NameObject(FT): NameObject(Btn),
+                NameObject(Ff): NumberObject(1 << 16),
+                NameObject(PdfType): NameObject(Annot),
+                NameObject(Subtype): NameObject(Widget),
+                NameObject(F): NumberObject(4),
+                NameObject(MK): DictionaryObject(
+                    {
+                        NameObject(TP): NumberObject(1),
+                        NameObject(IF): DictionaryObject(
+                            {NameObject(S): NameObject(A)}
+                        ),
+                        NameObject(BC): ArrayObject(
+                            FloatObject(value) for value in border_color
+                        ),
+                    }
+                ),
+                NameObject(BS): DictionaryObject(
+                    {
+                        NameObject(S): NameObject(S),
+                        NameObject(W): NumberObject(1),
+                    }
+                ),
+                NameObject(A): DictionaryObject(
+                    {
+                        NameObject(PdfType): NameObject(Action),
+                        NameObject(S): NameObject(JavaScript),
+                        NameObject(JS): TextStringObject(IMAGE_IMPORT_JAVASCRIPT),
+                    }
+                ),
+                NameObject(DA): TextStringObject("/Micr 12 Tf 0 0 0 rg"),
+                NameObject(Rect): ImageWidget._build_rectangle(widget, width, height),
+                NameObject(AP): DictionaryObject(
+                    {
+                        NameObject(N): appearance,
+                        NameObject(R): appearance,
+                        NameObject(D): appearance,
+                    }
+                ),
+                NameObject(T): TextStringObject(widget.name),
+            }
+        )
+        return out._add_object(  # type: ignore # noqa: SLF001 # pylint: disable=W0212
+            annotation
+        )
+
+    @staticmethod
+    def bulk_watermarks(widgets: List[SignatureWidget], stream: bytes) -> List[bytes]:
+        """
+        Constructs image widgets in page-aligned carrier PDFs.
+
+        Each image field is built as a push-button annotation whose JavaScript
+        action invokes `buttonImportIcon()` in viewers that support Acrobat
+        JavaScript. A single border-only appearance stream is reused for the
+        normal, rollover, and pressed states. It has a transparent interior and
+        the same dark-gray, one-point solid border as the signature widget.
+        ``build_widget_watermarks`` packages the annotations by source page.
+
+        Args:
+            widgets (List[SignatureWidget]): Image widgets to construct.
+            stream (bytes): Source PDF used to determine page count and page size.
+
+        Returns:
+            List[bytes]: Page-aligned PDF streams containing the constructed
+            image annotations.
+        """
+        return ImageWidget.build_widget_watermarks(
+            widgets, stream, ImageWidget._build_annotation
+        )
+
+
+@dataclass
+class ImageField(SignatureField):
+    """
+    Represents an image field in a PDF document.
+
+    This dataclass extends `SignatureField` and selects `ImageWidget` as its
+    widget implementation. It inherits the optional width and height values;
+    when omitted, the widget resolves them to 160 and 90 points.
+
+    Attributes:
+        _widget_class (Type[ImageWidget]): The widget class associated with this field type.
+    """
+
+    _widget_class: Type[ImageWidget] = ImageWidget

pypdfform-5.5.3/PyPDFForm/lib/widgets/signature.py

@@ -0,0 +1,353 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the `SignatureField` and `SignatureWidget` classes, which are
+used to describe and construct signature form fields.
+
+`SignatureField` stores the user-facing field definition. `SignatureWidget`
+normalizes that definition's values, constructs a `/Sig` widget annotation,
+and packages annotations in page-aligned PDFs so they can be copied into the
+destination document.
+
+Signature annotations and their appearance streams are constructed directly;
+they do not depend on ReportLab's AcroForm API or an external template PDF.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Any, Callable, List, Optional, Type
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.generic import (
+    ArrayObject,
+    DictionaryObject,
+    FloatObject,
+    NameObject,
+    NumberObject,
+    StreamObject,
+    TextStringObject,
+)
+
+from ..constants import (
+    AP,
+    BC,
+    BS,
+    DA,
+    FT,
+    MK,
+    Annot,
+    Annots,
+    BBox,
+    F,
+    Form,
+    H,
+    N,
+    Q,
+    Rect,
+    Resources,
+    S,
+    Sig,
+    Subtype,
+    T,
+    W,
+    Widget,
+    XObject,
+)
+from ..constants import Type as PdfType
+from .base import Field
+from .base import Widget as BaseWidget
+
+
+class SignatureWidget:
+    """
+    Represents a signature widget in a PDF form.
+
+    The widget stores placement, dimensions, and deferred hook values for a
+    signature field. Unlike widgets backed by ReportLab's AcroForm API, it
+    constructs its PDF annotation and normal appearance stream directly.
+
+    Attributes:
+        OPTIONAL_PARAMS (list): Width and height parameters with their defaults.
+        ALLOWED_HOOK_PARAMS (list): Parameters applied after the annotation has
+            been copied into the destination PDF.
+    """
+
+    OPTIONAL_PARAMS = [
+        ("width", 160),
+        ("height", 90),
+    ]
+    ALLOWED_HOOK_PARAMS = ["required", "tooltip"]
+
+    def __init__(
+        self,
+        name: str,
+        page_number: int,
+        x: float,
+        y: float,
+        **kwargs,
+    ) -> None:
+        """
+        Initializes a signature widget description.
+
+        The widget records placement information, resolves width and height with
+        defaults of 160 and 90 points, and captures `required` and `tooltip`
+        values for later application.
+
+        Args:
+            name (str): The name of the signature widget.
+            page_number (int): The 1-based destination page number.
+            x (float): The left edge of the widget in PDF page coordinates.
+            y (float): The bottom edge of the widget in PDF page coordinates.
+            **kwargs: Optional `width`, `height`, `required`, and `tooltip`
+                values.
+        """
+        super().__init__()
+        self.hook_params = []
+
+        self.page_number = page_number
+        self.name = name
+        self.x = x
+        self.y = y
+        self.optional_parameters = {
+            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)))
+
+    @staticmethod
+    def build_widget_watermarks(
+        widgets: List[SignatureWidget],
+        stream: bytes,
+        annotation_builder: Callable[[PdfWriter, SignatureWidget], Any],
+    ) -> List[bytes]:
+        """
+        Builds page-aligned carrier PDFs from widget annotation objects.
+
+        Widgets are grouped by their 1-based page number. For every page that
+        contains widgets, this method creates a blank, single-page PDF sized
+        from the source page's media box. It asks ``annotation_builder`` to
+        create each annotation and its dependent objects in that PDF's writer,
+        then stores the returned annotation references in the page's `/Annots`
+        array. Pages without widgets are represented by an empty byte string.
+
+        Args:
+            widgets (List[SignatureWidget]): Widgets to package into carrier PDFs.
+            stream (bytes): Source PDF used to determine page count and page size.
+            annotation_builder (Callable): Function that receives the destination
+                writer and a widget, creates the annotation and its dependent
+                objects, and returns the annotation object or reference.
+
+        Returns:
+            List[bytes]: Page-aligned PDF streams. Each non-empty entry is
+            a single-page PDF containing the annotations for that source page.
+        """
+        page_to_widgets = defaultdict(list)
+        for widget in widgets:
+            page_to_widgets[widget.page_number].append(widget)
+
+        input_pdf = PdfReader(BytesIO(stream))
+        page_count = len(input_pdf.pages)
+        result = [b""] * page_count
+
+        for page_num in range(1, page_count + 1):
+            page_widgets = page_to_widgets.get(page_num, [])
+            if not page_widgets:
+                continue
+
+            page = input_pdf.pages[page_num - 1]
+            watermark, canvas = BaseWidget.create_watermark_canvas(page)
+            canvas.showPage()
+            canvas.save()
+            watermark.seek(0)
+
+            out = PdfWriter(watermark)
+            annotations = [annotation_builder(out, widget) for widget in page_widgets]
+            out.pages[0][NameObject(Annots)] = ArrayObject(  # pylint: disable=E1137
+                annotations
+            )
+
+            with BytesIO() as result_stream:
+                out.write(result_stream)
+                result_stream.seek(0)
+                result[page_num - 1] = result_stream.read()
+
+        return result
+
+    @staticmethod
+    def _build_border_appearance(
+        width: float,
+        height: float,
+        border_color: tuple[float, float, float],
+    ) -> StreamObject:
+        """
+        Constructs the border-only appearance shared by signature and image widgets.
+
+        Args:
+            width (float): The width of the widget.
+            height (float): The height of the widget.
+            border_color (tuple): The RGB color of the widget border.
+
+        Returns:
+            StreamObject: An unregistered Form XObject containing the widget border.
+        """
+        appearance = StreamObject()
+        appearance.set_data(
+            (
+                f"{border_color[0]:g} "
+                f"{border_color[1]:g} "
+                f"{border_color[2]:g} RG\n"
+                "1 w\n"
+                f"0.5 0.5 {width - 1:g} {height - 1:g} re\n"
+                "s\n"
+            ).encode()
+        )
+        appearance.update(
+            {
+                NameObject(PdfType): NameObject(XObject),
+                NameObject(Subtype): NameObject(Form),
+                NameObject(BBox): ArrayObject(
+                    [
+                        FloatObject(0),
+                        FloatObject(0),
+                        FloatObject(width),
+                        FloatObject(height),
+                    ]
+                ),
+                NameObject(Resources): DictionaryObject(),
+            }
+        )
+        return appearance
+
+    @staticmethod
+    def _build_rectangle(
+        widget: SignatureWidget, width: float, height: float
+    ) -> ArrayObject:
+        """
+        Constructs the annotation rectangle shared by signature and image widgets.
+
+        Args:
+            widget (SignatureWidget): The widget whose placement defines the rectangle.
+            width (float): The width of the widget.
+            height (float): The height of the widget.
+
+        Returns:
+            ArrayObject: The annotation's lower-left and upper-right coordinates.
+        """
+        return ArrayObject(
+            [
+                FloatObject(widget.x),
+                FloatObject(widget.y),
+                FloatObject(widget.x + width),
+                FloatObject(widget.y + height),
+            ]
+        )
+
+    @staticmethod
+    def _build_annotation(out: PdfWriter, widget: SignatureWidget) -> Any:
+        """
+        Constructs a signature widget annotation owned by a PDF writer.
+
+        This method creates a border-only Form XObject for the normal appearance,
+        builds a `/Sig` widget from the normalized name, position, and dimensions,
+        and registers both objects with the same writer. It implements the
+        annotation-builder callback used by `build_widget_watermarks`.
+
+        Args:
+            out (PdfWriter): The writer that will own the appearance stream and
+                widget annotation.
+            widget (SignatureWidget): The normalized signature widget definition
+                to convert into a PDF annotation.
+
+        Returns:
+            Any: The writer-owned indirect reference to the widget annotation.
+        """
+        width = float(widget.optional_parameters["width"])
+        height = float(widget.optional_parameters["height"])
+        border_color = (0.1, 0.1, 0.1)
+
+        appearance = SignatureWidget._build_border_appearance(
+            width, height, border_color
+        )
+        appearance_ref = out._add_object(  # type: ignore # noqa: SLF001 # pylint: disable=W0212
+            appearance.flate_encode()
+        )
+
+        annotation = DictionaryObject(
+            {
+                NameObject(PdfType): NameObject(Annot),
+                NameObject(Subtype): NameObject(Widget),
+                NameObject(Rect): SignatureWidget._build_rectangle(
+                    widget, width, height
+                ),
+                NameObject(MK): DictionaryObject(
+                    {
+                        NameObject(BC): ArrayObject(
+                            FloatObject(value) for value in border_color
+                        )
+                    }
+                ),
+                NameObject(BS): DictionaryObject(
+                    {
+                        NameObject(S): NameObject(S),
+                        NameObject(W): NumberObject(1),
+                    }
+                ),
+                NameObject(AP): DictionaryObject({NameObject(N): appearance_ref}),
+                NameObject(DA): TextStringObject("/Helv 0 Tf 0 g"),
+                NameObject(F): NumberObject(4),
+                NameObject(FT): NameObject(Sig),
+                NameObject(H): NameObject(N),
+                NameObject(T): TextStringObject(widget.name),
+                NameObject(Q): NumberObject(0),
+            }
+        )
+        return out._add_object(  # type: ignore # noqa: SLF001 # pylint: disable=W0212
+            annotation
+        )
+
+    @staticmethod
+    def bulk_watermarks(widgets: List[SignatureWidget], stream: bytes) -> List[bytes]:
+        """
+        Constructs signature widgets in page-aligned carrier PDFs.
+
+        Each widget is represented by a `/Sig` annotation with a transparent
+        interior and a dark-gray, one-point solid border. Its normal appearance
+        stream contains only that border. The annotation and appearance are
+        created in the carrier PDF's writer, so they do not retain references
+        to another PDF. ``build_widget_watermarks`` then packages the
+        annotations by source page.
+
+        Args:
+            widgets (List[SignatureWidget]): Signature widgets to construct.
+            stream (bytes): Source PDF used to determine page count and page size.
+
+        Returns:
+            List[bytes]: Page-aligned PDF streams containing the constructed
+            signature annotations.
+        """
+        return SignatureWidget.build_widget_watermarks(
+            widgets, stream, SignatureWidget._build_annotation
+        )
+
+
+@dataclass
+class SignatureField(Field):
+    """
+    Represents a signature field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    dimensions that can be configured for a signature input field.
+
+    Attributes:
+        _widget_class (Type[SignatureWidget]): The widget class associated with this field type.
+        width (Optional[float]): The width of the signature field.
+        height (Optional[float]): The height of the signature field.
+    """
+
+    _widget_class: Type[SignatureWidget] = SignatureWidget
+
+    width: Optional[float] = None
+    height: Optional[float] = None