applied fixes on review [ch28499]

Author: spicquenot

dataikuapi/dss/dataset.py

@@ -244,6 +244,6 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the dataset
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "DATASET", self.dataset_name)

dataikuapi/dss/discussion.py

@@ -13,12 +13,7 @@ class DSSObjectDiscussions(object):
     A handle to manage discussions on a DSS object
     """
     def __init__(self, client, project_key, object_type, object_id):
-        """
-        :param DSSClient client: an api client to connect to the DSS backend
-        :param str project_key: identifier of the project to access
-        :param str object_type: DSS object type
-        :param str object_id: DSS object ID
-        """
+        """Do not call directly, use :meth:`dataikuapi.dssclient.DSSClient.get_object_discussions` or on any commentable DSS object"""
         self.client = client
         self.project_key = project_key
         self.object_type = object_type
@@ -32,14 +27,10 @@ def list_discussions(self):
         Get the list of discussions on the object
 
         :returns: list of discussions on the object
-        :rtype: list
+        :rtype: list of :class:`dataikuapi.dss.discussion.DSSDiscussion`
         """
         data = self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/" % (self.project_key, self.object_type, self.object_id))
-
-        discu_list = []
-        for discu_data in data:
-            discu_list.append(DSSDiscussion(self.client, self.project_key, self.object_type, self.object_id, discu_data['id'], discu_data, False))
-        return discu_list
+        return [DSSDiscussion(self.client, self.project_key, self.object_type, self.object_id, discu_data['id'], discu_data, False) for discu_data in data]
 
     def create_discussion(self, topic, message):
         """
@@ -48,7 +39,7 @@ def create_discussion(self, topic, message):
         :param str topic: the discussion topic
         :param str message: the markdown formatted first message
         :returns: the newly created discussion
-        :rtype: DSSDiscussion
+        :rtype: :class:`dataikuapi.dss.discussion.DSSDiscussion`
         """
         creation_data = {
             "topic" : topic,
@@ -63,15 +54,13 @@ def get_discussion(self, discussion_id):
 
         :param str discussion_id: the discussion ID
         :returns: the discussion
-        :rtype: DSSDiscussion
+        :rtype: :class:`dataikuapi.dss.discussion.DSSDiscussion`
         """
         discu_data = self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/%s" % (self.project_key, self.object_type, self.object_id, discussion_id))
         return DSSDiscussion(self.client, self.project_key, self.object_type, self.object_id, discussion_id, discu_data, True)
 
 class DSSDiscussion(object):
-    """
-    A handle to manage a discussion on a DSS object
-    """
+    """Do not call directly, use :meth:`dataikuapi.dss.discussion.DSSObjectDiscussions.get_discussion`"""
     def __init__(self, client, project_key, object_type, object_id, discussion_id, discussion_data, discussion_data_has_replies):
         """
         :param DSSClient client: an api client to connect to the DSS backend
@@ -129,15 +118,12 @@ def get_replies(self):
         Get the list of replies in this discussion
 
         :returns: a list of replies
-        :rtype: list
+        :rtype: list of :class:`dataikuapi.dss.discussion.DSSDiscussionReply`
         """
         if not self.discussion_data_has_replies:
             self._get_with_replies()
 
-        reply_list = []
-        for reply_data in self.discussion_data["replies"]:
-            reply_list.append(DSSDiscussionReply(reply_data))
-        return reply_list
+        return [DSSDiscussionReply(reply_data) for reply_data in self.discussion_data["replies"]]
 
     def add_reply(self, text):
         """
@@ -156,14 +142,12 @@ class DSSDiscussionReply(object):
     A read-only handle to access a discussion reply
     """
     def __init__(self, reply_data):
-        """
-        :param dict reply_data: the reply data from the discussion
-        """
+        """Do not call directly, use :meth:`dataikuapi.dss.discussion.DSSDiscussion.get_replies`"""
         self.reply_data = reply_data
 
-    def get_reply_data(self):
+    def get_raw_data(self):
         """
-        Get the reply data
+        Get the reply raw data
 
         :returns: the reply data
         :rtype: dict

dataikuapi/dss/managedfolder.py

@@ -170,6 +170,6 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the managed folder
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "MANAGED_FOLDER", self.odb_id)

dataikuapi/dss/notebook.py

@@ -56,6 +56,6 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the notebook
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "JUPYTER_NOTEBOOK", self.notebook_name)

dataikuapi/dss/project.py

@@ -755,7 +755,7 @@ def get_wiki(self):
         Get the wiki
 
         :returns: the wiki associated to the project
-        :rtype: DSSWiki
+        :rtype: :class:`dataikuapi.dss.wiki.DSSWiki`
         """
         return DSSWiki(self.client, self.project_key)
 
@@ -767,7 +767,7 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the project
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "PROJECT", self.project_key)
 

dataikuapi/dss/recipe.py

@@ -85,7 +85,7 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the recipe
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "RECIPE", self.recipe_name)
 

dataikuapi/dss/savedmodel.py

@@ -106,6 +106,6 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the saved model
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "SAVED_MODEL", self.sm_id)

dataikuapi/dss/scenario.py

@@ -164,7 +164,7 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the scenario
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "SCENARIO", self.id)
 

dataikuapi/dss/wiki.py

@@ -1,4 +1,5 @@
 from .discussion import DSSObjectDiscussions
+from dataikuapi.utils import DataikuException
 import json
 import sys
 
@@ -14,19 +15,16 @@ class DSSWiki(object):
     A handle to manage the wiki of a project
     """
     def __init__(self, client, project_key):
-        """
-        :param DSSClient client: an api client to connect to the DSS backend
-        :param str project_key: identifier of the project to access
-        """
+        """Do not call directly, use :meth:`dataikuapi.dss.project.DSSProject.get_wiki`"""
         self.client = client
         self.project_key = project_key
 
     def get_settings(self):
         """
         Get wiki settings
 
-        :returns: an handle to manage the wiki settings (taxonomy, home article)
-        :rtype: DSSWikiSettings
+        :returns: a handle to manage the wiki settings (taxonomy, home article)
+        :rtype: :class:`dataikuapi.dss.wiki.DSSWikiSettings`
         """
         return DSSWikiSettings(self.client, self.project_key, self.client._perform_json("GET", "/projects/%s/wiki/" % (self.project_key)))
 
@@ -35,8 +33,8 @@ def get_article(self, article_id):
         Get a wiki article
 
         :param str article_id: the article ID
-        :returns: an handle to manage the Article
-        :rtype: DSSWikiArticle
+        :returns: a handle to manage the Article
+        :rtype: :class:`dataikuapi.dss.wiki.DSSWikiArticle`
         """
         return DSSWikiArticle(self.client, self.project_key, article_id)
 
@@ -46,7 +44,7 @@ def __flatten_taxonomy__(self, taxonomy):
 
         :param list taxonomy:
         :returns: list of articles
-        :rtype: list
+        :rtype: list of :class:`dataikuapi.dss.wiki.DSSWikiArticle`
         """
         article_list = []
         for article in taxonomy:
@@ -56,10 +54,10 @@ def __flatten_taxonomy__(self, taxonomy):
 
     def list_articles(self):
         """
-        Get a list of all the articles
+        Get a list of all the articles in form of :class:`dataikuapi.dss.wiki.DSSWikiArticle` objects
 
         :returns: list of articles
-        :rtype: list
+        :rtype: list of :class:`dataikuapi.dss.wiki.DSSWikiArticle`
         """
         return self.__flatten_taxonomy__(self.get_settings().get_taxonomy())
 
@@ -71,7 +69,7 @@ def create_article(self, article_id, parent_id=None, content=None):
         :param str parent_id: the parent article ID (or None if the article has to be at root level)
         :param str content: the article content
         :returns: the created article
-        :rtype: DSSWikiArticle
+        :rtype: :class:`dataikuapi.dss.wiki.DSSWikiArticle`
         """
         body = {
             "projectKey": self.project_key,
@@ -94,24 +92,81 @@ class DSSWikiSettings(object):
     Global settings for the wiki, including taxonomy. Call save() to save
     """
     def __init__(self, client, project_key, settings):
-        """
-        :param DSSClient client: an api client to connect to the DSS backend
-        :param str project_key: identifier of the project to access
-        :param dict settings: current wiki settings (containing taxonomy and home article)
-        """
+        """Do not call directly, use :meth:`dataikuapi.dss.wiki.DSSWiki.get_settings`"""
         self.client = client
         self.project_key = project_key
         self.settings = settings
 
     def get_taxonomy(self):
         """
         Get the taxonomy
+        The taxonomy is an array listing at top level the root article IDs and their children in a tree format.
+        Every existing article of the wiki has to be in the taxonomy once and only once.
+        For instance:
+        [
+            {
+                'id': 'article1',
+                'children': []
+            },
+            {
+                'id': 'article2',
+                'children': [
+                    {
+                        'id': 'article3',
+                        'children': []
+                    }
+                ]
+            }
+        ]
+        Note that this is a direct reference, not a copy, so modifications to the returned object will be reflected when saving
 
         :returns: The taxonomy
         :rtype: list
         """
         return self.settings["taxonomy"]
 
+    def __retrieve_article_in_taxonomy__(self, taxonomy, article_id, remove=False):
+        """
+        Private recusive method that get the sub tree structure from the taxonomy for a specific article
+
+        :param list taxonomy: the current level of taxonomy
+        :param str article_id: the article to retrieve
+        :param bool remove: either remove the sub tree structure or not
+        """
+        idx = 0
+        for tax_article in taxonomy:
+            if tax_article["id"] == article_id:
+                ret = taxonomy.pop(idx) if remove else taxonomy[idx]
+                return ret
+            children_ret = self.__retrieve_article_in_taxonomy__(tax_article["children"], article_id, remove)
+            if children_ret is not None:
+                return children_ret
+            idx += 1
+        return None
+
+    def move_article_in_taxonomy(self, article_id, parent_article_id=None):
+        """
+        An helper to update the taxonomy by moving an article with its children as a child of another article
+
+        :param str article_id: the main article ID
+        :param str parent_article_id: the new parent article ID or None for root level
+        """
+        old_taxonomy = list(self.settings["taxonomy"])
+
+        tax_article = self.__retrieve_article_in_taxonomy__(self.settings["taxonomy"], article_id, True)
+        if tax_article is None:
+            raise DataikuException("Article not found: %s" % (article_id))
+
+        if parent_article_id is None:
+            self.settings["taxonomy"].append(tax_article)
+        else:
+            tax_parent_article = self.__retrieve_article_in_taxonomy__(self.settings["taxonomy"], parent_article_id, False)
+            if tax_article is None:
+                self.settings["taonomy"] = old_taxonomy
+                raise DataikuException("Parent article not found (or is one of the article descendants): %s" % (parent_article_id))
+            tax_parent_article["children"].append(tax_article)
+
+
     def set_taxonomy(self, taxonomy):
         """
         Set the taxonomy
@@ -148,11 +203,7 @@ class DSSWikiArticle(object):
     A handle to manage an article
     """
     def __init__(self, client, project_key, article_id):
-        """
-        :param DSSClient client: an api client to connect to the DSS backend
-        :param str project_key: identifier of the project to access
-        :param str article_id: the article ID
-        """
+        """Do not call directly, use :meth:`dataikuapi.dss.wiki.DSSWiki.get_article`"""
         self.client = client
         self.project_key = project_key
         self.article_id = article_id
@@ -165,18 +216,20 @@ def get_data(self):
         Get article data handle
 
         :returns: the article data handle
-        :rtype: DSSWikiArticleData
+        :rtype: :class:`dataikuapi.dss.wiki.DSSWikiArticleData`
         """
         article_data = self.client._perform_json("GET", "/projects/%s/wiki/%s" % (self.project_key, dku_quote_fn(self.article_id)))
         return DSSWikiArticleData(self.client, self.project_key, self.article_id, article_data)
 
-    def upload_attachement(self, fp):
+    def upload_attachement(self, fp, filename):
         """
         Upload an attachment file and attaches it to the article
+        Note that the type of file will be determined by the filename extension
 
         :param file fp: A file-like object that represents the upload file
+        :param str filename: The attachement filename
         """
-        self.client._perform_json("POST", "/projects/%s/wiki/%s/upload" % (self.project_key, dku_quote_fn(self.article_id)), files={"file":fp})
+        self.client._perform_json("POST", "/projects/%s/wiki/%s/upload" % (self.project_key, dku_quote_fn(self.article_id)), files={"file":(filename, fp)})
 
     def delete(self):
         """
@@ -189,7 +242,7 @@ def get_object_discussions(self):
         Get a handle to manage discussions on the article
 
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.dss.wiki.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self.client, self.project_key, "ARTICLE", self.article_id)
 
@@ -198,12 +251,7 @@ class DSSWikiArticleData(object):
     A handle to manage an article
     """
     def __init__(self, client, project_key, article_id, article_data):
-        """
-        :param DSSClient client: an api client to connect to the DSS backend
-        :param str project_key: identifier of the project to access
-        :param str article_id: the article ID
-        :param dict article_data: the article data got from the backend
-        """
+        """Do not call directly, use :meth:`dataikuapi.dss.wiki.DSSWikiArticle.get_data`"""
         self.client = client
         self.project_key = project_key
         self.article_id = article_id # don't need to check unicode here (already done in DSSWikiArticle)
@@ -229,6 +277,7 @@ def set_body(self, content):
     def get_metadata(self):
         """
         Get the article metadata
+        Note that this is a direct reference, not a copy, so modifications to the returned object will be reflected when saving
 
         :returns: the article metadata
         :rtype: dict

dataikuapi/dssclient.py

@@ -765,7 +765,7 @@ def get_object_discussions(self, project_key, object_type, object_id):
         :param str object_type: DSS object type
         :param str object_id: DSS object ID
         :returns: the handle to manage discussions
-        :rtype: DSSObjectDiscussions
+        :rtype: :class:`dataikuapi.discussion.DSSObjectDiscussions`
         """
         return DSSObjectDiscussions(self, project_key, object_type, object_id)