Merge pull request #160 from chinapandaman/PPF-159

PPF-159: update docs for radio button fill

Author: chinapandaman

PyPDFForm/__init__.py

@@ -2,4 +2,4 @@
 
 from .middleware.wrapper import PyPDFForm
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

docs/v2/api_reference.md

@@ -118,7 +118,10 @@ Its keys have to be `string` and need to match the annotated names of elements.
 Its values currently support the following:
     1) A `string`, which will be printed on the corresponding `text` element.
     2) A `boolean`, which will check the corresponding `checkbox` element.
-    3) A valid image `bytes` stream, which will be drawn on the corresponding `image` element.
+    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.
 
 * **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`.
@@ -159,13 +162,14 @@ such as font size and text wrap length.
 * **element_name** - a string which represents the annotated name of the element.
 
 * **element_type** - an enum which represents the type of the element, currently supporting 
-`text`, `checkbox` and `image`.
+`text`, `checkbox`, `radio` and `image`.
 
 * **element_value** - this is the value that's used to fill this element. 
 It currently supports the following based on the type of the element:
   1) A `string`, if the element is a `text`.
   2) A `boolean`, if the element is a `checkbox`.
-  3) A valid image `bytes` stream, if the element is an `image`.
+  3) An `integer`, if the element is a `radio`.
+  4) A valid image `bytes` stream, if the element is an `image`.
 
 ### **name**
 
@@ -174,7 +178,7 @@ A string which represents the annotated name of the element. Readonly.
 ### **type**
 
 An enum value which represents the type of the element, currently supporting 
-`text`, `checkbox` and `image`. Readonly.
+`text`, `checkbox`, `radio` and `image`. Readonly.
 
 ### **value**
 
@@ -183,7 +187,8 @@ It currently supports the following based on the type of the element:
 
 1) A `string`, if the element is a `text`.
 2) A `boolean`, if the element is a `checkbox`.
-3) A valid image `bytes` stream, if the element is an `image`.
+3) An `integer`, if the element is a `radio`.
+4) A valid image `bytes` stream, if the element is an `image`.
 
 ### **font** = *None*
 

docs/v2/examples.md

@@ -441,6 +441,40 @@ with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
 Link to this example: https://github.com/chinapandaman/PyPDFForm/blob/master/examples/fill_customized_elements.py
 
 
+## Fill a PDF form with radio buttons
+
+This example uses this [template](https://github.com/chinapandaman/PyPDFForm/blob/master/pdf_samples/v2/sample_template_with_radio_button.pdf). 
+It demos filling a PDF form's radio button elements.
+
+```python
+import os
+
+from PyPDFForm import PyPDFForm
+
+PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
+    os.path.expanduser("~/Downloads"), "sample_template_with_radio_button.pdf"
+)  # Change this to where you downloaded the sample PDF form
+
+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()).fill(
+        {
+            "radio_1": 0,
+            "radio_2": 1,
+            "radio_3": 2,
+        },
+    )
+
+    with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
+        output.write(filled_pdf.stream)
+```
+
+Link to this example: https://github.com/chinapandaman/PyPDFForm/blob/master/examples/simple_fill_radio.py
+
+
 ## Fill a PDF form with image elements
 
 This example uses this [template](https://github.com/chinapandaman/PyPDFForm/blob/master/pdf_samples/v2/sample_template_with_image_field.pdf) 

examples/simple_fill_radio.py

@@ -0,0 +1,23 @@
+import os
+
+from PyPDFForm import PyPDFForm
+
+PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
+    os.path.expanduser("~/Downloads"), "sample_template_with_radio_button.pdf"
+)  # Change this to where you downloaded the sample PDF form
+
+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()).fill(
+        {
+            "radio_1": 0,
+            "radio_2": 1,
+            "radio_3": 2,
+        },
+    )
+
+    with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
+        output.write(filled_pdf.stream)