Finishing the refactoring

Author: riibeirogabriel

README.md

@@ -19,7 +19,14 @@ pip install learning-orchestra-client
 
 # Usage
 
-Each functionality in learningOrchestra is contained in its own class. Check the [python client docs](https://learningorchestra.github.io/pythonClient/) for all the available.
+Each interoperable REST API service described in Learning Orchestra is translated 
+into Python. Details at [python client docs](https://learningorchestra.github.io/pythonClient/). 
+Furthermore, some extra method calls are included into Python client API to simplify 
+even more the Machine Learning services. For instance, the REST API is asynchronous, 
+except for GET HTTP requests, but the Python client enables also the synchronous API calls. 
+The wait API method, useful to receive notifications from ML pipes, is another important 
+example to ilustrate an extension of the original REST API. 
+
 
 # Example
 

learning_orchestra_client/builder/builder.py

@@ -1,4 +1,4 @@
-from learning_orchestra_client.observe import Observer
+from learning_orchestra_client.observe.observe import Observer
 from learning_orchestra_client.util._response_treat import ResponseTreat
 from learning_orchestra_client.util._entity_reader import EntityReader
 import requests
@@ -27,9 +27,10 @@ def run_spark_ml_sync(self,
                           pretty_response: bool = False) -> Union[dict, str]:
         """
         description: This method call runs several steps of a machine
-        learning pipeline (transform, tune, train and evaluate, for instance) using
-        a model code and several classifiers. It represents a way to run an entire pipeline.
-        The caller waits until the method execution ends, since it is a synchronous method.
+        learning pipeline (transform, tune, train and evaluate, for instance)
+        using a model code and several classifiers. It represents a way to run
+        an entire pipeline. The caller waits until the method execution ends,
+        since it is a synchronous method.
 
         train_dataset_name: Represent final train dataset.
         test_dataset_name: Represent final test dataset.
@@ -62,9 +63,10 @@ def run_spark_ml_async(self,
                            pretty_response: bool = False) -> Union[dict, str]:
         """
         description: This method call runs several steps of a machine
-        learning pipeline (transform, tune, train and evaluate, for instance) using
-        a model code and several classifiers. It represents a way to run an entire pipeline.
-        The caller does not wait until the method execution ends, since it is an asynchronous method.
+        learning pipeline (transform, tune, train and evaluate, for instance)
+        using a model code and several classifiers. It represents a way to run
+        an entire pipeline. The caller does not wait until the method execution
+        ends, since it is an asynchronous method.
 
         train_dataset_name: Represent final train dataset.
         test_dataset_name: Represent final test dataset.
@@ -120,9 +122,9 @@ def search_builder_register_predictions(self,
         set at 20 rows per request)
         skip: Number of rows to skip in pagination(default: 0)
 
-        return: A page with some tuples or registers inside or an error if the pipeline runs
-        incorrectly. The current page is also returned to be used in
-        future content requests.
+        return: A page with some tuples or registers inside or an error if the
+        pipeline runs incorrectly. The current page is also returned to be used
+        in future content requests.
         """
 
         response = self.__entity_reader.read_entity_content(
@@ -171,17 +173,16 @@ def delete_builder(self, builder_name: str, pretty_response: bool = False) \
 
         return self.__response_treat.treatment(response, pretty_response)
 
-    def wait(self, dataset_name: str, timeout: str) -> dict:
+    def wait(self, dataset_name: str, timeout: int = None) -> dict:
         """
            description: This method is responsible to create a synchronization
            barrier for the run_spark_ml_async method.
 
            dataset_name: Represents the pipeline name.
-           timeout: Represents the time in seconds to wait for a builder to finish its run. The -1 value
-           waits until the builder finishes.
+           timeout: Represents the time in seconds to wait for a builder to
+           finish its run.
 
            return: JSON object with an error message, a warning message or a
            correct execution of a pipeline
         """
         return self.__observer.wait(dataset_name, timeout)
-

learning_orchestra_client/dataset/_dataset.py

@@ -1,4 +1,4 @@
-from ..observe import Observer
+from learning_orchestra_client.observe.observe import Observer
 from learning_orchestra_client.util._response_treat import ResponseTreat
 from learning_orchestra_client.util._entity_reader import EntityReader
 import requests
@@ -59,7 +59,8 @@ def insert_dataset_async(self,
 
         return: A JSON object with an error or warning message or a URL
         indicating the correct operation (the caller must use such an URL to
-        proceed future checks to verify if the dataset is inserted - using wait method).
+        proceed future checks to verify if the dataset is inserted - using wait
+        method).
         """
         request_body = {self.__DATASET_NAME: dataset_name,
                         self.__URL: url}
@@ -122,7 +123,7 @@ def search_dataset_content(self,
         set at 20 rows per request)
         skip: Number of rows to skip in pagination(default: 0)
 
-        return A page with some tuples or registers inside or an error if there
+        return: A page with some tuples or registers inside or an error if there
         is no such dataset. The current page is also returned to be used in
         future content requests.
         """
@@ -132,14 +133,14 @@ def search_dataset_content(self,
 
         return self.__response_treat.treatment(response, pretty_response)
 
-    def wait(self, dataset_name: str, timeout: str) -> dict:
+    def wait(self, dataset_name: str, timeout: int = None) -> dict:
         """
            description: This method is responsible to create a synchronization
            barrier for the insert_dataset_async method.
 
            dataset_name: Represents the dataset name.
-           timeout: Represents the time in seconds to wait for a dataset download to finish its run. The -1 value
-           waits until the download finishes.
+           timeout: Represents the time in seconds to wait for a dataset
+           download to finish its run.
 
            return: JSON object with an error message, a warning message or a
            correct execution of a pipeline

learning_orchestra_client/evaluate/_evaluate.py

@@ -1,4 +1,4 @@
-from ..observe import Observer
+from learning_orchestra_client.observe.observe import Observer
 from learning_orchestra_client.util._response_treat import ResponseTreat
 from learning_orchestra_client.util._entity_reader import EntityReader
 import requests
@@ -93,8 +93,8 @@ def create_evaluate_async(self,
     def search_all_evaluates(self, pretty_response: bool = False) \
             -> Union[dict, str]:
         """
-        description: This method retrieves all created evaluations, i.e., it does
-        not retrieve the specific evaluation content.
+        description: This method retrieves all created evaluations, i.e., it
+        does not retrieve the specific evaluation content.
 
         pretty_response: If true it returns a string, otherwise a dictionary.
 
@@ -107,12 +107,12 @@ def search_all_evaluates(self, pretty_response: bool = False) \
     def delete_evaluate(self, name: str, pretty_response=False) \
             -> Union[dict, str]:
         """
-        description: This method is responsible for deleting an evaluation result.
-        This delete operation is asynchronous, so it does not lock the caller
-         until the deletion finished. Instead, it returns a JSON object with a
-         URL for a future use. The caller uses the wait method for delete checks. If a
-         dataset was used by another task (Ex. projection, histogram, pca, tune
-         and so forth), it cannot be deleted.
+        description: This method is responsible for deleting an evaluation
+        result. This delete operation is asynchronous, so it does not lock the
+        caller until the deletion finished. Instead, it returns a JSON object
+        with a URL for a future use. The caller uses the wait method for delete
+        checks. If a dataset was used by another task (Ex. projection,
+        histogram, tune, and so forth), it cannot be deleted.
 
         pretty_response: If true it returns a string, otherwise a dictionary.
         name: Represents the model name.
@@ -144,7 +144,7 @@ def search_evaluate_content(self,
         set at 20 rows per request)
         skip: Number of rows to skip in pagination(default: 0)
 
-        return A page with some metadata inside or an error if there
+        return: A page with some metadata inside or an error if there
         is no such dataset. The current page is also returned to be used in
         future content requests.
         """
@@ -154,14 +154,15 @@ def search_evaluate_content(self,
 
         return self.__response_treat.treatment(response, pretty_response)
 
-    def wait(self, name: str, timeout: str) -> dict:
+    def wait(self, name: str, timeout: int = None) -> dict:
         """
            description: This method is responsible to create a synchronization
-           barrier for the create_evaluate_async method and delete_evaluate_async method.
+           barrier for the create_evaluate_async method and
+           delete_evaluate_async method.
 
            name: Represents the model name.
-           timeout: Represents the time in seconds to wait for an evaluation to finish its run. The -1 value
-           waits until the evaluation finishes.
+           timeout: Represents the time in seconds to wait for an evaluation to
+           finish its run.
 
            return: JSON object with an error message, a warning message or a
            correct evaluation result

learning_orchestra_client/evaluate/scikitlearn.py

@@ -2,12 +2,6 @@
 
 
 class EvaluateScikitLearn(Evaluate):
-    __PARENT_NAME_FIELD = "parentName"
-    __METHOD_NAME_FIELD = "method"
-    __ClASS_PARAMETERS_FIELD = "methodParameters"
-    __NAME_FIELD = "name"
-    __DESCRIPTION_FIELD = "description"
-
     def __init__(self, cluster_ip: str):
         self.__api_path = "/api/learningOrchestra/v1/evaluate/scikitlearn"
         self.__cluster_ip = cluster_ip

learning_orchestra_client/evaluate/tensorflow.py

@@ -2,13 +2,7 @@
 
 
 class EvaluateTensorflow(Evaluate):
-    __PARENT_NAME_FIELD = "parentName"
-    __METHOD_NAME_FIELD = "method"
-    __ClASS_PARAMETERS_FIELD = "methodParameters"
-    __NAME_FIELD = "name"
-    __DESCRIPTION_FIELD = "description"
-
     def __init__(self, cluster_ip: str):
         self.__api_path = "/api/learningOrchestra/v1/evaluate/tensorflow"
         self.__cluster_ip = cluster_ip
-        super().__init__(cluster_ip, self.__api_path)
+        super().__init__(cluster_ip, self.__api_path)

learning_orchestra_client/explore/_explore.py

@@ -1,4 +1,4 @@
-from ..observe import Observer
+from learning_orchestra_client.observe.observe import Observer
 from learning_orchestra_client.util._response_treat import ResponseTreat
 from learning_orchestra_client.util._entity_reader import EntityReader
 import requests
@@ -21,13 +21,13 @@ def __init__(self, cluster_ip: str, api_path: str):
         self.__observer = Observer(self.__cluster_ip)
 
     def create_explore_sync(self,
-                             name: str,
-                             model_name: str,
-                             parent_name: str,
-                             method_name: str,
-                             parameters: dict,
-                             description: str = "",
-                             pretty_response: bool = False) -> \
+                            name: str,
+                            model_name: str,
+                            parent_name: str,
+                            method_name: str,
+                            parameters: dict,
+                            description: str = "",
+                            pretty_response: bool = False) -> \
             Union[dict, str]:
         """
         description: This method runs an evaluation about a model in sync mode
@@ -57,16 +57,17 @@ def create_explore_sync(self,
         return self.__response_treat.treatment(response, pretty_response)
 
     def create_explore_async(self,
-                              name: str,
-                              model_name: str,
-                              parent_name: str,
-                              method_name: str,
-                              parameters: dict,
-                              description: str = "",
-                              pretty_response: bool = False) -> \
+                             name: str,
+                             model_name: str,
+                             parent_name: str,
+                             method_name: str,
+                             parameters: dict,
+                             description: str = "",
+                             pretty_response: bool = False) -> \
             Union[dict, str]:
         """
-        description: This method runs an explore service about a model in async mode
+        description: This method runs an explore service about a model in async
+        mode
 
         pretty_response: If true it returns a string, otherwise a dictionary.
         name: Is the name of the model that will be explored.
@@ -93,8 +94,8 @@ def create_explore_async(self,
     def search_all_explores(self, pretty_response: bool = False) \
             -> Union[dict, str]:
         """
-        description: This method retrieves all created explorations, i.e., it does
-        not retrieve the specific explore content.
+        description: This method retrieves all created explorations, i.e., it
+        does not retrieve the specific explore content.
 
         pretty_response: If true it returns a string, otherwise a dictionary.
 
@@ -110,9 +111,9 @@ def delete_explore(self, name: str, pretty_response=False) \
         description: This method is responsible for deleting an explore result.
         This delete operation is asynchronous, so it does not lock the caller
          until the deletion finished. Instead, it returns a JSON object with a
-         URL for a future use. The caller uses the wait method for delete checks. If a
-         dataset was used by another task (Ex. projection, histogram, pca, tune
-         and so forth), it cannot be deleted.
+         URL for a future use. The caller uses the wait method for delete
+         checks. If a dataset was used by another task (Ex. projection,
+         histogram, tune and so forth), it cannot be deleted.
 
         pretty_response: If true it returns a string, otherwise a dictionary.
         name: Represents the model name.
@@ -127,17 +128,17 @@ def delete_explore(self, name: str, pretty_response=False) \
         return self.__response_treat.treatment(response, pretty_response)
 
     def search_explore_image(self,
-                                name: str,
-                                pretty_response: bool = False) \
+                             name: str,
+                             pretty_response: bool = False) \
             -> Union[dict, str]:
         """
         description:  This method is responsible for retrieving the explore
         image to be plotted
 
         pretty_response: If true it returns a string, otherwise a dictionary.
-        name: Is the name of the model.
+        name: Is the name of the explore instance.
 
-        return An URL with a link for an image or an error if there
+        return: An URL with a link for an image or an error if there
         is no such result.
         """
 
@@ -146,16 +147,37 @@ def search_explore_image(self,
 
         return self.__response_treat.treatment(response, pretty_response)
 
-    def wait(self, name: str, timeout: str) -> dict:
+    def search_explore_metadata(self,
+                                name: str,
+                                pretty_response: bool = False) \
+            -> Union[dict, str]:
+        """
+        description:  This method is responsible for retrieving the explore
+        metadata image.
+
+        pretty_response: If true it returns a string, otherwise a dictionary.
+        name: Is the name of the explore instance.
+
+        return: A page with some metadata inside or an error if there
+        is no such dataset. The current page is also returned to be used in
+        future content requests.
+        """
+
+        response = self.__entity_reader.read_explore_image_metadata(name)
+
+        return self.__response_treat.treatment(response, pretty_response)
+
+    def wait(self, name: str, timeout: int = None) -> dict:
         """
-           description: This method is responsible to create a synchronization
-           barrier for the create_explore_async method, delete_explore_async method.
+       description: This method is responsible to create a synchronization
+       barrier for the create_explore_async method, delete_explore_async
+       method.
 
-           name: Represents the model name.
-           timeout: Represents the time in seconds to wait for an explore to finish its run. The -1 value
-           waits until the explore finishes.
+       name: Represents the model name.
+       timeout: Represents the time in seconds to wait for an explore to
+       finish its run.
 
-           return: JSON object with an error message, a warning message or a
-           correct explore result (the image URL as an explore result)
+       return: JSON object with an error message, a warning message or a
+       correct explore result (the image URL as an explore result)
         """
         return self.__observer.wait(name, timeout)