Doc cleanup

Author: cstenac

dataikuapi/dss/admin.py

@@ -30,23 +30,26 @@ def delete(self):
     def get_definition(self):
         """
         Get the connection's definition (type, name, params, usage restrictions)
-
         Note: this call requires an API key with admin rights
         
-        Returns:
-            the connection definition, as a JSON object
+        :returns: The connection definition, as a dict.
+
+        The exact structure of the returned dict is not documented and depends on the connection
+        type. Create connections using the DSS UI and call :meth:`get_definition` to see the 
+        fields that are in it.
         """
         return self.client._perform_json(
             "GET", "/admin/connections/%s" % self.name)
 
     def set_definition(self, description):
         """
         Set the connection's definition.
-        
         Note: this call requires an API key with admin rights
         
-        Args:
-            definition: the definition for the connection, as a JSON object.            
+        You should only :meth:`set_definition` using an object that you obtained through :meth:`get_definition`, 
+        not create a new dict.
+
+        :param dict the definition for the connection, as a dict.
         """
         return self.client._perform_json(
             "PUT", "/admin/connections/%s" % self.name,
@@ -58,12 +61,11 @@ def set_definition(self, description):
 
     def sync_root_acls(self):
         """
-        Resync root permissions on this connection path
-        
-        Returns:
-            a DSSFuture handle to the task of resynchronizing the permissions
-        
+        Resync root permissions on this connection path. This is only useful for HDFS connections
+        when DSS is in multi-user-security mode.
         Note: this call requires an API key with admin rights
+        
+        :returns: a :class:`~dataikuapi.dss.future.DSSFuture`  handle to the task of resynchronizing the permissions
         """
         future_response = self.client._perform_json(
             "POST", "/admin/connections/%s/sync" % self.name,
@@ -72,12 +74,11 @@ def sync_root_acls(self):
 
     def sync_datasets_acls(self):
         """
-        Resync permissions on datasets in this connection path
-        
-        Returns:
-            a DSSFuture handle to the task of resynchronizing the permissions
-        
+        Resync permissions on datasets in this connection path. This is only useful for HDFS connections
+        when DSS is in multi-user-security mode.
         Note: this call requires an API key with admin rights
+        
+        :returns: a :class:`~dataikuapi.dss.future.DSSFuture`  handle to the task of resynchronizing the permissions
         """
         future_response = self.client._perform_json(
             "POST", "/admin/connections/%s/sync" % self.name,
@@ -87,7 +88,8 @@ def sync_datasets_acls(self):
 
 class DSSUser(object):
     """
-    A handle for a user on the DSS instance
+    A handle for a user on the DSS instance.
+    Do not create this directly, use :meth:`dataikuapi.DSSClient.get_user`
     """
     def __init__(self, client, login):
         self.client = client
@@ -100,7 +102,6 @@ def __init__(self, client, login):
     def delete(self):
         """
         Deletes the user
-
         Note: this call requires an API key with admin rights
         """
         return self.client._perform_empty(
@@ -113,7 +114,6 @@ def delete(self):
     def get_definition(self):
         """
         Get the user's definition (login, type, display name, permissions, ...)
-
         Note: this call requires an API key with admin rights
 
         :return: the user's definition, as a dict
@@ -124,31 +124,29 @@ def get_definition(self):
     def set_definition(self, definition):
         """
         Set the user's definition.
-
         Note: this call requires an API key with admin rights
 
-        :param dict definition: the definition for the user, as a dict. You should
-            obtain the definition using get_definition, not create one.
-            The fields that can be changed are:
-                
+        You should only :meth:`set_definition` using an object that you obtained through :meth:`get_definition`, 
+        not create a new dict.
+
+        The fields that may be changed in a user definition are:
+
                 * email
-                
                 * displayName
-                
                 * groups
-                
                 * userProfile
-                
-                * password
+                * password 
 
+        :param dict definition: the definition for the user, as a dict
         """
         return self.client._perform_json(
             "PUT", "/admin/users/%s" % self.login,
             body = definition)
 
 class DSSGroup(object):
     """
-    A group on the DSS instance
+    A group on the DSS instance.
+    Do not create this directly, use :meth:`dataikuapi.DSSClient.get_group`
     """
     def __init__(self, client, name):
         self.client = client
@@ -160,8 +158,7 @@ def __init__(self, client, name):
 
     def delete(self):
         """
-        Delete the group
-
+        Deletes the group
         Note: this call requires an API key with admin rights
         """
         return self.client._perform_empty(
@@ -175,32 +172,32 @@ def delete(self):
     def get_definition(self):
         """
         Get the group's definition (name, description, admin abilities, type, ldap name mapping)
-
         Note: this call requires an API key with admin rights
         
-        Returns:
-            the group definition, as a JSON object
+        :return: the group's definition, as a dict
         """
         return self.client._perform_json(
             "GET", "/admin/groups/%s" % self.name)
 
     def set_definition(self, definition):
         """
         Set the group's definition.
-        
         Note: this call requires an API key with admin rights
-        
+
+        You should only :meth:`set_definition` using an object that you obtained through :meth:`get_definition`, 
+        not create a new dict.
+
         Args:
-            definition: the definition for the group, as a JSON object.                        
+            definition: the definition for the group, as a dict
         """
         return self.client._perform_json(
             "PUT", "/admin/groups/%s" % self.name,
             body = definition)
-    
-        
+
 class DSSGeneralSettings(object):
     """
-    The general settings of the DSS instance
+    The general settings of the DSS instance.
+    Do not create this directly, use :meth:`dataikuapi.DSSClient.get_general_settings`
     """
     def __init__(self, client):
         self.client = client
@@ -213,7 +210,6 @@ def __init__(self, client):
     def save(self):
         """
         Save the changes that were made to the settings on the DSS instance
-
         Note: this call requires an API key with admin rights
         """
         return self.client._perform_empty("PUT", "/admin/general-settings", body = self.settings)
@@ -421,7 +417,8 @@ def group_regexp(self, regexp, unix_user, hadoop_user=None):
 
 class DSSCodeEnv(object):
     """
-    A code env on the DSS instance
+    A code env on the DSS instance.
+    Do not create this directly, use :meth:`dataikuapi.DSSClient.get_code_env`
     """
     def __init__(self, client, env_lang, env_name):
         self.client = client
@@ -434,8 +431,7 @@ def __init__(self, client, env_lang, env_name):
 
     def delete(self):
         """
-        Delete the connection
-
+        Delete the code env
         Note: this call requires an API key with admin rights
         """
         resp = self.client._perform_json(
@@ -457,16 +453,14 @@ def get_definition(self):
 
         Note: this call requires an API key with admin rights
         
-        Returns:
-            the code env definition, as a JSON object
+        :returns: the code env definition, as a dict
         """
         return self.client._perform_json(
             "GET", "/admin/code-envs/%s/%s" % (self.env_lang, self.env_name))
 
     def set_definition(self, env):
         """
-        Set the code env's definition. The definition should come from a call to the get_definition()
-        method. 
+        Set the code env's definition. The definition should come from a call to :meth:`get_definition`
 
         Fields that can be updated in design node:
 
@@ -480,18 +474,13 @@ def set_definition(self, env):
         * env.{version}.specCondaEnvironment, env.{version}.specPackageList, env.{version}.externalCondaEnvName, 
           env.{version}.desc.installCorePackages, env.{version}.desc.installJupyterSupport, env.{version}.desc.yarnPythonBin
 
-
-
         Note: this call requires an API key with admin rights
         
-        :param data: a code env definition
-
-        Returns:
-            the updated code env definition, as a JSON object
+        :param dict data: a code env definition
+        :return: the updated code env definition, as a dict
         """
         return self.client._perform_json(
             "PUT", "/admin/code-envs/%s/%s" % (self.env_lang, self.env_name), body=env)
-
 
     ########################################################
     # Code env actions

dataikuapi/dss/ml.py

@@ -744,6 +744,25 @@ def ensemble(self, model_ids=[], method=None):
         self.wait_train_complete()
         return train_ret
 
+
+    def start_train(self, session_name=None, session_description=None):
+        """
+        Starts asynchronously a new train session for this ML Task.
+
+        :param str session_name: name for the session
+        :param str session_description: description for the session
+
+        This returns immediately, before train is complete. To wait for train to complete, use ``wait_train_complete()``
+        """
+        session_info = {
+                            "sessionName" : session_name,
+                            "sessionDescription" : session_description
+                        }
+
+        return self.client._perform_json(
+                "POST", "/projects/%s/models/lab/%s/%s/train" % (self.project_key, self.analysis_id, self.mltask_id), body=session_info)
+
+
     def start_ensembling(self, model_ids=[], method=None):
         """
         Creates asynchronously a new ensemble models of a set of models.
@@ -765,23 +784,6 @@ def start_ensembling(self, model_ids=[], method=None):
                 "POST", "/projects/%s/models/lab/%s/%s/ensemble" % (self.project_key, self.analysis_id, self.mltask_id), body=ensembling_request)['id']
 
 
-    def start_train(self, session_name=None, session_description=None):
-        """
-        Starts asynchronously a new train session for this ML Task.
-
-        :param str session_name: name for the session
-        :param str session_description: description for the session
-
-        This returns immediately, before train is complete. To wait for train to complete, use ``wait_train_complete()``
-        """
-        session_info = {
-                            "sessionName" : session_name,
-                            "sessionDescription" : session_description
-                        }
-
-        return self.client._perform_json(
-                "POST", "/projects/%s/models/lab/%s/%s/train" % (self.project_key, self.analysis_id, self.mltask_id), body=session_info)
-
     def wait_train_complete(self):
         """
         Waits for train to be complete.