Added update validator property with documentation

Author: emlaver

CHANGES.rst

@@ -8,6 +8,7 @@
 - [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.
+- [NEW] Added ``validate_doc_update`` accessor property for update validators.
 - [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())``.
 - [IMPROVED] Made the 429 response code backoff optional and configurable. To enable the backoff add

src/cloudant/design_document.py

@@ -48,6 +48,32 @@ def __init__(self, database, document_id=None):
         for prop in self._nested_object_names:
             self.setdefault(prop, dict())
 
+    @property
+    def validate_doc_update(self):
+        """
+        Provides an accessor property to the update validators dictionary in
+        the locally cached DesignDocument.  Update validators evaluate whether a
+        document should be written to disk when insertions and updates are attempted.
+
+        Update validator example:
+
+        .. code-block:: python
+
+            # Add the update validator to ``validate_doc_update`` and save the design document
+            ddoc = DesignDocument(self.db, '_design/ddoc001')
+            ddoc['validate_doc_update'] = (
+                'function(newDoc, oldDoc, userCtx, secObj) { '
+                'if (newDoc.address === undefined) { '
+                'throw({forbidden: \'Document must have an address.\'}); }}')
+            ddoc.save()
+
+        For more details, see the `Update Validators documentation
+        <https://docs.cloudant.com/design_documents.html#update-validators>`_.
+
+        :returns: Dictionary containing update validator functions
+        """
+        return self.get('validate_doc_update')
+
     @property
     def updates(self):
         """

tests/unit/design_document_tests.py

@@ -21,6 +21,7 @@
 module docstring.
 
 """
+import json
 import os
 import unittest
 
@@ -1658,5 +1659,26 @@ def test_get_show_function(self):
             'html += \'</ol></body></html>\'; return html; }); }'
         )
 
+    def test_update_validator(self):
+        """
+        Test that update validator requires an address key for a new document.
+        """
+        ddoc = DesignDocument(self.db, '_design/ddoc001')
+        ddoc['validate_doc_update'] = (
+            'function(newDoc, oldDoc, userCtx, secObj) { '
+            'if (newDoc.address === undefined) { '
+            'throw({forbidden: \'Document must have an address.\'}); }}')
+        ddoc.save()
+        headers = {'Content-Type': 'application/json'}
+        resp = self.client.r_session.post(
+            self.db.database_url,
+            headers=headers,
+            data=json.dumps({'_id': 'test001'})
+        )
+        self.assertEqual(
+            resp.json(),
+            {'reason': 'Document must have an address.', 'error': 'forbidden'}
+        )
+
 if __name__ == '__main__':
     unittest.main()