PyPDFForm 2.4.0__tar.gz → 3.0.0__tar.gz

{pypdfform-2.4.0 → pypdfform-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 2.4.0
+Version: 3.0.0
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -42,7 +42,7 @@ Dynamic: license-file
 <p align="center">
     <a href="https://pypi.org/project/PyPDFForm/"><img src="https://img.shields.io/pypi/v/pypdfform?logo=pypi&logoColor=white&label=version&labelColor=black&color=magenta&style=for-the-badge"></a>
     <a href="https://chinapandaman.github.io/PyPDFForm/"><img src="https://img.shields.io/github/v/release/chinapandaman/pypdfform?logo=read%20the%20docs&logoColor=white&label=docs&labelColor=black&color=cyan&style=for-the-badge"></a>
-    <a href="https://github.com/chinapandaman/PyPDFForm/actions/workflows/python-package.yml"><img src="https://img.shields.io/github/actions/workflow/status/chinapandaman/pypdfform/python-package.yml?logo=github&logoColor=white&label=tests&labelColor=black&color=green&style=for-the-badge"></a>
+    <a href="https://github.com/chinapandaman/PyPDFForm/actions/workflows/python-package.yml"><img src="https://img.shields.io/badge/coverage-100%25-green?logo=codecov&logoColor=white&labelColor=black&style=for-the-badge"></a>
     <a href="https://github.com/chinapandaman/PyPDFForm/raw/master/LICENSE"><img src="https://img.shields.io/github/license/chinapandaman/pypdfform?logo=github&logoColor=white&label=license&labelColor=black&color=orange&style=for-the-badge"></a>
     <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/pypi/pyversions/pypdfform?logo=python&logoColor=white&label=python&labelColor=black&color=gold&style=for-the-badge"></a>
     <a href="https://pypistats.org/packages/pypdfform"><img src="https://img.shields.io/pypi/dm/pypdfform?logo=pypi&logoColor=white&label=downloads&labelColor=black&color=blue&style=for-the-badge"></a>
@@ -55,7 +55,7 @@ functionalities needed to interact with PDF forms:
 
 * Inspect what data a PDF form needs to be filled with.
 * Fill a PDF form by simply creating a Python dictionary.
-* Create a subset of form widgets on a PDF.
+* Create form fields on a PDF.
 
 It also supports other common utilities such as extracting pages and merging multiple PDFs together.
 
@@ -75,7 +75,7 @@ A sample PDF form can be found [here](https://github.com/chinapandaman/PyPDFForm
 ```python
 from PyPDFForm import PdfWrapper
 
-filled = PdfWrapper("sample_template.pdf").fill(
+filled = PdfWrapper("sample_template.pdf", adobe_mode=True).fill(
     {
         "test": "test_1",
         "check": True,
@@ -86,12 +86,11 @@ filled = PdfWrapper("sample_template.pdf").fill(
     },
 )
 
-with open("output.pdf", "wb+") as output:
-    output.write(filled.read())
+filled.write("output.pdf")
 ```
 
 After running the above code snippet you can find `output.pdf` at the location you specified, 
-and it should look like [this](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_filled.pdf).
+and it should look like [this](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/adobe_mode/sample_filled.pdf).
 
 ## Documentation
 

pypdfform-3.0.0/PyPDFForm/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""
+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.
+
+PyPDFForm aims to simplify PDF form manipulation, making it accessible to developers of all skill levels.
+"""
+
+__version__ = "3.0.0"
+
+from .middleware.text import Text  # exposing for setting global font attrs
+from .wrapper import PdfWrapper
+
+__all__ = ["PdfWrapper", "Text"]

pypdfform-3.0.0/PyPDFForm/adapter.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""
+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
+from typing import Any, BinaryIO, Union
+
+
+def readable(obj: Any) -> bool:
+    """
+    Check if an object has a readable "read" attribute.
+
+    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 (Any): The object to check for a readable "read" attribute.
+
+    Returns:
+        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:
+    """
+    Adapt a file path, file object, or stream to a byte stream.
+
+    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 (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 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
+
+    elif readable(fp_or_f_obj_or_stream):
+        result = fp_or_f_obj_or_stream.read()
+
+    elif isinstance(fp_or_f_obj_or_stream, str):
+        if not isfile(fp_or_f_obj_or_stream):
+            pass
+        else:
+            with open(fp_or_f_obj_or_stream, "rb+") as _file:
+                result = _file.read()
+    return result

{pypdfform-2.4.0 → pypdfform-3.0.0}/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-3.0.0/PyPDFForm/coordinate.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""
+Module for generating coordinate grids on PDFs.
+
+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 typing import Tuple
+
+from pypdf import PdfReader
+from reportlab.pdfbase.pdfmetrics import stringWidth
+
+from .constants import COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO, DEFAULT_FONT
+from .middleware.text import Text
+from .utils import stream_to_io
+from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
+
+
+def generate_coordinate_grid(
+    pdf: bytes, color: Tuple[float, float, float], margin: float
+) -> bytes:
+    """
+    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 (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: The PDF file with the coordinate grid overlay as bytes.
+    """
+    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] = []
+        texts_by_page[i + 1] = []
+        width = float(page.mediabox[2])
+        height = float(page.mediabox[3])
+
+        current = margin
+        while current < width:
+            lines_by_page[i + 1].append(
+                {
+                    "src_x": current,
+                    "src_y": 0,
+                    "dest_x": current,
+                    "dest_y": height,
+                    "color": color,
+                }
+            )
+            current += margin
+
+        current = margin
+        while current < height:
+            lines_by_page[i + 1].append(
+                {
+                    "src_x": 0,
+                    "src_y": current,
+                    "dest_x": width,
+                    "dest_y": current,
+                    "color": color,
+                }
+            )
+            current += margin
+
+        x = margin
+        while x < width:
+            y = margin
+            while y < height:
+                value = f"({x}, {y})"
+                font_size = margin * COORDINATE_GRID_FONT_SIZE_MARGIN_RATIO
+                text = Text("new_coordinate", value)
+                text.font = DEFAULT_FONT
+                text.font_size = font_size
+                text.font_color = color
+                texts_by_page[i + 1].append(
+                    {
+                        "widget": text,
+                        "x": x - stringWidth(value, DEFAULT_FONT, font_size),
+                        "y": y - font_size,
+                    }
+                )
+                y += margin
+            x += margin
+
+    for page, lines in lines_by_page.items():
+        watermarks.append(
+            create_watermarks_and_draw(pdf, page, "line", lines)[page - 1]
+        )
+
+    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]
+        )
+
+    return merge_watermarks_with_pdf(result, watermarks)

pypdfform-3.0.0/PyPDFForm/filler.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""
+Module containing functions to fill PDF forms.
+
+This module provides the core functionality for filling PDF forms programmatically.
+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.
+"""
+
+from io import BytesIO
+from typing import Dict, Union, cast
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.generic import DictionaryObject
+
+from .constants import WIDGET_TYPES, Annots
+from .image import get_draw_image_resolutions, get_image_dimensions
+from .middleware.checkbox import Checkbox
+from .middleware.dropdown import Dropdown
+from .middleware.image import Image
+from .middleware.radio import Radio
+from .middleware.signature import Signature
+from .middleware.text import Text
+from .patterns import (flatten_generic, flatten_radio, update_checkbox_value,
+                       update_dropdown_value, update_radio_value,
+                       update_text_value)
+from .template import get_widget_key
+from .utils import stream_to_io
+from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
+
+
+def signature_image_handler(
+    widget: dict, middleware: Union[Signature, Image], images_to_draw: list
+) -> bool:
+    """Handles signature and image widgets by extracting image data and preparing it for drawing.
+
+    This function processes signature and image widgets found in a PDF form. It extracts the
+    image data from the widget's middleware and prepares it for drawing on the form. The
+    function calculates the position and dimensions of the image based on the widget's
+    properties and the `preserve_aspect_ratio` setting. The image data is then stored in a
+    list for later drawing.
+
+    Args:
+        widget (dict): The widget dictionary representing the signature or image field.
+        middleware (Union[Signature, Image]): The middleware object containing the image data and properties.
+        images_to_draw (list): A list to store image data for drawing.
+
+    Returns:
+        bool: True if any image is to be drawn, False otherwise.
+    """
+    stream = middleware.stream
+    any_image_to_draw = False
+    if stream is not None:
+        any_image_to_draw = True
+        image_width, image_height = get_image_dimensions(stream)
+        x, y, width, height = get_draw_image_resolutions(
+            widget, middleware.preserve_aspect_ratio, image_width, image_height
+        )
+        images_to_draw.append(
+            {
+                "stream": stream,
+                "x": x,
+                "y": y,
+                "width": width,
+                "height": height,
+            }
+        )
+
+    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],
+    use_full_widget_name: bool,
+    flatten: bool = False,
+) -> tuple:
+    """Fills a PDF template with the given widgets.
+
+    This function fills a PDF template with the provided widget values. It iterates through the
+    widgets on each page of the PDF and updates their values based on the provided `widgets`
+    dictionary. The function supports various widget types, including text fields, checkboxes,
+    radio buttons, dropdowns, images, and signatures. It also supports flattening the filled
+    form to prevent further modifications.
+
+    Args:
+        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.
+        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.
+
+    Returns:
+        tuple: A tuple containing the filled PDF as bytes and the image drawn stream as bytes, if any.
+               The image drawn stream is only returned if there are any image or signature widgets
+               in the form.
+    """
+    pdf = PdfReader(stream_to_io(template))
+    out = PdfWriter()
+    out.append(pdf)
+
+    radio_button_tracker = {}
+    images_to_draw = {}
+    any_image_to_draw = False
+
+    for page_num, page in enumerate(out.pages):
+        images_to_draw[page_num + 1] = []
+        for annot in page.get(Annots, []):
+            annot = cast(DictionaryObject, annot.get_object())
+            key = get_widget_key(annot.get_object(), use_full_widget_name)
+
+            widget = widgets.get(key)
+            if widget is None:
+                continue
+
+            # flatten all
+            if flatten:
+                (flatten_radio if isinstance(widget, Radio) else flatten_generic)(annot)
+            if widget.value is None:
+                continue
+
+            if isinstance(widgets[key], (Signature, Image)):
+                any_image_to_draw |= signature_image_handler(
+                    annot, widgets[key], images_to_draw[page_num + 1]
+                )
+            elif type(widget) is Checkbox:
+                update_checkbox_value(annot, widget.value)
+            elif isinstance(widget, Radio):
+                if key not in radio_button_tracker:
+                    radio_button_tracker[key] = 0
+                radio_button_tracker[key] += 1
+                if widget.value == radio_button_tracker[key] - 1:
+                    update_radio_value(annot)
+            elif isinstance(widget, Dropdown):
+                update_dropdown_value(annot, widget)
+            elif isinstance(widget, Text):
+                update_text_value(annot, widget)
+
+    with BytesIO() as f:
+        out.write(f)
+        f.seek(0)
+        result = f.read()
+
+    return result, (
+        get_drawn_stream(images_to_draw, result, "image") if any_image_to_draw else None
+    )