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

PyPDFForm/__init__.py

@@ -20,10 +20,12 @@ The library supports various PDF form features, including:
 PyPDFForm aims to simplify PDF form manipulation, making it accessible to developers of all skill levels.
 """
 
-__version__ = "3.5.3"
+__version__ = "4.2.0"
 
-from .middleware.text import Text  # exposing for setting global font attrs
+from .assets.blank import BlankPage
+from .middleware import Widgets
+from .raw import RawElements
 from .widgets import Fields
 from .wrapper import PdfWrapper
 
-__all__ = ["PdfWrapper", "Text", "Fields"]
+__all__ = ["PdfWrapper", "Fields", "BlankPage", "RawElements", "Widgets"]

PyPDFForm/adapter.py

@@ -9,7 +9,6 @@ filling operations, where the input PDF template can be provided in different
 forms. The module ensures that the input is properly converted into a byte
 stream before further processing.
 """
-# TODO: For large PDF files, reading the entire file into memory using `_file.read()` in `fp_or_f_obj_or_stream_to_stream` can be inefficient. Consider streaming or chunking if downstream processing allows.
 
 from os.path import isfile
 from typing import Any, BinaryIO, Union
@@ -67,3 +66,36 @@ def fp_or_f_obj_or_stream_to_stream(
             with open(fp_or_f_obj_or_stream, "rb") as _file:
                 result = _file.read()
     return result
+
+
+def fp_or_f_obj_or_f_content_to_content(
+    fp_or_f_obj_or_f_content: Union[str, BinaryIO],
+) -> str:
+    """
+    Adapt a file path, file object, or file content to file content.
+
+    This function takes a file path, a file object, or file content and adapts it to a consistent string.
+    It handles different input types, including:
+        - file content (str)
+        - file paths (str)
+        - file-like objects with a read() method (BinaryIO)
+
+    Args:
+        fp_or_f_obj_or_f_content (Union[str, BinaryIO]): The input to adapt.
+            It can be file content, a file path (string), or a file object.
+
+    Returns:
+        str: The file content representation of the input.
+    """
+    result = ""
+    if readable(fp_or_f_obj_or_f_content):
+        result = str(fp_or_f_obj_or_f_content.read())
+
+    elif isinstance(fp_or_f_obj_or_f_content, str):
+        if isfile(fp_or_f_obj_or_f_content):
+            with open(fp_or_f_obj_or_f_content, "r", encoding="utf-8") as _file:
+                result = _file.read()
+        else:
+            result = fp_or_f_obj_or_f_content
+
+    return result

PyPDFForm/ap.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""
+A module for handling PDF appearance streams.
+
+This module provides functionality to manage appearance streams in PDF forms,
+which are necessary for form fields to display correctly after being filled.
+It uses both pypdf and pikepdf for manipulation.
+"""
+
+from functools import lru_cache
+from io import BytesIO
+
+from pikepdf import Pdf
+from pypdf import PdfReader, PdfWriter
+
+from .constants import XFA, AcroForm, Root
+from .template import (get_on_open_javascript, get_pdf_title,
+                       set_on_open_javascript, set_pdf_title)
+from .utils import stream_to_io
+
+
+@lru_cache
+def appearance_streams_handler(pdf: bytes, generate_appearance_streams: bool) -> bytes:
+    """
+    Handles appearance streams and the /NeedAppearances flag for a PDF form.
+
+    This function prepares a PDF for form filling by:
+    1. Removing the XFA dictionary if present, as it can interfere with standard
+       AcroForm processing.
+    2. Setting the /NeedAppearances flag in the AcroForm dictionary, which instructs
+       PDF viewers to generate appearance streams for form fields.
+    3. Optionally generating appearance streams explicitly using pikepdf if
+       `generate_appearance_streams` is True.
+    4. Preserving the title from the original PDF.
+    5. Preserving the on-open JavaScript from the original PDF.
+
+    The result is cached using lru_cache for performance.
+
+    Args:
+        pdf (bytes): The PDF file content as a bytes stream.
+        generate_appearance_streams (bool): Whether to explicitly generate appearance streams for all form fields.
+
+    Returns:
+        bytes: The modified PDF content as a bytes stream.
+    """
+    reader = PdfReader(stream_to_io(pdf))
+    writer = PdfWriter()
+
+    if AcroForm in reader.trailer[Root] and XFA in reader.trailer[Root][AcroForm]:
+        del reader.trailer[Root][AcroForm][XFA]
+
+    writer.append(reader)
+    writer.set_need_appearances_writer()
+
+    with BytesIO() as f:
+        writer.write(f)
+        f.seek(0)
+        result = f.read()
+
+    if generate_appearance_streams:
+        with Pdf.open(stream_to_io(result)) as f:
+            f.generate_appearance_streams()
+            with BytesIO() as r:
+                f.save(r)
+                r.seek(0)
+                result = r.read()
+
+    result = preserve_title(pdf, result)
+    return preserve_on_open_javascript(pdf, result)
+
+
+def preserve_title(src: bytes, dest: bytes) -> bytes:
+    """
+    Preserves the title from the source PDF to the destination PDF.
+
+    Args:
+        src (bytes): The source PDF file content as a bytes stream.
+        dest (bytes): The destination PDF file content as a bytes stream.
+
+    Returns:
+        bytes: The modified destination PDF content as a bytes stream.
+    """
+    title = get_pdf_title(src)
+    return set_pdf_title(dest, title)
+
+
+def preserve_on_open_javascript(src: bytes, dest: bytes) -> bytes:
+    """
+    Preserves the on-open JavaScript from the source PDF to the destination PDF.
+
+    Args:
+        src (bytes): The source PDF file content as a bytes stream.
+        dest (bytes): The destination PDF file content as a bytes stream.
+
+    Returns:
+        bytes: The modified destination PDF content as a bytes stream.
+    """
+    script = get_on_open_javascript(src)
+    return set_on_open_javascript(dest, script)

PyPDFForm/assets/blank.py

@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+"""
+Module for creating and managing a blank PDF page asset.
+
+This module provides the BlankPage class, which acts as a utility to generate
+a simple, empty PDF page with customizable dimensions (width and height).
+The primary use case is creating new PDF documents starting with a blank canvas
+or adding blank pages to existing documents. It supports multiplication to
+easily generate a PDF containing multiple identical blank pages.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from io import BytesIO
+
+from reportlab.pdfgen.canvas import Canvas
+
+from ..constants import BLANK_PAGE_DEFAULT_HEIGHT, BLANK_PAGE_DEFAULT_WIDTH
+from ..utils import merge_pdfs
+
+
+class BlankPage:
+    """
+    Class for creating a blank PDF page asset.
+
+    This class manages the generation and representation of a single blank PDF page
+    using reportlab. It provides a simple interface to access the page content as
+    a byte stream and supports page duplication via the multiplication operator.
+    """
+
+    def __init__(
+        self,
+        width: float = BLANK_PAGE_DEFAULT_WIDTH,
+        height: float = BLANK_PAGE_DEFAULT_HEIGHT,
+    ) -> None:
+        """
+        Initializes a BlankPage object.
+
+        Args:
+            width (float): The width of the blank page in points. Defaults to
+                           BLANK_PAGE_DEFAULT_WIDTH (612 points).
+            height (float): The height of the blank page in points. Defaults to
+                            BLANK_PAGE_DEFAULT_HEIGHT (792 points).
+        """
+        super().__init__()
+        self.width = width
+        self.height = height
+
+    def __mul__(self, count: int) -> bytes:
+        """
+        Multiplication operator to merge multiple blank pages into one PDF.
+
+        This allows syntax like `BlankPage() * 3` to create a 3-page PDF.
+        It merges copies of the current blank page asset using the efficient
+        pairwise merging strategy implemented in `merge_pdfs`.
+
+        Args:
+            count (int): The number of blank pages to merge. Must be an integer >= 1.
+
+        Returns:
+            bytes: The byte stream of the resulting PDF containing `count` blank pages.
+        """
+        if count == 1:
+            return self.read()
+
+        return merge_pdfs([self.read() for _ in range(count)])
+
+    def read(self) -> bytes:
+        """
+        Read the generated blank page PDF content.
+
+        This is a public interface to retrieve the cached byte stream of the single
+        blank PDF page created by this instance.
+
+        Returns:
+            bytes: The byte stream of the single blank PDF page.
+        """
+        return self._stream
+
+    @cached_property
+    def _stream(self) -> bytes:
+        """
+        Generates and returns the PDF byte stream of a single blank page.
+
+        This is a cached property that uses `reportlab.pdfgen.canvas.Canvas` to create
+        a minimal PDF document consisting of one blank page with the configured
+        dimensions (`self.width`, `self.height`). This generation occurs only once.
+
+        Returns:
+            bytes: The byte stream of the generated blank PDF page.
+        """
+        result = BytesIO()
+
+        canvas = Canvas(result, pagesize=(self.width, self.height))
+        canvas.showPage()
+        canvas.save()
+        result.seek(0)
+
+        return result.read()

PyPDFForm/constants.py

@@ -41,9 +41,8 @@ WIDGET_TYPES = Union[Text, Checkbox, Radio, Dropdown, Signature, Image]
 
 DEPRECATION_NOTICE = "{} will be deprecated soon. Use {} instead."
 
+Title = "/Title"
 Annots = "/Annots"
-A = "/A"
-JS = "/JS"
 T = "/T"
 TU = "/TU"
 Rect = "/Rect"
@@ -68,6 +67,21 @@ AS = "/AS"
 Yes = "/Yes"
 Off = "/Off"
 
+# javascript
+A = "/A"
+AA = "/AA"
+Action = "/Action"
+S = "/S"
+JavaScript = "/JavaScript"
+JS = "/JS"
+OpenAction = "/OpenAction"
+E = "/E"
+X = "/X"
+D = "/D"
+U = "/U"
+Fo = "/Fo"
+Bl = "/Bl"
+
 # Font dict
 Length = "/Length"
 Length1 = "/Length1"
@@ -129,3 +143,7 @@ COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO = DEFAULT_FONT_SIZE / 100
 UNIQUE_SUFFIX_LENGTH = 20
 
 SLASH = "/"
+
+# blank page
+BLANK_PAGE_DEFAULT_WIDTH = 612
+BLANK_PAGE_DEFAULT_HEIGHT = 792

PyPDFForm/coordinate.py

@@ -6,8 +6,6 @@ This module provides functionality to generate coordinate grids on existing PDF
 It allows developers to visualize the coordinate system of each page in a PDF, which can be helpful
 for debugging and precisely positioning elements when filling or drawing on PDF forms.
 """
-# TODO: The `PdfReader` object is initialized twice (lines 42 and implicitly within `create_watermarks_and_draw` if it re-reads the PDF). Consider initializing it once and passing the object or its relevant parts to avoid redundant parsing, especially for large PDFs.
-# TODO: Drawing operations for lines and texts are performed and merged separately. It might be more efficient to combine all drawing operations for a page into a single `create_watermarks_and_draw` call or to merge all watermarks in one final step to reduce PDF processing overhead.
 
 from typing import Tuple
 
@@ -44,7 +42,6 @@ def generate_coordinate_grid(
     pdf_file = PdfReader(stream_to_io(pdf))
     lines_by_page = {}
     texts_by_page = {}
-    watermarks = []
 
     for i, page in enumerate(pdf_file.pages):
         lines_by_page[i + 1] = []
@@ -98,16 +95,15 @@ def generate_coordinate_grid(
                 y += margin
             x += margin
 
+    to_draw = []
+
     for page, lines in lines_by_page.items():
-        watermarks.append(
-            create_watermarks_and_draw(pdf, page, "line", lines)[page - 1]
+        to_draw.extend(
+            [{"page_number": page, "type": "line", **line} for line in lines]
         )
-
-    result = merge_watermarks_with_pdf(pdf, watermarks)
-    watermarks = []
     for page, texts in texts_by_page.items():
-        watermarks.append(
-            create_watermarks_and_draw(pdf, page, "text", texts)[page - 1]
+        to_draw.extend(
+            [{"page_number": page, "type": "text", **text} for text in texts]
         )
 
-    return merge_watermarks_with_pdf(result, watermarks)
+    return merge_watermarks_with_pdf(pdf, create_watermarks_and_draw(pdf, to_draw))

PyPDFForm/deprecation.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+"""
+A module for handling deprecation notices within the PyPDFForm library.
+
+This module provides utility functions to issue standard DeprecationWarning
+messages, ensuring consistency across the library when notifying users of
+deprecated features.
+"""
+
+from warnings import warn
+
+from .constants import DEPRECATION_NOTICE
+
+
+def deprecation_notice(to_deprecate: str, to_replace: str) -> None:
+    """
+    Issues a DeprecationWarning for a feature that is being deprecated.
+
+    Args:
+        to_deprecate (str): The name of the feature or function being deprecated.
+        to_replace (str): The name of the feature or function that should be used instead.
+    """
+    warn(
+        DEPRECATION_NOTICE.format(
+            to_deprecate,
+            to_replace,
+        ),
+        DeprecationWarning,  # noqa: PT030
+        stacklevel=3,
+    )

PyPDFForm/filler.py

@@ -7,11 +7,6 @@ It includes functions for handling various form field types, such as text fields
 checkboxes, radio buttons, dropdowns, images, and signatures. The module also
 supports flattening the filled form to prevent further modifications.
 """
-# TODO: In `fill` function, `PdfReader(stream_to_io(template))` and `out.append(pdf)` might involve re-parsing or copying the entire PDF. For very large PDFs, consider if `pypdf` offers more efficient ways to modify in-place or stream processing.
-# TODO: The `get_widget_key` function is called repeatedly in a loop. If its internal logic is complex, consider caching its results or optimizing its implementation to avoid redundant computations.
-# TODO: The `signature_image_handler` function involves `get_image_dimensions` and `get_draw_image_resolutions`. If image processing is a bottleneck, consider optimizing these image-related operations, perhaps by using faster image libraries or pre-calculating dimensions if images are reused.
-# TODO: Similar to `coordinate.py`, `get_drawn_stream` involves multiple `create_watermarks_and_draw` and `merge_watermarks_with_pdf` calls. Combining drawing operations or merging watermarks in a single pass could reduce overhead.
-# TODO: The `radio_button_tracker` logic involves iterating through all radio buttons. For forms with many radio buttons, consider optimizing the lookup or update mechanism if performance becomes an issue.
 
 from io import BytesIO
 from typing import Dict, Union, cast
@@ -75,37 +70,10 @@ def signature_image_handler(
     return any_image_to_draw
 
 
-def get_drawn_stream(to_draw: dict, stream: bytes, action: str) -> bytes:
-    """Applies watermarks to specific pages of a PDF based on the provided drawing instructions.
-
-    This function takes a dictionary of drawing instructions and applies watermarks to the
-    specified pages of a PDF. It iterates through the drawing instructions, creates watermarks
-    for each page, and merges the watermarks with the original PDF content. The function
-    supports various drawing actions, such as adding images or text.
-
-    Args:
-        to_draw (dict): A dictionary containing page numbers as keys and lists of drawing instructions as values.
-                         Each drawing instruction specifies the type of drawing, position, dimensions, and content.
-        stream (bytes): The PDF content as bytes.
-        action (str): The type of action to perform (e.g., "image", "text").
-
-    Returns:
-        bytes: The modified PDF content with watermarks applied.
-    """
-    watermark_list = []
-    for page, stuffs in to_draw.items():
-        watermark_list.append(b"")
-        watermarks = create_watermarks_and_draw(stream, page, action, stuffs)
-        for i, watermark in enumerate(watermarks):
-            if watermark:
-                watermark_list[i] = watermark
-
-    return merge_watermarks_with_pdf(stream, watermark_list)
-
-
 def fill(
     template: bytes,
     widgets: Dict[str, WIDGET_TYPES],
+    need_appearances: bool,
     use_full_widget_name: bool,
     flatten: bool = False,
 ) -> tuple:
@@ -121,6 +89,9 @@ def fill(
         template (bytes): The PDF template as bytes.
         widgets (Dict[str, WIDGET_TYPES]): A dictionary of widgets to fill, where the keys are the
                                             widget names and the values are the widget objects.
+        need_appearances (bool): If True, skips updating the appearance stream (AP) for
+            text and dropdown fields to maintain compatibility with Adobe Reader's
+            behavior for certain fields.
         use_full_widget_name (bool): Whether to use the full widget name when looking up widgets
                                       in the `widgets` dictionary.
         flatten (bool): Whether to flatten the filled PDF. Defaults to False.
@@ -130,6 +101,7 @@ def fill(
                The image drawn stream is only returned if there are any image or signature widgets
                in the form.
     """
+    # pylint: disable=R0912
     pdf = PdfReader(stream_to_io(template))
     out = PdfWriter()
     out.append(pdf)
@@ -169,15 +141,24 @@ def fill(
                 if widget.value == radio_button_tracker[key] - 1:
                     update_radio_value(annot)
             elif isinstance(widget, Dropdown):
-                update_dropdown_value(annot, widget)
+                update_dropdown_value(annot, widget, need_appearances)
             elif isinstance(widget, Text):
-                update_text_value(annot, widget)
+                update_text_value(annot, widget, need_appearances)
 
     with BytesIO() as f:
         out.write(f)
         f.seek(0)
         result = f.read()
 
+    if not any_image_to_draw:
+        return result, None
+
+    images = []
+    for page, elements in images_to_draw.items():
+        images.extend(
+            [{"page_number": page, "type": "image", **element} for element in elements]
+        )
+
     return result, (
-        get_drawn_stream(images_to_draw, result, "image") if any_image_to_draw else None
+        merge_watermarks_with_pdf(result, create_watermarks_and_draw(result, images))
     )

PyPDFForm/font.py

@@ -6,11 +6,6 @@ It includes functions for registering fonts with ReportLab and within the PDF's
 allowing these fonts to be used when filling form fields. The module also provides utilities
 for extracting font information from TTF streams and managing font names within a PDF.
 """
-# TODO: In `get_additional_font_params`, iterating through `reader.pages[0][Resources][Font].values()` can be inefficient for PDFs with many fonts. Consider building a font lookup dictionary once per PDF or caching results if this function is called frequently with the same PDF.
-# TODO: In `register_font_acroform`, `PdfReader(stream_to_io(pdf))` and `writer.append(reader)` involve re-parsing and appending the PDF. For large PDFs, passing `PdfReader` and `PdfWriter` objects directly could reduce overhead.
-# TODO: In `register_font_acroform`, `compress(ttf_stream)` can be CPU-intensive. If the same font stream is registered multiple times within a single PDF processing session, consider caching the compressed stream to avoid redundant compression.
-# TODO: In `get_new_font_name`, while `existing` is a set, if `n` needs to increment many times due to a dense range of existing font names, the `while` loop could be slow. However, this is likely a minor bottleneck in typical scenarios.
-# TODO: In `get_all_available_fonts`, the `replace("/", "")` operation on `BaseFont` could be avoided if font names are consistently handled with or without the leading slash to prevent string manipulation overhead in a loop.
 
 from functools import lru_cache
 from io import BytesIO
@@ -99,7 +94,7 @@ def get_additional_font_params(pdf: bytes, base_font_name: str) -> tuple:
     return font_descriptor_params, font_dict_params
 
 
-def compute_font_glyph_widths(ttf_file: BytesIO, missing_width: float):
+def compute_font_glyph_widths(ttf_file: BytesIO, missing_width: float) -> list[float]:
     """
     Computes the advance widths for all glyphs in a TrueType font, scaled for PDF text space.
 
@@ -134,20 +129,23 @@ def compute_font_glyph_widths(ttf_file: BytesIO, missing_width: float):
     widths: list[float] = []
     if head_table and cmap_table and hmtx_table:
         cmap = cmap_table.getBestCmap()
-        units_per_em: int = head_table.unitsPerEm or 1
-
-        for codepoint in range(ENCODING_TABLE_SIZE):
-            glyph_name: str = cmap.get(codepoint, FontNotdef)
-            advance_width, _ = hmtx_table[glyph_name]
-            pdf_width: float = (advance_width / units_per_em) * EM_TO_PDF_FACTOR
-            widths.append(pdf_width)
+        if cmap:
+            units_per_em: int = head_table.unitsPerEm or 1
+
+            for codepoint in range(ENCODING_TABLE_SIZE):
+                glyph_name: str = cmap.get(codepoint, FontNotdef)
+                advance_width, _ = hmtx_table[glyph_name]
+                pdf_width: float = (advance_width / units_per_em) * EM_TO_PDF_FACTOR
+                widths.append(pdf_width)
     else:
         widths: list[float] = [missing_width] * ENCODING_TABLE_SIZE
 
     return widths
 
 
-def register_font_acroform(pdf: bytes, ttf_stream: bytes, adobe_mode: bool) -> tuple:
+def register_font_acroform(
+    pdf: bytes, ttf_stream: bytes, need_appearances: bool
+) -> tuple:
     """
     Registers a TrueType font within the PDF's AcroForm dictionary.
 
@@ -160,7 +158,9 @@ def register_font_acroform(pdf: bytes, ttf_stream: bytes, adobe_mode: bool) -> t
             will be modified to include the new font.
         ttf_stream (bytes): The font file data in TTF format as bytes. This is the
             raw data of the TrueType font file.
-        adobe_mode (bool): A flag indicating whether to use Adobe-specific font parameters.
+        need_appearances (bool): If True, attempts to retrieve existing font parameters
+            from the PDF's resources to ensure compatibility when appearance streams are
+            required.
 
     Returns:
         tuple: A tuple containing the modified PDF data as bytes and the new font name
@@ -173,7 +173,7 @@ def register_font_acroform(pdf: bytes, ttf_stream: bytes, adobe_mode: bool) -> t
 
     font_descriptor_params = {}
     font_dict_params = {}
-    if adobe_mode:
+    if need_appearances:
         font_descriptor_params, font_dict_params = get_additional_font_params(
             pdf, base_font_name
         )