Update statistics's API client according to latest API changes

fterrazzoni · fterrazzoni · commit da215496b7ce · 2020-02-10T20:39:48.000+01:00
diff --git a/dataikuapi/dss/dataset.py b/dataikuapi/dss/dataset.py
@@ -4,7 +4,7 @@
 import json
 from .metrics import ComputedMetrics
 from .discussion import DSSObjectDiscussions
-from .statistics import DSSStatisticsWorksheet, DSSStatisticsCard
+from .statistics import DSSStatisticsWorksheet
 
 class DSSDataset(object):
     """
@@ -210,6 +210,11 @@ def run_checks(self, partition='', checks=None):
     ########################################################
 
     def list_statistics_worksheets(self, as_objects=True):
+        """
+        List the statistics worksheets associated to this dataset.
+
+        :rtype: list of :class:`dataikuapi.dss.statistics.DSSStatisticsWorksheet`
+        """
         worksheets = self.client._perform_json(
             "GET", "/projects/%s/datasets/%s/statistics/worksheets/" % (self.project_key, self.dataset_name))
         if as_objects:
@@ -219,13 +224,13 @@ def list_statistics_worksheets(self, as_objects=True):
 
     def create_statistics_worksheet(self, name="My worksheet"):
         """
-        Create a new worksheet in the project, and return a handle to interact with it.
+        Create a new worksheet in the dataset, and return a handle to interact with it.
 
         :param string input_dataset: input dataset of the worksheet
         :param string worksheet_name: name of the worksheet
 
         Returns:
-            A :class:`dataikuapi.dss.dataset.DSSStatisticsWorksheet` dataset handle
+            A :class:`dataikuapi.dss.statistics.DSSStatisticsWorksheet` dataset handle
         """
 
         worksheet_definition = {
@@ -248,11 +253,11 @@ def create_statistics_worksheet(self, name="My worksheet"):
 
     def get_statistics_worksheet(self, worksheet_id):
         """
-        Get a handle to interact with a specific worksheet
+        Get a handle to interact with a statistics worksheet
 
         :param string worksheet_id: the ID of the desired worksheet
 
-        :returns: A :class:`dataikuapi.dss.worksheet.DSSStatisticsWorksheet` worksheet handle
+        :returns: A :class:`dataikuapi.dss.statistics.DSSStatisticsWorksheet` worksheet handle
         """
         return DSSStatisticsWorksheet(self.client, self.project_key, self.dataset_name, worksheet_id)
 
diff --git a/dataikuapi/dss/statistics.py b/dataikuapi/dss/statistics.py
@@ -7,7 +7,7 @@
 
 class DSSStatisticsWorksheet(object):
     """
-    A handle to interact with a worksheet on the DSS instance
+    A handle to interact with a worksheet.
     """
 
     def __init__(self, client, project_key, dataset_name, worksheet_id):
@@ -16,109 +16,169 @@ def __init__(self, client, project_key, dataset_name, worksheet_id):
         self.dataset_name = dataset_name
         self.worksheet_id = worksheet_id
 
-    ########################################################
-    # Worksheet deletion
-    ########################################################
-
     def delete(self):
         """
-        Delete the worksheet
+        Deletes the worksheet
         """
         return self.client._perform_empty(
             "DELETE", "/projects/%s/datasets/%s/statistics/worksheets/%s" % (self.project_key, self.dataset_name, self.worksheet_id))
 
-    ########################################################
-    # Worksheet definition
-    ########################################################
+    def get_settings(self):
+        """
+        Fetches the settings of this worksheet.
 
-    def get_definition(self):
+        :return: an object to interact with the settings
+        :rtype: :class:`DSSStatisticsWorksheetSettings`
+        """
+        worksheet_json = self.client._perform_json(
+            "GET", "/projects/%s/datasets/%s/statistics/worksheets/%s" % (
+                self.project_key, self.dataset_name, self.worksheet_id)
+        )
+        return DSSStatisticsWorksheetSettings(self.client, self.project_key,
+                                              self.dataset_name, self.worksheet_id, worksheet_json)
+
+    def run_worksheet(self):
         """
-        Get the definition of the worksheet
+        Computes the results of the whole worksheet.
 
-        Returns:
-            the definition, as a JSON object
+        :returns: a :class:`~dataikuapi.dss.future.DSSFuture` handle
         """
-        return self.client._perform_json(
-            "GET", "/projects/%s/datasets/%s/statistics/worksheets/%s" % (self.project_key, self.dataset_name, self.worksheet_id))
 
-    def set_definition(self, definition):
+        root_card = self.get_settings().get_raw()['rootCard']
+        return self.run_card(root_card)
+
+    def run_card(self, card):
         """
-        Set the definition of the worksheet
+        Runs a card in the context of the worksheet.
+
+        Note: the card does not need to belong to the worksheet.
 
-        Args:
-            definition: the definition, as a JSON object. You should only set a definition object 
-            that has been retrieved using the get_definition call.
+        :param card: a card to compute
+        :type card: :class:`DSSStatisticsCardSettings` or dict
+        :returns: a :class:`~dataikuapi.dss.future.DSSFuture` handle to the task of computing card's results
         """
-        return self.client._perform_json(
-            "PUT", "/projects/%s/datasets/%s/statistics/worksheets/%s" % (self.project_key, self.dataset_name, self.worksheet_id), body=definition)
 
-    def add_card(self, card_definition):
+        card = DSSStatisticsCardSettings._from_card_or_dict(self.client, card)
+        future_response = self.client._perform_json(
+            "POST",
+            "/projects/%s/datasets/%s/statistics/worksheets/%s/actions/run-card" % (
+                self.project_key, self.dataset_name, self.worksheet_id),
+            body=card.get_raw()
+        )
+        return DSSFuture(self.client, future_response.get("jobId", None), future_response)
+
+    def run_computation(self, computation):
         """
-        Add a new card to the worksheet
+        Runs a computation in the context of the worksheet.
 
-        The precise structure of ``card_definition`` depends on the specific card type. To know which 
-        fields exist for a given card type, create a worksheet from the UI,  and use 
-        :meth:`get_definition` to retrieve the configuration of the worksheet and inspect it.
+        :param computation: a card to compute
+        :type computation: :class:`DSSStatisticsComputationSettings` or dict
+        :returns: a :class:`~dataikuapi.dss.future.DSSFuture` handle to the task of computing computation's results
         """
-        worksheet = self.get_definition()
-        worksheet["rootCard"]["cards"].append(card_definition)
-        self.set_definition(worksheet)
 
-    def get_standalone_cards(self):
+        computation = DSSStatisticsComputationSettings._from_computation_or_dict(
+            computation)
+        future_response = self.client._perform_json(
+            "POST",
+            "/projects/%s/datasets/%s/statistics/worksheets/%s/actions/run-computation" % (
+                self.project_key, self.dataset_name, self.worksheet_id),
+            body=computation.get_raw()
+        )
+        return DSSFuture(self.client, future_response.get("jobId", None), future_response)
+
+
+class DSSStatisticsWorksheetSettings(object):
+    def __init__(self, client, project_key, dataset_name, worksheet_id, worksheet_definition):
+        self.client = client
+        self.project_key = project_key
+        self.dataset_name = dataset_name
+        self.worksheet_id = worksheet_id
+        self._worksheet_definition = worksheet_definition
+
+    def add_card(self, card):
         """
-        Extract cards from this worksheet. A standalone card can be computed without worksheet.
+        Adds a new card to the worksheet.
 
-        :returns: An list of :class:`dataikuapi.dss.worksheet.DSSStatisticsCard`
+        :param card: card to be added
+        :type card: :class:`DSSStatisticsCardSettings` or dict
         """
+        card = DSSStatisticsCardSettings._from_card_or_dict(self.client, card)
+        self._worksheet_definition['rootCard']['cards'].append(card)
 
-        definition = self.get_definition()
-        standalone_cards = []
-        for card in definition["rootCard"]["cards"]:
-            standalone_cards.append(DSSStatisticsCard(
-                self.client, self.project_key, self.dataset_name, definition['dataSpec'], card))
+    def list_cards(self):
+        """
+        Lists the cards of this worksheet.
 
-        return standalone_cards
+        :rtype: list of :class:`DSSStatisticsCardSettings`
+        """
+        return [DSSStatisticsCardSettings(self.client, card_definition)
+                for card_definition in self._worksheet_definition['rootCard']['cards']]
 
-    ########################################################
-    # Obtaining worksheet results
-    ########################################################
+    def get_raw(self):
+        """
+        Gets a reference to the raw settings of the worksheet.
 
-    def compute(self):
+        :rtype: dict
         """
-        Compute the results of the worksheet
+        return self._worksheet_definition
 
-        :returns: a :class:`~dataikuapi.dss.future.DSSFuture` handle to the task of computing worksheet's results
+    def save(self):
+        """
+        Saves the settings to DSS
         """
+        return self.client._perform_json(
+            "PUT",
+            "/projects/%s/datasets/%s/statistics/worksheets/%s" % (
+                self.project_key, self.dataset_name, self.worksheet_id),
+            body=self._worksheet_definition
+        )
 
-        future_response = self.client._perform_json(
-            "POST", "/projects/%s/datasets/%s/statistics/worksheets/%s/actions/compute-worksheet" % (self.project_key, self.dataset_name, self.worksheet_id))
 
-        return DSSFuture(self.client, future_response.get("jobId", None), future_response)
+class DSSStatisticsCardSettings(object):
+    def __init__(self, client, card_definition):
+        self.client = client
+        self._card_definition = card_definition
 
+    def get_raw(self):
+        """
+        Gets a reference to the raw settings of the card.
 
-class DSSStatisticsCard(object):
-    """
-    A handle to interact with a standalone card (a card outside a worksheet)
+        :rtype: dict
+        """
+        return self._card_definition
 
-    Unlike a worksheet, a standalone card is not persisted on the DSS instance
-    """
+    def compile(self):
+        """
+        Gets the underlying computation used to compute the card results.
 
-    def __init__(self, client, project_key, dataset_name, data_spec, card):
-        self.client = client
-        self.project_key = project_key
-        self.dataset_name = dataset_name
-        self.data_spec = data_spec
-        self.card = card
+        :rtype: DSSStatisticsComputationSettings
+        """
+        computation_json = self.client._perform_json(
+            "POST", "/statistics/cards/compile", body=self._card_definition
+        )
+        return DSSStatisticsComputationSettings(computation_json)
+
+    @staticmethod
+    def _from_card_or_dict(client, card_or_dict):
+        if isinstance(card_or_dict, DSSStatisticsCardSettings):
+            card_or_dict = card_or_dict.get_raw()
+        return DSSStatisticsCardSettings(client, card_or_dict)
 
-    def compute(self):
+
+class DSSStatisticsComputationSettings(object):
+    def __init__(self, computation_definition):
+        self._computation_definition = computation_definition
+
+    def get_raw(self):
         """
-        Compute the results of this single card (without worksheet)
+        Gets the raw settings of the computation.
 
-        :returns: a :class:`~dataikuapi.dss.future.DSSFuture` handle to the task of computing card's results
+        :rtype: dict
         """
+        return self._computation_definition
 
-        future_response = self.client._perform_json(
-            "POST", "/projects/%s/datasets/%s/statistics/cards/compute-card" % (
-                self.project_key, self.dataset_name),
-            body={"card": self.card, "dataSpec": self.data_spec})
-        return DSSFuture(self.client, future_response.get("jobId", None), future_response)
+    @staticmethod
+    def _from_computation_or_dict(computation_or_dict):
+        if isinstance(computation_or_dict, DSSStatisticsComputationSettings):
+            computation_or_dict = computation_or_dict.get_raw()
+        return DSSStatisticsComputationSettings(computation_or_dict)
