improved discu public api + few minor things on wiki

Author: spicquenot

dataikuapi/dss/discussion.py

@@ -1,113 +1,207 @@
 import json
+import sys
+
+if sys.version_info >= (3,0):
+  import urllib.parse
+  dku_quote_fn = urllib.parse.quote
+else:
+  import urllib
+  dku_quote_fn = urllib.quote
 
 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
+        """
         self.client = client
         self.project_key = project_key
         self.object_type = object_type
         self.object_id = object_id
+        # encode in UTF-8 if its python2 and unicode
+        if sys.version_info < (3,0) and isinstance(self.object_id, unicode):
+            self.object_id = self.object_id.encode('utf-8')
 
-    ##########################
-    # Discussions on an object
-    ##########################
     def list_discussions(self):
         """
-        Get list of discussions
+        Get the list of discussions on the object
 
-        Returns:
-            array of discussions on a DSS object
+        :returns: list of discussions on the object
+        :rtype: list
         """
-        return self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/" % (self.project_key, self.object_type, self.object_id))
+        data = self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/" % (self.project_key, self.object_type, self.object_id))
 
-    def create_discussion(self, discussion_creator):
-        """
-        Create a discussion
+        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
 
-        Args:
-            A DSSDiscussionCreator object containing the discussion definition
+    def create_discussion(self, topic, message):
+        """
+        Create a new discussion
 
-        Returns:
-            The newly created discussion
+        :param str topic: the discussion topic
+        :param str message: the markdown formatted first message
+        :returns: the newly created discussion
+        :rtype: DSSDiscussion
         """
-        return self.client._perform_json("POST", "/projects/%s/discussions/%s/%s/" % (self.project_key, self.object_type, self.object_id), body=discussion_creator.get_data())
+        creation_data = {
+            "topic" : topic,
+            "reply" : message
+        }
+        discu_data = self.client._perform_json("POST", "/projects/%s/discussions/%s/%s/" % (self.project_key, self.object_type, self.object_id), body=creation_data)
+        return DSSDiscussion(self.client, self.project_key, self.object_type, self.object_id, discu_data['id'], discu_data, True)
 
     def get_discussion(self, discussion_id):
         """
         Get a specific discussion
 
-        Returns:
-            a discussion
+        :param str discussion_id: the discussion ID
+        :returns: the discussion
+        :rtype: DSSDiscussion
         """
-        return DSSDiscussion(self.client, self.project_key, self.object_type, self.object_id, discussion_id)
+        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 single discussion
+    A handle to manage a discussion on a DSS object
     """
-    def __init__(self, client, project_key, object_type, object_id, discussion_id):
+    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
+        :param str project_key: identifier of the project to access
+        ;param str object_type: DSS object type
+        :param str object_id: DSS object ID
+        :param str discussion_id: identified of the discussion
+        :param dict discussion_data: the discussion data
+        :param bool discussion_data_has_replies: a flag that indicates if the replies has been loaded
+        """
         self.client = client
         self.project_key = project_key
         self.object_type = object_type
         self.object_id = object_id
         self.discussion_id = discussion_id
+        self.discussion_data = discussion_data
+        self.discussion_data_has_replies = discussion_data_has_replies
+
+    def _get_with_replies(self):
+        """
+        Reload the discussion data from the backend including the replies
+        """
+        self.discussion_data = self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/%s" % (self.project_key, self.object_type, self.object_id, self.discussion_id))
+        self.discussion_data_has_replies = True
 
-    ########################
-    # Single discussion
-    ########################
-    def get(self):
+    def get_metadata(self):
         """
-        Get the discussion details
+        Get the discussion metadata
 
-        Returns:
-            The specific discussion
+        :returns: the discussion metadata
+        :rtype: dict
         """
-        return self.client._perform_json("GET", "/projects/%s/discussions/%s/%s/%s" % (self.project_key, self.object_type, self.object_id, self.discussion_id))
+        metadata = dict(self.discussion_data)
+        if "replies" in metadata:
+            del metadata["replies"]
+        return metadata
 
-    def set(self, discussion_details):
+    def set_metadata(self, discussion_metadata):
         """
-        Update the discussion
+        Update the discussion metadata
+
+        :param dict discussion_metadata: the discussion metadata
+        """
+        if not self.discussion_data_has_replies:
+            self._get_with_replies()
+
+        edited_metadata = dict(discussion_metadata)
+        edited_metadata["replies"] = self.discussion_data["replies"]
 
-        Args:
-            The discussion definition as retrieved by the getter
+        self.discussion_data = self.client._perform_json("PUT", "/projects/%s/discussions/%s/%s/%s" % (self.project_key, self.object_type, self.object_id, self.discussion_id), body=edited_metadata)
+        self.discussion_data_has_replies = True
 
-        Returns:
-            The updated discussion
+    def get_replies(self):
         """
-        return self.client._perform_json("PUT", "/projects/%s/discussions/%s/%s/%s" % (self.project_key, self.object_type, self.object_id, self.discussion_id), body=discussion_details)
+        Get the list of replies in this discussion
 
-    def add_reply(self, reply):
+        :returns: a list of replies
+        :rtype: list
         """
-        Add a reply to a discussion
+        if not self.discussion_data_has_replies:
+            self._get_with_replies()
 
-        Args:
-            The reply message content
+        reply_list = []
+        for reply_data in self.discussion_data["replies"]:
+            reply_list.append(DSSDiscussionReply(reply_data))
+        return reply_list
 
-        Returns:
-            The updated discussion with details
+    def add_reply(self, text):
+        """
+        Add a reply to a discussion
+
+        :param str text: the markdown formatted text to reply
         """
         reply_data = {
-            "reply": reply
+            "reply": text
         }
-        return self.client._perform_json("POST", "/projects/%s/discussions/%s/%s/%s/replies/" % (self.project_key, self.object_type, self.object_id, self.discussion_id), body=reply_data)
+        self.discussion_data = self.client._perform_json("POST", "/projects/%s/discussions/%s/%s/%s/replies/" % (self.project_key, self.object_type, self.object_id, self.discussion_id), body=reply_data)
+        self.discussion_data_has_replies = True
 
-class DSSDiscussionCreator(object):
+class DSSDiscussionReply(object):
     """
-    A helper to create discussion
+    A read-only handle to access a discussion reply
     """
-    def __init__(self, topic, first_message):
-        self.data = {
-            "topic" : topic,
-            "reply" : first_message
-        }
+    def __init__(self, reply_data):
+        """
+        :param dict reply_data: the reply data from the discussion
+        """
+        self.reply_data = reply_data
+
+    def get_reply_data(self):
+        """
+        Get the reply data
+
+        :returns: the reply data
+        :rtype: dict
+        """
+        return self.reply_data
+
+    def get_text(self):
+        """
+        Get the reply text
+
+        :returns: the reply text
+        :rtype: str
+        """
+        return self.reply_data["text"]
+
+    def get_author(self):
+        """
+        Get the reply author
+
+        :returns: the author ID
+        :rtype: str
+        """
+        return self.reply_data["author"]
 
-    def get_data(self):
-        return self.data
+    def get_timestamp(self):
+        """
+        Get the reply timestamp
 
-    def set_topic(self, topic):
-        self.data["topic"] = topic
+        :returns: the reply timestamp
+        :rtype: long
+        """
+        return self.reply_data["time"]
 
-    def set_first_message(self, first_message):
-        self.data["reply"] = first_message
+    def get_edited_timestamp(self):
+        """
+        Get the last edition timestamp
+
+        :returns: the last edition timestamp
+        :rtype: long
+        """
+        return self.reply_data["editedOn"]

dataikuapi/dss/wiki.py

@@ -12,11 +12,12 @@
 class DSSWiki(object):
     """
     A handle to manage the wiki of a project
-
-    :param client: an api client to connect to the DSS backend
-    :param project_key: identifier of the project to access
     """
     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
+        """
         self.client = client
         self.project_key = project_key
 
@@ -91,12 +92,13 @@ def create_article(self, article_id, parent_id=None, content=None):
 class DSSWikiSettings(object):
     """
     Global settings for the wiki, including taxonomy. Call save() to save
-
-    :param client: an api client to connect to the DSS backend
-    :param project_key: identifier of the project to access
-    :param dict settings: current wiki settings (containing taxonomy and home article)
     """
     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)
+        """
         self.client = client
         self.project_key = project_key
         self.settings = settings
@@ -144,12 +146,13 @@ def save(self):
 class DSSWikiArticle(object):
     """
     A handle to manage an article
-
-    :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
     """
     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
+        """
         self.client = client
         self.project_key = project_key
         self.article_id = article_id
@@ -171,7 +174,7 @@ def upload_attachement(self, fp):
         """
         Upload an attachment file and attaches it to the article
 
-        :param filetype fp: A file-like object that represents the upload file
+        :param file fp: A file-like object that represents the upload file
         """
         self.client._perform_json("POST", "/projects/%s/wiki/%s/upload" % (self.project_key, dku_quote_fn(self.article_id)), files={"file":fp})
 
@@ -193,13 +196,14 @@ def get_object_discussions(self):
 class DSSWikiArticleData(object):
     """
     A handle to manage an article
-
-    :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
     """
     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
+        """
         self.client = client
         self.project_key = project_key
         self.article_id = article_id # don't need to check unicode here (already done in DSSWikiArticle)