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

PyPDFForm/__init__.py

@@ -1,12 +1,28 @@
 # -*- coding: utf-8 -*-
-"""PyPDFForm package for PDF form filling and manipulation.
+"""
+PyPDFForm is a pure Python library designed to streamline the process of filling PDF forms programmatically.
+
+It provides a simple and intuitive API for interacting with PDF forms, allowing users to:
+
+- Fill text fields with custom data.
+- Check or uncheck checkboxes.
+- Select radio button options.
+- Add images to image fields.
+- Flatten the filled form to prevent further modifications.
+
+The library supports various PDF form features, including:
+
+- Text field alignment (left, center, right).
+- Font customization (size, color, family).
+- Image field resizing and positioning.
+- Handling of complex form structures.
 
-This package provides tools for filling PDF forms, drawing text and images,
-and manipulating PDF form elements programmatically.
+PyPDFForm aims to simplify PDF form manipulation, making it accessible to developers of all skill levels.
 """
 
-__version__ = "2.5.0"
+__version__ = "3.0.0"
 
-from .wrapper import FormWrapper, PdfWrapper
+from .middleware.text import Text  # exposing for setting global font attrs
+from .wrapper import PdfWrapper
 
-__all__ = ["FormWrapper", "PdfWrapper"]
+__all__ = ["PdfWrapper", "Text"]

PyPDFForm/adapter.py

@@ -1,13 +1,13 @@
 # -*- coding: utf-8 -*-
-"""Provides adapters for handling different types of file inputs.
-
-This module contains utility functions for working with various file input types:
-- Raw bytes
-- File paths
-- File-like objects
-
-The adapters normalize these different input types into consistent byte streams
-that can be processed by the PDF manipulation functions.
+"""
+Module for adapting different types of input to a consistent byte stream.
+
+This module provides utility functions to adapt various types of input,
+such as file paths, file-like objects, and byte streams, into a consistent
+byte stream format. This is particularly useful when dealing with PDF form
+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.
 """
 
 from os.path import isfile
@@ -15,41 +15,43 @@ from typing import Any, BinaryIO, Union
 
 
 def readable(obj: Any) -> bool:
-    """Determines if an object is file-like and readable.
+    """
+    Check if an object has a readable "read" attribute.
 
-    Checks if the object has a callable read() method, indicating it can be
-    treated as a file-like object for reading operations.
+    This function determines whether the provided object has a "read" attribute that is callable.
+    It is used to identify file-like objects or streams that can be read from.
 
     Args:
-        obj: The object to check for read capability
+        obj (Any): The object to check for a readable "read" attribute.
 
     Returns:
-        bool: True if the object has a callable read() method, False otherwise
+        bool: True if the object has a callable "read" attribute, indicating it is readable.
+              Returns False otherwise.
     """
-
     return callable(getattr(obj, "read", None))
 
 
 def fp_or_f_obj_or_stream_to_stream(
     fp_or_f_obj_or_stream: Union[bytes, str, BinaryIO],
 ) -> bytes:
-    """Converts various file input types to a byte stream.
+    """
+    Adapt a file path, file object, or stream to a byte stream.
 
-    Handles conversion of:
-    - Raw bytes (passed through unchanged)
-    - File paths (reads file contents)
-    - File-like objects (reads using read() method)
+    This function takes a file path, a file object, or a byte stream and adapts it to a consistent byte stream.
+    It handles different input types, including:
+        - byte streams (bytes)
+        - file paths (str)
+        - file-like objects with a read() method (BinaryIO)
 
     Args:
-        fp_or_f_obj_or_stream: Input to convert, which can be:
-            - bytes: Raw PDF data
-            - str: Path to PDF file
-            - BinaryIO: File-like object containing PDF data
+        fp_or_f_obj_or_stream (Union[bytes, str, BinaryIO]): The input to adapt.
+            It can be a byte stream, a file path (string), or a file object.
 
     Returns:
-        bytes: The PDF data as a byte stream
+        bytes: The byte stream representation of the input.
+               Returns an empty byte string if the file path does not exist.
     """
-
+    # not cached to handle writing to the same disk file
     result = b""
     if isinstance(fp_or_f_obj_or_stream, bytes):
         result = fp_or_f_obj_or_stream

PyPDFForm/constants.py

@@ -1,15 +1,18 @@
 # -*- coding: utf-8 -*-
-"""Centralized location for all PyPDFForm constants and default values.
+"""
+Module containing constants used throughout the PyPDFForm library.
+
+This module defines a collection of constants that are used across various
+modules within the PyPDFForm library. These constants include:
 
-This module defines all the constants used throughout the package including:
-- PDF version identifiers and format strings
-- PDF field type and property constants
-- Default values for fonts, colors and sizes
-- Special identifiers and symbols
-- Field flag bitmasks
-- Button style definitions
+- String identifiers for PDF syntax elements (e.g., /Annots, /Rect, /FT).
+- Numerical values representing field flags (e.g., READ_ONLY, MULTILINE).
+- Default values for fonts, font sizes, and font colors.
+- Identifiers for image fields and coordinate grid calculations.
+- Version identifiers for PDF versions.
 
-All constants are organized by category and used consistently across the package.
+Using constants improves code readability and maintainability by providing
+meaningful names for frequently used values and reducing the risk of typos.
 """
 
 from typing import Union
@@ -54,25 +57,33 @@ I = "/I"  # noqa: E741
 N = "/N"
 Sig = "/Sig"
 DA = "/DA"
+DR = "/DR"
 DV = "/DV"
 Btn = "/Btn"
 MaxLen = "/MaxLen"
 Q = "/Q"
 Ch = "/Ch"
 Opt = "/Opt"
-MK = "/MK"
-CA = "/CA"
-BC = "/BC"
-BG = "/BG"
-BS = "/BS"
-W = "/W"
-S = "/S"
-D = "/D"
-U = "/U"
 AS = "/AS"
 Yes = "/Yes"
 Off = "/Off"
 
+# Font dict
+Length1 = "/Length1"
+Type = "/Type"
+FontDescriptor = "/FontDescriptor"
+FontName = "/FontName"
+FontFile2 = "/FontFile2"
+Font = "/Font"
+Subtype = "/Subtype"
+TrueType = "/TrueType"
+BaseFont = "/BaseFont"
+Encoding = "/Encoding"
+WinAnsiEncoding = "/WinAnsiEncoding"
+
+Resources = "/Resources"
+FONT_NAME_PREFIX = "/F"
+
 # For Adobe Acrobat
 AcroForm = "/AcroForm"
 Root = "/Root"
@@ -86,27 +97,11 @@ COMB = 1 << 24
 
 FONT_SIZE_IDENTIFIER = "Tf"
 FONT_COLOR_IDENTIFIER = " rg"
-DEFAULT_BORDER_WIDTH = 1
 DEFAULT_FONT = "Helvetica"
 DEFAULT_FONT_SIZE = 12
 DEFAULT_FONT_COLOR = (0, 0, 0)
-PREVIEW_FONT_COLOR = (1, 0, 0)
-
-NEW_LINE_SYMBOL = "\n"
 
 IMAGE_FIELD_IDENTIFIER = "event.target.buttonImportIcon();"
 
-DEFAULT_CHECKBOX_STYLE = "\u2713"
-DEFAULT_RADIO_STYLE = "\u25cf"
-BUTTON_STYLES = {
-    "4": "\u2713",  # check
-    "5": "\u00d7",  # cross
-    "l": "\u25cf",  # circle
-}
-
 COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO = DEFAULT_FONT_SIZE / 100
 UNIQUE_SUFFIX_LENGTH = 20
-
-# Used for adjusting paragraph font size
-FONT_SIZE_REDUCE_STEP = 0.5
-MARGIN_BETWEEN_LINES = 2

PyPDFForm/coordinate.py

@@ -1,412 +1,44 @@
 # -*- coding: utf-8 -*-
-"""Provides coordinate calculation utilities for PDF form elements.
-
-This module contains functions for calculating positions and dimensions
-for drawing various PDF form elements including:
-- Text fields and paragraphs
-- Checkboxes and radio buttons
-- Images and signatures
-- Borders and decorative elements
+"""
+Module for generating coordinate grids on PDFs.
 
-All calculations work in PDF coordinate space where:
-- Origin (0,0) is at bottom-left corner
-- Units are in PDF points (1/72 inch)
+This module provides functionality to generate coordinate grids on existing PDF documents.
+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.
 """
 
-from copy import deepcopy
-from typing import List, Tuple, Union
+from typing import Tuple
 
 from pypdf import PdfReader
 from reportlab.pdfbase.pdfmetrics import stringWidth
 
-from .constants import (COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO, DEFAULT_FONT,
-                        Rect)
+from .constants import COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO, DEFAULT_FONT
 from .middleware.text import Text
-from .patterns import WIDGET_ALIGNMENT_PATTERNS
-from .template import get_char_rect_width, is_text_multiline
-from .utils import extract_widget_property, handle_color, stream_to_io
+from .utils import stream_to_io
 from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
 
 
-def get_draw_border_coordinates(widget: dict, shape: str) -> dict:
-    """Calculates coordinates for drawing widget borders in PDF coordinate space.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect coordinates (in PDF points)
-        shape: Type of border to draw:
-            - "rect": Standard rectangular border
-            - "ellipse": Circular/oval border
-            - "line": Straight line border
-
-    Returns:
-        dict: Coordinate dictionary with different keys depending on shape:
-            - For "rect":
-                {
-                    "x": bottom-left x,
-                    "y": bottom-left y,
-                    "width": total width,
-                    "height": total height
-                }
-            - For "ellipse":
-                {
-                    "x1": left bound,
-                    "y1": bottom bound,
-                    "x2": right bound,
-                    "y2": top bound
-                }
-            - For "line":
-                {
-                    "src_x": start x,
-                    "src_y": start y,
-                    "dest_x": end x,
-                    "dest_y": end y
-                }
-
-    Note:
-        All coordinates are in PDF points (1/72 inch) with origin (0,0) at bottom-left.
-        For ellipses, the bounds form a square that would contain the ellipse.
-    """
-
-    result = {
-        "x": float(widget[Rect][0]),
-        "y": float(widget[Rect][1]),
-        "width": abs(float(widget[Rect][0]) - float(widget[Rect][2])),
-        "height": abs(float(widget[Rect][1]) - float(widget[Rect][3])),
-    }
-
-    if shape == "ellipse":
-        width = abs(float(widget[Rect][0]) - float(widget[Rect][2]))
-        height = abs(float(widget[Rect][1]) - float(widget[Rect][3]))
-
-        width_mid = (float(widget[Rect][0]) + float(widget[Rect][2])) / 2
-        height_mid = (float(widget[Rect][1]) + float(widget[Rect][3])) / 2
-
-        less = min(width, height)
-
-        result = {
-            "x1": width_mid - less / 2,
-            "y1": height_mid - less / 2,
-            "x2": width_mid + less / 2,
-            "y2": height_mid + less / 2,
-        }
-    elif shape == "line":
-        result = {
-            "src_x": float(widget[Rect][0]),
-            "src_y": float(widget[Rect][1]),
-            "dest_x": float(widget[Rect][2]),
-            "dest_y": float(widget[Rect][1]),
-        }
-
-    return result
-
-
-def get_draw_checkbox_radio_coordinates(
-    widget: dict,
-    widget_middleware: Text,
-    border_width: int,
-) -> Tuple[Union[float, int], Union[float, int]]:
-    """Calculates drawing coordinates for checkbox/radio button symbols.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect coordinates
-        widget_middleware: Text middleware containing font properties
-        border_width: Width of widget border in points
-
-    Returns:
-        Tuple[Union[float, int], Union[float, int]]: (x, y) coordinates
-            for drawing the checkbox/radio symbol
-    """
-
-    string_height = widget_middleware.font_size * 72 / 96
-    width_mid_point = (float(widget[Rect][0]) + float(widget[Rect][2])) / 2
-    half_widget_height = abs(float(widget[Rect][1]) - float(widget[Rect][3])) / 2
-
-    return (
-        width_mid_point
-        - stringWidth(
-            widget_middleware.value,
-            widget_middleware.font,
-            widget_middleware.font_size,
-        )
-        / 2,
-        float(widget[Rect][1])
-        + (half_widget_height - string_height / 2)
-        + border_width / 2,
-    )
-
-
-def get_draw_image_coordinates_resolutions(
-    widget: dict,
-    preserve_aspect_ratio: bool,
-    image_width: float,
-    image_height: float,
-) -> Tuple[float, float, float, float]:
-    """Calculates image drawing coordinates and scaling factors.
-
-    Args:
-        widget: PDF form widget dictionary containing Rect coordinates
-        preserve_aspect_ratio: Whether to maintain image proportions
-        image_width: Original width of the image in points
-        image_height: Original height of the image in points
-
-    Returns:
-        Tuple[float, float, float, float]: (x, y, width, height) where:
-            x,y: Bottom-left corner coordinates
-            width,height: Scaled dimensions for drawing
-    """
-
-    x = float(widget[Rect][0])
-    y = float(widget[Rect][1])
-    width = abs(float(widget[Rect][0]) - float(widget[Rect][2]))
-    height = abs(float(widget[Rect][1]) - float(widget[Rect][3]))
-
-    if preserve_aspect_ratio:
-        ratio = max(image_width / width, image_height / height)
-
-        new_width = image_width / ratio
-        new_height = image_height / ratio
-
-        x += abs(new_width - width) / 2
-        y += abs(new_height - height) / 2
-
-        width = new_width
-        height = new_height
-
-    return x, y, width, height
-
-
-def calculate_text_coord_x(
-    widget: dict,
-    widget_middleware: Text,
-    text_value: str,
-    length: int,
-    character_paddings: List[float],
-) -> float:
-    """
-    Calculate the horizontal (x) coordinate for text drawing within a PDF form field.
-
-    This function determines the x-coordinate based on:
-    - The widget's alignment setting (left, center, right)
-    - Whether the field uses comb formatting
-    - The width of the text string
-    - Character paddings for comb fields
-
-    Args:
-        widget: PDF form widget dictionary containing Rect and alignment info.
-        widget_middleware: Text middleware containing font and comb properties.
-        text_value: The text string to be drawn (already trimmed).
-        length: The length of the text string.
-        character_paddings: List of cumulative paddings for comb characters.
-
-    Returns:
-        float: The calculated x-coordinate for the text baseline start.
-    """
-
-    alignment = (
-        extract_widget_property(widget, WIDGET_ALIGNMENT_PATTERNS, None, int) or 0
-    )
-    # Default to left boundary
-    x = float(widget[Rect][0])
-
-    if int(alignment) == 0:
-        return x
-
-    # Calculate the horizontal midpoint of the widget rectangle
-    width_mid_point = (float(widget[Rect][0]) + float(widget[Rect][2])) / 2
-
-    # Calculate the width of the entire string in points
-    string_width = stringWidth(
-        text_value,
-        widget_middleware.font,
-        widget_middleware.font_size,
-    )
-
-    # If comb formatting, adjust string width to include last character's right padding
-    if widget_middleware.comb is True and length:
-        string_width = character_paddings[-1] + stringWidth(
-            text_value[-1],
-            widget_middleware.font,
-            widget_middleware.font_size,
-        )
-
-    if int(alignment) == 1:  # Center alignment
-        # Center text by offsetting half the string width from the midpoint
-        x = width_mid_point - string_width / 2
-    elif int(alignment) == 2:  # Right alignment
-        # Align text to the right edge minus the string width
-        x = float(widget[Rect][2]) - string_width
-        if length > 0 and widget_middleware.comb is True:
-            # For comb fields, adjust further by half the difference between comb box width and last character width
-            x -= (
-                get_char_rect_width(widget, widget_middleware)
-                - stringWidth(
-                    text_value[-1],
-                    widget_middleware.font,
-                    widget_middleware.font_size,
-                )
-            ) / 2
-
-    # Additional comb adjustment for center alignment
-    if int(alignment) == 1 and widget_middleware.comb is True and length != 0:
-        # Shift left by half the first character's padding
-        x -= character_paddings[0] / 2
-        if length % 2 == 0:
-            # For even-length comb text, shift further left by half the first char width plus padding
-            x -= (
-                character_paddings[0]
-                + stringWidth(
-                    text_value[:1],
-                    widget_middleware.font,
-                    widget_middleware.font_size,
-                )
-                / 2
-            )
-
-    return x
-
-
-def calculate_text_coord_y(widget: dict, widget_middleware: Text) -> float:
-    """
-    Calculate the vertical (y) coordinate for text drawing within a PDF form field.
-
-    This function determines the y-coordinate based on:
-    - The widget's rectangle height
-    - The font size
-    - Whether the field is multiline (which shifts text closer to the top)
-
-    Args:
-        widget: PDF form widget dictionary containing Rect info.
-        widget_middleware: Text middleware containing font size and multiline info.
-
-    Returns:
-        float: The calculated y-coordinate for the text baseline.
-    """
-
-    # Convert font size to PDF points (font size is in pixels, 96 dpi to 72 dpi)
-    string_height = widget_middleware.font_size * 96 / 72
-
-    # Calculate vertical midpoint of the widget rectangle
-    height_mid_point = (float(widget[Rect][1]) + float(widget[Rect][3])) / 2
-
-    # Default y: vertically center the text baseline within the widget
-    # This formula centers the text height around the vertical midpoint
-    y = (height_mid_point - string_height / 2 + height_mid_point) / 2
-
-    # If multiline, position baseline closer to the top edge for better appearance
-    if is_text_multiline(widget):
-        y = float(widget[Rect][3]) - string_height / 1.5
-
-    return y
-
-
-def get_draw_text_coordinates(
-    widget: dict, widget_middleware: Text
-) -> Tuple[Union[float, int], Union[float, int]]:
-    """
-    Calculate the (x, y) coordinates for drawing text within a PDF form field.
-
-    This function determines the starting position for rendering text,
-    taking into account:
-    - Preview mode (which offsets text above the field)
-    - Text length and wrapping
-    - Alignment (left, center, right)
-    - Comb formatting and character paddings
-    - Multiline adjustments for vertical position
-
-    Args:
-        widget: PDF form widget dictionary containing Rect and alignment info.
-        widget_middleware: Text middleware containing font, comb, and text properties.
-
-    Returns:
-        Tuple[Union[float, int], Union[float, int]]: The (x, y) coordinates
-            for the text baseline starting point.
-    """
-
-    # If preview mode, draw slightly above the top boundary for visibility
-    if widget_middleware.preview:
-        return (
-            float(widget[Rect][0]),
-            float(widget[Rect][3]) + 5,
-        )
-
-    # Prepare text value, respecting max length
-    text_value = widget_middleware.value or ""
-    length = (
-        min(len(text_value), widget_middleware.max_length)
-        if widget_middleware.max_length is not None
-        else len(text_value)
-    )
-    text_value = text_value[:length]
-
-    # Further trim text if wrapping is enabled
-    if widget_middleware.text_wrap_length is not None:
-        text_value = text_value[: widget_middleware.text_wrap_length]
-
-    # Prepare character paddings for comb fields
-    character_paddings = (
-        widget_middleware.character_paddings[:length]
-        if widget_middleware.character_paddings is not None
-        else widget_middleware.character_paddings
-    )
-
-    # Calculate horizontal position based on alignment and comb settings
-    x = calculate_text_coord_x(
-        widget, widget_middleware, text_value, length, character_paddings
-    )
-
-    # Calculate vertical position based on font size and multiline
-    y = calculate_text_coord_y(widget, widget_middleware)
-
-    return x, y
-
-
-def get_text_line_x_coordinates(
-    widget: dict, widget_middleware: Text
-) -> Union[List[float], None]:
-    """Calculates x-coordinates for each line in a multiline text field.
-
-    Args:
-        widget: PDF form widget dictionary
-        widget_middleware: Text middleware with text_lines property
-
-    Returns:
-        Union[List[float], None]: List of x-coordinates for each text line,
-            or None if not a multiline field
-    """
-
-    if (
-        widget_middleware.text_wrap_length is not None
-        and widget_middleware.text_lines is not None
-        and len(widget_middleware.text_lines)
-        and isinstance(widget_middleware.value, str)
-        and len(widget_middleware.value) > widget_middleware.text_wrap_length
-    ):
-        result = []
-        _widget = deepcopy(widget_middleware)
-        for each in widget_middleware.text_lines:
-            _widget.value = each
-            _widget.text_wrap_length = None
-            result.append(get_draw_text_coordinates(widget, _widget)[0])
-
-        return result
-
-    return None
-
-
 def generate_coordinate_grid(
     pdf: bytes, color: Tuple[float, float, float], margin: float
 ) -> bytes:
-    """Generates a coordinate grid overlay for a PDF document.
+    """
+    Generates a coordinate grid overlay on a PDF document.
+
+    This function takes a PDF file as bytes, along with a color and margin, and generates
+    a coordinate grid on each page of the PDF. The grid consists of lines and text indicating
+    the X and Y coordinates. This can be useful for visualizing the layout and positioning
+    elements on the PDF.
 
     Args:
-        pdf: Input PDF document as bytes
-        color: RGB tuple (0-1 range) for grid line color
-        margin: Spacing between grid lines in PDF points
+        pdf (bytes): The PDF file as bytes.
+        color (Tuple[float, float, float]): The color of the grid lines and text as a tuple of RGB values (0.0-1.0).
+                                            For example, (0.0, 0.0, 0.0) represents black.
+        margin (float): The margin between the grid lines and the edge of the page, in points.
+                        This value determines the spacing of the grid.
 
     Returns:
-        bytes: New PDF with grid overlay as byte stream
+        bytes: The PDF file with the coordinate grid overlay as bytes.
     """
-
     pdf_file = PdfReader(stream_to_io(pdf))
     lines_by_page = {}
     texts_by_page = {}
@@ -418,8 +50,6 @@ def generate_coordinate_grid(
         width = float(page.mediabox[2])
         height = float(page.mediabox[3])
 
-        r, g, b = color
-
         current = margin
         while current < width:
             lines_by_page[i + 1].append(
@@ -428,10 +58,7 @@ def generate_coordinate_grid(
                     "src_y": 0,
                     "dest_x": current,
                     "dest_y": height,
-                    "border_color": handle_color([r, g, b]),
-                    "background_color": None,
-                    "border_width": 1,
-                    "dash_array": None,
+                    "color": color,
                 }
             )
             current += margin
@@ -444,10 +71,7 @@ def generate_coordinate_grid(
                     "src_y": current,
                     "dest_x": width,
                     "dest_y": current,
-                    "border_color": handle_color([r, g, b]),
-                    "background_color": None,
-                    "border_width": 1,
-                    "dash_array": None,
+                    "color": color,
                 }
             )
             current += margin