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

PyPDFForm/middleware/template.py

@@ -3,68 +3,66 @@
 
 from typing import Dict
 
-from ..core.template import (construct_element, get_character_x_paddings,
-                             get_dropdown_choices, get_element_key,
-                             get_elements_by_page, get_text_field_max_length,
+from ..core.template import (construct_widget, get_character_x_paddings,
+                             get_dropdown_choices, get_text_field_max_length,
+                             get_widget_key, get_widgets_by_page,
                              is_text_field_comb)
-from .constants import ELEMENT_TYPES
+from .constants import WIDGET_TYPES
 from .dropdown import Dropdown
 from .radio import Radio
 from .text import Text
 
 
 def set_character_x_paddings(
-    pdf_stream: bytes, eles: Dict[str, ELEMENT_TYPES]
-) -> Dict[str, ELEMENT_TYPES]:
+    pdf_stream: bytes, widgets: Dict[str, WIDGET_TYPES]
+) -> Dict[str, WIDGET_TYPES]:
     """Sets paddings between characters for combed text fields."""
 
-    for elements in get_elements_by_page(pdf_stream).values():
-        for element in elements:
-            key = get_element_key(element)
-            _element = eles[key]
+    for _widgets in get_widgets_by_page(pdf_stream).values():
+        for widget in _widgets:
+            key = get_widget_key(widget)
+            _widget = widgets[key]
 
-            if isinstance(_element, Text) and _element.comb is True:
-                _element.character_paddings = get_character_x_paddings(
-                    element, _element
-                )
+            if isinstance(_widget, Text) and _widget.comb is True:
+                _widget.character_paddings = get_character_x_paddings(widget, _widget)
 
-    return eles
+    return widgets
 
 
-def build_elements(pdf_stream: bytes) -> Dict[str, ELEMENT_TYPES]:
-    """Builds an element dict given a PDF form stream."""
+def build_widgets(pdf_stream: bytes) -> Dict[str, WIDGET_TYPES]:
+    """Builds a widget dict given a PDF form stream."""
 
     results = {}
 
-    for elements in get_elements_by_page(pdf_stream).values():
-        for element in elements:
-            key = get_element_key(element)
+    for widgets in get_widgets_by_page(pdf_stream).values():
+        for widget in widgets:
+            key = get_widget_key(widget)
 
-            _element = construct_element(element, key)
+            _widget = construct_widget(widget, key)
 
-            if _element is not None:
-                if isinstance(_element, Text):
-                    _element.max_length = get_text_field_max_length(element)
-                    if _element.max_length is not None and is_text_field_comb(element):
-                        _element.comb = True
+            if _widget is not None:
+                if isinstance(_widget, Text):
+                    _widget.max_length = get_text_field_max_length(widget)
+                    if _widget.max_length is not None and is_text_field_comb(widget):
+                        _widget.comb = True
 
-                if isinstance(_element, Dropdown):
-                    _element.choices = get_dropdown_choices(element)
+                if isinstance(_widget, Dropdown):
+                    _widget.choices = get_dropdown_choices(widget)
 
-                if isinstance(_element, Radio):
+                if isinstance(_widget, Radio):
                     if key not in results:
-                        results[key] = _element
+                        results[key] = _widget
 
                     results[key].number_of_options += 1
                     continue
 
-                results[key] = _element
+                results[key] = _widget
 
     return results
 
 
 def dropdown_to_text(dropdown: Dropdown) -> Text:
-    """Converts a dropdown element to a text element."""
+    """Converts a dropdown widget to a text widget."""
 
     result = Text(dropdown.name)
 

PyPDFForm/middleware/text.py

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

PyPDFForm/middleware/{element.py → widget.py}

@@ -1,36 +1,36 @@
 # -*- coding: utf-8 -*-
-"""Contains element middleware."""
+"""Contains widget middleware."""
 
 from typing import Any, Union
 
 
-class Element:
-    """Base class for all PDF form elements."""
+class Widget:
+    """Base class for all PDF form widgets."""
 
     def __init__(
         self,
-        element_name: str,
-        element_value: Union[str, bool, int] = None,
+        name: str,
+        value: Union[str, bool, int] = None,
     ) -> None:
         """Constructs basic attributes for the object."""
 
-        self._name = element_name
-        self.value = element_value
+        self._name = name
+        self.value = value
 
     @property
     def name(self) -> str:
-        """Name of the element."""
+        """Name of the widget."""
 
         return self._name
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the element."""
+        """Json schema definition of the widget."""
 
         raise NotImplementedError
 
     @property
     def sample_value(self) -> Any:
-        """Sample value of the element."""
+        """Sample value of the widget."""
 
         raise NotImplementedError

PyPDFForm/wrapper.py

@@ -4,25 +4,27 @@
 from __future__ import annotations
 
 from typing import BinaryIO, Dict, List, Union
+from warnings import warn
 
 from .core.constants import DEFAULT_FONT, DEFAULT_FONT_COLOR, DEFAULT_FONT_SIZE
 from .core.filler import fill
 from .core.font import register_font, update_text_field_attributes
 from .core.image import any_image_to_jpg, rotate_image
 from .core.utils import (get_page_streams, merge_two_pdfs,
-                         preview_element_to_draw, remove_all_elements)
+                         preview_widget_to_draw, remove_all_widgets)
 from .core.watermark import (create_watermarks_and_draw,
                              merge_watermarks_with_pdf)
 from .middleware.adapter import fp_or_f_obj_or_stream_to_stream
-from .middleware.constants import (VERSION_IDENTIFIER_PREFIX,
+from .middleware.constants import (DEPRECATION_NOTICE,
+                                   VERSION_IDENTIFIER_PREFIX,
                                    VERSION_IDENTIFIERS)
 from .middleware.dropdown import Dropdown
-from .middleware.template import (build_elements, dropdown_to_text,
+from .middleware.template import (build_widgets, dropdown_to_text,
                                   set_character_x_paddings)
 from .middleware.text import Text
 
 
-class Wrapper:
+class PdfWrapper:
     """A class to represent a PDF form."""
 
     def __init__(
@@ -33,9 +35,9 @@ class Wrapper:
         """Constructs all attributes for the object."""
 
         self.stream = fp_or_f_obj_or_stream_to_stream(template)
-        self.elements = build_elements(self.stream) if self.stream else {}
+        self.widgets = build_widgets(self.stream) if self.stream else {}
 
-        for each in self.elements.values():
+        for each in self.widgets.values():
             if isinstance(each, Text):
                 each.font = kwargs.get("global_font")
                 each.font_size = kwargs.get("global_font_size")
@@ -46,11 +48,26 @@ class Wrapper:
 
         return self.stream
 
+    @property
+    def elements(self) -> dict:
+        """ToDo: deprecate this."""
+
+        warn(
+            DEPRECATION_NOTICE.format(
+                f"{self.__class__.__name__}.elements",
+                f"{self.__class__.__name__}.widgets",
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return self.widgets
+
     @property
     def sample_data(self) -> dict:
         """Returns a valid sample data that can be filled into the PDF form."""
 
-        return {key: value.sample_value for key, value in self.elements.items()}
+        return {key: value.sample_value for key, value in self.widgets.items()}
 
     @property
     def version(self) -> Union[str, None]:
@@ -63,12 +80,12 @@ class Wrapper:
         return None
 
     @property
-    def pages(self) -> List[Wrapper]:
-        """Returns a list of wrapper objects where each is a page of the PDF form."""
+    def pages(self) -> List[PdfWrapper]:
+        """Returns a list of pdf wrapper objects where each is a page of the PDF form."""
 
         return [self.__class__(each) for each in get_page_streams(self.stream)]
 
-    def change_version(self, version: str) -> Wrapper:
+    def change_version(self, version: str) -> PdfWrapper:
         """Changes the version of the PDF."""
 
         self.stream = self.stream.replace(
@@ -79,7 +96,7 @@ class Wrapper:
 
         return self
 
-    def __add__(self, other: Wrapper) -> Wrapper:
+    def __add__(self, other: PdfWrapper) -> PdfWrapper:
         """Overloaded addition operator to perform merging PDFs."""
 
         if not self.stream:
@@ -95,35 +112,32 @@ class Wrapper:
 
     @property
     def preview(self) -> bytes:
-        """Inspects all supported elements' names for the PDF form."""
+        """Inspects all supported widgets' names for the PDF form."""
 
         return fill(
             self.stream,
-            {
-                key: preview_element_to_draw(value)
-                for key, value in self.elements.items()
-            },
+            {key: preview_widget_to_draw(value) for key, value in self.widgets.items()},
         )
 
     def fill(
         self,
         data: Dict[str, Union[str, bool, int]],
-    ) -> Wrapper:
+    ) -> PdfWrapper:
         """Fills a PDF form."""
 
         for key, value in data.items():
-            if key in self.elements:
-                self.elements[key].value = value
+            if key in self.widgets:
+                self.widgets[key].value = value
 
-        for key, value in self.elements.items():
+        for key, value in self.widgets.items():
             if isinstance(value, Dropdown):
-                self.elements[key] = dropdown_to_text(value)
+                self.widgets[key] = dropdown_to_text(value)
 
-        update_text_field_attributes(self.stream, self.elements)
+        update_text_field_attributes(self.stream, self.widgets)
         if self.read():
-            self.elements = set_character_x_paddings(self.stream, self.elements)
+            self.widgets = set_character_x_paddings(self.stream, self.widgets)
 
-        self.stream = remove_all_elements(fill(self.stream, self.elements))
+        self.stream = remove_all_widgets(fill(self.stream, self.widgets))
 
         return self
 
@@ -134,14 +148,14 @@ class Wrapper:
         x: Union[float, int],
         y: Union[float, int],
         **kwargs,
-    ) -> Wrapper:
+    ) -> PdfWrapper:
         """Draws a text on a PDF form."""
 
-        new_element = Text("new")
-        new_element.value = text
-        new_element.font = kwargs.get("font", DEFAULT_FONT)
-        new_element.font_size = kwargs.get("font_size", DEFAULT_FONT_SIZE)
-        new_element.font_color = kwargs.get("font_color", DEFAULT_FONT_COLOR)
+        new_widget = Text("new")
+        new_widget.value = text
+        new_widget.font = kwargs.get("font", DEFAULT_FONT)
+        new_widget.font_size = kwargs.get("font_size", DEFAULT_FONT_SIZE)
+        new_widget.font_color = kwargs.get("font_color", DEFAULT_FONT_COLOR)
 
         watermarks = create_watermarks_and_draw(
             self.stream,
@@ -149,7 +163,7 @@ class Wrapper:
             "text",
             [
                 [
-                    new_element,
+                    new_widget,
                     x,
                     y,
                 ]
@@ -169,7 +183,7 @@ class Wrapper:
         width: Union[float, int],
         height: Union[float, int],
         rotation: Union[float, int] = 0,
-    ) -> Wrapper:
+    ) -> PdfWrapper:
         """Draws an image on a PDF form."""
 
         image = fp_or_f_obj_or_stream_to_stream(image)
@@ -183,18 +197,33 @@ class Wrapper:
 
         return self
 
-    def generate_schema(self) -> dict:
+    @property
+    def schema(self) -> dict:
         """Generates a json schema for the PDF form template."""
 
         result = {
             "type": "object",
             "properties": {
-                key: value.schema_definition for key, value in self.elements.items()
+                key: value.schema_definition for key, value in self.widgets.items()
             },
         }
 
         return result
 
+    def generate_schema(self) -> dict:
+        """ToDo: deprecate this."""
+
+        warn(
+            DEPRECATION_NOTICE.format(
+                f"{self.__class__.__name__}.generate_schema()",
+                f"{self.__class__.__name__}.schema",
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return self.schema
+
     @classmethod
     def register_font(
         cls, font_name: str, ttf_file: Union[bytes, str, BinaryIO]
@@ -204,3 +233,22 @@ class Wrapper:
         ttf_file = fp_or_f_obj_or_stream_to_stream(ttf_file)
 
         return register_font(font_name, ttf_file) if ttf_file is not None else False
+
+
+class PyPDFForm(PdfWrapper):
+    """ToDo: deprecate this."""
+
+    def __init__(
+        self,
+        template: Union[bytes, str, BinaryIO] = b"",
+        **kwargs,
+    ):
+        """Only extra thing is the deprecation notice."""
+
+        warn(
+            DEPRECATION_NOTICE.format("PyPDFForm.PyPDFForm", "PyPDFForm.PdfWrapper"),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        super().__init__(template, **kwargs)

{PyPDFForm-1.3.5.dist-info → PyPDFForm-1.4.0.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,26 @@
+PyPDFForm/__init__.py,sha256=rhfuv6pEoYKPZZjU_oHscNXkBManw1LvL-7SoJP7nUE,135
+PyPDFForm/wrapper.py,sha256=o9m4Kr5FcKk4ca9DPGHtfix-gSh7gn380xtioQ2SEkI,7568
+PyPDFForm/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+PyPDFForm/core/constants.py,sha256=0zd1tW4YBEv-SAJRwWUCOJWOolrxIWc_aTJ-ljHw_wo,774
+PyPDFForm/core/coordinate.py,sha256=hBAqC-U-Uzp2YsKS6Nc9bxOifU2uCFxp7BUGchGsAKs,5092
+PyPDFForm/core/filler.py,sha256=rNhVcBcAu1xsAlq_AuomlT_6B27KxCrzXqNBSr94kk8,2802
+PyPDFForm/core/font.py,sha256=W5LPZX5bqN19gaBRv_uvDcudb3cUMfOA1SFNc5CgmdQ,5848
+PyPDFForm/core/image.py,sha256=Fqh4GZKHRZEKZos_Dnp_oyeOXXbbJQ3MUOE7qQxp5Hg,1067
+PyPDFForm/core/patterns.py,sha256=oj6eQ13H353oUJt8H1TD7iQ_bz102wdj7i4NQUAiwzQ,2027
+PyPDFForm/core/template.py,sha256=XdOCEWcv3ZwGIllUEoCMtmFJ68edGtqSfgwAUTVd1t8,8778
+PyPDFForm/core/utils.py,sha256=bXUYCkZpn8HOlT5-H0fYKB_AUVSMtVg5KUvkOSe46Ro,3903
+PyPDFForm/core/watermark.py,sha256=rqg5UAvIUthjytqF9lwiZHdt9Z8elUUGsA65yRz8gXU,4245
+PyPDFForm/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+PyPDFForm/middleware/adapter.py,sha256=OgAIwcmukpBqHFBLymd3I7wA7wIdipRqgURZA2Y0Hgo,885
+PyPDFForm/middleware/checkbox.py,sha256=xnV5VUDwPHQAk6pYU_Pmm5LKsvHEqJ37nbHIyfAEPn0,618
+PyPDFForm/middleware/constants.py,sha256=Gk3z3yvKrqyncT3KkHkJ67z-n_DuLlzIXtUm75ZsKCE,548
+PyPDFForm/middleware/dropdown.py,sha256=wwZKzNnPDN9S4Hr2MeKBxAp84TvYxymdcqvATIYiayM,676
+PyPDFForm/middleware/radio.py,sha256=6T4XkOgHTduulytR9NHR2rQ8fvIC0oOZ8NfcswLcQ14,694
+PyPDFForm/middleware/template.py,sha256=T6EJWRhRfcsAA0xVdB_gs2oOW7bCXLkzv4s14d2LCYo,2378
+PyPDFForm/middleware/text.py,sha256=RqXo-C2zCZqufW-Uer90aUFvDLcPKLkKa1LRzRogv4o,1059
+PyPDFForm/middleware/widget.py,sha256=90DKZYoA1lTZ2Jk4rWjT2oH59PvAI2_-Xwr7qWodtj0,749
+PyPDFForm-1.4.0.dist-info/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
+PyPDFForm-1.4.0.dist-info/METADATA,sha256=9yPCr-yEwbZnqQsgD-fhkBzpSGpFcta0sORXBCrsY5Q,4919
+PyPDFForm-1.4.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+PyPDFForm-1.4.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
+PyPDFForm-1.4.0.dist-info/RECORD,,

PyPDFForm-1.3.5.dist-info/RECORD

@@ -1,26 +0,0 @@
-PyPDFForm/__init__.py,sha256=mDLQwqRktmWL81KsW8im1RyTOWzZsx-Q6w2noceNNao,122
-PyPDFForm/wrapper.py,sha256=XbCrc3RyRoBOV0SzNTDemuXfMH51phBHqfbm3gDyLLQ,6363
-PyPDFForm/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyPDFForm/core/constants.py,sha256=5ekojW6YlD72tbZG7-0vj0cNP0iIw2-dsOT2YJ2BABM,775
-PyPDFForm/core/coordinate.py,sha256=wEN--iRpEwirOikfOELAxlsInXfYmd41VuRUBP_HAO8,5175
-PyPDFForm/core/filler.py,sha256=Zi_adOTjKD6xbgy3ZOCjAoR0r3-R373pQN8uKuDa0fA,2827
-PyPDFForm/core/font.py,sha256=9H_K9R6zZraNQ5CeVGCBXG-AHfzzYdvSOkuDmK_rGXY,6024
-PyPDFForm/core/image.py,sha256=Fqh4GZKHRZEKZos_Dnp_oyeOXXbbJQ3MUOE7qQxp5Hg,1067
-PyPDFForm/core/patterns.py,sha256=Uyio6jahksPsYar8MnVukiRIhL1K5hlO9TEGHrx3SxU,2015
-PyPDFForm/core/template.py,sha256=VtzF1ceqgznMJRR9AbIcoYAPj5VsmxhXVQFRwY6hi5M,8868
-PyPDFForm/core/utils.py,sha256=fpfZ8-GMmnD6jRSZPf4CD5dl7zRvKcYes1Hp9cprKxo,3974
-PyPDFForm/core/watermark.py,sha256=vt6EFDAlOZ7g1nrZLfR_nMozDFSHxzw3cUyEzdgzFOo,4270
-PyPDFForm/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyPDFForm/middleware/adapter.py,sha256=OgAIwcmukpBqHFBLymd3I7wA7wIdipRqgURZA2Y0Hgo,885
-PyPDFForm/middleware/checkbox.py,sha256=fU_VV6B6m7aYe3i6HzXBUu9U9yH5gP0WXz1J9q4c0Fs,654
-PyPDFForm/middleware/constants.py,sha256=r56j2oURQei7KX0gWPqb10bQXRVdyVd0T8BapSlDlYM,481
-PyPDFForm/middleware/dropdown.py,sha256=OJQI_XffMPf4yxUCk5WOaLIqZpRd97gNV-YG-llFaa8,712
-PyPDFForm/middleware/element.py,sha256=Xo_lFRCTkEorfYOSU7RcP7tmvCrkKEpiZAzKIPHRwVs,787
-PyPDFForm/middleware/radio.py,sha256=gwNTE__eiaSqxY8_ov__tI8byz-cKOfTp9nWJ5DkFzQ,730
-PyPDFForm/middleware/template.py,sha256=U2Agl5Vs_fllaeyL1xBq1sP8PFUU33G_BRgjxQLS9LQ,2451
-PyPDFForm/middleware/text.py,sha256=rrTfXcxaXZlLsjuJ1C4KaHt_reZk2c9MQ-z0ec3OD9g,1095
-PyPDFForm-1.3.5.dist-info/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
-PyPDFForm-1.3.5.dist-info/METADATA,sha256=QxqBfGbUHFgo0JexoClZsTjZqvKTlmIhUkUGAToHiBY,4096
-PyPDFForm-1.3.5.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-PyPDFForm-1.3.5.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
-PyPDFForm-1.3.5.dist-info/RECORD,,