PyPDFForm 6.0.1__tar.gz → 6.1.0__tar.gz

{pypdfform-6.0.1 → pypdfform-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 6.0.1
+Version: 6.1.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -27,8 +27,8 @@ 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: pypdf<7.0.0,>=6.12.2
+Requires-Dist: pillow<14.0.0,>=12.2.0
+Requires-Dist: pypdf<7.0.0,>=6.19.0
 Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.26.1; 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.1 → pypdfform-6.1.0}/PyPDFForm/__init__.py

@@ -16,15 +16,14 @@ PyPDFForm aims to make PDF form automation straightforward whether it is used
 from Python code or from the command line.
 """
 
-__version__ = "6.0.1"
+__version__ = "6.1.0"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage
 from .lib.middleware import Widgets
 from .lib.raw import RawElements
-from .lib.types import PdfArray
 from .lib.widgets import Fields
-from .lib.wrapper import PdfWrapper
+from .lib.wrapper import PdfArray, PdfWrapper
 
 __all__ = [
     "PdfWrapper",

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/cli/common.py

@@ -312,6 +312,7 @@ def create_elements_from_file(
     options_param_hint: str,
     output: Path | None = None,
     element_type: str | None = None,
+    input_errors: tuple[type[Exception], ...] = (),
 ) -> None:
     """
     Creates PDF elements from a data file or command-line options.
@@ -321,7 +322,8 @@ def create_elements_from_file(
     from the additional command-line options stored in ``ctx.args``. The data
     file takes precedence when both input forms are supplied. Each definition
     is constructed after optional font registration and passed to `method_name`
-    on `PdfWrapper`.
+    on `PdfWrapper`. Errors of the `input_errors` types raised by that method
+    are reported against the input form that was used, without writing output.
 
     Args:
         pdf (Path): The path to the input PDF file.
@@ -342,6 +344,9 @@ def create_elements_from_file(
             omitted, the input PDF is overwritten. Defaults to None.
         element_type (str, optional): Element type selected for command-line
             input. Defaults to None.
+        input_errors (tuple[type[Exception], ...], optional): Exception types
+            raised by `method_name` for invalid element definitions. Defaults to
+            an empty tuple.
     """
     if data is not None:
         input_data = load_data_file(data, schema, file_param_hint)
@@ -370,4 +375,13 @@ def create_elements_from_file(
             handle_font_registration(obj, each, registered_font)
             ungrouped_input.append(element_map[k](**each))
 
-    getattr(obj, method_name)(ungrouped_input).write(output or pdf)
+    try:
+        result = getattr(obj, method_name)(ungrouped_input)
+    except input_errors as exc:
+        cli_bad_parameter(
+            str(exc),
+            param_hint=file_param_hint if data is not None else options_param_hint,
+            cause=exc,
+        )
+
+    result.write(output or pdf)

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/cli/create.py

@@ -126,7 +126,8 @@ def extract(
     The command validates that the requested end page does not precede the
     start page, converts the 1-based CLI page numbers into the slice expected
     by `PdfWrapper.pages`, and writes the extracted pages to the required
-    output path.
+    output path. Each page is extracted separately, so links to other pages
+    are removed.
 
     Args:
         ctx (typer.Context): Typer context containing global `PdfWrapper`
@@ -332,7 +333,8 @@ def annotation(
     The command maps input groups such as `text`, `link`, and `highlight` to
     annotation classes, validates the input against the CLI annotation schema,
     creates the corresponding annotation objects, and calls
-    `PdfWrapper.annotate` before writing the modified PDF. A data file can
+    `PdfWrapper.annotate` before writing the modified PDF. A link to a page
+    outside the PDF is reported as a parameter error. A data file can
     define multiple annotations grouped by type. Without `--file`, `--type` and
     the annotation options define one annotation. The data file takes
     precedence when both input forms are supplied.
@@ -368,6 +370,7 @@ def annotation(
         options_param_hint="annotation options",
         output=output,
         element_type=element_type,
+        input_errors=(ValueError,),
     )
 
 

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/cli/update.py

@@ -297,9 +297,10 @@ def field(
 
     The command validates the input against the field update schema, loads the
     PDF with the global CLI options stored in `ctx.obj`, resolves each field
-    name, registers any referenced fonts once per invocation, assigns the
-    requested widget properties, and writes the modified PDF to the requested
-    output path or back to the input file. A data file can update multiple
+    name, checks that each field type supports its requested properties,
+    registers any referenced fonts once per invocation, assigns the requested
+    widget properties, and writes the modified PDF to the requested output path
+    or back to the input file. A data file can update multiple
     fields. Without `--file`, `--field` and the property options update one
     field. The data file takes precedence when both input forms are supplied.
 
@@ -315,8 +316,9 @@ def field(
             Defaults to None.
 
     Raises:
-        typer.BadParameter: Raised when the input file is invalid or a requested
-            field does not exist.
+        typer.BadParameter: Raised when the input file is invalid, a requested
+            field does not exist, or a field type does not support a requested
+            property.
     """
     if data is not None:
         input_data = load_data_file(data, FIELD_SCHEMA, "--file")
@@ -337,12 +339,21 @@ def field(
         field_param_hint = "--field"
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
-    registered_font = {}
+    field_widgets = {}
     for k, each in input_data.items():
         field_widget = get_widget(obj, k, field_param_hint)
+        for param in each:
+            try:
+                field_widget.check_property_supported(param)
+            except AttributeError as exc:
+                cli_bad_parameter(str(exc), param_hint=field_param_hint, cause=exc)
+        field_widgets[k] = field_widget
+
+    registered_font = {}
+    for k, each in input_data.items():
         handle_font_registration(obj, each, registered_font)
         for param, v in each.items():
-            setattr(field_widget, param, v)
+            setattr(field_widgets[k], param, v)
 
     obj.write(output or pdf)
 

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/lib/adapter.py

@@ -10,6 +10,7 @@ forms. The module ensures that the input is properly converted into a byte
 stream before further processing.
 """
 
+from os import PathLike
 from os.path import isfile
 from typing import Any, BinaryIO
 
@@ -32,7 +33,7 @@ def readable(obj: Any) -> bool:
 
 
 def fp_or_f_obj_or_stream_to_stream(
-    fp_or_f_obj_or_stream: bytes | str | BinaryIO,
+    fp_or_f_obj_or_stream: bytes | str | PathLike | BinaryIO,
 ) -> bytes:
     """
     Adapt a file path, file object, or stream to a byte stream.
@@ -40,30 +41,37 @@ def fp_or_f_obj_or_stream_to_stream(
     This function takes a file path, a file object, or a byte stream and adapts it to a consistent byte stream.
     It handles different input types, including:
         - byte streams (bytes)
-        - file paths (str)
+        - file paths (str or PathLike)
         - file-like objects with a read() method (BinaryIO)
-    Unsupported inputs and string paths that do not point to files are treated
-    as empty input and return ``b""``.
+    Paths are opened directly, so a missing path raises ``FileNotFoundError``.
+    Empty bytes and empty readable objects are returned as ``b""``.
 
     Args:
-        fp_or_f_obj_or_stream (bytes | str | BinaryIO): The input to adapt.
-            It can be a byte stream, a file path (string), or a file object.
+        fp_or_f_obj_or_stream (bytes | str | PathLike | BinaryIO): The input to adapt.
+            It can be a byte stream, a file path, or a file object.
 
     Returns:
         bytes: The byte stream representation of the input.
-               Returns an empty byte string if the file path does not exist.
+
+    Raises:
+        OSError: If a file path cannot be opened, such as ``FileNotFoundError``
+            for a missing path.
+        TypeError: If the input is not bytes, a file path, or a readable object.
     """
     # not cached to handle writing to the same disk file
-    result = b""
     if isinstance(fp_or_f_obj_or_stream, bytes):
         result = fp_or_f_obj_or_stream
 
     elif readable(fp_or_f_obj_or_stream):
         result = fp_or_f_obj_or_stream.read()
 
-    elif isinstance(fp_or_f_obj_or_stream, str) and isfile(fp_or_f_obj_or_stream):
+    elif isinstance(fp_or_f_obj_or_stream, (str, PathLike)):
         with open(fp_or_f_obj_or_stream, "rb") as _file:
             result = _file.read()
+
+    else:
+        msg = f"Expected bytes, a file path, or a readable binary stream, got {type(fp_or_f_obj_or_stream).__name__}."
+        raise TypeError(msg)
     return result
 
 

pypdfform-6.1.0/PyPDFForm/lib/annotations/link.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the class for link annotations in PyPDFForm.
+
+It provides a structure for representing and interacting with PDF link
+annotations, which allow users to click and navigate to a URI or an internal page.
+
+Classes:
+    - `LinkAnnotation`: A dataclass representing the properties of a PDF link annotation.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from pypdf.generic import (
+    ArrayObject,
+    DictionaryObject,
+    IndirectObject,
+    NameObject,
+    TextStringObject,
+)
+
+from ..constants import A, Link, S
+from .base import Annotation
+
+
+@dataclass
+class LinkAnnotation(Annotation):
+    """
+    A dataclass representing the properties of a PDF link annotation.
+
+    This class extends the `Annotation` base class to specifically handle
+    link annotations, including the target URI or an internal page.
+
+    Attributes:
+        uri (str): The URI that the link annotation points to. Takes precedence
+            over `page` when both are set. Defaults to None.
+        page (int): The 1-based page number in the same PDF that the link
+            annotation points to. Defaults to None.
+    """
+
+    _annotation_type: str = Link
+
+    uri: Optional[str] = None
+    page: Optional[int] = None
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the link annotation.
+
+        This method extends the base properties with a URI action. A link to
+        an internal page needs the pages of the target PDF, so its destination
+        is built separately by `get_destination`.
+
+        Returns:
+            dict: A dictionary of PDF properties specific to the link annotation.
+        """
+        result = super().get_specific_properties()
+        if self.uri is not None:
+            result[NameObject(A)] = DictionaryObject(
+                {
+                    NameObject(S): NameObject("/URI"),
+                    NameObject("/URI"): TextStringObject(self.uri),
+                }
+            )
+
+        return result
+
+    def get_destination(
+        self, page_references: Sequence[IndirectObject]
+    ) -> Optional[ArrayObject]:
+        """
+        Gets the destination of a link to an internal page.
+
+        A destination in the same PDF must refer to the target page object
+        rather than a page index, which is reserved for destinations in other
+        PDFs. The 1-based `page` is resolved against the page references of the
+        PDF that will contain the link.
+
+        Args:
+            page_references (Sequence[IndirectObject]): References to the pages
+                of the PDF that will contain the link, in page order.
+
+        Returns:
+            Optional[ArrayObject]: The destination that fits the target page in
+                the window, or None if the link has a URI or no page.
+
+        Raises:
+            ValueError: If `page` is outside the pages of the PDF.
+        """
+        if self.uri is not None or self.page is None:
+            return None
+
+        if not 1 <= self.page <= len(page_references):
+            msg = f"Link page {self.page} must satisfy 1 <= page <= {len(page_references)}."
+            raise ValueError(msg)
+
+        return ArrayObject([page_references[self.page - 1], NameObject("/Fit")])

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/lib/constants.py

@@ -41,10 +41,30 @@ VERSION_IDENTIFIERS = [
 
 DEPRECATION_NOTICE = "{} will be deprecated soon."
 DEPRECATION_REPLACE_NOTICE = "Use {} instead."
+UNEXPECTED_KWARG_NOTICE = "{}() got an unexpected keyword argument '{}'."
+REMOVED_KWARG_NOTICE = "It was removed in PyPDFForm {}. {}"
+SUPPORTED_KWARGS_NOTICE = "Supported keyword arguments: {}."
+# method name -> removed keyword -> (version removed, migration guidance)
+REMOVED_KWARGS = {
+    "__init__": {
+        "preserve_metadata": (
+            "6.0.0",
+            "Remove it; input PDF metadata is preserved automatically.",
+        ),
+    },
+    "fill": {
+        "flatten": (
+            "6.0.0",
+            "Use readonly=True to make fields read-only; there is no form-flattening replacement.",
+        ),
+    },
+}
 
 Title = "/Title"
 Annots = "/Annots"
 Annot = "/Annot"
+Link = "/Link"
+Dest = "/Dest"
 Contents = "/Contents"
 Widget = "/Widget"
 XObject = "/XObject"
@@ -56,6 +76,7 @@ TU = "/TU"
 Rect = "/Rect"
 FT = "/FT"
 Parent = "/Parent"
+Kids = "/Kids"
 Ff = "/Ff"
 F = "/F"
 Tx = "/Tx"
@@ -89,6 +110,7 @@ A = "/A"
 AA = "/AA"
 Action = "/Action"
 S = "/S"
+GoTo = "/GoTo"
 JavaScript = "/JavaScript"
 JS = "/JS"
 OpenAction = "/OpenAction"

{pypdfform-6.0.1 → pypdfform-6.1.0}/PyPDFForm/lib/deprecation.py

@@ -4,13 +4,22 @@ A module for handling deprecation notices within the PyPDFForm library.
 
 This module provides utility functions to issue standard DeprecationWarning
 messages, ensuring consistency across the library when notifying users of
-deprecated features.
+deprecated features. It also rejects keyword arguments that are unsupported
+or were removed after deprecation.
 """
 
 from functools import wraps
+from typing import Any, Sequence
 from warnings import warn
 
-from .constants import DEPRECATION_NOTICE, DEPRECATION_REPLACE_NOTICE
+from .constants import (
+    DEPRECATION_NOTICE,
+    DEPRECATION_REPLACE_NOTICE,
+    REMOVED_KWARG_NOTICE,
+    REMOVED_KWARGS,
+    SUPPORTED_KWARGS_NOTICE,
+    UNEXPECTED_KWARG_NOTICE,
+)
 
 
 def deprecation_notice(to_replace: str, param: str = "") -> callable:
@@ -72,3 +81,39 @@ def deprecation_notice(to_replace: str, param: str = "") -> callable:
 
     decorator.emit_notice = emit_notice
     return decorator
+
+
+def reject_unsupported_kwargs(
+    obj: Any, method_name: str, kwargs: dict, supported: Sequence[str]
+) -> None:
+    """
+    Raises a TypeError for the first keyword argument a method does not support.
+
+    The message names the keyword like Python's own unexpected-keyword error.
+    Keywords listed for the method in `REMOVED_KWARGS` add the version that
+    removed them and their migration guidance; other keywords list the
+    supported ones.
+
+    Args:
+        obj (Any): The object whose method received the keyword arguments.
+        method_name (str): The method name, such as "__init__" or "fill".
+        kwargs (dict): The keyword arguments passed to the method.
+        supported (Sequence[str]): The keyword arguments the method supports.
+
+    Raises:
+        TypeError: If any keyword argument is not supported.
+    """
+
+    name = obj.__class__.__name__
+    if method_name != "__init__":
+        name = f"{name}.{method_name}"
+    removed = REMOVED_KWARGS.get(method_name, {})
+
+    for key in kwargs:
+        if key not in supported:
+            msg = UNEXPECTED_KWARG_NOTICE.format(name, key)
+            if key in removed:
+                msg = f"{msg} {REMOVED_KWARG_NOTICE.format(*removed[key])}"
+            else:
+                msg = f"{msg} {SUPPORTED_KWARGS_NOTICE.format(', '.join(supported))}"
+            raise TypeError(msg)

{pypdfform-6.0.1 → pypdfform-6.1.0}/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.1 → pypdfform-6.1.0}/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)