Merge pull request #9 from regulaforensics/enchance-docs

Enhance documentation

Author: ikliashchou

.github/workflows/run-smoke-test.yml

@@ -21,12 +21,10 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install --upgrade setuptools wheel
-          python -m pip install --upgrade pipenv==2018.11.26
       - name: Install test dependencies
-        run: pipenv install --dev
-        working-directory: example
+        run: pip install -e ./
       - name: Run smoke test
-        run: pipenv run python example.py
+        run: python example.py
         working-directory: example
         env:
           API_BASE_PATH: "http://test-api.regulaforensics.com"

.gitignore

@@ -1,6 +1,7 @@
 .idea
 example/portrait.jpg
 example/document-image.jpg
+example/regula.license
 
 
 # Byte-compiled / optimized / DLL files

README.md

@@ -1,17 +1,67 @@
-# Regula Document Reader web application python client
+# Regula Document Reader web API Python 3.5+ client
 
-## Development
+[![pypi](https://img.shields.io/pypi/v/regula.documentreader.webclient?style=flat-square)](https://support.regulaforensics.com/hc/en-us/articles/115000916306-Documentation)
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-defs-8c0a56?style=flat-square)](https://github.com/regulaforensics/DocumentReader-web-openapi)
+[![documentation](https://img.shields.io/badge/docs-en-f6858d?style=flat-square)](https://support.regulaforensics.com/hc/en-us/articles/115000916306-Documentation)
+[![live](https://img.shields.io/badge/live-demo-0a8c42?style=flat-square)](https://api.regulaforensics.com/)
+
+Documents recognition as easy as reading two bytes.
+
+If you have any problems with or questions about this client, please contact us
+through a [GitHub issue](https://github.com/regulaforensics/DocumentReader-web-python-client/issues).
+You are invited to contribute [new features, fixes, or updates](https://github.com/regulaforensics/DocumentReader-web-python-client/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22), large or small; 
+We are always thrilled to receive pull requests, and do our best to process them as fast as we can.
+See [dev guide](./dev.md)
+
+## Install package
+`regula.documentreader.webclient` is on the Python Package Index (PyPI):
 
-To regenerate models from openapi definition, 
-clone [latest open api definitions](https://github.com/regulaforensics/DocumentReader-api-openapi)
-and set `DEFINITION_FOLDER` as path to cloned directory, for example:
 ```bash
-DEFINITION_FOLDER="/home/user/projects/DocumentReader-api-openapi"
+pip install regula.documentreader.webclient
 ```
-Then use next command from the project root:
+
+Or using `pipenv`
 ```bash
-docker run --rm -v "${PWD}:/client" -v "${DEFINITION_FOLDER}:/definitions" \
-openapitools/openapi-generator-cli generate -g python \
--i /definitions/index.yml -o /client -c /client/generator-config.json \
--t /client/generator-templates
+pipenv install regula.documentreader.webclient
+```
+
+## Example
+Performing request:
+```python
+from regula.documentreader.webclient.ext.api import DocumentReaderApi
+from regula.documentreader.webclient.ext.models import *
+from regula.documentreader.webclient.gen.models import *
+
+with open("australia_passport.jpg", "rb") as f:
+    input_image = f.read()
+
+with DocumentReaderApi(host='http://localhost:8080') as api:
+    params = ProcessParams(
+        scenario=Scenario.FULL_PROCESS,
+        result_type_output=[Result.DOCUMENT_IMAGE, Result.STATUS, Result.TEXT, Result.IMAGES]
+    )
+    request = RecognitionRequest(process_params=params, images=[input_image])
+    response = api.process(request)
+```
+
+Parsing results:
+```python
+# status examples
+response_status = response.status
+doc_overall_status = "valid" if response_status.overall_status == CheckResult.OK else "not valid"
+
+# text fields example
+doc_number_field = response.text.get_field(TextFieldType.DOCUMENT_NUMBER)
+doc_number_mrz = doc_number_field.get_value()
+doc_number_visual = doc_number_field.get_value(Source.VISUAL)
+doc_number_visual_validity = doc_number_field.source_validity(Source.VISUAL)
+doc_number_mrz_validity = doc_number_field.source_validity(Source.MRZ)
+doc_number_mrz_visual_matching = doc_number_field.cross_source_comparison(Source.MRZ, Source.VISUAL)
+
+# images fields example
+normalized_input_image = response.images.document_image()
+portrait_field = response.images.get_field(GraphicFieldType.PORTRAIT)
+portrait_from_visual = portrait_field.get_value(Source.VISUAL)
+portrait_from_rfid = portrait_field.get_value(Source.RFID, original=True)
 ```
+You can find more detailed guide and run this sample in [example](./example) folder.

dev.md

@@ -0,0 +1,14 @@
+# Development
+
+To regenerate models, clone [latest OpenAPI definitions](https://github.com/regulaforensics/DocumentReader-web-openapi)
+and set `DEFINITION_FOLDER` as path to cloned directory, for example:
+```bash
+DEFINITION_FOLDER="/home/user/projects/DocumentReader-web-openapi"
+```
+Then use next command from the project root:
+```bash
+docker run --rm -v "${PWD}:/client" -v "${DEFINITION_FOLDER}:/definitions" \
+openapitools/openapi-generator-cli generate -g python \
+-i /definitions/index.yml -o /client -c /client/generator-config.json \
+-t /client/generator-templates
+```

example/Pipfile

@@ -0,0 +1,66 @@
+# Regula Document Reader web API Python 3.5+ client
+
+:bulb: Before you start: if you just want to play with an online demo, visit our [playground](https://api.regulaforensics.com).
+
+:warning: NOTE: for some systems `python3` and `pip3` commands should be used, instead of `python` and `pip`.
+
+Requirements:
+- installed python 3.5 or higher
+- installed [pip](https://pip.pypa.io/en/stable/installing/)
+
+Verify Python and pip versions:
+```bash
+python --version  
+> Python 3.8.2
+pip --version     
+> pip 20.2.1 from /home/user/.local/lib/python3.8/site-packages/pip (python 3.8)
+```
+
+Cloning example:
+```bash
+git clone https://github.com/regulaforensics/DocumentReader-web-python-client.git
+cd DocumentReader-web-python-client
+```
+
+Setup project and download dependencies:
+```bash
+pip install -e ./
+```
+
+### Running with local Regula Document Reader web API installation
+
+Follow [the instructions](https://docs.regulaforensics.com/web/quick-start-guide) to run Regula Document Reader web API. 
+Assuming you have successfully launched instance, use next line command to run example:
+```bash
+cd example
+python example.py
+
+# If Regula Document Reader web API is running not on localhost, specify host via env variable:
+API_BASE_PATH="http://192.168.0.101:8080" python example.py
+```
+
+### Running using Regula Document Reader web API test SaaS
+
+Get your [free trial here](https://mobile.regulaforensics.com/). You should obtain `regula.license` file. 
+Copy it to **example** folder. You are ready for running!
+
+Execute example:
+```bash
+cd example
+API_BASE_PATH="https://test-api.regulaforensics.com" python example.py
+```
+
+### Output 
+This sample generates next text output:
+```text
+    ---------------------------------------------------------------------------
+                   Document Overall Status: not valid
+                    Document Number Visual: U0996738
+                       Document Number MRZ: U0996738
+        Validity Of Document Number Visual: 1
+           Validity Of Document Number MRZ: 1
+              MRZ-Visual values comparison: 1
+    ---------------------------------------------------------------------------
+```
+Also, it creates [portrait](portrait.jpg) and [document image](document-image.jpg) pictures inside current folder.
+Edit on your own [example.py](./example.py), and re-run to see your results.

example/Pipfile.lock

@@ -6,13 +6,19 @@
     CheckResult, GraphicFieldType
 
 host = os.getenv("API_BASE_PATH", "http://localhost:8080")
-license = os.getenv("TEST_LICENSE", None)  # optional, used here only for smoke test purposes
+regula_license = os.getenv("TEST_LICENSE", None)  # optional, used here only for smoke test purposes
+
+# read optional local license file
+if os.path.isfile('regula.license') and os.access('regula.license', os.R_OK):
+    with open("regula.license", "rb") as f:
+        print("Found local license file. Using it for performing request...")
+        regula_license = f.read()
 
 with open("australia_passport.jpg", "rb") as f:
     input_image = f.read()
 
 with DocumentReaderApi(host) as api:
-    api.license = license  # used here only for smoke test purposes, most clients will attach license on server side
+    api.license = regula_license
 
     params = ProcessParams(
         scenario=Scenario.FULL_PROCESS,
@@ -27,21 +33,20 @@
 
     # text fields example
     doc_number_field = response.text.get_field(TextFieldType.DOCUMENT_NUMBER)
-    doc_number_visual = doc_number_field.get_value()
-    doc_number_mrz = doc_number_field.get_value(Source.MRZ)
+    doc_number_mrz = doc_number_field.get_value()
+    doc_number_visual = doc_number_field.get_value(Source.VISUAL)
     doc_number_visual_validity = doc_number_field.source_validity(Source.VISUAL)
     doc_number_mrz_validity = doc_number_field.source_validity(Source.MRZ)
     doc_number_mrz_visual_matching = doc_number_field.cross_source_comparison(Source.MRZ, Source.VISUAL)
 
     # images fields example
     document_image = response.images.document_image()
-    portrait_Field = response.images.get_field(GraphicFieldType.PORTRAIT)
-    portrait_From_Visual = portrait_Field.get_value(Source.VISUAL)
-    with open('portrait.jpg', 'wb') as f: f.write(portrait_From_Visual)
-    with open('document-image.jpg', 'wb') as f: f.write(document_image)
-
-    # low-lvl(original) response
-    response.low_lvl_response
+    portrait_field = response.images.get_field(GraphicFieldType.PORTRAIT)
+    portrait_from_visual = portrait_field.get_value(Source.VISUAL)
+    with open('portrait.jpg', 'wb') as f:
+        f.write(portrait_from_visual)
+    with open('document-image.jpg', 'wb') as f:
+        f.write(document_image)
 
     print("""
     ---------------------------------------------------------------------------

example/README.md

@@ -1,8 +1,13 @@
+import base64
+from typing import Union
+
 from regula.documentreader.webclient.ext.models.recognition_response import RecognitionResponse
 from regula.documentreader.webclient.gen import ApiClient, Configuration
 from regula.documentreader.webclient.gen.api import DefaultApi
 from regula.documentreader.webclient.gen.models import ProcessRequest
 
+Base64String = str
+
 
 class DocumentReaderApi(DefaultApi):
 
@@ -24,12 +29,15 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         self.api_client.close()
 
     @property
-    def license(self) -> str:
+    def license(self) -> Base64String:
         return self.__license
 
     @license.setter
-    def license(self, value: str):
-        self.__license = value
+    def license(self, value: Union[Base64String, bytes]):
+        if isinstance(value, bytes):
+            self.__license = base64.b64encode(value).decode("utf-8")
+        else:
+            self.__license = value
 
     def process(self, process_request: ProcessRequest) -> RecognitionResponse:
         process_request.system_info.license = self.license