PyPDFForm 6.0.0__tar.gz → 6.0.2__tar.gz

{pypdfform-6.0.0 → pypdfform-6.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 6.0.0
+Version: 6.0.2
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -27,7 +27,7 @@ License-File: LICENSE
 Requires-Dist: cryptography<51.0.0,>=50.0.0
 Requires-Dist: fonttools<5.0.0,>=4.63.0
 Requires-Dist: pikepdf<11.0.0,>=10.7.2
-Requires-Dist: pillow<13.0.0,>=12.2.0
+Requires-Dist: pillow<14.0.0,>=12.2.0
 Requires-Dist: pypdf<7.0.0,>=6.12.2
 Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
@@ -39,7 +39,7 @@ Requires-Dist: coverage<8.0.0,>=7.14.1; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.2.0; extra == "dev"
 Requires-Dist: mkdocs<2.0.0,>=1.6.1; extra == "dev"
 Requires-Dist: mkdocs-material<10.0.0,>=9.7.6; extra == "dev"
-Requires-Dist: pudb<2026.0.0,>=2025.1.5; extra == "dev"
+Requires-Dist: pudb<2027.0.0,>=2025.1.5; extra == "dev"
 Requires-Dist: pylint<5.0.0,>=4.0.5; extra == "dev"
 Requires-Dist: pyright<2.0.0,>=1.1.409; extra == "dev"
 Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/__init__.py

@@ -16,7 +16,7 @@ PyPDFForm aims to make PDF form automation straightforward whether it is used
 from Python code or from the command line.
 """
 
-__version__ = "6.0.0"
+__version__ = "6.0.2"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/constants.py

@@ -56,6 +56,7 @@ TU = "/TU"
 Rect = "/Rect"
 FT = "/FT"
 Parent = "/Parent"
+Kids = "/Kids"
 Ff = "/Ff"
 F = "/F"
 Tx = "/Tx"

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/egress.py

@@ -1,17 +1,22 @@
 # -*- coding: utf-8 -*-
 """
-A module for egress functions.
-
-This module provides functionalities that prepare the final PDF for output (egress),
-ensuring that it is properly formatted and ready for the end-user. This includes
-managing appearance streams (so form fields display correctly after being filled),
-handling the /NeedAppearances flag, and rebuilding the AcroForm `/Fields` array from
-the widget annotations present on each page. These functions are typically called
-right before the final PDF byte stream is returned by the wrapper module.
+Prepare PDF output and publish serialized PDFs to filesystem paths.
+
+Preparation helpers manage appearance streams and the /NeedAppearances flag,
+and rebuild the AcroForm `/Fields` array from page widget annotations before
+`PdfWrapper.read()` returns the final bytes.
+
+For path output, `write_path()` writes serialized bytes to a sibling temporary
+file and closes it before atomic replacement. It follows symlinks, preserves
+existing permission bits, and cleans up failed temporary writes.
 """
 
+import os
+import stat
+from contextlib import suppress
 from functools import lru_cache
 from io import BytesIO
+from tempfile import NamedTemporaryFile
 from warnings import catch_warnings, filterwarnings
 
 from pikepdf import Pdf
@@ -24,10 +29,57 @@ from .constants import (
     Annots,
     Fields,
     Parent,
+    Subtype,
+    Widget,
 )
 from .template import get_widget_key
 
 
+def write_path(dest: str | bytes | os.PathLike, content: bytes) -> None:
+    """
+    Write serialized content to a sibling temporary file and replace its target.
+
+    Symlinks are followed. Existing permission bits are copied before replacement;
+    new files retain the temporary file's private permissions. Other file metadata
+    and hard-link relationships are not preserved. Failures before replacement
+    leave the destination's bytes unchanged and remove the temporary file.
+    """
+    path = os.path.realpath(os.fsdecode(dest))
+    mode = None
+    try:
+        destination_stat = os.stat(path)
+    except FileNotFoundError:
+        pass
+    else:
+        if not stat.S_ISREG(destination_stat.st_mode):
+            message = "The output destination must be a regular file."
+            raise OSError(message)
+        mode = stat.S_IMODE(destination_stat.st_mode)
+
+    temporary_path = None
+    try:
+        with NamedTemporaryFile(
+            mode="wb", prefix=".pypdfform-", dir=os.path.dirname(path), delete=False
+        ) as output:
+            temporary_path = output.name
+            if output.write(content) != len(content):
+                message = "The temporary PDF write was incomplete."
+                raise OSError(message)
+
+        if mode is not None:
+            os.chmod(temporary_path, mode)
+        os.replace(temporary_path, path)
+    finally:
+        if temporary_path is not None:
+            with suppress(FileNotFoundError):
+                try:
+                    os.unlink(temporary_path)
+                except PermissionError:
+                    # Windows cannot unlink a temporary file made read-only above.
+                    os.chmod(temporary_path, stat.S_IRUSR | stat.S_IWUSR)
+                    os.unlink(temporary_path)
+
+
 @lru_cache(maxsize=8)
 def appearance_streams_handler(pdf: bytes, generate_appearance_streams: bool) -> bytes:
     """
@@ -85,8 +137,8 @@ def rebuild_acroform_fields(
     Rebuilds the AcroForm `/Fields` array from matching page annotations.
 
     The existing `/Fields` array is replaced, creating an AcroForm dictionary
-    when necessary. Each page annotation is resolved to a widget key, and only
-    annotations whose keys are present in `widget_keys` contribute their
+    when necessary. Only widget annotations are resolved to a widget key, and
+    those whose keys are present in `widget_keys` contribute their
     top-level field object to the new array. Page annotation arrays are left
     unchanged. When no matching page annotations are found, the original PDF
     stream is returned unchanged to avoid an unnecessary rewrite.
@@ -111,13 +163,17 @@ def rebuild_acroform_fields(
     seen_fields = set()
     for page in writer.pages:
         for annot in page.get(Annots, []):
-            key = get_widget_key(annot.get_object(), use_full_widget_name)
-            if key in widget_keys:
-                field_ref = _get_root_field_reference(writer, annot)
-                field_key = _field_reference_key(field_ref)
-                if field_key not in seen_fields:
-                    fields.append(field_ref)
-                    seen_fields.add(field_key)
+            annotation = annot.get_object()
+            if (
+                annotation.get(Subtype) != Widget
+                or get_widget_key(annotation, use_full_widget_name) not in widget_keys
+            ):
+                continue
+            field_ref = _get_root_field_reference(writer, annot)
+            field_key = _field_reference_key(field_ref)
+            if field_key not in seen_fields:
+                fields.append(field_ref)
+                seen_fields.add(field_key)
 
     if not seen_fields:
         return pdf

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/filler.py

@@ -12,9 +12,9 @@ from io import BytesIO
 from typing import Dict, cast
 
 from pypdf import PdfWriter
-from pypdf.generic import DictionaryObject
+from pypdf.generic import ArrayObject, DictionaryObject
 
-from .constants import Annots
+from .constants import AcroForm, Fields, Kids, Parent, Subtype, Widget
 from .hooks import update_field_readonly
 from .image import get_draw_image_resolutions, get_image_dimensions
 from .middleware import WIDGET_TYPES
@@ -90,7 +90,8 @@ def update_widget(
 
     This function updates the value of a single PDF form widget based on its type. It sets
     the read-only flag first when requested, skips value updates when the
-    middleware value is ``None``, tracks radio option indices within each group, and
+    middleware value is ``None``, tracks radio option indices within each group,
+    updates the entire radio group when its selected option is reached, and
     prepares images or signatures for later drawing instead of writing image data directly
     into the annotation.
 
@@ -156,6 +157,36 @@ def handle_image_drawing(
     return merge_watermarks_with_pdf(result, create_watermarks_and_draw(result, images))
 
 
+def _detach_consumed_widget(writer: PdfWriter, annot: DictionaryObject) -> None:
+    """
+    Detaches a consumed widget and empty ancestor fields from the AcroForm tree.
+
+    This function removes the widget from its parent's child array or the
+    AcroForm's root field array. It removes ancestors that become empty, stopping
+    at the first parent with remaining children. Resolved objects are compared
+    by identity so unrelated fields with the same name retain their references.
+    The caller is responsible for removing the widget from page annotations.
+
+    Args:
+        writer (PdfWriter): The PDF writer that owns the widget and field tree.
+        annot (DictionaryObject): The consumed image or signature widget to detach.
+    """
+    field = annot
+    while Parent in field:
+        parent = cast(DictionaryObject, field[Parent])
+        children = cast(ArrayObject, parent.get(Kids, ArrayObject()).get_object())
+        children[:] = [child for child in children if child.get_object() is not field]
+        if children:
+            return
+        field = parent
+
+    acroform = writer.root_object.get(AcroForm, DictionaryObject()).get_object()
+    fields = cast(ArrayObject, acroform.get(Fields, ArrayObject()).get_object())
+    fields[:] = [
+        reference for reference in fields if reference.get_object() is not field
+    ]
+
+
 def fill(
     template: bytes,
     widgets: Dict[str, WIDGET_TYPES],
@@ -169,8 +200,9 @@ def fill(
     widgets on each page of the PDF and updates their values based on the provided `widgets`
     dictionary. The function supports text fields, checkboxes, radio buttons, dropdowns,
     images, and signatures. It can set fields read-only during filling, and when images or
-    signatures are present it returns both the filled form stream and a second stream with
-    the image watermarks applied so callers can preserve non-image widgets separately.
+    signatures are present it removes only the widgets whose images were prepared,
+    including their field-tree entries, and returns a second stream with the image
+    watermarks applied. All other annotations retain their existing references.
 
     Args:
         template (bytes): The PDF template as bytes.
@@ -196,15 +228,21 @@ def fill(
 
     for page_num, page in enumerate(out.pages):
         images_to_draw[page_num + 1] = []
-        for annot in page.get(Annots, []):
-            annot = cast(DictionaryObject, annot.get_object())
+        annotations = page.annotations
+        if annotations is None:
+            continue
+        # Keep a snapshot because consumed widgets are removed during iteration.
+        for reference in annotations.copy():
+            annot = cast(DictionaryObject, reference.get_object())
+            if annot.get(Subtype) != Widget:
+                continue
             key = get_widget_key(annot.get_object(), use_full_widget_name)
 
             widget = widgets.get(key)
             if widget is None:
                 continue
 
-            any_image_to_draw |= update_widget(
+            consumed = update_widget(
                 annot,
                 widget,
                 key,
@@ -213,6 +251,12 @@ def fill(
                 need_appearances,
                 readonly,
             )
+            if consumed:
+                any_image_to_draw = True
+                annotations[:] = [
+                    item for item in annotations if item.get_object() is not annot
+                ]
+                _detach_consumed_widget(out, annot)
 
     with BytesIO() as f:
         out.write(f)

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/font.py

@@ -10,6 +10,7 @@ for extracting font information from TTF streams and managing font names within
 from contextlib import contextmanager
 from functools import lru_cache
 from io import BytesIO
+from re import fullmatch
 from typing import Generator
 from uuid import uuid4
 from zlib import compress
@@ -190,7 +191,14 @@ def temporary_font_registration(
     from the original font names to the unique names.
 
     The fonts are inserted into ReportLab's global font registry for the duration
-    of the context manager and removed again on exit.
+    of the context manager. Every inserted entry is tracked independently of the
+    alias mapping and removed on exit, including setup and drawing failures.
+    Repeated aliases resolve to the last registration. Cleanup only removes
+    entries still referencing the font objects inserted by this context.
+
+    Sequential and nested contexts are supported. Callers must serialize threaded
+    PyPDFForm and direct ReportLab operations in the same process for the entire
+    operation; this context manager does not synchronize the global registry.
 
     Args:
         fonts (list[tuple[str, bytes]]): A list of tuples, each containing a font name and its TTF stream.
@@ -199,16 +207,21 @@ def temporary_font_registration(
         dict: A mapping of the original font names to the temporary unique names used by ReportLab.
     """
     font_mapping = {}
-    for font_name, ttf_stream in fonts:
-        rl_name = uuid4().hex
-        font_mapping[font_name] = rl_name
-        _fonts[rl_name] = TTFont(rl_name, BytesIO(ttf_stream))
-
+    registered_fonts = {}
     try:
+        for font_name, ttf_stream in fonts:
+            rl_name = uuid4().hex
+            while rl_name in _fonts:
+                rl_name = uuid4().hex
+            font = TTFont(rl_name, BytesIO(ttf_stream))
+            registered_fonts[rl_name] = font
+            _fonts[rl_name] = font
+            font_mapping[font_name] = rl_name
+
         yield font_mapping
     finally:
-        for rl_name in font_mapping.values():
-            if rl_name in _fonts:
+        for rl_name, font in registered_fonts.items():
+            if _fonts.get(rl_name) is font:
                 del _fonts[rl_name]
 
 
@@ -382,8 +395,10 @@ def _get_new_font_name(fonts: dict) -> str:
     """
     Generates a new unique font name to avoid conflicts with existing fonts in the PDF.
 
-    This function inspects existing AcroForm resource keys that look like `/F#`
-    and returns the lowest unused numbered key with the same prefix.
+    This function inspects existing AcroForm resource keys that exactly match `/F`
+    followed by one or more ASCII decimal digits and returns the lowest unused
+    numbered key with the same prefix. Other resource names are left unchanged
+    and do not reserve a number.
 
     Args:
         fonts (dict): A dictionary of existing fonts in the PDF.
@@ -393,8 +408,8 @@ def _get_new_font_name(fonts: dict) -> str:
     """
     existing = set()
     for key in fonts:
-        if isinstance(key, str) and key.startswith(FONT_NAME_PREFIX):
-            existing.add(int(key[2:]))
+        if isinstance(key, str) and fullmatch(rf"{FONT_NAME_PREFIX}[0-9]+", key):
+            existing.add(int(key[len(FONT_NAME_PREFIX) :]))
 
     n = 1
     while n in existing:

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/hooks.py

@@ -314,7 +314,28 @@ def update_text_field_max_length(annot: DictionaryObject, val: int) -> None:
     annot[NameObject(MaxLen)] = NumberObject(val)
 
 
-def update_check_radio_size(annot: DictionaryObject, val: float) -> None:
+def _normalize_geometry_value(val: int | float) -> float:
+    """
+    Normalizes scalar geometry to a float before modifying an annotation.
+
+    Args:
+        val (int | float): The coordinate or dimension to normalize.
+
+    Returns:
+        float: The normalized geometry value.
+
+    Raises:
+        TypeError: If the value is not an integer or float, or is a boolean.
+    """
+    # bool subclasses int, so the numeric type check alone would accept booleans.
+    if isinstance(val, bool) or not isinstance(val, (int, float)):
+        # TODO: Refactor this raise into a centralized exception raiser when one is introduced.
+        msg = "Geometry values must be integers or floats; booleans are invalid."
+        raise TypeError(msg)
+    return float(val)
+
+
+def update_check_radio_size(annot: DictionaryObject, val: int | float) -> None:
     """
     Updates the size of a check box or radio button annotation.
 
@@ -325,8 +346,12 @@ def update_check_radio_size(annot: DictionaryObject, val: float) -> None:
     Args:
         annot (DictionaryObject): The annotation dictionary for the check box or
             radio button.
-        val (float): The new size (width and height) for the check box or radio button.
+        val (int | float): The new size (width and height) for the check box or radio button.
+
+    Raises:
+        TypeError: If the size is not an integer or float, or is a boolean.
     """
+    val = _normalize_geometry_value(val)
     rect = annot[Rect]
     # scale from bottom left
     new_rect = [
@@ -379,72 +404,88 @@ def update_field_readonly(annot: DictionaryObject, val: bool) -> None:
     _update_field_flag(annot, READ_ONLY, val)
 
 
-def update_field_x(annot: DictionaryObject, val: float) -> None:
+def update_field_x(annot: DictionaryObject, val: int | float) -> None:
     """
     Updates the X-coordinate (horizontal position) of a form field annotation.
 
     This function modifies the 'Rect' entry of the annotation dictionary to change
     the left X-coordinate of the field and adjusts the right X-coordinate by the
-    same delta to maintain the field's width. Non-float values are ignored.
+    same delta to maintain the field's width. Integer and float inputs are
+    normalized to floats before updating the rectangle.
 
     Args:
         annot (DictionaryObject): The annotation dictionary for the form field.
-        val (float): The new X-coordinate for the left edge of the field.
+        val (int | float): The new X-coordinate for the left edge of the field.
+
+    Raises:
+        TypeError: If the coordinate is not an integer or float, or is a boolean.
     """
-    if isinstance(val, float):
-        diff = val - annot[Rect][0]
-        annot[NameObject(Rect)][0] = FloatObject(val)
-        annot[NameObject(Rect)][2] = FloatObject(annot[NameObject(Rect)][2] + diff)
+    val = _normalize_geometry_value(val)
+    diff = val - annot[Rect][0]
+    annot[NameObject(Rect)][0] = FloatObject(val)
+    annot[NameObject(Rect)][2] = FloatObject(annot[NameObject(Rect)][2] + diff)
 
 
-def update_field_y(annot: DictionaryObject, val: float) -> None:
+def update_field_y(annot: DictionaryObject, val: int | float) -> None:
     """
     Updates the Y-coordinate (vertical position) of a form field annotation.
 
     This function modifies the 'Rect' entry of the annotation dictionary to change
     the bottom Y-coordinate of the field and adjusts the top Y-coordinate by the
-    same delta to maintain the field's height. Non-float values are ignored.
+    same delta to maintain the field's height. Integer and float inputs are
+    normalized to floats before updating the rectangle.
 
     Args:
         annot (DictionaryObject): The annotation dictionary for the form field.
-        val (float): The new Y-coordinate for the bottom edge of the field.
+        val (int | float): The new Y-coordinate for the bottom edge of the field.
+
+    Raises:
+        TypeError: If the coordinate is not an integer or float, or is a boolean.
     """
-    if isinstance(val, float):
-        diff = val - annot[Rect][1]
-        annot[NameObject(Rect)][1] = FloatObject(val)
-        annot[NameObject(Rect)][3] = FloatObject(annot[NameObject(Rect)][3] + diff)
+    val = _normalize_geometry_value(val)
+    diff = val - annot[Rect][1]
+    annot[NameObject(Rect)][1] = FloatObject(val)
+    annot[NameObject(Rect)][3] = FloatObject(annot[NameObject(Rect)][3] + diff)
 
 
-def update_field_width(annot: DictionaryObject, val: float) -> None:
+def update_field_width(annot: DictionaryObject, val: int | float) -> None:
     """
     Updates the width of a form field annotation.
 
     This function modifies the 'Rect' entry of the annotation dictionary to set
     the new width of the field, adjusting the rightmost coordinate while keeping
-    the leftmost coordinate fixed. Non-float values are ignored.
+    the leftmost coordinate fixed. Integer and float inputs are normalized to
+    floats before updating the rectangle.
 
     Args:
         annot (DictionaryObject): The annotation dictionary for the form field.
-        val (float): The new width of the field.
+        val (int | float): The new width of the field.
+
+    Raises:
+        TypeError: If the width is not an integer or float, or is a boolean.
     """
-    if isinstance(val, float):
-        annot[NameObject(Rect)][2] = FloatObject(annot[Rect][0] + val)
+    val = _normalize_geometry_value(val)
+    annot[NameObject(Rect)][2] = FloatObject(annot[Rect][0] + val)
 
 
-def update_field_height(annot: DictionaryObject, val: float) -> None:
+def update_field_height(annot: DictionaryObject, val: int | float) -> None:
     """
     Updates the height of a form field annotation.
 
     This function modifies the 'Rect' entry of the annotation dictionary to set
     the new height of the field, adjusting the topmost coordinate while keeping
-    the bottommost coordinate fixed. Non-float values are ignored.
+    the bottommost coordinate fixed. Integer and float inputs are normalized to
+    floats before updating the rectangle.
 
     Args:
         annot (DictionaryObject): The annotation dictionary for the form field.
-        val (float): The new height of the field.
+        val (int | float): The new height of the field.
+
+    Raises:
+        TypeError: If the height is not an integer or float, or is a boolean.
     """
-    if isinstance(val, float):
-        annot[NameObject(Rect)][3] = FloatObject(annot[Rect][1] + val)
+    val = _normalize_geometry_value(val)
+    annot[NameObject(Rect)][3] = FloatObject(annot[Rect][1] + val)
 
 
 def update_field_tooltip(annot: DictionaryObject, val: str) -> None:

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/middleware/base.py

@@ -8,9 +8,29 @@ common attributes and methods for all form widgets, such as name, value,
 and schema definition.
 """
 
+from dataclasses import dataclass
 from typing import Any, List, Optional, TextIO
 
 
+@dataclass(frozen=True)
+class PreparedValue:
+    """
+    Represents a widget value prepared for assignment.
+
+    Preparation validates and normalizes the value without changing the widget.
+    Dropdown updates can also include replacement choices, which are stored and
+    queued for PDF updates only when the prepared value is applied.
+
+    Attributes:
+        value (Any): The value to store in the widget.
+        choices (list | None): Replacement dropdown choices, or None when the
+            choices should remain unchanged.
+    """
+
+    value: Any
+    choices: list | None = None
+
+
 class Widget:
     """
     Base class for form widget.
@@ -136,7 +156,34 @@ class Widget:
         Args:
             value (Any): The value to set.
         """
-        self._value = value
+        self.apply_value(self.prepare_value(value))
+
+    def prepare_value(self, value: Any) -> PreparedValue:
+        """
+        Prepares a value for assignment without changing the widget.
+
+        The base implementation retains the supplied value. Subclasses can
+        validate or normalize it and stage related attribute changes here.
+
+        Args:
+            value (Any): The proposed value of the widget.
+
+        Returns:
+            PreparedValue: The value to apply after preparation succeeds.
+        """
+        return PreparedValue(value)
+
+    def apply_value(self, update: PreparedValue) -> None:
+        """
+        Applies a previously prepared value to the widget.
+
+        This method stores the value without repeating validation. Subclasses
+        can apply related attribute changes through their existing hooks.
+
+        Args:
+            update (PreparedValue): The prepared widget value to store.
+        """
+        self._value = update.value
 
     @property
     def schema_definition(self) -> dict:

{pypdfform-6.0.0 → pypdfform-6.0.2}/PyPDFForm/lib/middleware/checkbox.py

@@ -76,7 +76,7 @@ class Checkbox(Widget):
         return {"type": "boolean", **super().schema_definition}
 
     @property
-    def sample_value(self) -> bool | int:
+    def sample_value(self) -> bool | int | None:
         """
         Returns a sample value for the checkbox.
 
@@ -84,6 +84,6 @@ class Checkbox(Widget):
         checkbox field.
 
         Returns:
-            bool | int: A sample value for the checkbox.
+            bool | int | None: A sample value for the checkbox or its subclasses.
         """
         return True