PyPDFForm 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

PyPDFForm/__init__.py

@@ -1,7 +1,11 @@
 # -*- coding: utf-8 -*-
-"""Contains any object users might need."""
+"""PyPDFForm package for PDF form filling and manipulation.
 
-__version__ = "2.0.0"
+This package provides tools for filling PDF forms, drawing text and images,
+and manipulating PDF form elements programmatically.
+"""
+
+__version__ = "2.1.0"
 
 from .wrapper import FormWrapper, PdfWrapper
 

PyPDFForm/adapter.py

@@ -1,12 +1,31 @@
 # -*- coding: utf-8 -*-
-"""Contains user input adapters."""
+"""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.
+"""
 
 from os.path import isfile
 from typing import Any, BinaryIO, Union
 
 
 def readable(obj: Any) -> bool:
-    """Checks if an object is readable."""
+    """Determines if an object is file-like and readable.
+
+    Checks if the object has a callable read() method, indicating it can be
+    treated as a file-like object for reading operations.
+
+    Args:
+        obj: The object to check for read capability
+
+    Returns:
+        bool: True if the object has a callable read() method, False otherwise
+    """
 
     return callable(getattr(obj, "read", None))
 
@@ -14,7 +33,22 @@ def readable(obj: Any) -> bool:
 def fp_or_f_obj_or_stream_to_stream(
     fp_or_f_obj_or_stream: Union[bytes, str, BinaryIO],
 ) -> bytes:
-    """Converts a file path or a file object to a stream."""
+    """Converts various file input types to a byte stream.
+
+    Handles conversion of:
+    - Raw bytes (passed through unchanged)
+    - File paths (reads file contents)
+    - File-like objects (reads using read() method)
+
+    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
+
+    Returns:
+        bytes: The PDF data as a byte stream
+    """
 
     result = b""
     if isinstance(fp_or_f_obj_or_stream, bytes):

PyPDFForm/constants.py

@@ -1,5 +1,16 @@
 # -*- coding: utf-8 -*-
-"""Contains library constants."""
+"""Centralized location for all PyPDFForm constants and default values.
+
+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
+
+All constants are organized by category and used consistently across the package.
+"""
 
 from typing import Union
 

PyPDFForm/coordinate.py

@@ -1,5 +1,17 @@
 # -*- coding: utf-8 -*-
-"""Contains helpers for coordinates calculations."""
+"""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
+
+All calculations work in PDF coordinate space where:
+- Origin (0,0) is at bottom-left corner
+- Units are in PDF points (1/72 inch)
+"""
 
 from copy import deepcopy
 from typing import List, Tuple, Union
@@ -17,7 +29,17 @@ from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
 
 
 def get_draw_border_coordinates(widget: dict, shape: str) -> List[float]:
-    """Returns coordinates to draw each widget's border."""
+    """Calculates coordinates for drawing widget borders.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+        shape: Type of border to draw ("rectangle", "ellipse" or "line")
+
+    Returns:
+        List[float]: Coordinates in format [x1, y1, x2, y2] for the border
+            For ellipses: [center_x, center_y, radius_x, radius_y]
+            For lines: [x1, y1, x2, y2] endpoints
+    """
 
     result = [
         float(widget[Rect][0]),
@@ -57,7 +79,17 @@ def get_draw_checkbox_radio_coordinates(
     widget_middleware: Text,
     border_width: int,
 ) -> Tuple[Union[float, int], Union[float, int]]:
-    """Returns coordinates to draw at given a PDF form checkbox/radio widget."""
+    """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
@@ -83,8 +115,18 @@ def get_draw_image_coordinates_resolutions(
     image_width: float,
     image_height: float,
 ) -> Tuple[float, float, float, float]:
-    """
-    Returns coordinates and resolutions to draw image at given a PDF form signature/image widget.
+    """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])
@@ -107,17 +149,161 @@ def get_draw_image_coordinates_resolutions(
     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]]:
-    """Returns coordinates to draw text at given a PDF form text widget."""
+    """
+    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)
@@ -126,66 +312,24 @@ def get_draw_text_coordinates(
     )
     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
     )
 
-    alignment = (
-        extract_widget_property(widget, WIDGET_ALIGNMENT_PATTERNS, None, int) or 0
+    # Calculate horizontal position based on alignment and comb settings
+    x = calculate_text_coord_x(
+        widget, widget_middleware, text_value, length, character_paddings
     )
-    x = float(widget[Rect][0])
-
-    if int(alignment) != 0:
-        width_mid_point = (float(widget[Rect][0]) + float(widget[Rect][2])) / 2
-        string_width = stringWidth(
-            text_value,
-            widget_middleware.font,
-            widget_middleware.font_size,
-        )
-        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:
-            x = width_mid_point - string_width / 2
-        elif int(alignment) == 2:
-            x = float(widget[Rect][2]) - string_width
-            if length > 0 and widget_middleware.comb is True:
-                x -= (
-                    get_char_rect_width(widget, widget_middleware)
-                    - stringWidth(
-                        text_value[-1],
-                        widget_middleware.font,
-                        widget_middleware.font_size,
-                    )
-                ) / 2
-
-    string_height = widget_middleware.font_size * 96 / 72
-    height_mid_point = (float(widget[Rect][1]) + float(widget[Rect][3])) / 2
-    y = (height_mid_point - string_height / 2 + height_mid_point) / 2
-    if is_text_multiline(widget):
-        y = float(widget[Rect][3]) - string_height / 1.5
-
-    if int(alignment) == 1 and widget_middleware.comb is True and length != 0:
-        x -= character_paddings[0] / 2
-        if length % 2 == 0:
-            x -= (
-                character_paddings[0]
-                + stringWidth(
-                    text_value[:1],
-                    widget_middleware.font,
-                    widget_middleware.font_size,
-                )
-                / 2
-            )
+    # Calculate vertical position based on font size and multiline
+    y = calculate_text_coord_y(widget, widget_middleware)
 
     return x, y
 
@@ -193,9 +337,15 @@ def get_draw_text_coordinates(
 def get_text_line_x_coordinates(
     widget: dict, widget_middleware: Text
 ) -> Union[List[float], None]:
-    """
-    Returns the x coordinates to draw lines
-    of the text at given a PDF form paragraph widget.
+    """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 (
@@ -220,7 +370,16 @@ def get_text_line_x_coordinates(
 def generate_coordinate_grid(
     pdf: bytes, color: Tuple[float, float, float], margin: float
 ) -> bytes:
-    """Creates a grid view for the coordinates of a PDF."""
+    """Generates a coordinate grid overlay for a PDF document.
+
+    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
+
+    Returns:
+        bytes: New PDF with grid overlay as byte stream
+    """
 
     pdf_file = PdfReader(stream_to_io(pdf))
     lines_by_page = {}

PyPDFForm/filler.py

@@ -1,5 +1,16 @@
 # -*- coding: utf-8 -*-
-"""Contains helpers for filling a PDF form."""
+"""Provides core functionality for filling PDF form fields.
+
+This module handles:
+- Drawing text, images, borders and other elements onto PDF forms
+- Managing widget states and appearances
+- Supporting different filling modes (simple vs watermark-based)
+- Handling special cases like checkboxes, radio buttons and signatures
+
+The main functions are:
+- fill(): Uses watermark technique for complex form filling
+- simple_fill(): Directly modifies form fields for simpler cases
+"""
 
 from io import BytesIO
 from typing import Dict, Tuple, Union, cast
@@ -35,7 +46,20 @@ from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
 def check_radio_handler(
     widget: dict, middleware: Union[Checkbox, Radio], radio_button_tracker: dict
 ) -> Tuple[Text, Union[float, int], Union[float, int], bool]:
-    """Handles draw parameters for checkbox and radio button widgets."""
+    """Calculates drawing parameters for checkbox and radio button widgets.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+        middleware: Checkbox or Radio middleware instance
+        radio_button_tracker: Dictionary tracking radio button group states
+
+    Returns:
+        Tuple containing:
+        - Text: Prepared text object for drawing the symbol
+        - float/int: x coordinate for drawing
+        - float/int: y coordinate for drawing
+        - bool: Whether the symbol needs to be drawn
+    """
 
     font_size = (
         checkbox_radio_font_size(widget) if middleware.size is None else middleware.size
@@ -60,7 +84,16 @@ def check_radio_handler(
 def signature_image_handler(
     widget: dict, middleware: Union[Signature, Image], images_to_draw: list
 ) -> bool:
-    """Handles draw parameters for signature and image widgets."""
+    """Prepares image data for signature and image widgets.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+        middleware: Signature or Image middleware instance
+        images_to_draw: List to append image drawing parameters to
+
+    Returns:
+        bool: True if an image needs to be drawn, False otherwise
+    """
 
     stream = middleware.stream
     any_image_to_draw = False
@@ -86,7 +119,19 @@ def signature_image_handler(
 def text_handler(
     widget: dict, middleware: Text
 ) -> Tuple[Text, Union[float, int], Union[float, int], bool]:
-    """Handles draw parameters for text field widgets."""
+    """Prepares text field drawing parameters.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect and properties
+        middleware: Text middleware instance with text properties
+
+    Returns:
+        Tuple containing:
+        - Text: The text middleware to draw
+        - float/int: x coordinate for drawing
+        - float/int: y coordinate for drawing
+        - bool: Always True for text fields (they always need drawing)
+    """
 
     middleware.text_line_x_coordinates = get_text_line_x_coordinates(widget, middleware)
     x, y = get_draw_text_coordinates(widget, middleware)
@@ -103,7 +148,15 @@ def border_handler(
     ellipse_borders_to_draw: list,
     line_borders_to_draw: list,
 ) -> None:
-    """Handles draw parameters for each widget's border."""
+    """Prepares border drawing parameters for widgets.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+        middleware: Any widget middleware instance
+        rect_borders_to_draw: List to append rectangle border parameters to
+        ellipse_borders_to_draw: List to append ellipse border parameters to
+        line_borders_to_draw: List to append line border parameters to
+    """
 
     if (
         isinstance(middleware, Radio)
@@ -136,7 +189,16 @@ def border_handler(
 
 
 def get_drawn_stream(to_draw: dict, stream: bytes, action: str) -> bytes:
-    """Generates a stream of an input PDF stream with stuff drawn on it."""
+    """Applies drawing operations to a PDF stream.
+
+    Args:
+        to_draw: Dictionary mapping page numbers to drawing parameters
+        stream: Input PDF as bytes
+        action: Type of drawing operation ('text', 'image', 'rect', etc.)
+
+    Returns:
+        bytes: Modified PDF with drawings applied
+    """
 
     watermark_list = []
     for page, stuffs in to_draw.items():
@@ -153,7 +215,20 @@ def fill(
     template_stream: bytes,
     widgets: Dict[str, WIDGET_TYPES],
 ) -> bytes:
-    """Fills a PDF using watermarks."""
+    """Fills a PDF form using watermark technique for complex rendering.
+
+    This method:
+    - Handles text, images, borders for all widget types
+    - Preserves original form fields while adding visual elements
+    - Supports complex cases like multiline text and image scaling
+
+    Args:
+        template_stream: Input PDF form as bytes
+        widgets: Dictionary mapping field names to widget middleware
+
+    Returns:
+        bytes: Filled PDF form as bytes
+    """
 
     texts_to_draw = {}
     images_to_draw = {}
@@ -226,7 +301,12 @@ def fill(
 
 
 def enable_adobe_mode(pdf: PdfReader, adobe_mode: bool) -> None:
-    """Enables Adobe mode so that texts filled can show up in Acrobat."""
+    """Configures PDF for Adobe Acrobat compatibility.
+
+    Args:
+        pdf: PdfReader instance of the PDF
+        adobe_mode: If True, sets NeedAppearances flag for Acrobat
+    """
 
     if adobe_mode and AcroForm in pdf.trailer[Root]:
         pdf.trailer[Root][AcroForm].update(
@@ -240,7 +320,22 @@ def simple_fill(
     flatten: bool = False,
     adobe_mode: bool = False,
 ) -> bytes:
-    """Fills a PDF form in place."""
+    """Fills a PDF form by directly modifying form fields.
+
+    This method:
+    - Updates field values directly in the PDF
+    - Supports flattening to make fields read-only
+    - Works with Adobe Acrobat compatibility mode
+
+    Args:
+        template: Input PDF form as bytes
+        widgets: Dictionary mapping field names to widget middleware
+        flatten: If True, makes form fields read-only
+        adobe_mode: If True, enables Adobe Acrobat compatibility
+
+    Returns:
+        bytes: Filled PDF form as bytes
+    """
 
     pdf = PdfReader(stream_to_io(template))
     enable_adobe_mode(pdf, adobe_mode)