Merge pull request #189 from chinapandaman/PPF-179

PPF-179: update docs for file adapter

Author: chinapandaman

PyPDFForm/__init__.py

@@ -4,4 +4,4 @@
 
 PyPDFForm = Wrapper
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

README.md

@@ -31,24 +31,23 @@ PATH_TO_FILLED_PDF_FORM = os.path.join(
     os.path.expanduser("~"), "output.pdf"
 )  # Change this to where you wish to put your filled PDF form
 
-with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
-    filled_pdf = PyPDFForm(
-        template.read(),
-        simple_mode=False,
-        global_font_size=20,
-    ).fill(
-        {
-            "test": "test_1",
-            "check": True,
-            "test_2": "test_2",
-            "check_2": False,
-            "test_3": "test_3",
-            "check_3": True,
-        },
+with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
+    output.write(
+        PyPDFForm(
+            PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, simple_mode=False, global_font_size=20,
+        )
+        .fill(
+            {
+                "test": "test_1",
+                "check": True,
+                "test_2": "test_2",
+                "check_2": False,
+                "test_3": "test_3",
+                "check_3": True,
+            },
+        )
+        .read()
     )
-
-    with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
-        output.write(filled_pdf.read())
 ```
 
 After running the above code snippet you can find `output.pdf` at the location you specified, 

docs/v2/api_reference.md

@@ -15,8 +15,7 @@ mode on and off yields different interactions with the fill method.
 
 #### Parameters:
 
-* **template** - a byte stream of the unfilled PDF form template. Usually generated 
-by Python IO's `.read()` method.
+* **template** - a file path, file object, or `bytes` stream of the unfilled PDF form template.
 
 * **simple_mode** - a simple mode PyPDFForm object only allows filling data without specifying 
 details like font size. Turning simple mode on also allows leaving PDF editable 
@@ -48,13 +47,12 @@ This operation can also be done by assignment operator `+=`.
 
 ### **draw_image**(*image, page_number, x, y, width, height, rotation=0*)
 
-The draw image method takes an image byte stream and draws it 
+The draw image method takes an image and draws it 
 on the specified page, coordinates with specified resolutions and rotation angle.
 
 #### Parameters:
 
-* **image** - bytes, a byte stream of the image. Usually generated by Python IO's 
-`.read()` method.
+* **image** - a file path, file object, or `bytes` stream of the image.
 
 * **page_number** - integer, page number of which the image will be drawn on.
 
@@ -121,7 +119,7 @@ Its values currently support the following:
     3) An `integer`, which will select the corresponding option of a group of radio buttons with the same name.
        NOTE: Only groups of radio buttons with the same name are supported. If there is only one 
        radio button with a name, please consider using `checkbox` instead.
-    4) A valid image `bytes` stream, which will be drawn on the corresponding `image` element.
+    4) A valid image file path, file object, or `bytes` stream, which will be drawn on the corresponding `image` element.
 
 * **editable** - only available if `simple_mode` is `True`, enabling this will allow the filled PDF to be still 
 editable. NOTE: `image` elements that are filled via the `fill` method will NOT be editable even if this is `True`.
@@ -130,7 +128,7 @@ editable. NOTE: `image` elements that are filled via the `fill` method will NOT
 
 Returns the `stream`. This method allows the implementation of PyPDFForm to behave like a file object.
 
-### **register_font**(*font_name, ttf_stream*)
+### **register_font**(*font_name, ttf_file*)
 
 This class method takes a TTF font file stream and register it with the `font_name` specified. 
 Registered fonts can then be used by any instance of object.
@@ -140,7 +138,7 @@ Registered fonts can then be used by any instance of object.
 * **font_name** - a string of which the font will be registered as. Registered fonts can be referenced and 
 used via this name.
 
-* **ttf_stream** - a byte stream of the ttf font file.
+* **ttf_file** - a file path, file object, or `bytes` stream of the ttf font file.
 
 ### **simple_mode** = *True*
 
@@ -149,7 +147,7 @@ like font size.
 
 ### **stream** = *b""*
 
-A byte object which holds the stream with the current state of the PDF form. This can be used by 
+A `bytes` object which holds the stream with the current state of the PDF form. This can be used by 
 Python IO to `.write` to another destination.
 
 ## Element Object