Support new view parameters (#388)

* Support new view parameters: `stable` and `update`

* Copyrights

* Grammar (full stop)

* Add deprecation note.

Author: tomblench

CHANGES.md

@@ -5,6 +5,7 @@
 - [NEW] Added functionality to test if a key is in a database as in `key in db`, overriding dict `__contains__` and checking in the remote database.
 - [NEW] Moved `create_query_index` and other query related methods to `CouchDatabase` as the `_index`/`_find` API is available in CouchDB 2.x.
 - [NEW] Support IAM authentication in replication documents.
+- [NEW] Add new view parameters, `stable` and `update`, as keyword arguments to `get_view_result`.
 - [FIXED] Case where `Document` context manager would throw instead of creating a new document if no `_id` was provided.
 - [IMPROVED] Added support for IAM API key in `cloudant_bluemix` method.
 - [IMPROVED] Shortened length of client URLs by removing username and password.

src/cloudant/_common_util.py

@@ -60,9 +60,11 @@
     'limit': (int, LONGTYPE, NONETYPE,),
     'reduce': (bool,),
     'skip': (int, LONGTYPE, NONETYPE,),
+    'stable': (bool,),
     'stale': (STRTYPE,),
     'startkey': (int, LONGTYPE, STRTYPE, Sequence,),
     'startkey_docid': (STRTYPE,),
+    'update': (STRTYPE,),
 }
 
 # pylint: disable=unnecessary-lambda
@@ -196,7 +198,7 @@ def _py_to_couch_translate(key, val):
     equivalent.
     """
     try:
-        if key in ['keys', 'endkey_docid', 'startkey_docid', 'stale']:
+        if key in ['keys', 'endkey_docid', 'startkey_docid', 'stale', 'update']:
             return {key: val}
         elif val is None:
             return {key: None}

src/cloudant/database.py

@@ -312,15 +312,24 @@ def get_view_result(self, ddoc_id, view_name, raw_result=False, **kwargs):
         :param bool reduce: True to use the reduce function, false otherwise.
         :param int skip: Skip this number of rows from the start.
             Not valid when used with :class:`~cloudant.result.Result` iteration.
+        :param bool stable: Whether or not the view results should be returned
+            from a "stable" set of shards.
         :param str stale: Allow the results from a stale view to be used. This
             makes the request return immediately, even if the view has not been
             completely built yet. If this parameter is not given, a response is
-            returned only after the view has been built.
+            returned only after the view has been built. Note that this
+            parameter is deprecated and the appropriate combination of `stable`
+            and `update` should be used instead.
         :param startkey: Return records starting with the specified key.
             Not valid when used with :class:`~cloudant.result.Result` key
             access and key slicing.
         :param str startkey_docid: Return records starting with the specified
             document ID.
+        :param str update: Determine whether the view in question should be
+            updated prior to or after responding to the user. Valid values are:
+            false: return results before updating the view; true: Return results
+            after updating the view; lazy: Return the view results without
+            waiting for an update, but update them immediately after the request.
 
         :returns: The result content either wrapped in a QueryResult or
             as the raw response JSON content

src/cloudant/result.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2015 IBM. All rights reserved.
+# Copyright (C) 2015, 2018 IBM Corp. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -150,14 +150,24 @@ class Result(object):
     :param bool reduce: True to use the reduce function, false otherwise.
     :param int skip: Skip this number of rows from the start.
         Not valid when used with key iteration.
-    :param str stale: Allow the results from a stale view to be used. This
-        makes the request return immediately, even if the view has not been
-        completely built yet. If this parameter is not given, a response is
-        returned only after the view has been built.
+    :param bool stable: Whether or not the view results should be returned from
+        a "stable" set of shards.
+    :param str stale: Allow the results from a stale view to be used. This makes
+        the request return immediately, even if the view has not been completely
+        built yet. If this parameter is not given, a response is returned only
+        after the view has been built. Note that this parameter is deprecated
+        and the appropriate combination of `stable` and `update` should be used
+        instead.
     :param startkey: Return records starting with the specified key.
         Not valid when used with key access and key slicing.
     :param str startkey_docid: Return records starting with the specified
         document ID.
+    :param str update: Determine whether the view in question should be
+        updated prior to or after responding to the user. Valid values are:
+        false: return results before updating the view; true: Return results
+        after updating the view; lazy: Return the view results without
+        waiting for an update, but update them immediately after the request.
+
     """
     def __init__(self, method_ref, **options):
         self.options = options

tests/unit/param_translation_tests.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2016 IBM. All rights reserved.
+# Copyright (C) 2016, 2018 IBM Corp. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -215,6 +215,14 @@ def test_valid_startkey_docid(self):
             {'startkey_docid': 'foo'}
         )
 
+    def test_valid_update(self):
+        """
+        Test lazy translation is successful.
+        """
+        self.assertEqual(python_to_couch({'update': 'true'}), {'update': 'true'})
+        self.assertEqual(python_to_couch({'update': 'false'}), {'update': 'false'})
+        self.assertEqual(python_to_couch({'update': 'lazy'}), {'update': 'lazy'})
+
     def test_invalid_argument(self):
         """
         Test translation fails when an invalid argument is passed in.

tests/unit/view_execution_tests.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2016 IBM. All rights reserved.
+# Copyright (C) 2016, 2018 IBM Corp. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -467,7 +467,7 @@ def test_stale_ok(self):
         try:
             self.view001(stale='ok')
         except Exception as err:
-            self.assertFail(str(err), 'An unexpected error was encountered.')
+            self.fail('An unexpected error was encountered: '+str(err))
 
     def test_stale_update_after(self):
         """
@@ -480,8 +480,48 @@ def test_stale_update_after(self):
         try:
             self.view001(stale='update_after')
         except Exception as err:
-            self.assertFail(str(err), 'An unexpected error was encountered.')
+            self.fail('An unexpected error was encountered:' +str(err))
+            
+    def test_stable_true(self):
+        """
+        Test view query using the stable parameter set to true
+
+        
+        Since there is no way to know whether the view will return a response from a stable set of
+        shards or not the test here focuses on ensuring that the call itself is successful.
+
+        """
+        try:
+            self.view001(stable=True)
+        except Exception as err:
+            self.fail('An unexpected error was encountered: '+str(err))
+
+    def test_stable_update_lazy(self):
+        """
+        Test view query using the update parameter set to lazy
 
+        Since there is no way to know whether the view will update lazily or not the test here
+        focuses on ensuring that the call itself is successful.
+
+        """
+        try:
+            self.view001(update='lazy')
+        except Exception as err:
+            self.fail('An unexpected error was encountered: '+str(err))
+
+    def test_stable_update_true(self):
+        """
+        Test view query using the update parameter set to true
+
+        Since there is no way to know whether the view will update or not the test here focuses on
+        ensuring that the call itself is successful.
+
+        """
+        try:
+            self.view001(update='true')
+        except Exception as err:
+            self.fail('An unexpected error was encountered: '+str(err))
+                        
     def test_startkey_int(self):
         """
         Test view query using startkey parameter as an integer.