aboutsummaryrefslogtreecommitdiffstats
path: root/sdv/docs/docker/state/development/overview/result_api.rst
blob: 12fd62ceb297364443c6af34bc480ba45a1def12 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
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