Added support for list function query execution

- Added support for managing list functions in design document
- Added HTTP Headers argument to get_docs method
- Replaced repeating if statements for sub-object properties with for loop over a frozen set of all properties
- Replaced deprecated pylint disable-msg=too-many-branches with disable=too-many-branches

Author: emlaver

CHANGES.rst

@@ -2,6 +2,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 ``rewrites`` accessor property for URL rewriting.
 - [NEW] Added support for a custom ``requests.HTTPAdapter`` to be configured using an optional ``adapter`` arg e.g.
   ``Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME, adapter=Replay429Adapter())``.

src/cloudant/_common_util.py

@@ -234,14 +234,15 @@ def codify(code_or_str):
         return _Code(code_or_str)
     return code_or_str
 
-def get_docs(r_session, url, encoder=None, **params):
+def get_docs(r_session, url, encoder=None, headers=None, **params):
     """
     Provides a helper for functions that require GET or POST requests
     with a JSON, text, or raw response containing documents.
 
     :param r_session: Authentication session from the client
     :param str url: URL containing the endpoint
     :param JSONEncoder encoder: Custom encoder from the client
+    :param dict headers: Optional HTTP Headers to send with the request
 
     :returns: Raw response content from the specified endpoint
     """
@@ -253,9 +254,9 @@ def get_docs(r_session, url, encoder=None, **params):
 
     resp = None
     if keys:
-        resp = r_session.post(url, params=f_params, data=keys)
+        resp = r_session.post(url, headers=headers, params=f_params, data=keys)
     else:
-        resp = r_session.get(url, params=f_params)
+        resp = r_session.get(url, headers=headers, params=f_params)
     resp.raise_for_status()
     return resp
 

src/cloudant/database.py

@@ -762,6 +762,49 @@ def view_cleanup(self):
 
         return resp.json()
 
+    def get_list_function_result(self, ddoc_id, list_name, view_name, **kwargs):
+        """
+        Retrieves a customized MapReduce view result from the specified
+        database based on the list function provided.  List functions are
+        used, for example,  when you want to access Cloudant directly
+        from a browser, and need data to be returned in a different
+        format, such as HTML.
+
+        Note: All query parameters for View requests are supported.
+        See :class:`~cloudant.database.get_view_result` for
+        all supported query parameters.
+
+        For example:
+
+        .. code-block:: python
+
+            # Assuming that 'view001' exists as part of the
+            # 'ddoc001' design document in the remote database...
+            # Retrieve documents where the list function is 'list1'
+            resp = db.get_list_result('ddoc001', 'list1', 'view001', limit=10)
+            for row in resp['rows']:
+                # Process data (in text format).
+
+        For more detail on list functions, refer to the
+        `Cloudant documentation <https://docs.cloudant.com/
+        design_documents.html#list-functions>`_.
+
+        :param str ddoc_id: Design document id used to get result.
+        :param str list_name: Name used in part to identify the
+            list function.
+        :param str view_name: Name used in part to identify the view.
+
+        :return: Formatted view 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, '_list', list_name, view_name]),
+                        self.client.encoder,
+                        headers,
+                        **kwargs)
+        return resp.text
+
 class CloudantDatabase(CouchDatabase):
     """
     Encapsulates a Cloudant database.  A CloudantDatabase object is

src/cloudant/design_document.py

@@ -44,8 +44,19 @@ 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.setdefault('views', dict())
-        self.setdefault('indexes', dict())
+        self._nested_object_names = frozenset(['views', 'indexes', 'lists'])
+        for prop in self._nested_object_names:
+            self.setdefault(prop, dict())
+
+    @property
+    def lists(self):
+        """
+        Provides an accessor property to the lists dictionary in the locally
+        cached DesignDocument.
+
+        :returns: Dictionary containing list names and objects as key/value
+        """
+        return self.get('lists')
 
     @property
     def rewrites(self):
@@ -149,6 +160,21 @@ def add_search_index(self, index_name, search_func, analyzer=None):
 
         self.indexes.__setitem__(index_name, search)
 
+    def add_list_function(self, list_name, list_func):
+        """
+        Appends a list function to the locally cached DesignDocument
+        indexes dictionary.
+
+        :param str list_name: Name used to identify the list function.
+        :param str list_func: Javascript list function.
+        """
+        if self.get_list_function(list_name) is not None:
+            msg = ('A list with name {0} already exists in this design doc'
+                   .format(list_name))
+            raise CloudantArgumentError(msg)
+
+        self.lists.__setitem__(list_name, codify(list_func))
+
     def update_view(self, view_name, map_func, reduce_func=None, **kwargs):
         """
         Modifies/overwrites an existing MapReduce view definition in the
@@ -195,6 +221,21 @@ def update_search_index(self, index_name, search_func, analyzer=None):
 
         self.indexes.__setitem__(index_name, search)
 
+    def update_list_function(self, list_name, list_func):
+        """
+        Modifies/overwrites an existing list function in the
+        locally cached DesignDocument indexes dictionary.
+
+        :param str list_name: Name used to identify the list function.
+        :param str list_func: Javascript list function.
+        """
+        if self.get_list_function(list_name) is None:
+            msg = ('A list with name {0} does not exist in this design doc'
+                   .format(list_name))
+            raise CloudantArgumentError(msg)
+
+        self.lists.__setitem__(list_name, codify(list_func))
+
     def delete_view(self, view_name):
         """
         Removes an existing MapReduce view definition from the locally cached
@@ -227,6 +268,15 @@ def delete_index(self, index_name):
 
         self.indexes.__delitem__(index_name)
 
+    def delete_list_function(self, list_name):
+        """
+        Removes an existing list function in the locally cached DesignDocument
+        lists dictionary.
+
+        :param str list_name: Name used to identify the list.
+        """
+        self.lists.__delitem__(list_name)
+
     def fetch(self):
         """
         Retrieves the remote design document content and populates the locally
@@ -236,10 +286,7 @@ def fetch(self):
         ``dict`` types.
         """
         super(DesignDocument, self).fetch()
-        if not self.views:
-            # Ensure views dict exists in locally cached DesignDocument.
-            self.setdefault('views', dict())
-        else:
+        if self.views:
             for view_name, view_def in iteritems_(self.get('views', dict())):
                 if self.get('language', None) != QUERY_LANGUAGE:
                     self['views'][view_name] = View(
@@ -258,11 +305,11 @@ def fetch(self):
                         **view_def
                     )
 
-        if not self.indexes:
-            # Ensure indexes dict exists in locally cached DesignDocument.
-            self.setdefault('indexes', dict())
+        for prop in self._nested_object_names:
+            # Ensure views, indexes, and lists dict exist in locally cached DesignDocument.
+            getattr(self, prop, self.setdefault(prop, dict()))
 
-    # pylint: disable-msg=too-many-branches
+    # pylint: disable=too-many-branches
     def save(self):
         """
         Saves changes made to the locally cached DesignDocument object's data
@@ -285,9 +332,6 @@ def save(self):
                             'View {0} must be of type QueryIndexView.'
                         ).format(view_name)
                         raise CloudantException(msg)
-        else:
-            # Ensure empty views dict is not saved remotely.
-            self.__delitem__('views')
 
         if self.indexes:
             if self.get('language', None) != QUERY_LANGUAGE:
@@ -307,18 +351,17 @@ def save(self):
                             'be of type dict.'
                         ).format(index_name)
                         raise CloudantException(msg)
-        else:
-            # Ensure empty indexes dict is not saved remotely.
-            self.__delitem__('indexes')
+
+        for prop in self._nested_object_names:
+            if not getattr(self, prop):
+                # Ensure empty views, indexes, or lists dict is not saved remotely.
+                self.__delitem__(prop)
 
         super(DesignDocument, self).save()
 
-        if not self.views:
-            # Ensure views dict exists in locally cached DesignDocument.
-            self.setdefault('views', dict())
-        if not self.indexes:
-            # Ensure indexes dict exists in locally cached DesignDocument.
-            self.setdefault('indexes', dict())
+        for prop in self._nested_object_names:
+            # Ensure views, indexes, and lists dict exist in locally cached DesignDocument.
+            getattr(self, prop, self.setdefault(prop, dict()))
 
     def __setitem__(self, key, value):
         """
@@ -368,6 +411,17 @@ def iterindexes(self):
         for index_name, search_func in iteritems_(self.indexes):
             yield index_name, search_func
 
+    def iterlists(self):
+        """
+        Provides a way to iterate over the locally cached DesignDocument
+        lists dictionary.
+
+        :returns: Iterable containing list function name and associated
+            list function
+        """
+        for list_name, list_func in iteritems_(self.lists):
+            yield list_name, list_func
+
     def list_views(self):
         """
         Retrieves a list of available View objects in the locally cached
@@ -386,6 +440,15 @@ def list_indexes(self):
         """
         return list(self.indexes.keys())
 
+    def list_list_functions(self):
+        """
+        Retrieves a list of available list functions in the locally cached
+        DesignDocument lists dictionary.
+
+        :returns: List of list function names
+        """
+        return list(self.lists.keys())
+
     def get_view(self, view_name):
         """
         Retrieves a specific View from the locally cached DesignDocument by
@@ -408,6 +471,17 @@ def get_index(self, index_name):
         """
         return self.indexes.get(index_name)
 
+    def get_list_function(self, list_name):
+        """
+        Retrieves a specific list function from the locally cached DesignDocument
+        lists dictionary by name.
+
+        :param str list_name: Name used to identify the list function.
+
+        :returns: Index dictionary for the specified list function name
+        """
+        return self.lists.get(list_name)
+
     def info(self):
         """
         Retrieves the design document view information data, returns dictionary

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': {}})
+                                      'views': {}, 'lists': {}})
         # Add the design document to the database
         map_func = 'function(doc) {\n emit(doc._id, 1); \n}'
         local_ddoc.add_view('view01', map_func)
@@ -625,6 +625,48 @@ def test_changes_inifinite_feed_call(self):
         self.assertFalse(changes._raw_data)
         self.assertDictEqual(changes._options, {'feed': 'continuous'})
 
+    def test_get_list_function_result_with_invalid_argument(self):
+        """
+        Test get_list_result by passing in invalid arguments
+        """
+        with self.assertRaises(CloudantArgumentError) as cm:
+            self.db.get_list_function_result('ddoc001', 'list001', 'view001', foo={'bar': 'baz'})
+        err = cm.exception
+        self.assertEqual(str(err), 'Invalid argument foo')
+
+    def test_get_list_function_result(self):
+        """
+        Test get_list_result executes a list function against a view's MapReduce
+        function.
+        """
+        self.populate_db_with_documents()
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc.add_view('view001', 'function (doc) {\n  emit(doc._id, 1);\n}')
+        ddoc.add_list_function(
+            'list001',
+            'function(head, req) { provides(\'html\', function() '
+            '{var html = \'<html><body><ol>\\n\'; while (row = getRow()) '
+            '{ html += \'<li>\' + row.key + \':\' + row.value + \'</li>\\n\';} '
+            'html += \'</ol></body></html>\'; return html; }); }')
+        ddoc.save()
+        # Execute list function
+        resp = self.db.get_list_function_result(
+            '_design/ddoc001',
+            'list001',
+            'view001',
+            limit=5
+        )
+        self.assertEqual(
+            resp,
+            '<html><body><ol>\n'
+            '<li>julia000:1</li>\n'
+            '<li>julia001:1</li>\n'
+            '<li>julia002:1</li>\n'
+            '<li>julia003:1</li>\n'
+            '<li>julia004:1</li>\n'
+            '</ol></body></html>'
+        )
+
 @unittest.skipUnless(
     os.environ.get('RUN_CLOUDANT_TESTS') is not None,
     'Skipping Cloudant specific Database tests'
@@ -857,6 +899,7 @@ def test_create_json_index(self):
                 {'_id': index.design_document_id,
                  '_rev': ddoc['_rev'],
                  'indexes': {},
+                 'lists': {},
                  'language': 'query',
                  'views': {index.name: {'map': {'fields': {'name': 'asc', 
                                                            'age': 'asc'}},
@@ -883,6 +926,7 @@ def test_create_text_index(self):
                  '_rev': ddoc['_rev'],
                  'language': 'query',
                  'views': {},
+                 'lists': {},
                  'indexes': {index.name: {'index': {'index_array_lengths': True,
                                 'fields': [{'name': 'name', 'type': 'string'},
                                            {'name': 'age', 'type': 'number'}],
@@ -907,6 +951,7 @@ def test_create_all_fields_text_index(self):
                  '_rev': ddoc['_rev'],
                  'language': 'query',
                  'views': {},
+                 'lists': {},
                  'indexes': {index.name: {'index': {'index_array_lengths': True,
                                 'fields': 'all_fields',
                                 'default_field': {},
@@ -942,6 +987,7 @@ def test_create_multiple_indexes_one_ddoc(self):
                 {'_id': '_design/ddoc001',
                  '_rev': ddoc['_rev'],
                  'language': 'query',
+                 'lists': {},
                  'views': {'json-index-001': {
                                 'map': {'fields': {'name': 'asc', 
                                                    'age': 'asc'}},