PyPDFForm 1.3.5__tar.gz → 1.4.0__tar.gz

{PyPDFForm-1.3.5 → PyPDFForm-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyPDFForm
-Version: 1.3.5
+Version: 1.4.0
 Summary: The Python library for PDF forms.
 Home-page: https://github.com/chinapandaman/PyPDFForm
 Author: Jinge Li
@@ -24,12 +24,28 @@ Requires-Dist: reportlab
     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-orange.svg"></a>
 </p>
 
+## Important API Changes
+
+Happy new year fellow developers! We start the year 2024 with a new release of v1.4.0 and 
+there are some important changes I'm making to the APIs of the library.
+
+* The PDF object that gets instantiated is now `PyPDFForm.PdfWrapper`, changed from `PyPDFForm.PyPDFForm`.
+* Form widgets are now accessed via the `PdfWrapper.widgets` attribute, changed from `PdfWrapper.elements`.
+* The JSON schema of the form data is now accessed via a new attribute called `PdfWrapper.schema`, 
+changed from the old method of `PdfWrapper.generate_schema()`.
+
+All the old APIs will be persisted for half a year and then fully deprecated. Each of them 
+will emit a `DeprecationWarning` when invoked, so it is advised that you make the switch before they are 
+removed and start breaking your code.
+
+Happy hacking!
+
 ## Introduction
 
 PyPDFForm is a pure Python library for PDF form processing. 
 It allows filling a PDF form programmatically by creating 
 a Python dictionary with keys matching its annotated names 
-for elements like text fields and checkboxes. It also supports other functionalities such as 
+for widgets like text fields and checkboxes. It also supports other functionalities such as 
 drawing image and merging multiple PDFs together.
 
 ## Installing
@@ -48,7 +64,7 @@ A sample PDF form can be found [here](https://github.com/chinapandaman/PyPDFForm
 ```python
 import os
 
-from PyPDFForm import PyPDFForm
+from PyPDFForm import PdfWrapper
 
 PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
     os.path.expanduser("~/Downloads"), "sample_template.pdf"
@@ -60,7 +76,7 @@ PATH_TO_FILLED_PDF_FORM = os.path.join(
 
 with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
     output.write(
-        PyPDFForm(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM)
+        PdfWrapper(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM)
         .fill(
             {
                 "test": "test_1",

PyPDFForm-1.4.0/PyPDFForm/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""Contains any object users might need."""
+
+__version__ = "1.4.0"
+
+from .wrapper import PdfWrapper, PyPDFForm

{PyPDFForm-1.3.5 → PyPDFForm-1.4.0}/PyPDFForm/core/constants.py

@@ -6,7 +6,7 @@ ANNOTATION_FIELD_KEY = "/T"
 ANNOTATION_RECTANGLE_KEY = "/Rect"
 SUBTYPE_KEY = "/Subtype"
 WIDGET_SUBTYPE_KEY = "/Widget"
-ELEMENT_TYPE_KEY = "/FT"
+WIDGET_TYPE_KEY = "/FT"
 PARENT_KEY = "/Parent"
 FIELD_FLAG_KEY = "/Ff"
 TEXT_FIELD_IDENTIFIER = "/Tx"

PyPDFForm-1.4.0/PyPDFForm/core/coordinate.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""Contains helpers for coordinates calculations."""
+
+from copy import deepcopy
+from typing import List, Tuple, Union
+
+from pdfrw import PdfDict
+from reportlab.pdfbase.pdfmetrics import stringWidth
+
+from ..middleware.text import Text
+from .constants import ANNOTATION_RECTANGLE_KEY
+from .template import (get_char_rect_width, get_widget_alignment,
+                       is_text_multiline)
+
+
+def get_draw_checkbox_radio_coordinates(
+    widget: PdfDict,
+    widget_middleware: Text,
+) -> Tuple[Union[float, int], Union[float, int]]:
+    """Returns coordinates to draw at given a PDF form checkbox/radio widget."""
+
+    string_height = widget_middleware.font_size * 96 / 72
+    width_mid_point = (
+        float(widget[ANNOTATION_RECTANGLE_KEY][0])
+        + float(widget[ANNOTATION_RECTANGLE_KEY][2])
+    ) / 2
+    height_mid_point = (
+        float(widget[ANNOTATION_RECTANGLE_KEY][1])
+        + float(widget[ANNOTATION_RECTANGLE_KEY][3])
+    ) / 2
+
+    return (
+        width_mid_point
+        - stringWidth(
+            widget_middleware.value,
+            widget_middleware.font,
+            widget_middleware.font_size,
+        )
+        / 2,
+        (height_mid_point - string_height / 2 + height_mid_point) / 2,
+    )
+
+
+def get_draw_text_coordinates(
+    widget: PdfDict, widget_middleware: Text
+) -> Tuple[Union[float, int], Union[float, int]]:
+    """Returns coordinates to draw text at given a PDF form text widget."""
+
+    if widget_middleware.preview:
+        return (
+            float(widget[ANNOTATION_RECTANGLE_KEY][0]),
+            float(widget[ANNOTATION_RECTANGLE_KEY][3]) + 5,
+        )
+
+    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]
+
+    if widget_middleware.text_wrap_length is not None:
+        text_value = text_value[: widget_middleware.text_wrap_length]
+
+    character_paddings = (
+        widget_middleware.character_paddings[:length]
+        if widget_middleware.character_paddings is not None
+        else widget_middleware.character_paddings
+    )
+
+    alignment = get_widget_alignment(widget) or 0
+    x = float(widget[ANNOTATION_RECTANGLE_KEY][0])
+
+    if int(alignment) != 0:
+        width_mid_point = (
+            float(widget[ANNOTATION_RECTANGLE_KEY][0])
+            + float(widget[ANNOTATION_RECTANGLE_KEY][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[ANNOTATION_RECTANGLE_KEY][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[ANNOTATION_RECTANGLE_KEY][1])
+        + float(widget[ANNOTATION_RECTANGLE_KEY][3])
+    ) / 2
+    y = (height_mid_point - string_height / 2 + height_mid_point) / 2
+    if is_text_multiline(widget):
+        y = float(widget[ANNOTATION_RECTANGLE_KEY][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
+            )
+
+    return x, y
+
+
+def get_text_line_x_coordinates(
+    widget: PdfDict, widget_middleware: Text
+) -> Union[List[float], None]:
+    """
+    Returns the x coordinates to draw lines
+    of the text at given a PDF form paragraph widget.
+    """
+
+    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

{PyPDFForm-1.3.5 → PyPDFForm-1.4.0}/PyPDFForm/core/filler.py

@@ -6,20 +6,20 @@ from typing import Dict
 from pdfrw import PdfReader
 
 from ..middleware.checkbox import Checkbox
-from ..middleware.constants import ELEMENT_TYPES
+from ..middleware.constants import WIDGET_TYPES
 from ..middleware.radio import Radio
 from .coordinate import (get_draw_checkbox_radio_coordinates,
                          get_draw_text_coordinates,
                          get_text_line_x_coordinates)
 from .font import checkbox_radio_font_size
-from .template import get_element_key, get_elements_by_page
+from .template import get_widget_key, get_widgets_by_page
 from .utils import checkbox_radio_to_draw, generate_stream
 from .watermark import create_watermarks_and_draw, merge_watermarks_with_pdf
 
 
 def fill(
     template_stream: bytes,
-    elements: Dict[str, ELEMENT_TYPES],
+    widgets: Dict[str, WIDGET_TYPES],
 ) -> bytes:
     """Fills a PDF using watermarks."""
 
@@ -30,31 +30,31 @@ def fill(
 
     radio_button_tracker = {}
 
-    for page, _elements in get_elements_by_page(template_pdf).items():
+    for page, _widgets in get_widgets_by_page(template_pdf).items():
         texts_to_draw[page] = []
         text_watermarks.append(b"")
-        for _element in _elements:
-            key = get_element_key(_element)
+        for _widget in _widgets:
+            key = get_widget_key(_widget)
             needs_to_be_drawn = False
 
-            if isinstance(elements[key], (Checkbox, Radio)):
-                font_size = checkbox_radio_font_size(_element)
-                _to_draw = checkbox_radio_to_draw(elements[key], font_size)
-                x, y = get_draw_checkbox_radio_coordinates(_element, _to_draw)
-                if isinstance(elements[key], Checkbox) and elements[key].value:
+            if isinstance(widgets[key], (Checkbox, Radio)):
+                font_size = checkbox_radio_font_size(_widget)
+                _to_draw = checkbox_radio_to_draw(widgets[key], font_size)
+                x, y = get_draw_checkbox_radio_coordinates(_widget, _to_draw)
+                if isinstance(widgets[key], Checkbox) and widgets[key].value:
                     needs_to_be_drawn = True
-                elif isinstance(elements[key], Radio):
+                elif isinstance(widgets[key], Radio):
                     if key not in radio_button_tracker:
                         radio_button_tracker[key] = 0
                     radio_button_tracker[key] += 1
-                    if elements[key].value == radio_button_tracker[key] - 1:
+                    if widgets[key].value == radio_button_tracker[key] - 1:
                         needs_to_be_drawn = True
             else:
-                elements[key].text_line_x_coordinates = get_text_line_x_coordinates(
-                    _element, elements[key]
+                widgets[key].text_line_x_coordinates = get_text_line_x_coordinates(
+                    _widget, widgets[key]
                 )
-                x, y = get_draw_text_coordinates(_element, elements[key])
-                _to_draw = elements[key]
+                x, y = get_draw_text_coordinates(_widget, widgets[key])
+                _to_draw = widgets[key]
                 needs_to_be_drawn = True
 
             if needs_to_be_drawn:

{PyPDFForm-1.3.5 → PyPDFForm-1.4.0}/PyPDFForm/core/font.py

@@ -10,15 +10,14 @@ from pdfrw import PdfDict, PdfReader
 from reportlab.pdfbase.pdfmetrics import registerFont, standardFonts
 from reportlab.pdfbase.ttfonts import TTFError, TTFont
 
-from ..middleware.constants import ELEMENT_TYPES
+from ..middleware.constants import WIDGET_TYPES
 from ..middleware.text import Text
 from .constants import (ANNOTATION_RECTANGLE_KEY, DEFAULT_FONT,
                         DEFAULT_FONT_SIZE, FONT_COLOR_IDENTIFIER,
                         FONT_SIZE_IDENTIFIER)
 from .patterns import TEXT_FIELD_APPEARANCE_PATTERNS
-from .template import (get_element_key, get_elements_by_page,
-                       get_paragraph_auto_wrap_length, get_paragraph_lines,
-                       is_text_multiline)
+from .template import (get_paragraph_auto_wrap_length, get_paragraph_lines,
+                       get_widget_key, get_widgets_by_page, is_text_multiline)
 from .utils import traverse_pattern
 
 
@@ -39,14 +38,14 @@ def register_font(font_name: str, ttf_stream: bytes) -> bool:
     return result
 
 
-def auto_detect_font(element: PdfDict) -> str:
+def auto_detect_font(widget: PdfDict) -> str:
     """Returns the font of the text field if it is one of the standard fonts."""
 
     result = DEFAULT_FONT
 
     text_appearance = None
     for pattern in TEXT_FIELD_APPEARANCE_PATTERNS:
-        text_appearance = traverse_pattern(pattern, element)
+        text_appearance = traverse_pattern(pattern, widget)
 
         if text_appearance:
             break
@@ -76,46 +75,46 @@ def auto_detect_font(element: PdfDict) -> str:
     return result
 
 
-def text_field_font_size(element: PdfDict) -> Union[float, int]:
+def text_field_font_size(widget: PdfDict) -> Union[float, int]:
     """
     Calculates the font size it should be drawn with
-    given a text field element.
+    given a text field widget.
     """
 
-    if is_text_multiline(element):
+    if is_text_multiline(widget):
         return DEFAULT_FONT_SIZE
 
     height = abs(
-        float(element[ANNOTATION_RECTANGLE_KEY][1])
-        - float(element[ANNOTATION_RECTANGLE_KEY][3])
+        float(widget[ANNOTATION_RECTANGLE_KEY][1])
+        - float(widget[ANNOTATION_RECTANGLE_KEY][3])
     )
 
     return height * 2 / 3
 
 
-def checkbox_radio_font_size(element: PdfDict) -> Union[float, int]:
+def checkbox_radio_font_size(widget: PdfDict) -> Union[float, int]:
     """
     Calculates the font size it should be drawn with
-    given a checkbox/radio button element.
+    given a checkbox/radio button widget.
     """
 
     area = abs(
-        float(element[ANNOTATION_RECTANGLE_KEY][0])
-        - float(element[ANNOTATION_RECTANGLE_KEY][2])
+        float(widget[ANNOTATION_RECTANGLE_KEY][0])
+        - float(widget[ANNOTATION_RECTANGLE_KEY][2])
     ) * abs(
-        float(element[ANNOTATION_RECTANGLE_KEY][1])
-        - float(element[ANNOTATION_RECTANGLE_KEY][3])
+        float(widget[ANNOTATION_RECTANGLE_KEY][1])
+        - float(widget[ANNOTATION_RECTANGLE_KEY][3])
     )
 
     return sqrt(area) * 72 / 96
 
 
-def get_text_field_font_size(element: PdfDict) -> Union[float, int]:
+def get_text_field_font_size(widget: PdfDict) -> Union[float, int]:
     """Returns the font size of the text field if presented or zero."""
 
     result = 0
     for pattern in TEXT_FIELD_APPEARANCE_PATTERNS:
-        text_appearance = traverse_pattern(pattern, element)
+        text_appearance = traverse_pattern(pattern, widget)
         if text_appearance:
             text_appearance = text_appearance.replace("(", "").replace(")", "")
             properties = text_appearance.split(" ")
@@ -127,13 +126,13 @@ def get_text_field_font_size(element: PdfDict) -> Union[float, int]:
 
 
 def get_text_field_font_color(
-    element: PdfDict,
+    widget: PdfDict,
 ) -> Union[Tuple[float, float, float], None]:
     """Returns the font color tuple of the text field if presented or black."""
 
     result = (0, 0, 0)
     for pattern in TEXT_FIELD_APPEARANCE_PATTERNS:
-        text_appearance = traverse_pattern(pattern, element)
+        text_appearance = traverse_pattern(pattern, widget)
         if text_appearance:
             if FONT_COLOR_IDENTIFIER not in text_appearance:
                 return result
@@ -155,32 +154,27 @@ def get_text_field_font_color(
 
 def update_text_field_attributes(
     template_stream: bytes,
-    elements: Dict[str, ELEMENT_TYPES],
+    widgets: Dict[str, WIDGET_TYPES],
 ) -> None:
     """Auto updates text fields' attributes."""
 
     template_pdf = PdfReader(fdata=template_stream)
 
-    for _, _elements in get_elements_by_page(template_pdf).items():
-        for _element in _elements:
-            key = get_element_key(_element)
-
-            if isinstance(elements[key], Text):
-                if elements[key].font is None:
-                    elements[key].font = auto_detect_font(_element)
-                if elements[key].font_size is None:
-                    elements[key].font_size = get_text_field_font_size(
-                        _element
-                    ) or text_field_font_size(_element)
-                if elements[key].font_color is None:
-                    elements[key].font_color = get_text_field_font_color(_element)
-                if (
-                    is_text_multiline(_element)
-                    and elements[key].text_wrap_length is None
-                ):
-                    elements[key].text_wrap_length = get_paragraph_auto_wrap_length(
-                        _element, elements[key]
-                    )
-                    elements[key].text_lines = get_paragraph_lines(
-                        _element, elements[key]
+    for _, _widgets in get_widgets_by_page(template_pdf).items():
+        for _widget in _widgets:
+            key = get_widget_key(_widget)
+
+            if isinstance(widgets[key], Text):
+                if widgets[key].font is None:
+                    widgets[key].font = auto_detect_font(_widget)
+                if widgets[key].font_size is None:
+                    widgets[key].font_size = get_text_field_font_size(
+                        _widget
+                    ) or text_field_font_size(_widget)
+                if widgets[key].font_color is None:
+                    widgets[key].font_color = get_text_field_font_color(_widget)
+                if is_text_multiline(_widget) and widgets[key].text_wrap_length is None:
+                    widgets[key].text_wrap_length = get_paragraph_auto_wrap_length(
+                        _widget, widgets[key]
                     )
+                    widgets[key].text_lines = get_paragraph_lines(_widget, widgets[key])

{PyPDFForm-1.3.5 → PyPDFForm-1.4.0}/PyPDFForm/core/patterns.py

@@ -1,52 +1,53 @@
 # -*- coding: utf-8 -*-
-"""Contains patterns used for identifying properties of elements."""
+"""Contains patterns used for identifying properties of widgets."""
 
 from ..middleware.checkbox import Checkbox
 from ..middleware.dropdown import Dropdown
 from ..middleware.radio import Radio
 from ..middleware.text import Text
 from .constants import (ANNOTATION_FIELD_KEY, CHOICE_FIELD_IDENTIFIER,
-                        CHOICES_IDENTIFIER, ELEMENT_TYPE_KEY, FIELD_FLAG_KEY,
-                        PARENT_KEY, SELECTABLE_IDENTIFIER, SUBTYPE_KEY,
+                        CHOICES_IDENTIFIER, FIELD_FLAG_KEY, PARENT_KEY,
+                        SELECTABLE_IDENTIFIER, SUBTYPE_KEY,
                         TEXT_FIELD_ALIGNMENT_IDENTIFIER,
                         TEXT_FIELD_APPEARANCE_IDENTIFIER,
-                        TEXT_FIELD_IDENTIFIER, WIDGET_SUBTYPE_KEY)
+                        TEXT_FIELD_IDENTIFIER, WIDGET_SUBTYPE_KEY,
+                        WIDGET_TYPE_KEY)
 
-ELEMENT_TYPE_PATTERNS = [
+WIDGET_TYPE_PATTERNS = [
     (
-        ({ELEMENT_TYPE_KEY: TEXT_FIELD_IDENTIFIER},),
+        ({WIDGET_TYPE_KEY: TEXT_FIELD_IDENTIFIER},),
         Text,
     ),
     (
-        ({ELEMENT_TYPE_KEY: SELECTABLE_IDENTIFIER},),
+        ({WIDGET_TYPE_KEY: SELECTABLE_IDENTIFIER},),
         Checkbox,
     ),
     (
-        ({ELEMENT_TYPE_KEY: CHOICE_FIELD_IDENTIFIER},),
+        ({WIDGET_TYPE_KEY: CHOICE_FIELD_IDENTIFIER},),
         Dropdown,
     ),
     (
-        ({PARENT_KEY: {ELEMENT_TYPE_KEY: CHOICE_FIELD_IDENTIFIER}},),
+        ({PARENT_KEY: {WIDGET_TYPE_KEY: CHOICE_FIELD_IDENTIFIER}},),
         Dropdown,
     ),
     (
-        ({PARENT_KEY: {ELEMENT_TYPE_KEY: TEXT_FIELD_IDENTIFIER}},),
+        ({PARENT_KEY: {WIDGET_TYPE_KEY: TEXT_FIELD_IDENTIFIER}},),
         Text,
     ),
     (
         (
-            {PARENT_KEY: {ELEMENT_TYPE_KEY: SELECTABLE_IDENTIFIER}},
+            {PARENT_KEY: {WIDGET_TYPE_KEY: SELECTABLE_IDENTIFIER}},
             {PARENT_KEY: {SUBTYPE_KEY: WIDGET_SUBTYPE_KEY}},
         ),
         Checkbox,
     ),
     (
-        ({PARENT_KEY: {ELEMENT_TYPE_KEY: SELECTABLE_IDENTIFIER}},),
+        ({PARENT_KEY: {WIDGET_TYPE_KEY: SELECTABLE_IDENTIFIER}},),
         Radio,
     ),
 ]
 
-ELEMENT_KEY_PATTERNS = [
+WIDGET_KEY_PATTERNS = [
     {ANNOTATION_FIELD_KEY: True},
     {PARENT_KEY: {ANNOTATION_FIELD_KEY: True}},
 ]
@@ -56,7 +57,7 @@ DROPDOWN_CHOICE_PATTERNS = [
     {PARENT_KEY: {CHOICES_IDENTIFIER: True}},
 ]
 
-ELEMENT_ALIGNMENT_PATTERNS = [
+WIDGET_ALIGNMENT_PATTERNS = [
     {TEXT_FIELD_ALIGNMENT_IDENTIFIER: True},
     {PARENT_KEY: {TEXT_FIELD_ALIGNMENT_IDENTIFIER: True}},
 ]