PyPDFForm 1.3.5__py3-none-any.whl → 1.4.0__py3-none-any.whl

PyPDFForm/core/template.py

@@ -6,19 +6,19 @@ from typing import Dict, List, Tuple, Union
 from pdfrw import PdfDict, PdfReader
 from reportlab.pdfbase.pdfmetrics import stringWidth
 
-from ..middleware.constants import ELEMENT_TYPES
+from ..middleware.constants import WIDGET_TYPES
 from ..middleware.text import Text
 from .constants import (ANNOTATION_KEY, ANNOTATION_RECTANGLE_KEY,
                         FIELD_FLAG_KEY, NEW_LINE_SYMBOL,
                         TEXT_FIELD_MAX_LENGTH_KEY)
-from .patterns import (DROPDOWN_CHOICE_PATTERNS, ELEMENT_ALIGNMENT_PATTERNS,
-                       ELEMENT_KEY_PATTERNS, ELEMENT_TYPE_PATTERNS,
-                       TEXT_FIELD_FLAG_PATTERNS)
+from .patterns import (DROPDOWN_CHOICE_PATTERNS, TEXT_FIELD_FLAG_PATTERNS,
+                       WIDGET_ALIGNMENT_PATTERNS, WIDGET_KEY_PATTERNS,
+                       WIDGET_TYPE_PATTERNS)
 from .utils import find_pattern_match, traverse_pattern
 
 
-def get_elements_by_page(pdf: Union[bytes, PdfReader]) -> Dict[int, List[PdfDict]]:
-    """Iterates through a PDF and returns all elements found grouped by page."""
+def get_widgets_by_page(pdf: Union[bytes, PdfReader]) -> Dict[int, List[PdfDict]]:
+    """Iterates through a PDF and returns all widgets found grouped by page."""
 
     if isinstance(pdf, bytes):
         pdf = PdfReader(fdata=pdf)
@@ -26,86 +26,86 @@ def get_elements_by_page(pdf: Union[bytes, PdfReader]) -> Dict[int, List[PdfDict
     result = {}
 
     for i, page in enumerate(pdf.pages):
-        elements = page[ANNOTATION_KEY]
+        widgets = page[ANNOTATION_KEY]
         result[i + 1] = []
-        if elements:
-            for element in elements:
-                for each in ELEMENT_TYPE_PATTERNS:
+        if widgets:
+            for widget in widgets:
+                for each in WIDGET_TYPE_PATTERNS:
                     patterns = each[0]
                     check = True
                     for pattern in patterns:
-                        check = check and find_pattern_match(pattern, element)
+                        check = check and find_pattern_match(pattern, widget)
                     if check:
-                        result[i + 1].append(element)
+                        result[i + 1].append(widget)
                         break
 
     return result
 
 
-def get_element_key(element: PdfDict) -> Union[str, None]:
-    """Finds a PDF element's annotated key by pattern matching."""
+def get_widget_key(widget: PdfDict) -> Union[str, None]:
+    """Finds a PDF widget's annotated key by pattern matching."""
 
     result = None
-    for pattern in ELEMENT_KEY_PATTERNS:
-        value = traverse_pattern(pattern, element)
+    for pattern in WIDGET_KEY_PATTERNS:
+        value = traverse_pattern(pattern, widget)
         if value:
             result = value[1:-1]
             break
     return result
 
 
-def get_element_alignment(element: PdfDict) -> Union[str, None]:
-    """Finds a PDF element's alignment by pattern matching."""
+def get_widget_alignment(widget: PdfDict) -> Union[str, None]:
+    """Finds a PDF widget's alignment by pattern matching."""
 
     result = None
-    for pattern in ELEMENT_ALIGNMENT_PATTERNS:
-        value = traverse_pattern(pattern, element)
+    for pattern in WIDGET_ALIGNMENT_PATTERNS:
+        value = traverse_pattern(pattern, widget)
         if value:
             result = value
             break
     return result
 
 
-def construct_element(element: PdfDict, key: str) -> Union[ELEMENT_TYPES, None]:
-    """Finds a PDF element's annotated type by pattern matching."""
+def construct_widget(widget: PdfDict, key: str) -> Union[WIDGET_TYPES, None]:
+    """Finds a PDF widget's annotated type by pattern matching."""
 
     result = None
-    for each in ELEMENT_TYPE_PATTERNS:
+    for each in WIDGET_TYPE_PATTERNS:
         patterns, _type = each
         check = True
         for pattern in patterns:
-            check = check and find_pattern_match(pattern, element)
+            check = check and find_pattern_match(pattern, widget)
         if check:
             result = _type(key)
             break
     return result
 
 
-def get_text_field_max_length(element: PdfDict) -> Union[int, None]:
+def get_text_field_max_length(widget: PdfDict) -> Union[int, None]:
     """Returns the max length of the text field if presented or None."""
 
     return (
-        int(element[TEXT_FIELD_MAX_LENGTH_KEY])
-        if TEXT_FIELD_MAX_LENGTH_KEY in element
+        int(widget[TEXT_FIELD_MAX_LENGTH_KEY])
+        if TEXT_FIELD_MAX_LENGTH_KEY in widget
         else None
     )
 
 
-def is_text_field_comb(element: PdfDict) -> bool:
+def is_text_field_comb(widget: PdfDict) -> bool:
     """Returns true if characters in a text field needs to be formatted into combs."""
 
     try:
-        return "{0:b}".format(int(element[FIELD_FLAG_KEY]))[::-1][24] == "1"
+        return "{0:b}".format(int(widget[FIELD_FLAG_KEY]))[::-1][24] == "1"
     except (IndexError, TypeError):
         return False
 
 
-def is_text_multiline(element: PdfDict) -> bool:
+def is_text_multiline(widget: PdfDict) -> bool:
     """Returns true if a text field is a paragraph field."""
 
     field_flag = None
     for pattern in TEXT_FIELD_FLAG_PATTERNS:
-        field_flag = traverse_pattern(pattern, element)
+        field_flag = traverse_pattern(pattern, widget)
         if field_flag is not None:
             break
 
@@ -118,12 +118,12 @@ def is_text_multiline(element: PdfDict) -> bool:
         return False
 
 
-def get_dropdown_choices(element: PdfDict) -> Union[Tuple[str], None]:
+def get_dropdown_choices(widget: PdfDict) -> Union[Tuple[str], None]:
     """Returns string options of a dropdown field."""
 
     result = None
     for pattern in DROPDOWN_CHOICE_PATTERNS:
-        choices = traverse_pattern(pattern, element)
+        choices = traverse_pattern(pattern, widget)
         if choices:
             result = tuple(
                 (each if isinstance(each, str) else str(each[1]))
@@ -136,45 +136,44 @@ def get_dropdown_choices(element: PdfDict) -> Union[Tuple[str], None]:
     return result
 
 
-def get_char_rect_width(element: PdfDict, element_middleware: Text) -> float:
+def get_char_rect_width(widget: PdfDict, widget_middleware: Text) -> float:
     """Returns rectangular width of each character for combed text fields."""
 
     rect_width = 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])
     )
-    return rect_width / element_middleware.max_length
+    return rect_width / widget_middleware.max_length
 
 
-def get_character_x_paddings(element: PdfDict, element_middleware: Text) -> List[float]:
+def get_character_x_paddings(widget: PdfDict, widget_middleware: Text) -> List[float]:
     """Returns paddings between characters for combed text fields."""
 
-    length = min(len(element_middleware.value or ""), element_middleware.max_length)
-    char_rect_width = get_char_rect_width(element, element_middleware)
+    length = min(len(widget_middleware.value or ""), widget_middleware.max_length)
+    char_rect_width = get_char_rect_width(widget, widget_middleware)
 
     result = []
 
     current_x = 0
-    for char in (element_middleware.value or "")[:length]:
+    for char in (widget_middleware.value or "")[:length]:
         current_mid_point = current_x + char_rect_width / 2
         result.append(
             current_mid_point
-            - stringWidth(char, element_middleware.font, element_middleware.font_size)
-            / 2
+            - stringWidth(char, widget_middleware.font, widget_middleware.font_size) / 2
         )
         current_x += char_rect_width
 
     return result
 
 
-def calculate_wrap_length(element: PdfDict, element_middleware: Text, v: str) -> int:
+def calculate_wrap_length(widget: PdfDict, widget_middleware: Text, v: str) -> int:
     """Increments the substring until reaching maximum horizontal width."""
 
     width = 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])
     )
-    value = element_middleware.value or ""
+    value = widget_middleware.value or ""
     value = value.replace(NEW_LINE_SYMBOL, " ")
 
     counter = 0
@@ -183,26 +182,26 @@ def calculate_wrap_length(element: PdfDict, element_middleware: Text, v: str) ->
         counter += 1
         _width = stringWidth(
             v[:counter],
-            element_middleware.font,
-            element_middleware.font_size,
+            widget_middleware.font,
+            widget_middleware.font_size,
         )
     return counter - 1
 
 
-def get_paragraph_lines(element: PdfDict, element_middleware: Text) -> List[str]:
+def get_paragraph_lines(widget: PdfDict, widget_middleware: Text) -> List[str]:
     """Splits the paragraph field's text to a list of lines."""
 
     # pylint: disable=R0912
     lines = []
     result = []
-    text_wrap_length = element_middleware.text_wrap_length
-    value = element_middleware.value or ""
-    if element_middleware.max_length is not None:
-        value = value[: element_middleware.max_length]
+    text_wrap_length = widget_middleware.text_wrap_length
+    value = widget_middleware.value or ""
+    if widget_middleware.max_length is not None:
+        value = value[: widget_middleware.max_length]
 
     width = 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])
     )
 
     split_by_new_line_symbol = value.split(NEW_LINE_SYMBOL)
@@ -226,8 +225,8 @@ def get_paragraph_lines(element: PdfDict, element_middleware: Text) -> List[str]
         while (
             stringWidth(
                 line[:text_wrap_length],
-                element_middleware.font,
-                element_middleware.font_size,
+                widget_middleware.font,
+                widget_middleware.font_size,
             )
             > width
         ):
@@ -256,26 +255,26 @@ def get_paragraph_lines(element: PdfDict, element_middleware: Text) -> List[str]
     return result
 
 
-def get_paragraph_auto_wrap_length(element: PdfDict, element_middleware: Text) -> int:
+def get_paragraph_auto_wrap_length(widget: PdfDict, widget_middleware: Text) -> int:
     """Calculates the text wrap length of a paragraph field."""
 
-    value = element_middleware.value or ""
+    value = widget_middleware.value or ""
     value = value.replace(NEW_LINE_SYMBOL, " ")
     width = 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])
     )
     text_width = stringWidth(
         value,
-        element_middleware.font,
-        element_middleware.font_size,
+        widget_middleware.font,
+        widget_middleware.font_size,
     )
 
     lines = text_width / width
     if lines > 1:
         current_min = 0
         while len(value) and current_min < len(value):
-            result = calculate_wrap_length(element, element_middleware, value)
+            result = calculate_wrap_length(widget, widget_middleware, value)
             value = value[result:]
             if current_min == 0:
                 current_min = result

PyPDFForm/core/utils.py

@@ -7,7 +7,7 @@ from typing import List, Union
 from pdfrw import PdfDict, PdfReader, PdfWriter
 
 from ..middleware.checkbox import Checkbox
-from ..middleware.constants import ELEMENT_TYPES
+from ..middleware.constants import WIDGET_TYPES
 from ..middleware.radio import Radio
 from ..middleware.text import Text
 from .constants import (ANNOTATION_KEY, CHECKBOX_TO_DRAW, DEFAULT_FONT,
@@ -30,51 +30,51 @@ def generate_stream(pdf: PdfReader) -> bytes:
 
 
 def checkbox_radio_to_draw(
-    element: Union[Checkbox, Radio], font_size: Union[float, int]
+    widget: Union[Checkbox, Radio], font_size: Union[float, int]
 ) -> Text:
-    """Converts a checkbox/radio element to a drawable text element."""
+    """Converts a checkbox/radio widget to a drawable text widget."""
 
-    new_element = Text(
-        element_name=element.name,
-        element_value="",
+    new_widget = Text(
+        name=widget.name,
+        value="",
     )
-    new_element.font = DEFAULT_FONT
-    new_element.font_size = font_size
-    new_element.font_color = DEFAULT_FONT_COLOR
+    new_widget.font = DEFAULT_FONT
+    new_widget.font_size = font_size
+    new_widget.font_color = DEFAULT_FONT_COLOR
 
-    if isinstance(element, Checkbox):
-        new_element.value = CHECKBOX_TO_DRAW
-    elif isinstance(element, Radio):
-        new_element.value = RADIO_TO_DRAW
+    if isinstance(widget, Checkbox):
+        new_widget.value = CHECKBOX_TO_DRAW
+    elif isinstance(widget, Radio):
+        new_widget.value = RADIO_TO_DRAW
 
-    return new_element
+    return new_widget
 
 
-def preview_element_to_draw(element: ELEMENT_TYPES) -> Text:
-    """Converts an element to a preview text element."""
+def preview_widget_to_draw(widget: WIDGET_TYPES) -> Text:
+    """Converts a widget to a preview text widget."""
 
-    new_element = Text(
-        element_name=element.name,
-        element_value="{" + f" {element.name} " + "}",
+    new_widget = Text(
+        name=widget.name,
+        value="{" + f" {widget.name} " + "}",
     )
-    new_element.font = DEFAULT_FONT
-    new_element.font_size = DEFAULT_FONT_SIZE
-    new_element.font_color = PREVIEW_FONT_COLOR
-    new_element.preview = True
+    new_widget.font = DEFAULT_FONT
+    new_widget.font_size = DEFAULT_FONT_SIZE
+    new_widget.font_color = PREVIEW_FONT_COLOR
+    new_widget.preview = True
 
-    return new_element
+    return new_widget
 
 
-def remove_all_elements(pdf: bytes) -> bytes:
-    """Removes all elements from a pdfrw parsed PDF form."""
+def remove_all_widgets(pdf: bytes) -> bytes:
+    """Removes all widgets from a pdfrw parsed PDF form."""
 
     pdf = PdfReader(fdata=pdf)
 
     for page in pdf.pages:
-        elements = page[ANNOTATION_KEY]
-        if elements:
-            for j in reversed(range(len(elements))):
-                elements.pop(j)
+        widgets = page[ANNOTATION_KEY]
+        if widgets:
+            for j in reversed(range(len(widgets))):
+                widgets.pop(j)
 
     return generate_stream(pdf)
 
@@ -114,10 +114,10 @@ def merge_two_pdfs(pdf: bytes, other: bytes) -> bytes:
     return result
 
 
-def find_pattern_match(pattern: dict, element: PdfDict) -> bool:
-    """Checks if a PDF dict pattern exists in a PDF element."""
+def find_pattern_match(pattern: dict, widget: PdfDict) -> bool:
+    """Checks if a PDF dict pattern exists in a PDF widget."""
 
-    for key, value in element.items():
+    for key, value in widget.items():
         result = False
         if key in pattern:
             if isinstance(pattern[key], dict) and isinstance(value, PdfDict):
@@ -129,10 +129,10 @@ def find_pattern_match(pattern: dict, element: PdfDict) -> bool:
     return False
 
 
-def traverse_pattern(pattern: dict, element: PdfDict) -> Union[str, list, None]:
+def traverse_pattern(pattern: dict, widget: PdfDict) -> Union[str, list, None]:
     """Traverses down a PDF dict pattern and find the value."""
 
-    for key, value in element.items():
+    for key, value in widget.items():
         result = None
         if key in pattern:
             if isinstance(pattern[key], dict) and isinstance(value, PdfDict):

PyPDFForm/core/watermark.py

@@ -23,70 +23,68 @@ def draw_text(
 ) -> None:
     """Draws a text on the watermark."""
 
-    canv = args[0]
-    element = args[1]
+    canvas = args[0]
+    widget = args[1]
     coordinate_x = args[2]
     coordinate_y = args[3]
 
-    text_to_draw = element.value
+    text_to_draw = widget.value
 
     if not text_to_draw:
         text_to_draw = ""
 
-    if element.max_length is not None:
-        text_to_draw = text_to_draw[: element.max_length]
+    if widget.max_length is not None:
+        text_to_draw = text_to_draw[: widget.max_length]
 
-    canv.setFont(element.font, element.font_size)
-    canv.setFillColorRGB(
-        element.font_color[0], element.font_color[1], element.font_color[2]
+    canvas.setFont(widget.font, widget.font_size)
+    canvas.setFillColorRGB(
+        widget.font_color[0], widget.font_color[1], widget.font_color[2]
     )
 
-    if element.comb is True:
+    if widget.comb is True:
         for i, char in enumerate(text_to_draw):
-            canv.drawString(
-                coordinate_x + element.character_paddings[i],
+            canvas.drawString(
+                coordinate_x + widget.character_paddings[i],
                 coordinate_y,
                 char,
             )
     elif (
-        element.text_wrap_length is None or len(text_to_draw) < element.text_wrap_length
-    ) and element.text_lines is None:
-        canv.drawString(
+        widget.text_wrap_length is None or len(text_to_draw) < widget.text_wrap_length
+    ) and widget.text_lines is None:
+        canvas.drawString(
             coordinate_x,
             coordinate_y,
             text_to_draw,
         )
     else:
-        text_obj = canv.beginText(0, 0)
-        for i, line in enumerate(element.text_lines):
+        text_obj = canvas.beginText(0, 0)
+        for i, line in enumerate(widget.text_lines):
             cursor_moved = False
             if (
-                element.text_line_x_coordinates is not None
-                and element.text_line_x_coordinates[i] - coordinate_x != 0
+                widget.text_line_x_coordinates is not None
+                and widget.text_line_x_coordinates[i] - coordinate_x != 0
             ):
-                text_obj.moveCursor(
-                    element.text_line_x_coordinates[i] - coordinate_x, 0
-                )
+                text_obj.moveCursor(widget.text_line_x_coordinates[i] - coordinate_x, 0)
                 cursor_moved = True
             text_obj.textLine(line)
             if cursor_moved:
                 text_obj.moveCursor(
-                    -1 * (element.text_line_x_coordinates[i] - coordinate_x), 0
+                    -1 * (widget.text_line_x_coordinates[i] - coordinate_x), 0
                 )
 
-        canv.saveState()
-        canv.translate(
+        canvas.saveState()
+        canvas.translate(
             coordinate_x,
             coordinate_y,
         )
-        canv.drawText(text_obj)
-        canv.restoreState()
+        canvas.drawText(text_obj)
+        canvas.restoreState()
 
 
 def draw_image(*args: Union[Canvas, bytes, float, int]) -> None:
     """Draws an image on the watermark."""
 
-    canv = args[0]
+    canvas = args[0]
     image_stream = args[1]
     coordinate_x = args[2]
     coordinate_y = args[3]
@@ -97,7 +95,7 @@ def draw_image(*args: Union[Canvas, bytes, float, int]) -> None:
     image_buff.write(image_stream)
     image_buff.seek(0)
 
-    canv.drawImage(
+    canvas.drawImage(
         ImageReader(image_buff),
         coordinate_x,
         coordinate_y,
@@ -129,7 +127,7 @@ def create_watermarks_and_draw(
     pdf_file = PdfReader(fdata=pdf)
     buff = BytesIO()
 
-    canv = Canvas(
+    canvas = Canvas(
         buff,
         pagesize=(
             float(pdf_file.pages[page_number - 1].MediaBox[2]),
@@ -139,12 +137,12 @@ def create_watermarks_and_draw(
 
     if action_type == "image":
         for each in actions:
-            draw_image(*([canv, *each]))
+            draw_image(*([canvas, *each]))
     elif action_type == "text":
         for each in actions:
-            draw_text(*([canv, *each]))
+            draw_text(*([canvas, *each]))
 
-    canv.save()
+    canvas.save()
     buff.seek(0)
 
     watermark = buff.read()

PyPDFForm/middleware/checkbox.py

@@ -1,20 +1,20 @@
 # -*- coding: utf-8 -*-
 """Contains checkbox middleware."""
 
-from .element import Element
+from .widget import Widget
 
 
-class Checkbox(Element):
-    """A class to represent a checkbox element."""
+class Checkbox(Widget):
+    """A class to represent a checkbox widget."""
 
     def __init__(
         self,
-        element_name: str,
-        element_value: bool = None,
+        name: str,
+        value: bool = None,
     ) -> None:
         """Constructs all attributes for the checkbox."""
 
-        super().__init__(element_name, element_value)
+        super().__init__(name, value)
 
     @property
     def schema_definition(self) -> dict:

PyPDFForm/middleware/constants.py

@@ -21,4 +21,6 @@ VERSION_IDENTIFIERS = [
 ]
 VERSION_IDENTIFIER_PREFIX = b"%PDF-"
 
-ELEMENT_TYPES = Union[Text, Checkbox, Radio, Dropdown]
+WIDGET_TYPES = Union[Text, Checkbox, Radio, Dropdown]
+
+DEPRECATION_NOTICE = "{} will be deprecated soon. Use {} instead."

PyPDFForm/middleware/dropdown.py

@@ -1,20 +1,20 @@
 # -*- coding: utf-8 -*-
 """Contains dropdown middleware."""
 
-from .element import Element
+from .widget import Widget
 
 
-class Dropdown(Element):
-    """A class to represent a dropdown element."""
+class Dropdown(Widget):
+    """A class to represent a dropdown widget."""
 
     def __init__(
         self,
-        element_name: str,
-        element_value: int = None,
+        name: str,
+        value: int = None,
     ) -> None:
         """Constructs all attributes for the dropdown."""
 
-        super().__init__(element_name, element_value)
+        super().__init__(name, value)
 
         self.choices = None
 

PyPDFForm/middleware/radio.py

@@ -1,20 +1,20 @@
 # -*- coding: utf-8 -*-
 """Contains radio middleware."""
 
-from .element import Element
+from .widget import Widget
 
 
-class Radio(Element):
-    """A class to represent a radiobutton element."""
+class Radio(Widget):
+    """A class to represent a radiobutton widget."""
 
     def __init__(
         self,
-        element_name: str,
-        element_value: int = None,
+        name: str,
+        value: int = None,
     ) -> None:
         """Constructs all attributes for the radiobutton."""
 
-        super().__init__(element_name, element_value)
+        super().__init__(name, value)
 
         self.number_of_options = 0