more documentation for tables import:

Author: cstenac

dataikuapi/dss/project.py

@@ -825,9 +825,18 @@ def get_object_discussions(self):
     ########################################################
 
     def init_tables_import(self):
-        return TablesImportBuffer(self.client, self.project_key)
+        """
+        Start an operation to import Hive or SQL tables as datasets into this project
+
+        :returns: a :class:`TablesImportDefinition` to add tables to import
+        :rtype: :class:`TablesImportDefinition`
+        """
+        return TablesImportDefinition(self.client, self.project_key)
 
-class TablesImportBuffer(object):
+class TablesImportDefinition(object):
+    """
+    Temporary structure holding the list of tables to import
+    """
 
     def __init__(self, client, project_key):
         """Do not call this directly, use :meth:`DSSProject.init_tables_import`"""
@@ -836,19 +845,30 @@ def __init__(self, client, project_key):
         self.keys = []
 
     def add_hive_table(self, hive_database, hive_table):
+        """Add a Hive table to the list of tables to import"""
         self.keys.append({
             "connectionName" : "@virtual(hive-jdbc):" + hive_database,
             "name" : hive_table
         })
 
     def add_sql_table(self, connection, schema, table):
+        """Add a SQL table to the list of table to import"""
         self.keys.append({
             "connectionName" : connection,
             "schema": schema,
             "name" : table
         })
 
     def prepare(self):
+        """
+        Run the first step of the import process. In this step, DSS will check
+        the tables whose import you have requested and prepare dataset names and 
+        target connections
+
+        :returns: a :class:`TablesPreparedImport` object that allows you to finalize the import process
+        :rtype: :class:`TablesPreparedImport`
+
+        """
         ret = self.client._perform_json("POST", "/projects/%s/datasets/tables-import/actions/prepare-from-keys" % (self.project_key),
                 body = {"keys": self.keys} )
 
@@ -857,16 +877,19 @@ def prepare(self):
         return TablesPreparedImport(self.client, self.project_key, future.get_result())
 
 class TablesPreparedImport(object):
-    """Do not call this directly, use :meth:`DSSProject.init_tables_import` and then prepare"""
+    """Result of preparing a tables import. Import can now be finished"""
+    
     def __init__(self, client, project_key, candidates):
+        """Do not call this directly, use :meth:`DSSProject.init_tables_import` and then prepare"""
         self.client = client
         self.project_key = project_key
         self.candidates = candidates
 
     def execute(self):
         """
-        Executes the import in background
+        Starts executing the import in background and returns a :class:`dataikuapi.dss.future.DSSFuture` to wait on the result
 
+        :returns: a future to wait on the result
         :rtype: :class:`dataikuapi.dss.future.DSSFuture`
         """
         ret = self.client._perform_json("POST", "/projects/%s/datasets/tables-import/actions/execute-from-candidates" % (self.project_key),

dataikuapi/dss/recipe.py

@@ -28,22 +28,21 @@ def delete(self):
 
     def get_definition_and_payload(self):
         """
-        Get the definition of the recipe
+        Gets the definition of the recipe
 
-        Returns:
-            the definition, as a DSSRecipeDefinitionAndPayload object, containing the recipe definition itself and its payload
+        :returns: the definition, as a :py:class:`DSSRecipeDefinitionAndPayload` object, containing the recipe definition itself and its payload
+        :rtype: :py:class:`DSSRecipeDefinitionAndPayload`
         """
         data = self.client._perform_json(
                 "GET", "/projects/%s/recipes/%s" % (self.project_key, self.recipe_name))
         return DSSRecipeDefinitionAndPayload(data)
 
     def set_definition_and_payload(self, definition):
         """
-        Set the definition of the recipe
+        Sets and saves the definition of the recipe
 
-        Args:
-            definition: the definition, as a DSSRecipeDefinitionAndPayload object. You should only set a definition object 
-            that has been retrieved using the get_definition call.
+        :param definition object: the definition, as a :py:class:`DSSRecipeDefinitionAndPayload` object. You should only set a definition object 
+            that has been retrieved using the :py:meth:get_definition_and_payload call.
         """
         return self.client._perform_json(
                 "PUT", "/projects/%s/recipes/%s" % (self.project_key, self.recipe_name),