Merge pull request #196 from cloudant/186-support-show-functions

emlaver · web-flow · commit 6960cbad29b8 · 2016-07-22T10:53:13.000-04:00
Added support for show functions
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -3,6 +3,7 @@
 - [NEW] Added support for Cloudant Search execution.
 - [NEW] Added support for Cloudant Search index management.
 - [NEW] Added support for managing and querying list functions.
+- [NEW] Added support for managing and querying show functions.
 - [NEW] Added ``rewrites`` accessor property for URL rewriting.
 - [NEW] Added ``st_indexes`` accessor property for Cloudant Geospatial indexes.
 - [NEW] Added support for DesignDocument ``_info`` and ``_search_info`` endpoints.
diff --git a/src/cloudant/database.py b/src/cloudant/database.py
@@ -805,6 +805,43 @@ def get_list_function_result(self, ddoc_id, list_name, view_name, **kwargs):
                         **kwargs)
         return resp.text
 
+    def get_show_function_result(self, ddoc_id, show_name, doc_id):
+        """
+        Retrieves a formatted document from the specified database
+        based on the show function provided.  Show functions, for example,
+        are used when you want to access Cloudant directly from a browser,
+        and need data to be returned in a different format, such as HTML.
+
+        For example:
+
+        .. code-block:: python
+
+            # Assuming that 'view001' exists as part of the
+            # 'ddoc001' design document in the remote database...
+            # Retrieve a formatted 'doc001' document where the show function is 'show001'
+            resp = db.get_show_function_result('ddoc001', 'show001', 'doc001')
+            for row in resp['rows']:
+                # Process data (in text format).
+
+        For more detail on show functions, refer to the
+        `Cloudant documentation <https://docs.cloudant.com/
+        design_documents.html#show-functions>`_.
+
+        :param str ddoc_id: Design document id used to get the result.
+        :param str show_name: Name used in part to identify the
+            show function.
+        :param str doc_id: The ID of the document to show.
+
+        :return: Formatted document result data in text format
+        """
+        ddoc = DesignDocument(self, ddoc_id)
+        headers = {'Content-Type': 'application/json'}
+        resp = get_docs(self.r_session,
+                        '/'.join([ddoc.document_url, '_show', show_name, doc_id]),
+                        self.client.encoder,
+                        headers)
+        return resp.text
+
 class CloudantDatabase(CouchDatabase):
     """
     Encapsulates a Cloudant database.  A CloudantDatabase object is
diff --git a/src/cloudant/design_document.py b/src/cloudant/design_document.py
@@ -44,7 +44,7 @@ def __init__(self, database, document_id=None):
         if document_id and not document_id.startswith('_design/'):
             document_id = '_design/{0}'.format(document_id)
         super(DesignDocument, self).__init__(database, document_id)
-        self._nested_object_names = frozenset(['views', 'indexes', 'lists'])
+        self._nested_object_names = frozenset(['views', 'indexes', 'lists', 'shows'])
         for prop in self._nested_object_names:
             self.setdefault(prop, dict())
 
@@ -98,6 +98,17 @@ def lists(self):
         """
         return self.get('lists')
 
+    @property
+    def shows(self):
+        """
+        Provides an accessor property to the shows dictionary in the
+        locally cached DesignDocument.
+
+        :returns: Dictionary containing show names and functions
+            as key/value
+        """
+        return self.get('shows')
+
     @property
     def rewrites(self):
         """
@@ -215,6 +226,21 @@ def add_list_function(self, list_name, list_func):
 
         self.lists.__setitem__(list_name, codify(list_func))
 
+    def add_show_function(self, show_name, show_func):
+        """
+        Appends a show function to the locally cached DesignDocument
+        shows dictionary.
+
+        :param show_name: Name used to identify the show function.
+        :param show_func: Javascript show function.
+        """
+        if self.get_show_function(show_name) is not None:
+            msg = ('A show function with name {0} already exists in this design doc'
+                   .format(show_name))
+            raise CloudantArgumentError(msg)
+
+        self.shows.__setitem__(show_name, show_func)
+
     def update_view(self, view_name, map_func, reduce_func=None, **kwargs):
         """
         Modifies/overwrites an existing MapReduce view definition in the
@@ -276,6 +302,21 @@ def update_list_function(self, list_name, list_func):
 
         self.lists.__setitem__(list_name, codify(list_func))
 
+    def update_show_function(self, show_name, show_func):
+        """
+        Modifies/overwrites an existing show function in the
+        locally cached DesignDocument shows dictionary.
+
+        :param show_name: Name used to identify the show function.
+        :param show_func: Javascript show function.
+        """
+        if self.get_show_function(show_name) is None:
+            msg = ('A show function with name {0} does not exist in this design doc'
+                   .format(show_name))
+            raise CloudantArgumentError(msg)
+
+        self.shows.__setitem__(show_name, show_func)
+
     def delete_view(self, view_name):
         """
         Removes an existing MapReduce view definition from the locally cached
@@ -317,6 +358,18 @@ def delete_list_function(self, list_name):
         """
         self.lists.__delitem__(list_name)
 
+    def delete_show_function(self, show_name):
+        """
+        Removes an existing show function in the locally cached DesignDocument
+        shows dictionary.
+
+        :param show_name: Name used to identify the list.
+        """
+        if self.get_show_function(show_name) is None:
+            return
+
+        self.shows.__delitem__(show_name)
+
     def fetch(self):
         """
         Retrieves the remote design document content and populates the locally
@@ -346,7 +399,7 @@ def fetch(self):
                     )
 
         for prop in self._nested_object_names:
-            # Ensure views, indexes, and lists dict exist in locally cached DesignDocument.
+            # Ensure dict for each sub-object exists in locally cached DesignDocument.
             getattr(self, prop, self.setdefault(prop, dict()))
 
     # pylint: disable=too-many-branches
@@ -394,7 +447,7 @@ def save(self):
 
         for prop in self._nested_object_names:
             if not getattr(self, prop):
-                # Ensure empty views, indexes, or lists dict is not saved remotely.
+                # Ensure empty dict for each sub-object is not saved remotely.
                 self.__delitem__(prop)
 
         super(DesignDocument, self).save()
@@ -462,6 +515,17 @@ def iterlists(self):
         for list_name, list_func in iteritems_(self.lists):
             yield list_name, list_func
 
+    def itershows(self):
+        """
+        Provides a way to iterate over the locally cached DesignDocument
+        shows dictionary.
+
+        :returns: Iterable containing show function name and associated
+            show function
+        """
+        for show_name, show_func in iteritems_(self.shows):
+            yield show_name, show_func
+
     def list_views(self):
         """
         Retrieves a list of available View objects in the locally cached
@@ -489,6 +553,15 @@ def list_list_functions(self):
         """
         return list(self.lists.keys())
 
+    def list_show_functions(self):
+        """
+        Retrieves a list of available show functions in the locally cached
+        DesignDocument shows dictionary.
+
+        :returns: List of show function names
+        """
+        return list(self.shows.keys())
+
     def get_view(self, view_name):
         """
         Retrieves a specific View from the locally cached DesignDocument by
@@ -518,10 +591,21 @@ def get_list_function(self, list_name):
 
         :param str list_name: Name used to identify the list function.
 
-        :returns: Index dictionary for the specified list function name
+        :returns: String form of the specified list function
         """
         return self.lists.get(list_name)
 
+    def get_show_function(self, show_name):
+        """
+        Retrieves a specific show function from the locally cached DesignDocument
+        shows dictionary by name.
+
+        :param str show_name: Name used to identify the show function.
+
+        :returns: String form of the specified show function
+        """
+        return self.shows.get(show_name)
+
     def info(self):
         """
         Retrieves the design document view information data, returns dictionary
diff --git a/tests/unit/database_tests.py b/tests/unit/database_tests.py
@@ -254,7 +254,7 @@ def test_retrieve_design_document(self):
         # Get an empty design document object that does not exist remotely
         local_ddoc = self.db.get_design_document('_design/ddoc01')
         self.assertEqual(local_ddoc, {'_id': '_design/ddoc01', 'indexes': {},
-                                      'views': {}, 'lists': {}})
+                                      'views': {}, 'lists': {}, 'shows': {}})
         # Add the design document to the database
         map_func = 'function(doc) {\n emit(doc._id, 1); \n}'
         local_ddoc.add_view('view01', map_func)
@@ -667,6 +667,31 @@ def test_get_list_function_result(self):
             '</ol></body></html>'
         )
 
+    def test_get_show_result(self):
+        """
+        Test get_show_result executes a show function against a document.
+        """
+        self.populate_db_with_documents()
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc.add_show_function(
+            'show001',
+            'function(doc, req) { '
+            'if (doc) { return \'Hello from \' + doc._id + \'!\'; } '
+            'else { return \'Hello, world!\'; } }')
+        ddoc.save()
+        doc = Document(self.db, 'doc001')
+        doc.save()
+        # Execute show function
+        resp = self.db.get_show_function_result(
+            '_design/ddoc001',
+            'show001',
+            'doc001'
+        )
+        self.assertEqual(
+            resp,
+            'Hello from doc001!'
+        )
+
 @unittest.skipUnless(
     os.environ.get('RUN_CLOUDANT_TESTS') is not None,
     'Skipping Cloudant specific Database tests'
@@ -900,6 +925,7 @@ def test_create_json_index(self):
                  '_rev': ddoc['_rev'],
                  'indexes': {},
                  'lists': {},
+                 'shows': {},
                  'language': 'query',
                  'views': {index.name: {'map': {'fields': {'name': 'asc', 
                                                            'age': 'asc'}},
@@ -927,6 +953,7 @@ def test_create_text_index(self):
                  'language': 'query',
                  'views': {},
                  'lists': {},
+                 'shows': {},
                  'indexes': {index.name: {'index': {'index_array_lengths': True,
                                 'fields': [{'name': 'name', 'type': 'string'},
                                            {'name': 'age', 'type': 'number'}],
@@ -952,6 +979,7 @@ def test_create_all_fields_text_index(self):
                  'language': 'query',
                  'views': {},
                  'lists': {},
+                 'shows': {},
                  'indexes': {index.name: {'index': {'index_array_lengths': True,
                                 'fields': 'all_fields',
                                 'default_field': {},
@@ -988,6 +1016,7 @@ def test_create_multiple_indexes_one_ddoc(self):
                  '_rev': ddoc['_rev'],
                  'language': 'query',
                  'lists': {},
+                 'shows': {},
                  'views': {'json-index-001': {
                                 'map': {'fields': {'name': 'asc', 
                                                    'age': 'asc'}},
diff --git a/tests/unit/design_document_tests.py b/tests/unit/design_document_tests.py
diff --git a/tests/unit/index_tests.py b/tests/unit/index_tests.py
