PyPDFForm 3.5.1__py3-none-any.whl → 4.2.0__py3-none-any.whl

PyPDFForm/wrapper.py

@@ -15,51 +15,41 @@ methods for interacting with its form fields and content. It leverages
 lower-level modules within the `PyPDFForm` library to handle the
 underlying PDF manipulation.
 """
-# TODO: The `__add__` method (merging PDFs) involves multiple `self.read()` and `other.read()` calls, leading to redundant PDF parsing. Consider optimizing by passing `PdfReader` objects directly or by performing a single read and then merging.
-# TODO: In `_init_helper`, `build_widgets` and `get_all_available_fonts` both call `self.read()`, causing the PDF to be parsed multiple times. Optimize by parsing the PDF once and passing the `PdfReader` object to these functions.
-# TODO: The `pages` property's implementation involves `get_page_streams(remove_all_widgets(self.read()))` and `copy_watermark_widgets(each, self.read(), None, i)`. This leads to excessive PDF parsing, widget removal, and copying for each page. Refactor to minimize PDF I/O operations, possibly by working with `pypdf` page objects directly.
-# TODO: The `read` method triggers `trigger_widget_hooks` and `enable_adobe_mode`, both of which can involve PDF parsing and writing. Since `read` is called frequently, this can be a performance bottleneck. Consider a more granular dirty-flag system to only apply changes when necessary, or accumulate changes and apply them in a single PDF write operation.
-# TODO: The `write` method calls `self.read()`, which in turn triggers all pending operations. This can lead to redundant processing if `read()` has already been called or if multiple `write()` calls are made.
-# TODO: In `change_version`, replacing a byte string in the entire PDF stream can be inefficient for very large PDFs. Consider if `pypdf` offers a more direct way to update the PDF version without full stream manipulation.
-# TODO: In `generate_coordinate_grid`, `self.read()` is called multiple times, and then `remove_all_widgets`, `generate_coordinate_grid`, and `copy_watermark_widgets` are called, all of which involve PDF parsing and manipulation. Optimize by minimizing PDF I/O and object re-creation.
-# TODO: In `fill`, `self.read()` is called, and then `fill` (from `filler.py`), `remove_all_widgets`, and `copy_watermark_widgets` are called. This is a major operation and likely a performance hotspot due to repeated PDF processing. Streamline the PDF modification workflow to reduce redundant parsing and writing.
-# TODO: In `create_widget`, `obj.watermarks(self.read())` and `copy_watermark_widgets(self.read(), watermarks, [name], None)` involve reading the PDF multiple times. Optimize by passing the PDF stream or `PdfReader` object more efficiently.
-# TODO: The `commit_widget_key_updates` method calls `update_widget_keys`, which involves re-parsing and writing the PDF. For bulk updates, consider a mechanism to apply all key changes in a single PDF modification operation.
-# TODO: General: Many methods repeatedly call `self.read()`, which re-parses the PDF. Consider maintaining a persistent `pypdf.PdfReader` and `pypdf.PdfWriter` object internally and only writing to a byte stream when explicitly requested (e.g., by the `read()` or `write()` methods) to avoid redundant I/O and parsing overhead.
 
 from __future__ import annotations
 
+from collections import defaultdict
 from dataclasses import asdict
 from functools import cached_property
-from typing import TYPE_CHECKING, BinaryIO, Dict, List, Sequence, Tuple, Union
-from warnings import warn
-
-from .adapter import fp_or_f_obj_or_stream_to_stream
-from .constants import (DEFAULT_FONT, DEFAULT_FONT_COLOR, DEFAULT_FONT_SIZE,
-                        DEPRECATION_NOTICE, VERSION_IDENTIFIER_PREFIX,
-                        VERSION_IDENTIFIERS)
+from os import PathLike
+from typing import (TYPE_CHECKING, BinaryIO, Dict, Sequence, TextIO, Tuple,
+                    Union)
+
+from .adapter import (fp_or_f_obj_or_f_content_to_content,
+                      fp_or_f_obj_or_stream_to_stream)
+from .ap import appearance_streams_handler
+from .constants import VERSION_IDENTIFIER_PREFIX, VERSION_IDENTIFIERS
 from .coordinate import generate_coordinate_grid
 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, update_widget_keys
-from .utils import (enable_adobe_mode, generate_unique_suffix,
-                    get_page_streams, merge_two_pdfs, remove_all_widgets)
+from .raw import RawText, RawTypes
+from .template import (build_widgets, get_on_open_javascript, get_pdf_title,
+                       set_on_open_javascript, set_pdf_title,
+                       update_widget_keys)
+from .types import PdfWrapperList
+from .utils import (generate_unique_suffix, get_page_streams, merge_pdfs,
+                    remove_all_widgets)
 from .watermark import (copy_watermark_widgets, create_watermarks_and_draw,
                         merge_watermarks_with_pdf)
-from .widgets.checkbox import CheckBoxWidget
-from .widgets.dropdown import DropdownWidget
-from .widgets.image import ImageWidget
-from .widgets.radio import RadioWidget
-from .widgets.signature import SignatureWidget
-from .widgets.text import TextWidget
+from .widgets import CheckBoxField, ImageField, RadioGroup, SignatureField
 
 if TYPE_CHECKING:
+    from .assets.blank import BlankPage
     from .widgets import FieldTypes
 
 
@@ -78,18 +68,22 @@ class PdfWrapper:
             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.
+                - `need_appearances` (bool): Whether to set the `NeedAppearances` flag in the PDF's AcroForm dictionary.
+                - `generate_appearance_streams` (bool): Whether to explicitly generate appearance streams for all form fields using pikepdf.
+                - `title` (str): The title of the PDF document.
 
     """
 
     USER_PARAMS = [
         ("use_full_widget_name", False),
-        ("adobe_mode", False),
+        ("need_appearances", False),
+        ("generate_appearance_streams", False),
+        ("title", None),
     ]
 
     def __init__(
         self,
-        template: Union[bytes, str, BinaryIO] = b"",
+        template: Union[bytes, str, BinaryIO, BlankPage] = b"",
         **kwargs,
     ) -> None:
         """
@@ -98,14 +92,15 @@ class PdfWrapper:
         Initializes a new `PdfWrapper` object with the given template PDF and optional keyword arguments.
 
         Args:
-            template (Union[bytes, str, BinaryIO]): The template PDF, provided as either:
+            template (Union[bytes, str, BinaryIO, BlankPage]): 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.
+                - BlankPage: A blank page object.
                 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`.
+                For example: `use_full_widget_name=True` or `need_appearances=False`.
         """
 
         super().__init__()
@@ -120,26 +115,37 @@ class PdfWrapper:
         for attr, default in self.USER_PARAMS:
             setattr(self, attr, kwargs.get(attr, default))
 
+        if getattr(self, "generate_appearance_streams") is True:
+            self.need_appearances = True
+
         self._init_helper()
 
-    def __add__(self, other: PdfWrapper) -> PdfWrapper:
+    def __add__(self, other: Union[PdfWrapper, Sequence[PdfWrapper]]) -> PdfWrapper:
         """
-        Merges two PDF wrappers together, creating a new `PdfWrapper` containing the combined content.
+        Merges PDF wrappers together, creating a new `PdfWrapper` containing the combined content.
 
-        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.
+        This method allows you to combine 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
+        form being merged.
 
         Args:
-            other (PdfWrapper): The other `PdfWrapper` object to merge with.
+            other (Union[PdfWrapper, Sequence[PdfWrapper]]): The other `PdfWrapper` object or
+                a sequence of `PdfWrapper` objects to merge with.
 
         Returns:
             PdfWrapper: A new `PdfWrapper` object containing the merged PDFs.
         """
 
-        if not self.read():
+        if isinstance(other, Sequence):
+            result = self
+            for each in other:
+                result += each
+            return result
+
+        if not self or not self._read():
             return other
 
-        if not other.read():
+        if not other or not other._read():
             return self
 
         unique_suffix = generate_unique_suffix()
@@ -151,7 +157,7 @@ class PdfWrapper:
 
         # user params are based on the first object
         result = self.__class__(
-            merge_two_pdfs(self.read(), other.read()),
+            merge_pdfs([self._read(), other._read()]),
             **{each[0]: getattr(self, each[0], each[1]) for each in self.USER_PARAMS},
         )
 
@@ -172,10 +178,10 @@ class PdfWrapper:
 
         new_widgets = (
             build_widgets(
-                self.read(),
+                self._read(),
                 getattr(self, "use_full_widget_name"),
             )
-            if self.read()
+            if self._read()
             else {}
         )
         # ensure old widgets don't get overwritten
@@ -195,8 +201,8 @@ class PdfWrapper:
 
         self.widgets = new_widgets
 
-        if self.read():
-            self._available_fonts.update(**get_all_available_fonts(self.read()))
+        if self._read():
+            self._available_fonts.update(**get_all_available_fonts(self._read()))
 
     def _reregister_font(self) -> PdfWrapper:
         """
@@ -217,6 +223,28 @@ class PdfWrapper:
 
         return self
 
+    @property
+    def title(self) -> Union[str, None]:
+        """
+        Returns the title of the PDF document.
+
+        Returns:
+            Union[str, None]: The title of the PDF, or None if it's not set.
+        """
+
+        return get_pdf_title(self._read())
+
+    @title.setter
+    def title(self, value: str) -> None:
+        """
+        Sets the title of the PDF document.
+
+        Args:
+            value (str): The new title for the PDF document.
+        """
+
+        self._stream = set_pdf_title(self._read(), value)
+
     @property
     def schema(self) -> dict:
         """
@@ -274,7 +302,7 @@ class PdfWrapper:
         """
 
         for each in VERSION_IDENTIFIERS:
-            if self.read().startswith(each):
+            if self._read().startswith(each):
                 return each.replace(VERSION_IDENTIFIER_PREFIX, b"").decode()
 
         return None
@@ -293,20 +321,20 @@ class PdfWrapper:
     @cached_property
     def pages(self) -> Sequence[PdfWrapper]:
         """
-        Returns a sequence of `PdfWrapper` objects, each representing a single page in the PDF document.
+        Returns a list 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:
-            Sequence[PdfWrapper]: A sequence of `PdfWrapper` objects, one for each page in the PDF.
+            Sequence[PdfWrapper]: A list of `PdfWrapper` objects, one for each page in the PDF.
         """
 
         result = [
             self.__class__(
-                copy_watermark_widgets(each, self.read(), None, i),
+                copy_watermark_widgets(each, self._read(), None, i),
                 **{param: getattr(self, param) for param, _ in self.USER_PARAMS},
             )
-            for i, each in enumerate(get_page_streams(remove_all_widgets(self.read())))
+            for i, each in enumerate(get_page_streams(remove_all_widgets(self._read())))
         ]
 
         # because copy_watermark_widgets and remove_all_widgets
@@ -315,17 +343,62 @@ class PdfWrapper:
                 for page in result:
                     page.register_font(event[0], event[1])
 
-        return result
+        return PdfWrapperList(result)
+
+    @property
+    def on_open_javascript(self) -> Union[str, None]:
+        """
+        Returns the JavaScript that runs when the PDF is opened.
+
+        Returns:
+            Union[str, None]: The JavaScript that runs when the PDF is opened, or None if it's not set.
+        """
+
+        return get_on_open_javascript(self._read())
+
+    @on_open_javascript.setter
+    def on_open_javascript(self, value: Union[str, TextIO]) -> None:
+        """
+        Sets the JavaScript that runs when the PDF is opened.
+
+        Args:
+            value (Union[str, TextIO]): The JavaScript to run when the PDF is opened.
+                Can be a string or a text file-like object.
+        """
+
+        self._stream = set_on_open_javascript(
+            self._read(), fp_or_f_obj_or_f_content_to_content(value)
+        )
 
     def read(self) -> bytes:
         """
-        Reads the PDF content from the underlying stream.
+        Reads the PDF document and returns its content as bytes.
+
+        This method retrieves the PDF stream and optionally generates appearance
+        streams for form fields if `need_appearances` is enabled.
+
+        Returns:
+            bytes: The PDF document content as a byte string.
+        """
+
+        result = self._read()
+        if getattr(self, "need_appearances") and result:
+            result = appearance_streams_handler(
+                result, getattr(self, "generate_appearance_streams")
+            )  # cached
+
+        return result
+
+    def _read(self) -> bytes:
+        """
+        Reads the PDF stream, triggering widget hooks and updating fonts if necessary.
 
-        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.
+        This internal method ensures that all widget hooks are executed and that
+        fonts are correctly mapped to their internal PDF names before returning
+        the raw PDF stream.
 
         Returns:
-            bytes: The PDF content as bytes.
+            bytes: The raw PDF stream.
         """
 
         if any(widget.hooks_to_trigger for widget in self.widgets.values()):
@@ -345,24 +418,25 @@ class PdfWrapper:
                 getattr(self, "use_full_widget_name"),
             )
 
-        if getattr(self, "adobe_mode") and self._stream:
-            self._stream = enable_adobe_mode(self._stream)  # cached
-
         return self._stream
 
-    def write(self, path: str) -> PdfWrapper:
+    def write(self, dest: Union[str, BinaryIO]) -> PdfWrapper:
         """
-        Writes the PDF content to a file.
+        Writes the PDF to a file.
 
         Args:
-            path (str): The file path to write the PDF to.
+            dest (Union[str, BinaryIO]): The destination to write the PDF to.
+                Can be a file path (str) or a file-like object (BinaryIO).
 
         Returns:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        with open(path, "wb+") as f:
-            f.write(self.read())
+        if isinstance(dest, (str, bytes, PathLike)):
+            with open(dest, "wb+") as f:
+                f.write(self.read())
+        else:
+            dest.write(self.read())
 
         return self
 
@@ -377,7 +451,7 @@ class PdfWrapper:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        self._stream = self.read().replace(
+        self._stream = self._read().replace(
             VERSION_IDENTIFIER_PREFIX + bytes(self.version, "utf-8"),
             VERSION_IDENTIFIER_PREFIX + bytes(version, "utf-8"),
             1,
@@ -399,10 +473,10 @@ class PdfWrapper:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        stream_with_widgets = self.read()
+        stream_with_widgets = self._read()
         self._stream = copy_watermark_widgets(
             generate_coordinate_grid(
-                remove_all_widgets(self.read()),
+                remove_all_widgets(self._read()),
                 color,
                 margin,
             ),
@@ -417,15 +491,16 @@ class PdfWrapper:
 
     def fill(
         self,
-        data: Dict[str, Union[str, bool, int]],
+        data: Dict[str, Union[str, bool, int, BinaryIO, bytes]],
         **kwargs,
     ) -> PdfWrapper:
         """
         Fills the PDF form with data from a dictionary.
 
         Args:
-            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.
+            data (Dict[str, Union[str, bool, int, BinaryIO, bytes]]): A dictionary where keys
+                are form field names and values are the data to fill the fields with.
+                Values can be strings, booleans, integers, file-like objects, or bytes.
             **kwargs: Additional keyword arguments:
                 - `flatten` (bool): Whether to flatten the form after filling, making the fields read-only (default: False).
 
@@ -438,8 +513,9 @@ class PdfWrapper:
                 self.widgets[key].value = value
 
         filled_stream, image_drawn_stream = fill(
-            self.read(),
+            self._read(),
             self.widgets,
+            need_appearances=getattr(self, "need_appearances"),
             use_full_widget_name=getattr(self, "use_full_widget_name"),
             flatten=kwargs.get("flatten", False),
         )
@@ -462,112 +538,125 @@ class PdfWrapper:
 
         return self
 
-    def create_field(
-        self,
-        field: FieldTypes,
-    ) -> PdfWrapper:
+    def bulk_create_fields(self, fields: Sequence[FieldTypes]) -> PdfWrapper:
         """
-        Creates a new form field (widget) on the PDF using a `FieldTypes` object.
+        Creates multiple new form fields (widgets) on the PDF in a single operation.
 
-        This method simplifies widget creation by taking a `FieldTypes` object,
-        extracting its properties, and then delegating to the `create_widget` method.
+        This method takes a list of field definition objects (`FieldTypes`),
+        groups them by type (if necessary for specific widget handling, like CheckBoxField),
+        and then delegates the creation to the internal `_bulk_create_fields` method.
+        This is the preferred method for creating multiple fields as it minimizes
+        PDF manipulation overhead.
 
         Args:
-            field (FieldTypes): An object representing the field to create.
-                This object encapsulates all necessary properties like name,
-                page number, coordinates, and type of the field.
+            fields (Sequence[FieldTypes]): A list of field definition objects
+                (e.g., `TextField`, `CheckBoxField`, etc.) to be created.
 
         Returns:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        field_dict = asdict(field)
-        widget_type = field_dict.pop("_field_type")
-        name = field_dict.pop("name")
-        page_number = field_dict.pop("page_number")
-        x = field_dict.pop("x")
-        y = field_dict.pop("y")
-
-        field_dict["suppress_deprecation_notice"] = True
-        return self.create_widget(
-            widget_type,
-            name,
-            page_number,
-            x,
-            y,
-            **{k: v for k, v in field_dict.items() if v is not None},
-        )
+        needs_separate_creation = [
+            CheckBoxField,
+            RadioGroup,
+            SignatureField,
+            ImageField,
+        ]
+        needs_separate_creation_dict = defaultdict(list)
+        general_creation = []
+
+        for each in fields:
+            if type(each) in needs_separate_creation:
+                needs_separate_creation_dict[type(each)].append(each)
+            else:
+                general_creation.append(each)
+
+        needs_separate_creation_dict[SignatureField] = needs_separate_creation_dict.pop(
+            SignatureField, []
+        ) + needs_separate_creation_dict.pop(ImageField, [])
+        needs_separate_creation_dict[CheckBoxField] = needs_separate_creation_dict.pop(
+            CheckBoxField, []
+        ) + needs_separate_creation_dict.pop(RadioGroup, [])
+
+        for each in list(needs_separate_creation_dict.values()) + [general_creation]:
+            if each:
+                self._bulk_create_fields(each)
 
-    def create_widget(
-        self,
-        widget_type: str,
-        name: str,
-        page_number: int,
-        x: Union[float, List[float]],
-        y: Union[float, List[float]],
-        **kwargs,
-    ) -> PdfWrapper:
+        return self
+
+    def _bulk_create_fields(self, fields: Sequence[FieldTypes]) -> PdfWrapper:
         """
-        Creates a new form field (widget) on the PDF.
+        Internal method to create multiple new form fields (widgets) on the PDF in a single operation.
+
+        This method takes a list of field definition objects (`FieldTypes`),
+        converts them into `Widget` objects, and efficiently draws them onto the
+        PDF using bulk watermarking. It is designed to be called by the public
+        `bulk_create_fields` method after fields have been grouped for creation.
 
         Args:
-            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.
+            fields (Sequence[FieldTypes]): A list of field definition objects
+                (e.g., `TextField`, `CheckBoxField`, etc.) to be created.
 
         Returns:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        if not kwargs.get("suppress_deprecation_notice"):
-            warn(
-                DEPRECATION_NOTICE.format(
-                    f"{self.__class__.__name__}.create_widget()",
-                    f"{self.__class__.__name__}.create_field()",
-                ),
-                DeprecationWarning,  # noqa: PT030
-                stacklevel=2,
+        widgets = []
+        widget_class = None
+        for field in fields:
+            field_dict = asdict(field)
+            widget_class = getattr(field, "_widget_class")
+            name = field_dict.pop("name")
+            page_number = field_dict.pop("page_number")
+            x = field_dict.pop("x")
+            y = field_dict.pop("y")
+            widgets.append(
+                widget_class(
+                    name=name,
+                    page_number=page_number,
+                    x=x,
+                    y=y,
+                    **{k: v for k, v in field_dict.items() if v is not None},
+                )
             )
 
-        _class = None
-        if widget_type == "text":
-            _class = TextWidget
-        if widget_type == "checkbox":
-            _class = CheckBoxWidget
-        if widget_type == "dropdown":
-            _class = DropdownWidget
-        if widget_type == "radio":
-            _class = RadioWidget
-        if widget_type == "signature":
-            _class = SignatureWidget
-        if widget_type == "image":
-            _class = ImageWidget
-        if _class is None:
-            return self
-
-        obj = _class(name=name, page_number=page_number, x=x, y=y, **kwargs)
-        watermarks = obj.watermarks(self.read())
-
-        self._stream = copy_watermark_widgets(self.read(), watermarks, [name], None)
-        hook_params = obj.hook_params
+        watermarks = getattr(widget_class, "bulk_watermarks")(widgets, self._read())
+        self._stream = copy_watermark_widgets(
+            self._read(),
+            watermarks,
+            [widget.name for widget in widgets],
+            None,
+        )
 
         self._init_helper()
-        for k, v in hook_params:
-            self.widgets[name].__setattr__(k, v)
+
+        for widget in widgets:
+            for k, v in widget.hook_params:
+                self.widgets[widget.name].__setattr__(k, v)
 
         return self
 
+    def create_field(
+        self,
+        field: FieldTypes,
+    ) -> PdfWrapper:
+        """
+        Creates a new form field (widget) on the PDF using a `FieldTypes` object.
+
+        This method simplifies widget creation by taking a `FieldTypes` object
+        and delegating to the internal `_bulk_create_fields` method.
+
+        Args:
+            field (FieldTypes): An object representing the field to create.
+                This object encapsulates all necessary properties like name,
+                page number, coordinates, and type of the field.
+
+        Returns:
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
+        """
+
+        return self._bulk_create_fields([field])
+
     def update_widget_key(
         self, old_key: str, new_key: str, index: int = 0, defer: bool = False
     ) -> PdfWrapper:
@@ -598,7 +687,7 @@ class PdfWrapper:
 
         self._key_update_tracker[new_key] = old_key
         self._stream = update_widget_keys(
-            self.read(), self.widgets, [old_key], [new_key], [index]
+            self._read(), self.widgets, [old_key], [new_key], [index]
         )
         self._init_helper()
 
@@ -623,7 +712,7 @@ class PdfWrapper:
         indices = [each[2] for each in self._keys_to_update]
 
         self._stream = update_widget_keys(
-            self.read(), self.widgets, old_keys, new_keys, indices
+            self._read(), self.widgets, old_keys, new_keys, indices
         )
 
         for each in self._keys_to_update:
@@ -633,102 +722,29 @@ class PdfWrapper:
 
         return self
 
-    def draw_text(
-        self,
-        text: str,
-        page_number: int,
-        x: Union[float, int],
-        y: Union[float, int],
-        **kwargs,
-    ) -> PdfWrapper:
+    def draw(self, elements: Sequence[RawTypes]) -> PdfWrapper:
         """
-        Draws text on the PDF.
-
-        Args:
-            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: The `PdfWrapper` object, allowing for method chaining.
-        """
-
-        new_widget = Text("new")
-        new_widget.value = text
-        new_widget.font = kwargs.get("font", DEFAULT_FONT)
-        new_widget.font_size = kwargs.get("font_size", DEFAULT_FONT_SIZE)
-        new_widget.font_color = kwargs.get("font_color", DEFAULT_FONT_COLOR)
+        Draws raw elements (text, images, etc.) directly onto the PDF pages.
 
-        watermarks = create_watermarks_and_draw(
-            self.read(),
-            page_number,
-            "text",
-            [
-                {
-                    "widget": new_widget,
-                    "x": x,
-                    "y": y,
-                }
-            ],
-        )
-
-        stream_with_widgets = self.read()
-        self._stream = merge_watermarks_with_pdf(self.read(), watermarks)
-        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
-
-    def draw_image(
-        self,
-        image: Union[bytes, str, BinaryIO],
-        page_number: int,
-        x: Union[float, int],
-        y: Union[float, int],
-        width: Union[float, int],
-        height: Union[float, int],
-        rotation: Union[float, int] = 0,
-    ) -> PdfWrapper:
-        """
-        Draws an image on the PDF.
+        This method is the primary mechanism for drawing non-form field content.
+        It takes a list of `RawText` or `RawImage` objects and renders them
+        onto the PDF document as watermarks.
 
         Args:
-            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).
+            elements (Sequence[RawTypes]): A list of raw elements to draw (e.g., [RawText(...), RawImage(...)]).
 
         Returns:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
-        image = fp_or_f_obj_or_stream_to_stream(image)
-        image = rotate_image(image, rotation)
         watermarks = create_watermarks_and_draw(
-            self.read(),
-            page_number,
-            "image",
-            [{"stream": image, "x": x, "y": y, "width": width, "height": height}],
+            self._read(), [each.to_draw for each in elements]
         )
 
-        stream_with_widgets = self.read()
-        self._stream = merge_watermarks_with_pdf(self.read(), watermarks)
+        stream_with_widgets = self._read()
+        self._stream = merge_watermarks_with_pdf(self._read(), watermarks)
         self._stream = copy_watermark_widgets(
-            remove_all_widgets(self.read()), stream_with_widgets, None, None
+            remove_all_widgets(self._read()), stream_with_widgets, None, None
         )
         # because copy_watermark_widgets and remove_all_widgets
         self._reregister_font()
@@ -751,7 +767,7 @@ class PdfWrapper:
                 - 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.
+                If True and `need_appearances` is enabled, a blank text string is drawn to ensure the font is properly embedded in the PDF.
 
         Returns:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
@@ -760,10 +776,10 @@ class PdfWrapper:
         ttf_file = fp_or_f_obj_or_stream_to_stream(ttf_file)
 
         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)
+            if first_time and getattr(self, "need_appearances"):
+                self.draw([RawText(" ", 1, 0, 0, font=font_name)])
             self._stream, new_font_name = register_font_acroform(
-                self.read(), ttf_file, getattr(self, "adobe_mode")
+                self._read(), ttf_file, getattr(self, "need_appearances")
             )
             self._available_fonts[font_name] = new_font_name
             self._font_register_events.append((font_name, ttf_file))