PyPDFForm 5.6.0__tar.gz → 6.0.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 5.6.0
+Version: 6.0.1
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -12,16 +12,16 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: File Formats
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Text Processing
 Classifier: Topic :: Utilities
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cryptography<51.0.0,>=50.0.0

{pypdfform-5.6.0 → pypdfform-6.0.1}/PyPDFForm/__init__.py

@@ -16,9 +16,7 @@ PyPDFForm aims to make PDF form automation straightforward whether it is used
 from Python code or from the command line.
 """
 
-import logging
-
-__version__ = "5.6.0"
+__version__ = "6.0.1"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage
@@ -28,13 +26,6 @@ from .lib.types import PdfArray
 from .lib.widgets import Fields
 from .lib.wrapper import PdfWrapper
 
-# TODO: figure out why `Annotation sizes differ:`
-for logger in [
-    logging.getLogger(name) for name in getattr(logging.root.manager, "loggerDict")
-]:
-    if "pypdf" in logger.name:
-        logger.setLevel(logging.ERROR)
-
 __all__ = [
     "PdfWrapper",
     "PdfArray",

{pypdfform-5.6.0 → pypdfform-6.0.1}/PyPDFForm/cli/root.py

@@ -108,14 +108,6 @@ def main(
             help="Generate form field appearance streams.",
         ),
     ] = False,
-    preserve_metadata: Annotated[
-        bool,
-        typer.Option(
-            "--preserve-metadata",
-            help="Preserve input PDF metadata.",
-            hidden=True,
-        ),
-    ] = False,
     use_full_widget_name: Annotated[
         bool,
         typer.Option(
@@ -138,15 +130,12 @@ def main(
             field appearances.
         generate_appearance_streams (bool): Whether to generate form field
             appearance streams while handling PDFs.
-        preserve_metadata (bool): Deprecated compatibility option. Input PDF
-            metadata is preserved automatically.
         use_full_widget_name (bool): Whether widget lookups should use full
             form field names.
     """
     ctx.obj = {
         "need_appearances": need_appearances,
         "generate_appearance_streams": generate_appearance_streams,
-        "preserve_metadata": preserve_metadata,
         "use_full_widget_name": use_full_widget_name,
     }
 
@@ -163,10 +152,6 @@ def fill(
         Path | None, data_file_option("YAML or JSON file with form field values.")
     ] = None,
     output: OPTIONAL_OUTPUT_PDF = None,
-    flatten: Annotated[
-        bool,
-        typer.Option("--flatten", help="Deprecated alias for --readonly.", hidden=True),
-    ] = None,
     readonly: Annotated[
         bool,
         typer.Option("--readonly", help="Make form fields read-only when filling."),
@@ -191,9 +176,8 @@ def fill(
             options in ``ctx.args``. Defaults to None.
         output (Path, optional): Output PDF path. If omitted, the input PDF is
             overwritten. Defaults to None.
-        flatten (bool, optional): Deprecated alias for `readonly`. Defaults to None.
         readonly (bool): Whether to make form fields read-only when filling.
-            Defaults to False. Either `readonly` or `flatten` enables read-only fields.
+            Defaults to False.
     """
     obj = PdfWrapper(str(pdf), **ctx.obj)
 
@@ -231,4 +215,4 @@ def fill(
             )
             input_data[k] = input_data[k]["path"]
 
-    obj.fill(input_data, readonly=readonly, flatten=flatten).write(output or pdf)
+    obj.fill(input_data, readonly=readonly).write(output or pdf)

{pypdfform-5.6.0 → pypdfform-6.0.1}/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
@@ -382,8 +383,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 +396,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-5.6.0 → pypdfform-6.0.1}/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-5.6.0 → pypdfform-6.0.1}/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-5.6.0 → pypdfform-6.0.1}/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

{pypdfform-5.6.0 → pypdfform-6.0.1}/PyPDFForm/lib/middleware/dropdown.py

@@ -6,9 +6,9 @@ This module defines the Dropdown class, which is a subclass of the
 Widget class. It represents a dropdown form field in a PDF document.
 """
 
-from typing import Optional
+from typing import Any, Optional
 
-from .base import Widget
+from .base import PreparedValue, Widget
 
 
 class Dropdown(Widget):
@@ -18,7 +18,7 @@ class Dropdown(Widget):
     Inherits from the Widget class and provides specific functionality
     for handling dropdown form fields. The stored value is an option index; string
     assignments are normalized to an existing option index or appended as a new
-    choice.
+    choice. Integer indices must identify an existing option.
 
     Key attributes:
         font (str): The font of the dropdown field.
@@ -81,21 +81,92 @@ class Dropdown(Widget):
 
         If the value is a string, it attempts to find the corresponding
         index in the choices list. If not found, the string value is
-        added to the choices, and its new index is used. Integer values are stored
-        directly as indices.
+        added to the choices, and its new index is used. Integer values are checked
+        against the current choices before being stored.
 
         Args:
             value (str | int): The value to set. Can be a string
                                       (option text) or an integer (index).
+
+        Raises:
+            ValueError: If an integer index is outside the current choices.
+        """
+        self.apply_value(self.prepare_value(value))
+
+    def prepare_value(self, value: Any) -> PreparedValue:
         """
+        Prepares a dropdown selection without changing its value or choices.
+
+        Integer indices are checked against the current choices. Strings are
+        normalized to an existing index or staged as a new last option. New
+        choices do not trigger hooks until the prepared selection is applied.
+
+        Args:
+            value (Any): The proposed option text or index.
+
+        Returns:
+            PreparedValue: The selected index and any replacement choices.
+
+        Raises:
+            ValueError: If an integer index is outside the current choices.
+        """
+        self.validate_choice_index(value)
         if isinstance(value, str):
             index = self._get_option_index(value)
             if index is None:
-                self.choices = list(self.choices) + [value]
-                index = len(self.choices) - 1
+                choices = list(self.choices) + [value]
+                return PreparedValue(len(choices) - 1, choices)
             value = index
 
-        self._value = value
+        return super().prepare_value(value)
+
+    def apply_value(self, update: PreparedValue) -> None:
+        """
+        Applies a previously prepared dropdown selection.
+
+        Replacement choices are stored through the existing attribute setter
+        so their PDF update hook is queued before the selected index is stored.
+        Validation and option lookup are not repeated during application.
+
+        Args:
+            update (PreparedValue): The prepared selection and optional choices.
+        """
+        if update.choices is not None:
+            self.choices = update.choices
+        super().apply_value(update)
+
+    def choice_index_schema(self) -> dict:
+        """
+        Returns the schema definition for indices into the current choices.
+
+        Valid indices range from zero to the number of choices minus one. An
+        empty dropdown explicitly rejects every integer selection.
+
+        Returns:
+            dict: A dictionary representing the schema definition for indices.
+        """
+        number_of_options = len(self.choices or [])
+        if not number_of_options:
+            return {"type": "integer", "not": {}}
+        return {"type": "integer", "minimum": 0, "maximum": number_of_options - 1}
+
+    def validate_choice_index(self, value: object) -> None:
+        """
+        Validates an integer selection against the current dropdown choices.
+
+        Non-integer values retain their existing handling, including strings
+        normalized during preparation and None for an unset selection.
+
+        Args:
+            value (object): The proposed value of the dropdown.
+
+        Raises:
+            ValueError: If an integer index is outside the current choices.
+        """
+        number_of_options = len(self.choices or [])
+        if isinstance(value, int) and not 0 <= value < number_of_options:
+            msg = f"Choice index {value} must satisfy 0 <= index < {number_of_options}."
+            raise ValueError(msg)
 
     def _get_option_index(self, value: str) -> int | None:
         """
@@ -128,8 +199,7 @@ class Dropdown(Widget):
         return {
             "anyOf": [
                 {
-                    "type": "integer",
-                    "maximum": len(self.choices) - 1,
+                    **self.choice_index_schema(),
                     **super().schema_definition,
                 },
                 {"type": "string"},
@@ -137,14 +207,15 @@ class Dropdown(Widget):
         }
 
     @property
-    def sample_value(self) -> int:
+    def sample_value(self) -> int | None:
         """
         Returns a sample value for the dropdown.
 
         The sample value is used to generate example data for the
-        dropdown field. It selects the last available option.
+        dropdown field. It selects the last available option, or returns None
+        when no choices are available so sample data can omit the field.
 
         Returns:
-            int: A sample value for the dropdown.
+            int | None: The last option index, or None when there are no choices.
         """
-        return len(self.choices) - 1
+        return len(self.choices) - 1 if self.choices else None

pypdfform-6.0.1/PyPDFForm/lib/middleware/radio.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""
+Module representing a radio button widget.
+
+This module defines the Radio class, which is a subclass of the
+Checkbox class. It represents a radio button form field in a PDF
+document, allowing users to select one option from a group of choices.
+"""
+
+from typing import Any
+
+from .base import PreparedValue
+from .checkbox import Checkbox
+
+
+class Radio(Checkbox):
+    """
+    Represents a radio button widget.
+
+    The Radio class provides a concrete implementation for radio button
+    form fields. It inherits from the Checkbox class and implements
+    the schema_definition and sample_value properties.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        value: int = None,
+    ) -> None:
+        """
+        Initializes a radio button widget.
+
+        Args:
+            name (str): The name of the radio button.
+            value (int): The initial value of the radio button. Defaults to None.
+
+        Attributes:
+            number_of_options (int): The number of options for the radio button.
+        """
+        super().__init__(name, value)
+
+        self.number_of_options: int = 0
+
+    def prepare_value(self, value: Any) -> PreparedValue:
+        """
+        Prepares a radio selection without changing the current value.
+
+        Integer indices are checked against the current option count. The
+        inherited value setter and PDF filling use this same preparation step.
+
+        Args:
+            value (Any): The proposed index of the option to select.
+
+        Returns:
+            PreparedValue: The selection to apply after validation succeeds.
+
+        Raises:
+            ValueError: If an integer index is outside the current options.
+        """
+        self.validate_choice_index(value)
+        return super().prepare_value(value)
+
+    def choice_index_schema(self) -> dict:
+        """
+        Returns the schema definition for indices into the current radio group.
+
+        Valid indices range from zero to the option count minus one. A group
+        with no options explicitly rejects every integer selection.
+
+        Returns:
+            dict: A dictionary representing the schema definition for indices.
+        """
+        if self.number_of_options <= 0:
+            return {"type": "integer", "not": {}}
+        return {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": self.number_of_options - 1,
+        }
+
+    def validate_choice_index(self, value: object) -> None:
+        """
+        Validates an integer selection against the current radio option count.
+
+        Non-integer values retain their existing handling, including None for
+        an unset selection. Broader value-type validation is left to callers.
+
+        Args:
+            value (object): The proposed value of the radio button group.
+
+        Raises:
+            ValueError: If an integer index is outside the current options.
+        """
+        if isinstance(value, int) and not 0 <= value < self.number_of_options:
+            msg = f"Choice index {value} must satisfy 0 <= index < {self.number_of_options}."
+            raise ValueError(msg)
+
+    @property
+    def schema_definition(self) -> dict:
+        """
+        Returns the schema definition for the radio button.
+
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the radio button value,
+        which is expected to be an integer representing the index
+        of the selected option.
+
+        Returns:
+            dict: A dictionary representing the schema definition.
+        """
+        return {
+            **super().schema_definition,
+            **self.choice_index_schema(),
+        }
+
+    @property
+    def sample_value(self) -> int | None:
+        """
+        Returns a sample value for the radio button.
+
+        The sample value is used to generate example data for the
+        radio button field. It returns the index of the last option
+        in the group, or None when no options are available so sample data can
+        omit the field.
+
+        Returns:
+            int | None: The last option index, or None when there are no options.
+        """
+        return self.number_of_options - 1 if self.number_of_options > 0 else None

{pypdfform-5.6.0 → pypdfform-6.0.1}/PyPDFForm/lib/middleware/text.py

@@ -89,7 +89,7 @@ class Text(Widget):
         Args:
             value (str): The value to set.
         """
-        self._value = value
+        self.apply_value(self.prepare_value(value))
 
     @property
     def schema_definition(self) -> dict: