PyPDFForm 5.2.4__tar.gz → 5.3.0__tar.gz

{pypdfform-5.2.4 → pypdfform-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.4
+Version: 5.3.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -33,6 +33,7 @@ Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.26.1; extra == "cli"
 Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "cli"
+Requires-Dist: PyYAML<7.0.0,>=6.0.3; extra == "cli"
 Provides-Extra: dev
 Requires-Dist: coverage<8.0.0,>=7.14.1; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.2.0; extra == "dev"

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/__init__.py

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

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/cli/common.py

@@ -2,8 +2,8 @@
 """
 This module provides shared helpers for PyPDFForm CLI commands.
 
-It contains utilities for loading JSON command input, registering custom fonts
-once per command invocation, and converting grouped JSON element definitions
+It contains utilities for loading structured command input, registering custom
+fonts once per command invocation, and converting grouped element definitions
 into the objects expected by `PdfWrapper` methods.
 """
 
@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import Annotated, Any, NoReturn
 
 import typer
+import yaml
 from jsonschema import ValidationError, validate
 
 from .. import PdfWrapper
@@ -62,15 +63,15 @@ FIELD_NAMES = Annotated[
 ]
 
 
-def json_file_option(help_text: str):
+def data_file_option(help_text: str):
     """
-    Creates the common validated JSON file option.
+    Creates the common validated structured data file option.
 
     Args:
         help_text (str): Help text to display for the option.
 
     Returns:
-        typer.Option: A configured `--file` / `-f` option for JSON file input.
+        typer.Option: A configured `--file` / `-f` option for file input.
     """
     return typer.Option(
         "--file",
@@ -109,7 +110,7 @@ def cli_bad_parameter(
 
 def _validation_error_path(exc: ValidationError) -> str:
     """
-    Builds a dotted JSON path for a validation error.
+    Builds a dotted input data path for a validation error.
 
     Args:
         exc (ValidationError): The JSON schema validation error.
@@ -120,28 +121,45 @@ def _validation_error_path(exc: ValidationError) -> str:
     return ".".join(str(each) for each in exc.absolute_path)
 
 
-def load_json_file(data: Path, schema: dict, param_hint: str) -> Any:
+def _input_file_kind(data: Path) -> str:
     """
-    Loads a JSON CLI input file and validates it against a schema.
+    Gets the structured data format to use for a CLI input file.
 
     Args:
-        data (Path): JSON file path.
+        data (Path): Input file path.
+
+    Returns:
+        str: The upper-case format name for user-facing messages.
+    """
+    if data.suffix.lower() in {".yaml", ".yml"}:
+        return "YAML"
+
+    return "JSON"
+
+
+def load_data_file(data: Path, schema: dict, param_hint: str) -> Any:
+    """
+    Loads a YAML or JSON CLI input file and validates it against a schema.
+
+    Args:
+        data (Path): YAML or JSON file path.
         schema (dict): JSON schema to validate against.
-        param_hint (str): CLI parameter associated with the JSON file.
+        param_hint (str): CLI parameter associated with the input file.
 
     Returns:
-        Any: Parsed and validated JSON input.
+        Any: Parsed and validated input data.
 
     Raises:
         typer.BadParameter: Raised when the file cannot be loaded or validation
             fails.
     """
+    input_kind = _input_file_kind(data)
     try:
         with open(data, "r", encoding="utf-8") as f:
-            input_data = json.load(f)
-    except (OSError, json.JSONDecodeError) as exc:
+            input_data = yaml.safe_load(f) if input_kind == "YAML" else json.load(f)
+    except (OSError, json.JSONDecodeError, yaml.YAMLError) as exc:
         cli_bad_parameter(
-            f"Invalid JSON file: {exc}",
+            f"Invalid {input_kind} file: {exc}",
             param_hint=param_hint,
             cause=exc,
         )
@@ -152,7 +170,7 @@ def load_json_file(data: Path, schema: dict, param_hint: str) -> Any:
         error_path = _validation_error_path(exc)
         location = f" at {error_path}" if error_path else ""
         cli_bad_parameter(
-            f"Invalid JSON file{location}: {exc.message}",
+            f"Invalid {input_kind} file{location}: {exc.message}",
             param_hint=param_hint,
             cause=exc,
         )
@@ -191,15 +209,15 @@ def handle_font_registration(
     """
     Registers a custom font referenced by CLI input.
 
-    CLI JSON files may provide a file path in a `font` parameter. This helper
+    CLI input files may provide a file path in a `font` parameter. This helper
     registers each unique font path on the supplied `PdfWrapper` once, assigns
     it a generated internal font name, and mutates `params["font"]` to that
     registered name so downstream field or element constructors can use it.
 
     Args:
         obj (PdfWrapper): The wrapper for the PDF currently being modified.
-        params (dict): The element or widget parameters loaded from JSON. This
-            dictionary is mutated when it contains a `font` key.
+        params (dict): The element or widget parameters loaded from the input
+            file. This dictionary is mutated when it contains a `font` key.
         registered_font (dict): Mapping of source font paths to generated
             `PdfWrapper` font names for the current command invocation.
     """
@@ -222,9 +240,9 @@ def create_elements_from_file(
     output: Path | None = None,
 ) -> None:
     """
-    Creates PDF elements from grouped JSON definitions.
+    Creates PDF elements from grouped file definitions.
 
-    The input JSON is expected to group element definitions by type, such as
+    The input data is expected to group element definitions by type, such as
     `text`, `image`, or `highlight`. Each group key is resolved through
     `element_map`, each item is constructed after optional font registration,
     and the resulting objects are passed to `method_name` on `PdfWrapper`.
@@ -232,21 +250,21 @@ def create_elements_from_file(
 
     Args:
         pdf (Path): The path to the input PDF file.
-        data (Path): The path to the JSON file containing grouped element
+        data (Path): The path to the input file containing grouped element
             definitions.
-        element_map (dict): Mapping from JSON group names to element classes or
-            callables used to construct each object.
+        element_map (dict): Mapping from input group names to element classes
+            or callables used to construct each object.
         schema (dict): JSON schema used to validate the grouped definitions.
         method_name (str): Name of the `PdfWrapper` method that accepts the
             constructed elements, such as `bulk_create_fields`, `draw`, or
             `annotate`.
         ctx (typer.Context): Typer context containing global wrapper options in
             `ctx.obj`.
-        param_hint (str): CLI parameter associated with the JSON file.
+        param_hint (str): CLI parameter associated with the input file.
         output (Path, optional): Path where the modified PDF should be saved. If
             omitted, the input PDF is overwritten. Defaults to None.
     """
-    input_data = load_json_file(data, schema, param_hint)
+    input_data = load_data_file(data, schema, param_hint)
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     ungrouped_input = []

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/cli/create.py

@@ -4,8 +4,8 @@ This module defines CLI commands for creating PDF files and PDF content.
 
 It exposes the `create` command group for blank PDFs, extracted page ranges,
 merged PDFs, form fields, raw drawn elements, annotations, and coordinate grid
-views. Commands in this module translate command-line arguments or grouped JSON
-input into `PdfWrapper`, `BlankPage`, `Fields`, `RawElements`, and
+views. Commands in this module translate command-line arguments or grouped
+YAML/JSON input into `PdfWrapper`, `BlankPage`, `Fields`, `RawElements`, and
 `Annotations` operations.
 """
 
@@ -21,7 +21,7 @@ from .common import (
     REQUIRED_OUTPUT_PDF,
     cli_bad_parameter,
     create_elements_from_file,
-    json_file_option,
+    data_file_option,
 )
 from .schemas.create import ANNOTATION_SCHEMA, FIELD_SCHEMA, RAW_SCHEMA
 
@@ -194,13 +194,15 @@ def merge(
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Add form fields described by grouped JSON definitions.
+    Add form fields described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `check`, and `signature` to
+    The command maps input groups such as `text`, `check`, and `signature` to
     PyPDFForm field classes, validates the input file against the CLI field
     schema, creates the corresponding field objects, and calls
     `PdfWrapper.bulk_create_fields` before writing the modified PDF.
@@ -209,7 +211,8 @@ def field(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing grouped form field definitions.
+        data (Path): YAML or JSON file containing grouped form field
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """
@@ -240,13 +243,15 @@ def field(
 def raw(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with raw element definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with raw element definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Draw raw elements described by grouped JSON definitions.
+    Draw raw elements described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `image`, and `rectangle` to
+    The command maps input groups such as `text`, `image`, and `rectangle` to
     raw element classes, validates the input file against the CLI raw element
     schema, creates the corresponding drawable objects, and calls
     `PdfWrapper.draw` before writing the modified PDF.
@@ -255,7 +260,8 @@ def raw(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing grouped raw element definitions.
+        data (Path): YAML or JSON file containing grouped raw element
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """
@@ -286,13 +292,15 @@ def raw(
 def annotation(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with annotation definitions.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with annotation definitions.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Add annotations described by grouped JSON definitions.
+    Add annotations described by grouped YAML or JSON definitions.
 
-    The command maps JSON groups such as `text`, `link`, and `highlight` to
+    The command maps input groups such as `text`, `link`, and `highlight` to
     annotation classes, validates the input file against the CLI annotation
     schema, creates the corresponding annotation objects, and calls
     `PdfWrapper.annotate` before writing the modified PDF.
@@ -301,7 +309,8 @@ def annotation(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing grouped annotation definitions.
+        data (Path): YAML or JSON file containing grouped annotation
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
     """

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/cli/entry.py

@@ -10,7 +10,7 @@ of an import traceback when those optional dependencies are absent.
 import importlib
 import sys
 
-CLI_DEPENDENCIES = {"jsonschema", "typer"}
+CLI_DEPENDENCIES = {"jsonschema", "typer", "yaml"}
 CLI_INSTALL_HINT = 'pipx install "PyPDFForm[cli]"'
 CLI_ENV_INSTALL_HINT = "pip install 'PyPDFForm[cli]'"
 

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/cli/root.py

@@ -8,7 +8,7 @@ commands. The root callback collects global flags in the Typer context so each
 subcommand can initialize `PdfWrapper` with consistent settings.
 
 Commands:
-    - `fill`: Fill an existing PDF form from JSON data.
+    - `fill`: Fill an existing PDF form from YAML or JSON data.
     - `create`: Create PDFs, fields, annotations, raw elements, and grid views.
     - `inspect`: Print form metadata and field data as JSON.
     - `update`: Modify PDF metadata, field names, properties, geometry, and scripts.
@@ -21,7 +21,7 @@ from typing import Annotated
 import typer
 
 from .. import PdfWrapper, Widgets, __version__
-from .common import INPUT_PDF, OPTIONAL_OUTPUT_PDF, json_file_option, load_json_file
+from .common import INPUT_PDF, OPTIONAL_OUTPUT_PDF, data_file_option, load_data_file
 from .create import create_cli
 from .inspect import inspect_cli
 from .remove import remove_cli
@@ -145,12 +145,14 @@ def main(
 
 @cli_app.command(
     no_args_is_help=True,
-    help="Fill a PDF form with JSON data.",
+    help="Fill a PDF form with YAML or JSON data.",
 )
 def fill(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field values.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field values.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
     flatten: Annotated[
         bool,
@@ -158,11 +160,11 @@ def fill(
     ] = None,
 ) -> None:
     """
-    Fill an existing PDF form from a validated JSON file.
+    Fill an existing PDF form from a validated YAML or JSON file.
 
     The command loads the input PDF with the global options stored by the root
     callback, expands the generated schema so image and signature widgets can
-    accept path objects, validates the JSON input, normalizes image and
+    accept path objects, validates the input file, normalizes image and
     signature values, and writes the filled PDF to the requested output path or
     back to the input file.
 
@@ -170,7 +172,7 @@ def fill(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF form path.
-        data (Path): JSON file containing form field values.
+        data (Path): YAML or JSON file containing form field values.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
         flatten (bool, optional): Whether to flatten form fields after filling.
@@ -196,7 +198,7 @@ def fill(
                 ]
             }
 
-    input_data = load_json_file(data, schema, "--file")
+    input_data = load_data_file(data, schema, "--file")
     for k, each in obj.widgets.items():
         if (
             k in input_data

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/cli/update.py

@@ -5,8 +5,8 @@ This module defines CLI commands for updating existing PDF files.
 It exposes the `update` command group for metadata changes, PDF version
 changes, field bounds edits, field renames, field property updates, and
 document-level JavaScript actions. Commands in this module load command-line or
-JSON input, apply the matching `PdfWrapper` operation, and write the modified
-PDF to either the requested output path or the original file.
+YAML/JSON input, apply the matching `PdfWrapper` operation, and write the
+modified PDF to either the requested output path or the original file.
 """
 
 from enum import Enum
@@ -22,10 +22,10 @@ from .common import (
     INPUT_PDF,
     OPTIONAL_OUTPUT_PDF,
     cli_bad_parameter,
+    data_file_option,
     get_widget,
     handle_font_registration,
-    json_file_option,
-    load_json_file,
+    load_data_file,
 )
 from .schemas.update import FIELD_SCHEMA, RENAME_SCHEMA
 
@@ -186,18 +186,20 @@ def bounds(
 
 @update_cli.command(
     no_args_is_help=True,
-    help="Rename form fields from JSON.",
+    help="Rename form fields from YAML or JSON.",
 )
 def rename(
     ctx: typer.Context,
     pdf: INPUT_PDF,
-    data: Annotated[Path, json_file_option("JSON file with form field renames.")],
+    data: Annotated[
+        Path, data_file_option("YAML or JSON file with form field renames.")
+    ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Rename form fields using a validated JSON mapping file.
+    Rename form fields using a validated YAML or JSON mapping file.
 
-    The command rejects full widget name mode, validates the JSON file against
+    The command rejects full widget name mode, validates the input file against
     the rename schema, resolves each existing field, queues the requested key
     updates on the `PdfWrapper`, commits the rename operations, and writes the
     modified PDF to the requested output path or back to the input file.
@@ -206,13 +208,14 @@ def rename(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing form field rename definitions.
+        data (Path): YAML or JSON file containing form field rename
+            definitions.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
 
     Raises:
         typer.BadParameter: Raised when full widget name mode is enabled, the
-            JSON file is invalid, or a requested field does not exist.
+            input file is invalid, or a requested field does not exist.
     """
     if ctx.obj.get("use_full_widget_name"):
         cli_bad_parameter(
@@ -221,7 +224,7 @@ def rename(
             param_hint="--use-full-widget-name",
         )
 
-    input_data = load_json_file(data, RENAME_SCHEMA, "--file")
+    input_data = load_data_file(data, RENAME_SCHEMA, "--file")
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     for item in input_data:
@@ -234,20 +237,20 @@ def rename(
 
 @update_cli.command(
     no_args_is_help=True,
-    help="Update form field properties from JSON.",
+    help="Update form field properties from YAML or JSON.",
 )
 def field(
     ctx: typer.Context,
     pdf: INPUT_PDF,
     data: Annotated[
-        Path, json_file_option("JSON file with form field property updates.")
+        Path, data_file_option("YAML or JSON file with form field property updates.")
     ],
     output: OPTIONAL_OUTPUT_PDF = None,
 ) -> None:
     """
-    Update form field properties from a validated JSON file.
+    Update form field properties from a validated YAML or JSON file.
 
-    The command validates the JSON input against the field update schema, loads
+    The command validates the input file 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
@@ -257,15 +260,15 @@ def field(
         ctx (typer.Context): Typer context containing global `PdfWrapper`
             options in `ctx.obj`.
         pdf (Path): Input PDF path.
-        data (Path): JSON file containing form field property updates.
+        data (Path): YAML or JSON file containing form field property updates.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
 
     Raises:
-        typer.BadParameter: Raised when the JSON file is invalid or a requested
+        typer.BadParameter: Raised when the input file is invalid or a requested
             field does not exist.
     """
-    input_data = load_json_file(data, FIELD_SCHEMA, "--file")
+    input_data = load_data_file(data, FIELD_SCHEMA, "--file")
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     registered_font = {}

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/lib/egress.py

@@ -28,6 +28,7 @@ from .constants import (
     Fields,
     JavaScript,
     OpenAction,
+    Parent,
     Root,
     S,
     Title,
@@ -140,10 +141,10 @@ def rebuild_acroform_fields(
 
     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` are added 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.
+    annotations 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.
 
     Args:
         pdf (bytes): The PDF stream whose AcroForm fields should be rebuilt.
@@ -155,25 +156,110 @@ def rebuild_acroform_fields(
         bytes: The PDF stream with a rebuilt AcroForm `/Fields` array, or the
             original stream when there are no matching widgets to rebuild.
     """
+    if not widget_keys:
+        return pdf
+
     writer = PdfWriter(BytesIO(pdf))
     root = writer._root_object  # type: ignore # noqa: SLF001 # # pylint: disable=W0212
 
-    if AcroForm not in root:
-        root[NameObject(AcroForm)] = DictionaryObject({})
-    root[AcroForm][NameObject(Fields)] = ArrayObject([])
-
-    needs_update = False
+    fields = ArrayObject([])
+    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:
-                root[AcroForm][Fields].append(annot)
-                needs_update = True
+                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 needs_update:
+    if not seen_fields:
         return pdf
 
+    if AcroForm not in root:
+        root[NameObject(AcroForm)] = DictionaryObject({})
+    root[AcroForm][NameObject(Fields)] = fields
+
     with BytesIO() as f:
         writer.write(f)
         f.seek(0)
         return f.read()
+
+
+def _get_root_field_reference(writer: PdfWriter, annot):
+    """
+    Returns the top-level AcroForm field reference for an annotation.
+
+    Widget annotations can be leaf nodes under a parent field dictionary. The
+    catalog `/AcroForm/Fields` array must point at root fields rather than
+    child widgets, otherwise readers such as pypdf will not expose hierarchical
+    fields like radio groups via `get_fields`.
+
+    Args:
+        writer (PdfWriter): The PDF writer that owns the annotation objects.
+        annot: The widget annotation reference or object.
+
+    Returns:
+        IndirectObject: The top-level AcroForm field reference.
+    """
+    field = annot
+    field_object = field.get_object()
+    visited = set()
+
+    while Parent in field_object and id(field_object) not in visited:
+        visited.add(id(field_object))
+        field = field_object[Parent]
+        field_object = field.get_object()
+
+    return _ensure_indirect_reference(writer, field)
+
+
+def _ensure_indirect_reference(writer: PdfWriter, field):
+    """
+    Returns an indirect reference for a field object.
+
+    pypdf expects entries in `/AcroForm/Fields` to have an indirect reference
+    when it builds field objects. Parent fields cloned from page annotations can
+    appear as direct dictionaries that still know their original indirect
+    reference, so prefer that before adding a new indirect object.
+
+    Args:
+        writer (PdfWriter): The PDF writer that will own newly added objects.
+        field: The field reference or direct field object to normalize.
+
+    Returns:
+        IndirectObject: An indirect reference to the field object.
+    """
+    field_object = field.get_object()
+    indirect_reference = getattr(field_object, "indirect_reference", None)
+    if indirect_reference is not None:
+        return indirect_reference
+
+    result = field
+    if not hasattr(field, "idnum"):
+        result = writer._add_object(field_object)  # type: ignore[attr-defined] # noqa: SLF001 # pylint: disable=W0212
+
+    return result
+
+
+def _field_reference_key(field_ref) -> tuple:
+    """
+    Returns a stable key for deduplicating root fields in one writer.
+
+    Args:
+        field_ref: The field reference to identify.
+
+    Returns:
+        tuple: A stable key for the field reference.
+    """
+    field_object = field_ref.get_object()
+    indirect_reference = getattr(field_object, "indirect_reference", field_ref)
+    idnum = getattr(indirect_reference, "idnum", None)
+    generation = getattr(indirect_reference, "generation", None)
+
+    result = (id(field_object),)
+    if idnum is not None:
+        result = idnum, generation
+
+    return result

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/lib/utils.py

@@ -354,16 +354,15 @@ def get_version(pdf: bytes) -> str | None:
             start with a known PDF version identifier.
     """
 
-    result = None
-    for each in VERSION_IDENTIFIERS:
-        if pdf.startswith(each):
-            result = each.replace(VERSION_IDENTIFIER_PREFIX, b"").decode()
-            break
+    version_identifier_length = len(VERSION_IDENTIFIERS[0])
+    version_identifier = pdf[:version_identifier_length]
+    if version_identifier not in VERSION_IDENTIFIERS:
+        return None
 
-    return result
+    return version_identifier[len(VERSION_IDENTIFIER_PREFIX) :].decode()
 
 
-def set_version(pdf: bytes, old: str, new: str) -> bytes:
+def set_version(pdf: bytes, old: str | None, new: str | None) -> bytes:
     """
     Replaces the first PDF header version marker in a byte stream.
 
@@ -374,15 +373,34 @@ def set_version(pdf: bytes, old: str, new: str) -> bytes:
 
     Args:
         pdf (bytes): The PDF stream to update.
-        old (str): The currently present PDF version string.
-        new (str): The PDF version string to write into the header.
+        old (str | None): The currently present PDF version string. When
+            None, the header token after `%PDF-` is replaced if one exists.
+        new (str | None): The PDF version string to write into the header. When
+            None, the PDF stream is returned unchanged.
 
     Returns:
         bytes: The PDF stream with the first matching version marker replaced.
     """
 
-    return pdf.replace(
-        VERSION_IDENTIFIER_PREFIX + bytes(old, "utf-8"),
-        VERSION_IDENTIFIER_PREFIX + bytes(new, "utf-8"),
-        1,
-    )
+    if new is None or old == new:
+        return pdf
+
+    new_header = VERSION_IDENTIFIER_PREFIX + new.encode()
+
+    if old is None:
+        if not pdf.startswith(VERSION_IDENTIFIER_PREFIX):
+            return pdf
+
+        header_end = len(pdf)
+        for separator in (b"\r", b"\n"):
+            separator_index = pdf.find(separator, len(VERSION_IDENTIFIER_PREFIX))
+            if separator_index != -1:
+                header_end = min(header_end, separator_index)
+
+        return new_header + pdf[header_end:]
+
+    old_header = VERSION_IDENTIFIER_PREFIX + old.encode()
+    if pdf.startswith(old_header):
+        return new_header + pdf[len(old_header) :]
+
+    return pdf.replace(old_header, new_header, 1)

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm/lib/wrapper.py

@@ -585,8 +585,10 @@ class PdfWrapper:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        if self.version:
-            self._stream = set_version(self._read(), self.version, version)
+        current_stream = self._read()
+        updated_stream = set_version(current_stream, self.version, version)
+        if updated_stream != current_stream:
+            self._stream = updated_stream
             self._version = version
 
         return self

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.2.4
+Version: 5.3.0
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -33,6 +33,7 @@ Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.26.1; extra == "cli"
 Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "cli"
+Requires-Dist: PyYAML<7.0.0,>=6.0.3; extra == "cli"
 Provides-Extra: dev
 Requires-Dist: coverage<8.0.0,>=7.14.1; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.2.0; extra == "dev"

{pypdfform-5.2.4 → pypdfform-5.3.0}/PyPDFForm.egg-info/requires.txt

@@ -8,6 +8,7 @@ reportlab<6.0.0,>=4.5.1
 [cli]
 typer<1.0.0,>=0.26.1
 jsonschema<5.0.0,>=4.26.0
+PyYAML<7.0.0,>=6.0.3
 
 [dev]
 coverage<8.0.0,>=7.14.1

{pypdfform-5.2.4 → pypdfform-5.3.0}/pyproject.toml

@@ -43,7 +43,11 @@ Documentation = "https://chinapandaman.github.io/PyPDFForm/"
 
 [project.optional-dependencies]
 # update `CLI_DEPENDENCIES` in `PyPDFForm/cli/entry.py` when changing cli dependencies
-cli = ["typer>=0.26.1,<1.0.0", "jsonschema>=4.26.0,<5.0.0"]
+cli = [
+    "typer>=0.26.1,<1.0.0",
+    "jsonschema>=4.26.0,<5.0.0",
+    "PyYAML>=6.0.3,<7.0.0",
+]
 dev = [
     "coverage>=7.14.1,<8.0.0",
     "mike>=2.2.0,<3.0.0",

{pypdfform-5.2.4 → pypdfform-5.3.0}/tests/test_functional.py

@@ -21,6 +21,7 @@ from PyPDFForm.lib.constants import (
 from PyPDFForm.lib.deprecation import deprecation_notice
 from PyPDFForm.lib.middleware.base import Widget
 from PyPDFForm.lib.template import get_widget_key, get_widgets_by_page
+from PyPDFForm.lib.utils import get_version, set_version
 
 
 def test_deprecation_warning():
@@ -113,10 +114,11 @@ def test_write(template_stream, tmp_path):
 
 def test_write_io(template_stream):
     buff = BytesIO()
-    PdfWrapper(template_stream).write(buff)
+    obj = PdfWrapper(template_stream)
+    obj.write(buff)
     buff.seek(0)
 
-    assert buff.read()
+    assert PdfWrapper(buff.read()).widgets.keys() == obj.widgets.keys()
 
 
 def test_fill_flatten_then_unflatten(template_stream, pdf_samples, data_dict, request):
@@ -507,7 +509,14 @@ def test_version(pdf_samples):
 
     obj = PdfWrapper(os.path.join(pdf_samples, "versions", "unknown.pdf"))
     assert obj.version is None
-    assert obj.read()
+    stream = obj.read()
+    assert stream.startswith(b"%PDF-2.1")
+    assert get_version(b"not a pdf") is None
+    assert set_version(stream, obj.version, None) == stream
+    assert set_version(b"not a pdf", None, "2.0") == b"not a pdf"
+    assert set_version(b"prefix %PDF-1.7\n", "1.7", "2.0") == b"prefix %PDF-2.0\n"
+    assert obj.change_version("2.0").version == "2.0"
+    assert obj.read().startswith(b"%PDF-2.0")
 
 
 @pytest.mark.requires_zlib_over_zlib_ng
@@ -855,7 +864,10 @@ def test_remove_fields_update_widgets(template_stream):
 
 
 def test_remove_fields_no_keys_specified(template_stream):
-    assert PdfWrapper(template_stream).remove_fields([]).read()
+    assert (
+        PdfWrapper(template_stream).remove_fields([]).widgets.keys()
+        == PdfWrapper(template_stream).widgets.keys()
+    )
 
 
 def test_merge(template_stream):