PyPDFForm 5.5.2__tar.gz → 5.5.4__tar.gz

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

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

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

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

{pypdfform-5.5.2 → pypdfform-5.5.4}/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.4}/PyPDFForm/lib/egress.py

@@ -28,7 +28,7 @@ from .constants import (
 from .template import get_widget_key
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def appearance_streams_handler(pdf: bytes, generate_appearance_streams: bool) -> bytes:
     """
     Handles appearance streams and the /NeedAppearances flag for a PDF form.
@@ -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.4}/PyPDFForm/lib/font.py

@@ -66,7 +66,7 @@ from .raw.text import RawText
 from .watermark import create_watermarks_and_draw
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def validate_font(font_name: str, ttf_stream: bytes) -> bool:
     """
     Validates a TrueType font stream.
@@ -212,7 +212,7 @@ def temporary_font_registration(
                 del _fonts[rl_name]
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def _get_watermark_with_font(ttf_stream: bytes) -> bytes:
     """
     Creates a watermark PDF with a single space character using the specified font.
@@ -235,7 +235,7 @@ def _get_watermark_with_font(ttf_stream: bytes) -> bytes:
         )[0]
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def _compress_ttf(ttf_stream: bytes) -> bytes:
     """
     Compresses a TrueType font stream for embedding in a PDF.
@@ -361,7 +361,7 @@ def register_font_acroform(
         return f.read(), new_font_name
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def _get_base_font_name(ttf_stream: bytes) -> str:
     """
     Extracts the base font name from a TrueType font stream.
@@ -402,7 +402,6 @@ def _get_new_font_name(fonts: dict) -> str:
     return f"{FONT_NAME_PREFIX}{n}"
 
 
-@lru_cache(maxsize=128)
 def get_all_available_fonts(pdf: bytes) -> dict:
     """
     Retrieves all available fonts from a PDF document's AcroForm.

{pypdfform-5.5.2 → pypdfform-5.5.4}/PyPDFForm/lib/image.py

@@ -16,7 +16,7 @@ from PIL import Image
 from .constants import Rect
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def rotate_image(image_stream: bytes, rotation: float | int) -> bytes:
     """
     Rotates an image by a specified angle in degrees.
@@ -49,13 +49,12 @@ def rotate_image(image_stream: bytes, rotation: float | int) -> bytes:
     return result
 
 
-@lru_cache(maxsize=128)
 def get_image_dimensions(image_stream: bytes) -> Tuple[float, float]:
     """
     Retrieves the width and height of an image from its byte stream.
 
-    This cached function uses the PIL library to open the image from the provided
-    byte stream and returns its dimensions (width and height) as a tuple of floats.
+    This function uses the PIL library to open the image from the provided byte
+    stream and returns its dimensions (width and height) as a tuple of floats.
 
     Args:
         image_stream (bytes): The image data as bytes.

{pypdfform-5.5.2 → pypdfform-5.5.4}/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.4}/PyPDFForm/lib/template.py

@@ -53,7 +53,6 @@ from .patterns import (
 from .utils import extract_widget_property, find_pattern_match
 
 
-@lru_cache(maxsize=128)
 def get_metadata(pdf: bytes) -> dict:
     """
     Retrieves the metadata of a PDF.
@@ -85,13 +84,12 @@ def get_title(pdf: bytes) -> str | None:
     return get_metadata(pdf).get(Title)
 
 
-@lru_cache(maxsize=128)
 def get_on_open_javascript(pdf: bytes) -> str | None:
     """
     Retrieves the JavaScript configured to run when a PDF is opened.
 
-    Results are cached by PDF stream. Only a document-catalog `/OpenAction`
-    whose action type is JavaScript is returned.
+    Only a document-catalog `/OpenAction` whose action type is JavaScript is
+    returned.
 
     Args:
         pdf (bytes): The PDF stream to inspect for a document-open action.
@@ -201,7 +199,7 @@ def build_widgets(
     return deepcopy(_build_widget_cache(pdf_stream, use_full_widget_name))
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def _build_widget_cache(
     pdf_stream: bytes,
     use_full_widget_name: bool,
@@ -379,7 +377,6 @@ def _handle_radio_widget(
         radio.value = radio.number_of_options - 1
 
 
-@lru_cache(maxsize=128)
 def get_widgets_by_page(pdf: bytes) -> Dict[int, List[dict]]:
     """
     Retrieves widgets from a PDF stream, organized by page number.

{pypdfform-5.5.2 → pypdfform-5.5.4}/PyPDFForm/lib/utils.py

@@ -12,7 +12,6 @@ It includes functions for:
 """
 
 from collections.abc import Callable
-from functools import lru_cache
 from io import BytesIO
 from secrets import choice
 from string import ascii_letters, digits, punctuation
@@ -30,7 +29,6 @@ from .constants import (
 )
 
 
-@lru_cache(maxsize=128)
 def remove_all_widgets(pdf: bytes) -> bytes:
     """
     Removes all widgets (form fields) from a PDF, effectively flattening the form.

{pypdfform-5.5.2 → pypdfform-5.5.4}/PyPDFForm/lib/watermark.py

@@ -22,7 +22,7 @@ from .constants import Annots
 from .patterns import get_widget_key
 
 
-@lru_cache(maxsize=128)
+@lru_cache(maxsize=8)
 def _get_image_reader(image_stream: bytes) -> ImageReader:
     """
     Creates a cached ReportLab image reader for an image byte stream.

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

@@ -20,7 +20,7 @@ from inspect import signature
 from io import BytesIO
 from typing import List, Optional
 
-from pypdf import PdfReader
+from pypdf import PageObject, PdfReader
 from reportlab.lib.colors import Color
 from reportlab.pdfgen.canvas import Canvas
 
@@ -107,7 +107,7 @@ class Widget:
                 self.hook_params.append((each, kwargs.get(each)))
 
     @staticmethod
-    @lru_cache(maxsize=128)
+    @lru_cache(maxsize=8)
     def _get_default_field_flags(acro_form_class: type, acro_form_func: str) -> tuple:
         """
         Retrieves the default field flags for a ReportLab AcroForm method.
@@ -172,6 +172,28 @@ class Widget:
         """
         getattr(canvas.acroForm, self.ACRO_FORM_FUNC)(**self.acro_form_params)
 
+    @staticmethod
+    def create_watermark_canvas(page: PageObject) -> tuple[BytesIO, Canvas]:
+        """
+        Creates a PDF canvas sized to a source page.
+
+        Args:
+            page (PageObject): 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 +231,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.4/PyPDFForm/lib/widgets/image.py

@@ -0,0 +1,171 @@
+# -*- 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 Type
+
+from pypdf import PdfWriter
+from pypdf.generic import (
+    ArrayObject,
+    DictionaryObject,
+    FloatObject,
+    IndirectObject,
+    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) -> IndirectObject:
+        """
+        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:
+            IndirectObject: 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
+        )
+
+
+@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