PyPDFForm 2.5.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

PyPDFForm/wrapper.py

@@ -1,43 +1,43 @@
 # -*- coding: utf-8 -*-
-"""Provides high-level wrapper classes for working with PDF forms.
-
-This module contains the FormWrapper and PdfWrapper classes which provide
-a user-friendly interface for:
-- Filling PDF form fields
-- Creating and modifying PDF form widgets
-- Drawing text and images on PDFs
-- Merging PDF documents
-- Generating coordinate grids
-- Other PDF manipulation tasks
-
-The wrappers handle low-level PDF operations while exposing simple methods
-for common use cases.
+"""
+A module for wrapping PDF form operations, providing a high-level interface
+for filling, creating, and manipulating PDF forms.
+
+This module simplifies common tasks such as:
+- Filling PDF forms with data from a dictionary.
+- Creating new form fields (widgets) on a PDF.
+- Drawing text and images onto a PDF.
+- Registering custom fonts for use in form fields.
+- Merging multiple PDF forms.
+
+The core class, `PdfWrapper`, encapsulates a PDF document and provides
+methods for interacting with its form fields and content. It leverages
+lower-level modules within the `PyPDFForm` library to handle the
+underlying PDF manipulation.
 """
 
 from __future__ import annotations
 
 from functools import cached_property
-from typing import BinaryIO, Dict, List, Tuple, Union
+from typing import BinaryIO, Dict, List, Sequence, Tuple, Union
 
 from .adapter import fp_or_f_obj_or_stream_to_stream
 from .constants import (DEFAULT_FONT, DEFAULT_FONT_COLOR, DEFAULT_FONT_SIZE,
-                        NEW_LINE_SYMBOL, VERSION_IDENTIFIER_PREFIX,
-                        VERSION_IDENTIFIERS)
+                        VERSION_IDENTIFIER_PREFIX, VERSION_IDENTIFIERS)
 from .coordinate import generate_coordinate_grid
-from .filler import fill, simple_fill
-from .font import register_font
+from .filler import fill
+from .font import (get_all_available_fonts, register_font,
+                   register_font_acroform)
 from .hooks import trigger_widget_hooks
 from .image import rotate_image
 from .middleware.dropdown import Dropdown
+from .middleware.signature import Signature
 from .middleware.text import Text
-from .template import (build_widgets, dropdown_to_text,
-                       set_character_x_paddings, update_text_field_attributes,
-                       update_widget_keys)
-from .utils import (generate_unique_suffix, get_page_streams, merge_two_pdfs,
-                    preview_widget_to_draw, remove_all_widgets)
+from .template import build_widgets, update_widget_keys
+from .utils import (enable_adobe_mode, generate_unique_suffix,
+                    get_page_streams, merge_two_pdfs, remove_all_widgets)
 from .watermark import (copy_watermark_widgets, create_watermarks_and_draw,
                         merge_watermarks_with_pdf)
-from .widgets.base import handle_non_acro_form_params
 from .widgets.checkbox import CheckBoxWidget
 from .widgets.dropdown import DropdownWidget
 from .widgets.image import ImageWidget
@@ -46,272 +46,198 @@ from .widgets.signature import SignatureWidget
 from .widgets.text import TextWidget
 
 
-class FormWrapper:
-    """Base class providing core PDF form filling functionality.
+class PdfWrapper:
+    """
+    A class to wrap PDF form operations, providing a simplified interface
+    for common tasks such as filling, creating, and manipulating PDF forms.
 
-    This wrapper handles basic PDF form operations:
-    - Accessing raw PDF data through the read() method
-    - Filling existing form fields with provided values
+    The `PdfWrapper` class encapsulates a PDF document and provides methods
+    for interacting with its form fields (widgets) and content. It leverages
+    lower-level modules within the `PyPDFForm` library to handle the
+    underlying PDF manipulation.
 
-    Note: This class does not parse or analyze form fields - it only fills values
-    into fields that already exist in the template PDF.
+    Attributes:
+        USER_PARAMS (list): A list of user-configurable parameters and their default values.
+            These parameters can be set during initialization using keyword arguments.
+            Current parameters include:
+                - `use_full_widget_name` (bool): Whether to use the full widget name when filling the form.
+                - `adobe_mode` (bool): Whether to enable Adobe-specific compatibility mode.
 
-    The FormWrapper is designed to be extended by PdfWrapper which adds
-    more advanced features like form analysis and widget creation.
     """
 
+    USER_PARAMS = [
+        ("use_full_widget_name", False),
+        ("adobe_mode", False),
+    ]
+
     def __init__(
         self,
         template: Union[bytes, str, BinaryIO] = b"",
         **kwargs,
     ) -> None:
-        """Initializes the base form wrapper with a PDF template.
-
-        Args:
-            template: PDF form as bytes, file path, or file object. Defaults to
-                empty bytes if not provided.
-            **kwargs: Additional options:
-                use_full_widget_name: If True, uses complete widget names including
-                    field hierarchy (default: False)
+        """
+        Constructor method for the `PdfWrapper` class.
 
-        Initializes:
-            - Internal PDF stream from the template
-            - Basic form filling capabilities
-            - Widget naming configuration from kwargs
+        Initializes a new `PdfWrapper` object with the given template PDF and optional keyword arguments.
 
-        Note:
-            This base class is designed to be extended by PdfWrapper which adds
-            more advanced features. For most use cases, you'll want to use PdfWrapper.
+        Args:
+            template (Union[bytes, str, BinaryIO]): The template PDF, provided as either:
+                - bytes: The raw PDF data as a byte string.
+                - str: The file path to the PDF.
+                - BinaryIO: An open file-like object containing the PDF data.
+                Defaults to an empty byte string (b""), which creates a blank PDF.
+            **kwargs: Additional keyword arguments to configure the `PdfWrapper`.
+                These arguments are used to set the user-configurable parameters defined in `USER_PARAMS`.
+                For example: `use_full_widget_name=True` or `adobe_mode=False`.
         """
 
         super().__init__()
         self._stream = fp_or_f_obj_or_stream_to_stream(template)
-        self.use_full_widget_name = kwargs.get("use_full_widget_name", False)
+        self.widgets = {}
+        self._available_fonts = {}  # for setting /F1
+        self._font_register_events = []  # for reregister
+        self._key_update_tracker = {}  # for update key preserve old key attrs
+        self._keys_to_update = []  # for bulk update keys
 
-    def read(self) -> bytes:
-        """Returns the raw bytes of the PDF form data.
+        # sets attrs from kwargs
+        for attr, default in self.USER_PARAMS:
+            setattr(self, attr, kwargs.get(attr, default))
 
-        This method provides access to the underlying PDF bytes after operations
-        like fill() have been performed. No parsing or analysis of the PDF
-        content is done - the bytes are returned as-is.
+        self._init_helper()
 
-        Returns:
-            bytes: The complete PDF document as a byte string
+    def __add__(self, other: PdfWrapper) -> PdfWrapper:
         """
+        Merges two PDF wrappers together, creating a new `PdfWrapper` containing the combined content.
 
-        return self._stream
-
-    def fill(
-        self,
-        data: Dict[str, Union[str, bool, int]],
-        **kwargs,
-    ) -> FormWrapper:
-        """Fills form fields in the PDF with provided values.
-
-        Takes a dictionary of field names to values and updates the corresponding
-        form fields in the PDF. Supports these value types:
-            - Strings for text fields
-            - Booleans for checkboxes (True=checked, False=unchecked)
-            - Integers for numeric fields and dropdown selections
-
-        Only fields that exist in the template PDF will be filled - unknown field
-        names are silently ignored.
+        This method allows you to combine two PDF forms into a single form.  It handles potential
+        naming conflicts between form fields by adding a unique suffix to the field names in the second form.
 
         Args:
-            data: Dictionary mapping field names to values. Supported types:
-                str: For text fields
-                bool: For checkboxes (True=checked)
-                int: For numeric fields and dropdown selections
-            **kwargs: Additional options:
-                flatten (bool): If True, makes form fields read-only after filling
-                    (default: False)
-                adobe_mode (bool): If True, uses Adobe-compatible filling logic
-                    (default: False)
+            other (PdfWrapper): The other `PdfWrapper` object to merge with.
 
         Returns:
-            FormWrapper: Returns self to allow method chaining
+            PdfWrapper: A new `PdfWrapper` object containing the merged PDFs.
         """
 
-        widgets = (
-            build_widgets(self.read(), self.use_full_widget_name, False)
-            if self.read()
-            else {}
-        )
-
-        for key, value in data.items():
-            if key in widgets:
-                widgets[key].value = value
-
-        self._stream = simple_fill(
-            self.read(),
-            widgets,
-            use_full_widget_name=self.use_full_widget_name,
-            flatten=kwargs.get("flatten", False),
-            adobe_mode=kwargs.get("adobe_mode", False),
-        )
-
-        return self
-
-
-class PdfWrapper(FormWrapper):
-    """Extended PDF form wrapper with advanced features.
-
-    Inherits from FormWrapper and adds capabilities for:
-    - Creating and modifying form widgets
-    - Drawing text and images
-    - Merging PDF documents
-    - Generating coordinate grids
-    - Form schema generation
-    - Font registration
-
-    Key Features:
-    - Maintains widget state and properties
-    - Supports per-page operations
-    - Handles PDF version management
-    - Provides preview functionality
-    """
-
-    USER_PARAMS = [
-        ("global_font", None),
-        ("global_font_size", None),
-        ("global_font_color", None),
-        ("use_full_widget_name", False),
-        ("render_widgets", True),
-    ]
-    # TODO: remove, always default to True
-    TRIGGER_WIDGET_HOOKS = False
+        if not self.read():
+            return other
 
-    def __init__(
-        self,
-        template: Union[bytes, str, BinaryIO] = b"",
-        **kwargs,
-    ) -> None:
-        """Initializes the PDF wrapper with template and configuration.
+        if not other.read():
+            return self
 
-        Args:
-            template: PDF form as bytes, file path, or file object. Defaults to
-                empty bytes if not provided.
-            **kwargs: Optional configuration parameters including:
-                global_font: Default font name for text fields
-                global_font_size: Default font size
-                global_font_color: Default font color as RGB tuple
-                use_full_widget_name: Whether to use full widget names
-                render_widgets: Whether to render widgets in the PDF
-
-        Initializes:
-            - Widgets dictionary to track form fields
-            - Keys update queue for deferred operations
-            - Any specified global settings from kwargs
-        """
-
-        super().__init__(template)
-        self.widgets = {}
-        self._keys_to_update = []
+        unique_suffix = generate_unique_suffix()
+        for k in self.widgets:
+            if k in other.widgets:
+                other.update_widget_key(k, f"{k}-{unique_suffix}", defer=True)
 
-        for attr, default in self.USER_PARAMS:
-            setattr(self, attr, kwargs.get(attr, default))
+        other.commit_widget_key_updates()
 
-        self._init_helper()
+        # user params are based on the first object
+        result = self.__class__(
+            merge_two_pdfs(self.read(), other.read()),
+            **{each[0]: getattr(self, each[0], each[1]) for each in self.USER_PARAMS},
+        )
 
-    def _init_helper(self, key_to_refresh: str = None) -> None:
-        """Internal method to refresh widget state after PDF stream changes.
+        # inherit fonts
+        for event in self._font_register_events:
+            result.register_font(event[0], event[1])
 
-        Called whenever the underlying PDF stream is modified to:
-        - Rebuild the widgets dictionary
-        - Preserve existing widget properties
-        - Apply global font settings to text widgets
-        - Handle special refresh cases for specific widgets
+        return result
 
-        Args:
-            key_to_refresh: Optional specific widget key that needs refreshing.
-                If provided, only that widget's font properties will be updated.
-                If None, all text widgets will have their fonts updated.
+    def _init_helper(self) -> None:
+        """
+        Helper method to initialize widgets and available fonts.
 
-        Note:
-            This is an internal method and typically shouldn't be called directly.
-            It's automatically invoked after operations that modify the PDF stream.
+        This method is called during initialization and after certain operations
+        that modify the PDF content (e.g., filling, creating widgets, updating keys).
+        It rebuilds the widget dictionary and updates the available fonts.
         """
 
-        refresh_not_needed = {}
         new_widgets = (
             build_widgets(
                 self.read(),
                 getattr(self, "use_full_widget_name"),
-                getattr(self, "render_widgets"),
             )
             if self.read()
             else {}
         )
+        # ensure old widgets don't get overwritten
         for k, v in self.widgets.items():
             if k in new_widgets:
                 new_widgets[k] = v
-                refresh_not_needed[k] = True
+
+        # update key preserve old key attrs
+        for k, v in new_widgets.items():
+            if k in self._key_update_tracker:
+                for name, value in self.widgets[
+                    self._key_update_tracker[k]
+                ].__dict__.items():
+                    if not name.startswith("_"):
+                        setattr(v, name, value)
+        self._key_update_tracker = {}
+
         self.widgets = new_widgets
 
-        for key, value in self.widgets.items():
-            if (key_to_refresh and key == key_to_refresh) or (
-                key_to_refresh is None
-                and isinstance(value, Text)
-                and not refresh_not_needed.get(key)
-            ):
-                value.font = getattr(self, "global_font")
-                value.font_size = getattr(self, "global_font_size")
-                value.font_color = getattr(self, "global_font_color")
+        if self.read():
+            self._available_fonts.update(**get_all_available_fonts(self.read()))
 
-    def read(self) -> bytes:
-        """Returns the raw bytes of the PDF form data with optional widget hook processing.
+    def _reregister_font(self) -> PdfWrapper:
+        """
+        Reregisters fonts after PDF content modifications.
+
+        This method is called after operations that modify the PDF content
+        (e.g., drawing text, drawing images) to ensure that custom fonts
+        are correctly registered and available for use.
+        """
 
-        Extends FormWrapper.read() with additional functionality:
-        - Triggers any registered widget hooks if TRIGGER_WIDGET_HOOKS is True
-        - Maintains all parent class behavior of returning raw PDF bytes
+        font_register_events_len = len(self._font_register_events)
+        for i in range(font_register_events_len):
+            event = self._font_register_events[i]
+            self.register_font(event[0], event[1], False)
+        self._font_register_events = self._font_register_events[
+            font_register_events_len:
+        ]
 
-        The method first processes any widget hooks that need triggering, then delegates
-        to the parent class's read() implementation to return the PDF bytes.
+        return self
 
-        Returns:
-            bytes: The complete PDF document as a byte string, after any hook processing
+    @property
+    def schema(self) -> dict:
         """
+        Returns the JSON schema of the PDF form, describing the structure and data types of the form fields.
 
-        if self.TRIGGER_WIDGET_HOOKS and any(
-            widget.hooks_to_trigger for widget in self.widgets.values()
-        ):
-            self._stream = trigger_widget_hooks(
-                self._stream,
-                self.widgets,
-                getattr(self, "use_full_widget_name"),
-            )
+        This schema can be used to generate user interfaces or validate data before filling the form.
 
-        return super().read()
+        Returns:
+            dict: A dictionary representing the JSON schema of the PDF form.
+        """
+
+        return {
+            "type": "object",
+            "properties": {
+                key: value.schema_definition for key, value in self.widgets.items()
+            },
+        }
 
     @property
     def sample_data(self) -> dict:
-        """Generates a dictionary of sample values for all form fields.
+        """
+        Returns sample data for the PDF form, providing example values for each form field.
 
-        Returns a dictionary mapping each widget/field name to an appropriate
-        sample value based on its type:
-        - Text fields: Field name (truncated if max_length specified)
-        - Checkboxes: True
-        - Dropdowns: Index of last available choice
-        - Other fields: Type-specific sample values
+        This sample data can be used for testing or demonstration purposes.
 
         Returns:
-            dict: Field names mapped to their sample values
+            dict: A dictionary containing sample data for the PDF form.
         """
 
         return {key: value.sample_value for key, value in self.widgets.items()}
 
     @property
     def version(self) -> Union[str, None]:
-        """Gets the PDF version number from the document header.
-
-        The version is extracted from the PDF header which contains a version
-        identifier like '%PDF-1.4'. This method returns just the version number
-        portion (e.g. '1.4') if found, or None if no valid version identifier
-        is present.
+        """
+        Returns the PDF version of the underlying PDF document.
 
         Returns:
-            str: The PDF version number (e.g. '1.4') if found
-            None: If no valid version identifier exists in the PDF
+            Union[str, None]: The PDF version as a string, or None if the version cannot be determined.
         """
 
         for each in VERSION_IDENTIFIERS:
@@ -320,22 +246,29 @@ class PdfWrapper(FormWrapper):
 
         return None
 
-    @cached_property
-    def pages(self) -> List[PdfWrapper]:
-        """Returns individual page wrappers for each page in the PDF.
+    @property
+    def fonts(self) -> list:
+        """
+        Returns a list of the names of the currently registered fonts.
 
-        Creates a separate PdfWrapper instance for each page, maintaining all
-        the original wrapper's settings (fonts, rendering options etc.). This
-        allows per-page operations while preserving the parent's configuration.
+        Returns:
+            list: A list of font names (str).
+        """
 
-        The result is cached after first access for better performance with
-        repeated calls.
+        return list(self._available_fonts.keys())
+
+    @cached_property
+    def pages(self) -> Sequence[PdfWrapper]:
+        """
+        Returns a sequence of `PdfWrapper` objects, each representing a single page in the PDF document.
+
+        This allows you to work with individual pages of the PDF, for example, to extract text or images from a specific page.
 
         Returns:
-            List[PdfWrapper]: List of wrapper objects, one per page
+            Sequence[PdfWrapper]: A sequence of `PdfWrapper` objects, one for each page in the PDF.
         """
 
-        return [
+        result = [
             self.__class__(
                 copy_watermark_widgets(each, self.read(), None, i),
                 **{param: getattr(self, param) for param, _ in self.USER_PARAMS},
@@ -343,113 +276,109 @@ class PdfWrapper(FormWrapper):
             for i, each in enumerate(get_page_streams(remove_all_widgets(self.read())))
         ]
 
-    def change_version(self, version: str) -> PdfWrapper:
-        """Changes the PDF version identifier in the document header.
+        # because copy_watermark_widgets and remove_all_widgets
+        if self._font_register_events:
+            for event in self._font_register_events:
+                for page in result:
+                    page.register_font(event[0], event[1])
 
-        Modifies the version header (e.g. '%PDF-1.4') to match the specified version.
-        Note this only changes the version identifier, not the actual PDF features used.
+        return result
 
-        Args:
-            version: Target version string (e.g. '1.4', '1.7')
+    def read(self) -> bytes:
+        """
+        Reads the PDF content from the underlying stream.
+
+        This method returns the current state of the PDF as a byte string.
+        It also triggers any pending widget hooks and applies Adobe mode if enabled.
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
+            bytes: The PDF content as bytes.
         """
 
-        self._stream = self.read().replace(
-            VERSION_IDENTIFIER_PREFIX + bytes(self.version, "utf-8"),
-            VERSION_IDENTIFIER_PREFIX + bytes(version, "utf-8"),
-            1,
-        )
+        if any(widget.hooks_to_trigger for widget in self.widgets.values()):
+            for widget in self.widgets.values():
+                if (
+                    isinstance(widget, (Text, Dropdown))
+                    and widget.font not in self._available_fonts.values()
+                    and widget.font in self._available_fonts
+                ):
+                    widget.font = self._available_fonts.get(
+                        widget.font
+                    )  # from `new_font` to `/F1`
 
-        return self
+            self._stream = trigger_widget_hooks(
+                self._stream,
+                self.widgets,
+                getattr(self, "use_full_widget_name"),
+            )
 
-    def __add__(self, other: PdfWrapper) -> PdfWrapper:
-        """Merges two PDF forms together using the + operator.
+        if getattr(self, "adobe_mode") and self._stream:
+            self._stream = enable_adobe_mode(self._stream)  # cached
 
-        Combines the content of both PDF forms while:
-        - Preserving each form's widgets and data
-        - Adding unique suffixes to duplicate field names
-        - Maintaining all page content and ordering
+        return self._stream
+
+    def write(self, path: str) -> PdfWrapper:
+        """
+        Writes the PDF content to a file.
 
         Args:
-            other: Another PdfWrapper instance to merge with
+            path (str): The file path to write the PDF to.
 
         Returns:
-            PdfWrapper: New wrapper containing merged PDF
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        if not self.read():
-            return other
+        with open(path, "wb+") as f:
+            f.write(self.read())
 
-        if not other.read():
-            return self
-
-        unique_suffix = generate_unique_suffix()
-        for k in self.widgets:
-            if k in other.widgets:
-                other.update_widget_key(k, f"{k}-{unique_suffix}", defer=True)
-
-        other.commit_widget_key_updates()
-
-        return self.__class__(merge_two_pdfs(self.read(), other.read()))
+        return self
 
-    @property
-    def preview(self) -> bytes:
-        """Generates a preview PDF showing widget names above their locations.
+    def change_version(self, version: str) -> PdfWrapper:
+        """
+        Changes the PDF version of the underlying document.
 
-        Creates a modified version of the PDF where:
-        - All form widgets are removed
-        - Widget names are drawn slightly above their original positions
-        - Helps visualize form field locations without interactive widgets
+        Args:
+            version (str): The new PDF version string (e.g., "1.7").
 
         Returns:
-            bytes: PDF bytes containing the preview annotations
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        return remove_all_widgets(
-            fill(
-                self.read(),
-                {
-                    key: preview_widget_to_draw(key, value, True)
-                    for key, value in self.widgets.items()
-                },
-                getattr(self, "use_full_widget_name"),
-            )
+        self._stream = self.read().replace(
+            VERSION_IDENTIFIER_PREFIX + bytes(self.version, "utf-8"),
+            VERSION_IDENTIFIER_PREFIX + bytes(version, "utf-8"),
+            1,
         )
 
+        return self
+
     def generate_coordinate_grid(
         self, color: Tuple[float, float, float] = (1, 0, 0), margin: float = 100
     ) -> PdfWrapper:
-        """Generates a coordinate grid overlay for the PDF.
-
-        Creates a visual grid showing x,y coordinates to help with:
-        - Precise widget placement
-        - Measuring distances between elements
-        - Debugging layout issues
+        """
+        Generates a coordinate grid on the PDF, useful for debugging layout issues.
 
         Args:
-            color: RGB tuple (0-1 range) for grid line color (default: red)
-            margin: Spacing between grid lines in PDF units (default: 100)
+            color (Tuple[float, float, float]): The color of the grid lines, specified as an RGB tuple (default: red).
+            margin (float): The margin around the grid, in points (default: 100).
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
-        """
-
-        self._stream = generate_coordinate_grid(
-            remove_all_widgets(
-                fill(
-                    self.read(),
-                    {
-                        key: preview_widget_to_draw(key, value, False)
-                        for key, value in self.widgets.items()
-                    },
-                    getattr(self, "use_full_widget_name"),
-                )
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
+        """
+
+        stream_with_widgets = self.read()
+        self._stream = copy_watermark_widgets(
+            generate_coordinate_grid(
+                remove_all_widgets(self.read()),
+                color,
+                margin,
             ),
-            color,
-            margin,
+            stream_with_widgets,
+            None,
+            None,
         )
+        # because copy_watermark_widgets and remove_all_widgets
+        self._reregister_font()
 
         return self
 
@@ -458,40 +387,45 @@ class PdfWrapper(FormWrapper):
         data: Dict[str, Union[str, bool, int]],
         **kwargs,
     ) -> PdfWrapper:
-        """Fills form fields while preserving widget properties and positions.
-
-        Extends FormWrapper.fill() with additional features:
-        - Maintains widget properties like fonts and styles
-        - Converts dropdowns to text fields while preserving choices
-        - Updates text field attributes and character spacing
+        """
+        Fills the PDF form with data from a dictionary.
 
         Args:
-            data: Dictionary mapping field names to values (str, bool or int)
-            **kwargs: Currently unused, maintained for future compatibility
+            data (Dict[str, Union[str, bool, int]]): A dictionary where keys are form field names
+                and values are the data to fill the fields with.  Values can be strings, booleans, or integers.
+            **kwargs: Additional keyword arguments:
+                - `flatten` (bool): Whether to flatten the form after filling, making the fields read-only (default: False).
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
         for key, value in data.items():
             if key in self.widgets:
                 self.widgets[key].value = value
 
-        for key, value in self.widgets.items():
-            if isinstance(value, Dropdown):
-                self.widgets[key] = dropdown_to_text(value)
-
-        update_text_field_attributes(
-            self.read(), self.widgets, getattr(self, "use_full_widget_name")
+        filled_stream, image_drawn_stream = fill(
+            self.read(),
+            self.widgets,
+            use_full_widget_name=getattr(self, "use_full_widget_name"),
+            flatten=kwargs.get("flatten", False),
         )
-        if self.read():
-            self.widgets = set_character_x_paddings(
-                self.read(), self.widgets, getattr(self, "use_full_widget_name")
+
+        if image_drawn_stream is not None:
+            keys_to_copy = [
+                k for k, v in self.widgets.items() if not isinstance(v, Signature)
+            ]  # only copy non-image fields
+            filled_stream = copy_watermark_widgets(
+                remove_all_widgets(image_drawn_stream),
+                filled_stream,
+                keys_to_copy,
+                None,
             )
 
-        self._stream = remove_all_widgets(
-            fill(self.read(), self.widgets, getattr(self, "use_full_widget_name"))
-        )
+        self._stream = filled_stream
+        if image_drawn_stream is not None:
+            # because copy_watermark_widgets and remove_all_widgets
+            self._reregister_font()
 
         return self
 
@@ -505,35 +439,26 @@ class PdfWrapper(FormWrapper):
         **kwargs,
     ) -> PdfWrapper:
         """
-        Creates a new interactive widget (form field) on the PDF.
-
-        Supported widget types:
-            - "text": Text input field
-            - "checkbox": Checkbox field
-            - "dropdown": Dropdown/combobox field
-            - "radio": Radio button field
-            - "signature": Signature field
-            - "image": Image field
+        Creates a new form field (widget) on the PDF.
 
         Args:
-            widget_type (str): Type of widget to create. Must be one of:
-                "text", "checkbox", "dropdown", "radio", "signature", or "image".
-            name (str): Unique name/identifier for the widget.
-            page_number (int): 1-based page number to add the widget to.
-            x (float or List[float]): X coordinate(s) for widget position.
-            y (float or List[float]): Y coordinate(s) for widget position.
-            **kwargs: Additional widget-specific parameters:
-                For text fields: width, height, font, font_size, etc.
-                For checkboxes: size, checked, etc.
-                For dropdowns: choices, default_index, etc.
-                For signature/image: width, height, etc.
+            widget_type (str): The type of widget to create.  Valid values are:
+                - "text": A text field.
+                - "checkbox": A checkbox field.
+                - "dropdown": A dropdown field.
+                - "radio": A radio button field.
+                - "signature": A signature field.
+                - "image": An image field.
+            name (str): The name of the widget.  This name will be used to identify the widget when filling the form.
+            page_number (int): The page number to create the widget on (1-based).
+            x (Union[float, List[float]]): The x coordinate(s) of the widget.
+                If a list is provided, it specifies the x coordinates of multiple instances of the widget.
+            y (Union[float, List[float]]): The y coordinate(s) of the widget.
+                If a list is provided, it specifies the y coordinates of multiple instances of the widget.
+            **kwargs: Additional keyword arguments specific to the widget type.
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining.
-
-        Notes:
-            - If an unsupported widget_type is provided, the method returns self unchanged.
-            - After widget creation, the internal widget state is refreshed.
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
         _class = None
@@ -556,38 +481,33 @@ class PdfWrapper(FormWrapper):
         watermarks = obj.watermarks(self.read())
 
         self._stream = copy_watermark_widgets(self.read(), watermarks, [name], None)
-        if obj.non_acro_form_params:
-            self._stream = handle_non_acro_form_params(
-                self.read(), name, obj.non_acro_form_params
-            )
-
-        key_to_refresh = ""
-        if widget_type in ("text", "dropdown"):
-            key_to_refresh = name
+        hook_params = obj.hook_params
 
-        self._init_helper(key_to_refresh)
+        self._init_helper()
+        for k, v in hook_params:
+            self.widgets[name].__setattr__(k, v)
 
         return self
 
     def update_widget_key(
         self, old_key: str, new_key: str, index: int = 0, defer: bool = False
     ) -> PdfWrapper:
-        """Updates the field name/key of an existing widget in the PDF form.
+        """
+        Updates the key (name) of a widget, allowing you to rename form fields.
 
-        Allows renaming form fields while preserving all other properties.
-        Supports both immediate and deferred (batched) updates.
+        This method allows you to change the name of a form field in the PDF.  This can be useful for
+        standardizing field names or resolving naming conflicts.  The update can be performed immediately
+        or deferred until `commit_widget_key_updates` is called.
 
         Args:
-            old_key: Current field name/key to be updated
-            new_key: New field name/key to use
-            index: Index for widgets with duplicate names (default: 0)
-            defer: If True, queues the update for later batch processing
+            old_key (str): The old key of the widget that you want to rename.
+            new_key (str): The new key to assign to the widget.
+            index (int): The index of the widget if there are multiple widgets with the same name (default: 0).
+            defer (bool): Whether to defer the update. If True, the update is added to a queue and applied
+                when `commit_widget_key_updates` is called. If False, the update is applied immediately (default: False).
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
-
-        Raises:
-            NotImplementedError: When use_full_widget_name is enabled
+            PdfWrapper: The PdfWrapper object.
         """
 
         if getattr(self, "use_full_widget_name"):
@@ -597,6 +517,7 @@ class PdfWrapper(FormWrapper):
             self._keys_to_update.append((old_key, new_key, index))
             return self
 
+        self._key_update_tracker[new_key] = old_key
         self._stream = update_widget_keys(
             self.read(), self.widgets, [old_key], [new_key], [index]
         )
@@ -605,17 +526,14 @@ class PdfWrapper(FormWrapper):
         return self
 
     def commit_widget_key_updates(self) -> PdfWrapper:
-        """Processes all deferred widget key updates in a single batch operation.
+        """
+        Commits deferred widget key updates, applying all queued key renames to the PDF.
 
-        Applies all key updates that were queued using update_widget_key() with
-        defer=True. This is more efficient than individual updates when renaming
-        multiple fields.
+        This method applies all widget key updates that were deferred using the `defer=True` option
+        in the `update_widget_key` method.  It updates the underlying PDF stream with the new key names.
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
-
-        Raises:
-            NotImplementedError: When use_full_widget_name is enabled
+            PdfWrapper: The PdfWrapper object.
         """
 
         if getattr(self, "use_full_widget_name"):
@@ -628,6 +546,9 @@ class PdfWrapper(FormWrapper):
         self._stream = update_widget_keys(
             self.read(), self.widgets, old_keys, new_keys, indices
         )
+
+        for each in self._keys_to_update:
+            self._key_update_tracker[each[1]] = each[0]
         self._init_helper()
         self._keys_to_update = []
 
@@ -641,26 +562,21 @@ class PdfWrapper(FormWrapper):
         y: Union[float, int],
         **kwargs,
     ) -> PdfWrapper:
-        """Draws static text onto the PDF document at specified coordinates.
-
-        Adds non-interactive text that becomes part of the PDF content rather
-        than a form field. The text is drawn using a temporary Text widget and
-        merged via watermark operations, preserving existing form fields.
-
-        Supports multi-line text (using NEW_LINE_SYMBOL) and custom formatting.
+        """
+        Draws text on the PDF.
 
         Args:
-            text: The text content to draw (supports newlines with NEW_LINE_SYMBOL)
-            page_number: Page number (1-based) to draw text on
-            x: X coordinate for text position
-            y: Y coordinate for text position
-            **kwargs: Text formatting options:
-                font: Font name (default: "Helvetica")
-                font_size: Font size in points (default: 12)
-                font_color: Font color as RGB tuple (default: (0, 0, 0))
+            text (str): The text to draw.
+            page_number (int): The page number to draw on.
+            x (Union[float, int]): The x coordinate of the text.
+            y (Union[float, int]): The y coordinate of the text.
+            **kwargs: Additional keyword arguments:
+                - `font` (str): The name of the font to use (default: DEFAULT_FONT).
+                - `font_size` (float): The font size in points (default: DEFAULT_FONT_SIZE).
+                - `font_color` (Tuple[float, float, float]): The font color as an RGB tuple (default: DEFAULT_FONT_COLOR).
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
         new_widget = Text("new")
@@ -669,9 +585,6 @@ class PdfWrapper(FormWrapper):
         new_widget.font_size = kwargs.get("font_size", DEFAULT_FONT_SIZE)
         new_widget.font_color = kwargs.get("font_color", DEFAULT_FONT_COLOR)
 
-        if NEW_LINE_SYMBOL in text:
-            new_widget.text_lines = text.split(NEW_LINE_SYMBOL)
-
         watermarks = create_watermarks_and_draw(
             self.read(),
             page_number,
@@ -690,6 +603,8 @@ class PdfWrapper(FormWrapper):
         self._stream = copy_watermark_widgets(
             remove_all_widgets(self.read()), stream_with_widgets, None, None
         )
+        # because copy_watermark_widgets and remove_all_widgets
+        self._reregister_font()
 
         return self
 
@@ -703,22 +618,23 @@ class PdfWrapper(FormWrapper):
         height: Union[float, int],
         rotation: Union[float, int] = 0,
     ) -> PdfWrapper:
-        """Draws an image onto the PDF document at specified coordinates.
-
-        The image is merged via watermark operations, preserving existing form fields.
-        Supports common formats (JPEG, PNG) from bytes, file paths, or file objects.
+        """
+        Draws an image on the PDF.
 
         Args:
-            image: Image data as bytes, file path, or file object
-            page_number: Page number (1-based) to draw image on
-            x: X coordinate for image position (lower-left corner)
-            y: Y coordinate for image position (lower-left corner)
-            width: Width of the drawn image in PDF units
-            height: Height of the drawn image in PDF units
-            rotation: Rotation angle in degrees (default: 0)
+            image (Union[bytes, str, BinaryIO]): The image data, provided as either:
+                - bytes: The raw image data as a byte string.
+                - str: The file path to the image.
+                - BinaryIO: An open file-like object containing the image data.
+            page_number (int): The page number to draw the image on.
+            x (Union[float, int]): The x coordinate of the image.
+            y (Union[float, int]): The y coordinate of the image.
+            width (Union[float, int]): The width of the image.
+            height (Union[float, int]): The height of the image.
+            rotation (Union[float, int]): The rotation of the image in degrees (default: 0).
 
         Returns:
-            PdfWrapper: Returns self to allow method chaining
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
         image = fp_or_f_obj_or_stream_to_stream(image)
@@ -735,50 +651,42 @@ class PdfWrapper(FormWrapper):
         self._stream = copy_watermark_widgets(
             remove_all_widgets(self.read()), stream_with_widgets, None, None
         )
+        # because copy_watermark_widgets and remove_all_widgets
+        self._reregister_font()
 
         return self
 
-    @property
-    def schema(self) -> dict:
-        """Generates a JSON schema describing the PDF form's fields and types.
-
-        The schema includes:
-        - Field names as property names
-        - Type information (string, boolean, integer)
-        - Field-specific constraints like max lengths for text fields
-        - Choice indices for dropdown fields
-
-        Note: Does not include required field indicators since the PDF form's
-        validation rules are not extracted.
-
-        Returns:
-            dict: A JSON Schema dictionary following Draft 7 format
-        """
-
-        return {
-            "type": "object",
-            "properties": {
-                key: value.schema_definition for key, value in self.widgets.items()
-            },
-        }
-
-    @classmethod
     def register_font(
-        cls, font_name: str, ttf_file: Union[bytes, str, BinaryIO]
-    ) -> bool:
-        """Class method to register a TrueType font for use in PDF form text fields.
-
-        Registers the font globally so it can be used by all PdfWrapper instances.
-        The font will be available when specified by name in text operations.
+        self,
+        font_name: str,
+        ttf_file: Union[bytes, str, BinaryIO],
+        first_time: bool = True,
+    ) -> PdfWrapper:
+        """
+        Registers a custom font for use in the PDF.
 
         Args:
-            font_name: Name to register the font under (used when setting font)
-            ttf_file: The TTF font data as bytes, file path, or file object
+            font_name (str): The name of the font. This name will be used to reference the font when drawing text.
+            ttf_file (Union[bytes, str, BinaryIO]): The TTF file data, provided as either:
+                - bytes: The raw TTF file data as a byte string.
+                - str: The file path to the TTF file.
+                - BinaryIO: An open file-like object containing the TTF file data.
+            first_time (bool): Whether this is the first time the font is being registered (default: True).
+                If True and `adobe_mode` is enabled, a blank text string is drawn to ensure the font is properly embedded in the PDF.
 
         Returns:
-            bool: True if registration succeeded, False if failed
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
         ttf_file = fp_or_f_obj_or_stream_to_stream(ttf_file)
 
-        return register_font(font_name, ttf_file) if ttf_file is not None else False
+        if register_font(font_name, ttf_file) if ttf_file is not None else False:
+            if first_time and getattr(self, "adobe_mode"):
+                self.draw_text(" ", 1, 0, 0, font=font_name)
+            self._stream, new_font_name = register_font_acroform(
+                self.read(), ttf_file, getattr(self, "adobe_mode")
+            )
+            self._available_fonts[font_name] = new_font_name
+            self._font_register_events.append((font_name, ttf_file))
+
+        return self