Merge pull request #172 from cloudant/159-search-index-management

Cloudant Search index management

Author: emlaver

CHANGES.rst

@@ -1,7 +1,7 @@
 2.1.0 (Unreleased)
 ==================
 - [NEW] Added support for Cloudant Search execution.
-
+- [NEW] Added support for Cloudant Search index management.
 
 2.0.3 (2016-06-03)
 ==================

src/cloudant/design_document.py

@@ -15,25 +15,25 @@
 """
 API module/class for interacting with a design document in a database.
 """
-from ._2to3 import iteritems_
+from ._2to3 import iteritems_, STRTYPE
+from ._common_util import QUERY_LANGUAGE, codify
 from .document import Document
 from .view import View, QueryIndexView
 from .error import CloudantArgumentError, CloudantException
-from ._common_util import QUERY_LANGUAGE
 
 class DesignDocument(Document):
     """
     Encapsulates a specialized version of a
     :class:`~cloudant.document.Document`.  A DesignDocument object is
     instantiated with a reference to a database and
-    provides an API to view management, list and show
-    functions, search indexes, etc.  When instantiating a DesignDocument or
+    provides an API to view management, index management, list and show
+    functions, etc.  When instantiating a DesignDocument or
     when setting the document id (``_id``) field, the value must start with
     ``_design/``.  If it does not, then ``_design/`` will be prepended to
     the provided document id value.
 
-    Note:  Currently only the view management API exists.  Remaining design
-    document functionality will be added later.
+    Note:  Currently only the view management and search index management API
+    exists.  Remaining design document functionality will be added later.
 
     :param database: A database instance used by the DesignDocument.  Can be
         either a ``CouchDatabase`` or ``CloudantDatabase`` instance.
@@ -45,6 +45,7 @@ def __init__(self, database, document_id=None):
             document_id = '_design/{0}'.format(document_id)
         super(DesignDocument, self).__init__(database, document_id)
         self.setdefault('views', dict())
+        self.setdefault('indexes', dict())
 
     @property
     def views(self):
@@ -56,6 +57,17 @@ def views(self):
         """
         return self.get('views')
 
+    @property
+    def indexes(self):
+        """
+        Provides an accessor property to the indexes dictionary in the
+        locally cached DesignDocument.
+
+        :returns: Dictionary containing index names and index objects
+            as key/value
+        """
+        return self.get('indexes')
+
     def add_view(self, view_name, map_func, reduce_func=None, **kwargs):
         """
         Appends a MapReduce view to the locally cached DesignDocument View
@@ -79,6 +91,26 @@ def add_view(self, view_name, map_func, reduce_func=None, **kwargs):
         view = View(self, view_name, map_func, reduce_func, **kwargs)
         self.views.__setitem__(view_name, view)
 
+    def add_search_index(self, index_name, search_func, analyzer=None):
+        """
+        Appends a Cloudant search index to the locally cached DesignDocument
+        indexes dictionary.
+
+        :param str index_name: Name used to identify the search index.
+        :param str search_func: Javascript search index function.
+        :param analyzer: Optional analyzer for this search index.
+        """
+        if self.get_index(index_name) is not None:
+            msg = ('An index with name {0} already exists in this design doc'
+                   .format(index_name))
+            raise CloudantArgumentError(msg)
+        if analyzer is not None:
+            search = {'index': codify(search_func), 'analyzer': analyzer}
+        else:
+            search = {'index': codify(search_func)}
+
+        self.indexes.__setitem__(index_name, search)
+
     def update_view(self, view_name, map_func, reduce_func=None, **kwargs):
         """
         Modifies/overwrites an existing MapReduce view definition in the
@@ -104,6 +136,27 @@ def update_view(self, view_name, map_func, reduce_func=None, **kwargs):
         view = View(self, view_name, map_func, reduce_func, **kwargs)
         self.views.__setitem__(view_name, view)
 
+    def update_search_index(self, index_name, search_func, analyzer=None):
+        """
+        Modifies/overwrites an existing Cloudant search index in the
+        locally cached DesignDocument indexes dictionary.
+
+        :param str index_name: Name used to identify the search index.
+        :param str search_func: Javascript search index function.
+        :param analyzer: Optional analyzer for this search index.
+        """
+        search = self.get_index(index_name)
+        if search is None:
+            msg = ('An index with name {0} does not exist in this design doc'
+                   .format(index_name))
+            raise CloudantArgumentError(msg)
+        if analyzer is not None:
+            search = {'index': codify(search_func), 'analyzer': analyzer}
+        else:
+            search = {'index': codify(search_func)}
+
+        self.indexes.__setitem__(index_name, search)
+
     def delete_view(self, view_name):
         """
         Removes an existing MapReduce view definition from the locally cached
@@ -123,6 +176,19 @@ def delete_view(self, view_name):
 
         self.views.__delitem__(view_name)
 
+    def delete_index(self, index_name):
+        """
+        Removes an existing index in the locally cached DesignDocument
+        indexes dictionary.
+
+        :param str index_name: Name used to identify the index.
+        """
+        index = self.get_index(index_name)
+        if index is None:
+            return
+
+        self.indexes.__delitem__(index_name)
+
     def fetch(self):
         """
         Retrieves the remote design document content and populates the locally
@@ -154,6 +220,11 @@ def fetch(self):
                         **view_def
                     )
 
+        if not self.indexes:
+            # Ensure indexes dict exists in locally cached DesignDocument.
+            self.setdefault('indexes', dict())
+
+    # pylint: disable-msg=too-many-branches
     def save(self):
         """
         Saves changes made to the locally cached DesignDocument object's data
@@ -180,11 +251,36 @@ def save(self):
             # Ensure empty views dict is not saved remotely.
             self.__delitem__('views')
 
+        if self.indexes:
+            if self.get('language', None) != QUERY_LANGUAGE:
+                for index_name, search in self.iterindexes():
+                    # Check the instance of the javascript search function
+                    if not isinstance(search['index'], STRTYPE):
+                        msg = (
+                            'Function for search index {0} must '
+                            'be of type string.'
+                        ).format(index_name)
+                        raise CloudantException(msg)
+            else:
+                for index_name, index in self.iterindexes():
+                    if not isinstance(index['index'], dict):
+                        msg = (
+                            'Definition for query text index {0} must '
+                            'be of type dict.'
+                        ).format(index_name)
+                        raise CloudantException(msg)
+        else:
+            # Ensure empty indexes dict is not saved remotely.
+            self.__delitem__('indexes')
+
         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())
 
     def __setitem__(self, key, value):
         """
@@ -216,6 +312,24 @@ def iterviews(self):
         for view_name, view in iteritems_(self.views):
             yield view_name, view
 
+    def iterindexes(self):
+        """
+        Provides a way to iterate over the locally cached DesignDocument
+        indexes dictionary.
+
+        For example:
+
+        .. code-block:: python
+
+            for index_name, search_func in ddoc.iterindexes():
+                # Perform search index processing
+
+        :returns: Iterable containing index name and associated
+            index object
+        """
+        for index_name, search_func in iteritems_(self.indexes):
+            yield index_name, search_func
+
     def list_views(self):
         """
         Retrieves a list of available View objects in the locally cached
@@ -225,6 +339,15 @@ def list_views(self):
         """
         return list(self.views.keys())
 
+    def list_indexes(self):
+        """
+        Retrieves a list of available indexes in the locally cached
+        DesignDocument.
+
+        :returns: List of index names
+        """
+        return list(self.indexes.keys())
+
     def get_view(self, view_name):
         """
         Retrieves a specific View from the locally cached DesignDocument by
@@ -236,6 +359,17 @@ def get_view(self, view_name):
         """
         return self.views.get(view_name)
 
+    def get_index(self, index_name):
+        """
+        Retrieves a specific index from the locally cached DesignDocument
+        indexes dictionary by name.
+
+        :param str index_name: Name used to identify the index.
+
+        :returns: Index dictionary for the specified index name
+        """
+        return self.indexes.get(index_name)
+
     def info(self):
         """
         Retrieves the design document view information data, returns dictionary

tests/unit/database_tests.py

@@ -253,8 +253,8 @@ 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', 'views': {}})
-
+        self.assertEqual(local_ddoc, {'_id': '_design/ddoc01', 'indexes': {},
+                                      'views': {}})
         # Add the design document to the database
         map_func = 'function(doc) {\n emit(doc._id, 1); \n}'
         local_ddoc.add_view('view01', map_func)
@@ -856,6 +856,7 @@ def test_create_json_index(self):
         self.assertEqual(ddoc,
                 {'_id': index.design_document_id,
                  '_rev': ddoc['_rev'],
+                 'indexes': {},
                  'language': 'query',
                  'views': {index.name: {'map': {'fields': {'name': 'asc', 
                                                            'age': 'asc'}},