From e0a327b8e02c9202732752cbb14ca4900c49bc52 Mon Sep 17 00:00:00 2001 From: opensource-tnbt Date: Mon, 30 Nov 2020 23:30:03 +0530 Subject: DOCS: Update the Documentation. This patch updates the documentation for Jerma. Signed-off-by: Sridhar K. N. Rao Change-Id: Ic0d61a74b1c8d31c8facaa16837894fc816ac739 --- docs/state/development/design/index.rst | 0 docs/state/development/overview/index.rst | 0 .../overview/result-api-architecture.png | Bin 0 -> 24756 bytes docs/state/development/overview/result_api.rst | 178 +++++++++++++++++++++ docs/state/development/overview/settings.rst | 38 +++++ 5 files changed, 216 insertions(+) create mode 100644 docs/state/development/design/index.rst create mode 100644 docs/state/development/overview/index.rst create mode 100644 docs/state/development/overview/result-api-architecture.png create mode 100644 docs/state/development/overview/result_api.rst create mode 100644 docs/state/development/overview/settings.rst (limited to 'docs/state/development') diff --git a/docs/state/development/design/index.rst b/docs/state/development/design/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/state/development/overview/index.rst b/docs/state/development/overview/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/state/development/overview/result-api-architecture.png b/docs/state/development/overview/result-api-architecture.png new file mode 100644 index 0000000..e464187 Binary files /dev/null and b/docs/state/development/overview/result-api-architecture.png differ diff --git a/docs/state/development/overview/result_api.rst b/docs/state/development/overview/result_api.rst new file mode 100644 index 0000000..6412c7d --- /dev/null +++ b/docs/state/development/overview/result_api.rst @@ -0,0 +1,178 @@ +SDVState: Result API +==================== + +Table of contents +^^^^^^^^^^^^^^^^^ + +- `Description <#Description>`__ +- `Architecture <#Architecture>`__ +- `Managing configuration <#Managing%20configuration>`__ +- `How to Use <#How%20to%20Use>`__ + +---------------------- + +Description +~~~~~~~~~~~ + +Result API is very simple write-only API for storing results of any size +to multiple storage endpoints. + +Results API focuses on only sending test results to required +destinations so that they can be later viewed by user but do not +implements read functionality as this is not required while running +tests + +Usage is very simple: +''''''''''''''''''''' + +.. code:: python + + from result_api import result_api as api + from result_api import Local + + # First register storage enpoints + endpoint = Local() + api.register_storage(endpoint) + + # Now, use anywhere in program + api.store(data) + +Note: In above example we used only one storage endpoints so, whenever +``api`` will make call to ``store()`` method it will be used. But if +register multiple storage endpoints then whenever ``api`` will make call +to ``store()`` method all endpoints will be called to store data. This +package doesn't allows to selectively make calls to different storage +endpoint for storing. Instead follows **one api -> many endpoint (one to +many)** design. + +---------------------- + +Architecture +~~~~~~~~~~~~ + +|img| + +*ResultsAPI exports data to various storage endpoints like harddisk, +SQL, Mongo, etc. exposed by StorageAPI in write-only mode* + +---------------------- + +Managing configuration +~~~~~~~~~~~~~~~~~~~~~~ + +Result API uses `Conf: Program Settings handler <../conf/readme.md>`__ +to manage all it's settings. So, user can change any settings of +ResultAPI as they need. ``Conf`` allows to change settings in two ways +either read from file ``settings.load_from_file(path/to/file)`` or set +inside program ``settings.setValue(key, Value)`` + +Configurations available: + ++-----------------+---------------------+-------------------------------------+ +| Storage | setting | optional | ++=================+=====================+=====================================+ +| Local Storage | results\_path | Yes, defaults to ``/tmp/local/`` | ++-----------------+---------------------+-------------------------------------+ +| Local Storage | results\_filename | Yes, defaults to ``results.json`` | ++-----------------+---------------------+-------------------------------------+ + +---------------------- + +How to Use +~~~~~~~~~~ + +For using ResultAPI successfully the following steps are required + +#. **Import result\_api instance** from ResultAPI package as this + instance will be commonly used across our program. +#. **Import required StorageAPI** +#. **Set Storage settings** or load settings from file +#. **Create Storage Endpoints from StorageAPI** +#. **Register Storage Endpoints with result\_api** + +Now, result\_api is ready to use. We can send values to all registered +storage endpoints by making a simple call to ```store()`` +method <#store()%20method>`__ + +store() method +'''''''''''''' + +``result_api`` has ``store(dict)`` method for storing data. + +.. code:: python + + # data must be a dict + data = { 'key1': "value1", 'key2': 5, 'dumykeytext': "dummy string value"} + result_api.store(data) + +rfile +''''' + +rfile stands for result file. When you have extremely big value for a +key you would like to tell your storage endpoint to store them in +separate file and refer them in actual key. For storing value of type +file in result\_api use rfile construct. + +.. code:: python + + data = { 'name': 'example', 'myfile': rfile('Text to store in this file')} + result_api.store(data) + # Respective StorageAPI will evaluate "data" for all rfile values and store their text in some separate file/storage-object and put there refernece in "data" + +Use Local Storage with Result API +''''''''''''''''''''''''''''''''' + +.. code:: python + + from result_api import result_api as api + from result_api import Local + from result_api import rfile + + def main(): + # Update settings required for Local storage + settings.setValue('results_path', '/tmp/myresults/') + settings.setValue('results_filename', 'results.json') + + # Register Local() to result_api, this will load above settings automatically + api.register_storage(Local()) + + data = { 'testcase': "RA1.24", 'value': 'Pass', 'logs': rfile('These are logs')} + + # Now, store any data + api.store(data) + +Register Storage Endpoint +''''''''''''''''''''''''' + +.. code:: python + + from result_api.storage.mystorageapi import MyStorageAPI + + # Set required settings values for storage endpoint + settings.setValue('mysetting1', 'value') + settings.setValue('mysetting2', 'value2') + + #Now Register StorageAPI to ResultAPI + endpoint = MyStorageAPI() + api.register_storage(endpoint) + +Changing settings +''''''''''''''''' + +.. code:: python + + # Set values in a yaml file and load it + settings.load_from_file('result.yml') + + # Or set in program + settings.setValue('key', 'value') + + # Note above steps will only change settings values but will not impact any previously registered storage endpoints + # To use endpoints with new value, register new endpoints + endpoint = MyStorageAPI() + api.register_storage(endpoint) + + # And do not forget to unregister old endpoint as they have old settings + api.unregister_storage(old_endpoint) + +.. |img| image:: result-api-architecture.png diff --git a/docs/state/development/overview/settings.rst b/docs/state/development/overview/settings.rst new file mode 100644 index 0000000..29068c5 --- /dev/null +++ b/docs/state/development/overview/settings.rst @@ -0,0 +1,38 @@ +SDVState: Program Settings handler +---------------------------------- + +``from tools.conf import settings`` + +Settings will be loaded from several ``.yaml`` or ``.yml`` files and any +user provided settings files. + +So, that user can use these settings values across program. + +This utility loads settings from yaml files in form of key and value +where key is always ``string`` while value can be of type python: + +- ``int`` e.g. 5, 45, 1234 +- ``str`` e.g. hello, world +- ``float`` e.g. 34.56, 12.7 +- ``list`` e.g. [ ‘month’ , ‘is’, 45 ] +- ``dict`` e.g. {‘program’: ‘sdv’, ‘language’: ‘python’} +- ``bool`` e.g. True, False + +keys are case-insensitive +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The utility is case-insensitive to keys used as it automatically +converts all keys to lower case. + +E.g. ``Program : sdv``, ``program : sdv``, ``PrOgRam : sdv`` all are +same. + +- ``settings.load_from_file(path/to/file)`` +- ``settings.load_from_env()`` +- ``settings.load_from_dir(directory/to/search/yamls)`` + +``settings.load_from_dir()`` reads all yaml files in given directory and +all it’s sub-directory recursively in ascending order, hence if a +configuration item exists in more than one file, then the setting in the +file that occurs in the last read file will have high precedence and +overwrite previous values. . -- cgit 1.2.3-korg