add option to run example with local license

Author: hleb-albau

.gitignore

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

example/README.md

@@ -1,15 +1,12 @@
 # Regula Document Reader web API Python 3.5+ client
 
-Before you start: if you just want to play with an online demo, visit our [playground](https://api.regulaforensics.com).
+:bulb: Before you start: if you just want to play with an online demo, visit our [playground](https://api.regulaforensics.com).
 
-## Running local example
-
-NOTE: for some systems `python3` and `pip3` commands should be used, instead of `python` and `pip`.
+: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/)
-- running [Regula Document Reader web API with trial license](https://docs.regulaforensics.com/web/quick-start-guide)
 
 Verify Python and pip versions:
 ```bash
@@ -30,15 +27,30 @@ Setup project and download dependencies:
 pip install -e ./
 ```
 
-Run example:
+### 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, also specify host via env variable:
+# 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
     ---------------------------------------------------------------------------
@@ -50,11 +62,5 @@ This sample generates next text output:
               MRZ-Visual values comparison: 1
     ---------------------------------------------------------------------------
 ```
-Also, it creates [portrait](portrait.jpg) and [document image](document-image.jpg) 
-pictures inside current folder.
-
+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.
-
-## Detailed guide
-
-tbd

example/example.py

@@ -8,11 +8,17 @@
 host = os.getenv("API_BASE_PATH", "http://localhost:8080")
 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...")
+        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 = license
 
     params = ProcessParams(
         scenario=Scenario.FULL_PROCESS,

regula/documentreader/webclient/ext/api/document_reader_api.py

@@ -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