Merge pull request #199 from cloudant/193-update-handlers

Added support for update handlers

Author: emlaver

CHANGES.rst

@@ -4,6 +4,7 @@
 - [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 support for querying update handlers.
 - [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.

src/cloudant/database.py

@@ -842,6 +842,57 @@ def get_show_function_result(self, ddoc_id, show_name, doc_id):
                         headers)
         return resp.text
 
+    def update_handler_result(self, ddoc_id, handler_name, doc_id=None, data=None, **params):
+        """
+        Creates or updates a document from the specified database based on the
+        update handler function provided.  Update handlers are used, for
+        example, to provide server-side modification timestamps, and document
+        updates to individual fields without the latest revision. You can
+        provide query parameters needed by the update handler function using
+        the ``params`` argument.
+
+        Create a document with a generated ID:
+
+        .. code-block:: python
+
+            # Assuming that 'update001' update handler exists as part of the
+            # 'ddoc001' design document in the remote database...
+            # Execute 'update001' to create a new document
+            resp = db.update_handler_result('ddoc001', 'update001', data={'name': 'John',
+                                            'message': 'hello'})
+
+        Create or update a document with the specified ID:
+
+        .. code-block:: python
+
+            # Assuming that 'update001' update handler exists as part of the
+            # 'ddoc001' design document in the remote database...
+            # Execute 'update001' to update document 'doc001' in the database
+            resp = db.update_handler_result('ddoc001', 'update001', 'doc001',
+                                            data={'month': 'July'})
+
+        For more details, see the `update handlers documentation
+        <https://docs.cloudant.com/design_documents.html#update-handlers>`_.
+
+        :param str ddoc_id: Design document id used to get result.
+        :param str handler_name: Name used in part to identify the
+            update handler function.
+        :param str doc_id: Optional document id used to specify the
+            document to be handled.
+
+        :returns: Result of update handler function in text format
+        """
+        ddoc = DesignDocument(self, ddoc_id)
+        if doc_id:
+            resp = self.r_session.put(
+                '/'.join([ddoc.document_url, '_update', handler_name, doc_id]),
+                params=params, data=data)
+        else:
+            resp = self.r_session.post(
+                '/'.join([ddoc.document_url, '_update', handler_name]),
+                params=params, data=data)
+        return resp.text
+
 class CloudantDatabase(CouchDatabase):
     """
     Encapsulates a Cloudant database.  A CloudantDatabase object is

src/cloudant/design_document.py

@@ -48,6 +48,44 @@ def __init__(self, database, document_id=None):
         for prop in self._nested_object_names:
             self.setdefault(prop, dict())
 
+    @property
+    def updates(self):
+        """
+        Provides an accessor property to the updates dictionary in the locally
+        cached DesignDocument. Update handlers are custom functions stored on
+        Cloudant's server that will create or update a document.
+        To execute the update handler function, see
+        :func:`~cloudant.database.CouchDatabase.update_handler_result`.
+
+        Update handlers receive two arguments: ``doc`` and ``req``. If a document ID is
+        provided in the request to the update handler, then ``doc`` will be the
+        document corresponding with that ID.
+        If no ID was provided, ``doc`` will be null.
+
+        Update handler example:
+
+        .. code-block:: python
+
+            # Add the update handler to ``updates`` and save the design document
+            ddoc = DesignDocument(self.db, '_design/ddoc001')
+            ddoc001['updates'] = {
+                'update001': 'function(doc, req) { if (!doc) '
+                             '{ if ('id' in req && req.id){ return [{_id: req.id}, '
+                             '\"New World\"] } return [null, \"Empty World\"] } '
+                             'doc.world = \'hello\'; '
+                             'return [doc, \"Added world.hello!\"]} '
+            }
+            ddoc.save()
+
+        Note: Update handler functions must return an array of two elements,
+        the first being the document to save (or null, if you don't want to
+        save anything), and the second being the response body.
+
+        :returns: Dictionary containing update handler names and objects
+            as key/value
+        """
+        return self.get('updates')
+
     @property
     def st_indexes(self):
         """

tests/unit/database_tests.py

@@ -692,6 +692,61 @@ def test_get_show_result(self):
             'Hello from doc001!'
         )
 
+    def test_create_doc_with_update_handler(self):
+        """
+        Test update_handler_result executes an update handler function
+        that creates a new document
+        """
+        self.populate_db_with_documents()
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc['updates'] = {
+            'update001': 'function(doc, req) { if (!doc) { var new_doc = req.form; '
+                         'new_doc._id = \'testDoc\'; return [new_doc, '
+                         '\'Created new doc: \' + JSON.stringify(new_doc)]; }} '
+        }
+
+        ddoc.save()
+        resp = self.db.update_handler_result('ddoc001', 'update001', data={'message': 'hello'})
+        self.assertEqual(
+            resp,
+            'Created new doc: {"message":"hello","_id":"testDoc"}'
+        )
+
+    def test_update_doc_with_update_handler(self):
+        """
+        Test update_handler_result executes an update handler function
+        that updates a document with query parameters
+        """
+        self.populate_db_with_documents()
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc['updates'] = {
+            'update001': 'function(doc, req) { '
+                         'var field = req.query.field; '
+                         'var value = req.query.value; '
+                         'var new_doc = doc; '
+                         'doc[field] = value; '
+                         'for(var key in req.form) doc[key]=req.form[key]; '
+                         'var message = \'set \'+field+\' to \'+value'
+                         '+\' and add data \'+ JSON.stringify(req.form); '
+                         'return [doc, message]; } '
+        }
+        ddoc.save()
+        resp = self.db.update_handler_result('ddoc001', 'update001', 'julia001',
+                                             field='new_field', value='new_value',
+                                             data={'message': 'hello'})
+        self.assertEqual(
+            resp,
+            'set new_field to new_value and add data {"message":"hello"}'
+        )
+        ddoc_remote = Document(self.db, 'julia001')
+        ddoc_remote.fetch()
+        self.assertEqual(
+            ddoc_remote,
+            {'age': 1, 'name': 'julia', 'new_field': 'new_value',
+             '_rev': ddoc_remote['_rev'], '_id': 'julia001',
+             'message': 'hello'}
+        )
+
 @unittest.skipUnless(
     os.environ.get('RUN_CLOUDANT_TESTS') is not None,
     'Skipping Cloudant specific Database tests'