Merge pull request #274 from cloudant/257-default-timeout

257 timeout argument

Author: emlaver

CHANGES.rst

@@ -1,6 +1,6 @@
 2.4.0 (Unreleased)
 ==================
-
+- [NEW] Added ``timeout`` option to the client constructor for setting a timeout on a HTTP connection or a response.
 
 2.3.1 (2016-11-30)
 ==================

docs/getting_started.rst

@@ -27,6 +27,10 @@ Note: If you require retrying requests after an HTTP 429 error, the
 ``Replay429Adapter`` can be added when constructing a ``Cloudant``
 client and configured with an initial back off and retry count.
 
+Note: Currently, the connect and read timeout will wait forever for
+a HTTP connection or a response on all requests.  A timeout can be
+set using the ``timeout`` argument when constructing a client.
+
 Connecting with a client
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -46,6 +50,10 @@ Connecting with a client
     # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
     #                   adapter=Replay429Adapter(retries=10, initialBackoff=0.01))
 
+    # or with a connect and read timeout of 5 minutes
+    # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
+    #                   timeout=300)
+
     # Perform client tasks...
     session = client.session()
     print 'Username: {0}'.format(session['userCtx']['name'])

src/cloudant/_common_util.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2015, 2016 IBM. All rights reserved.
+# Copyright (c) 2015, 2016, 2017 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.
@@ -292,19 +292,21 @@ class InfiniteSession(Session):
     information in the event of expired session authentication.
     """
 
-    def __init__(self, username, password, server_url):
+    def __init__(self, username, password, server_url, **kwargs):
         super(InfiniteSession, self).__init__()
         self._username = username
         self._password = password
         self._server_url = server_url
+        self._timeout = kwargs.get('timeout', None)
 
     def request(self, method, url, **kwargs):
         """
         Overrides ``requests.Session.request`` to perform a POST to the
         _session endpoint to renew Session cookie authentication settings and
         then retry the original request, if necessary.
         """
-        resp = super(InfiniteSession, self).request(method, url, **kwargs)
+        resp = super(InfiniteSession, self).request(
+            method, url, timeout=self._timeout, **kwargs)
         path = url_parse(url).path.lower()
         post_to_session = method.upper() == 'POST' and path == '/_session'
         is_expired = any((
@@ -319,10 +321,30 @@ def request(self, method, url, **kwargs):
                 data={'name': self._username, 'password': self._password},
                 headers={'Content-Type': 'application/x-www-form-urlencoded'}
             )
-            resp = super(InfiniteSession, self).request(method, url, **kwargs)
+            resp = super(InfiniteSession, self).request(
+                method, url, timeout=self._timeout, **kwargs)
 
         return resp
 
+class ClientSession(Session):
+    """
+    This class extends Session and provides a default timeout.
+    """
+
+    def __init__(self, username, password, server_url, **kwargs):
+        super(ClientSession, self).__init__()
+        self._username = username
+        self._password = password
+        self._server_url = server_url
+        self._timeout = kwargs.get('timeout', None)
+
+    def request(self, method, url, **kwargs):
+        """
+        Overrides ``requests.Session.request`` to set the timeout.
+        """
+        resp = super(ClientSession, self).request(
+            method, url, timeout=self._timeout, **kwargs)
+        return resp
 
 class CloudFoundryService(object):
     """ Manages Cloud Foundry service configuration. """

src/cloudant/client.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (C) 2015, 2016 IBM Corp. All rights reserved.
+# Copyright (C) 2015, 2016, 2017 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.
@@ -19,7 +19,6 @@
 import base64
 import json
 import posixpath
-import requests
 
 from ._2to3 import bytes_, unicode_
 from .database import CloudantDatabase, CouchDatabase
@@ -28,8 +27,8 @@
 from ._common_util import (
     USER_AGENT,
     append_response_error_content,
-    InfiniteSession
-)
+    InfiniteSession,
+    ClientSession)
 
 
 class CouchDB(dict):
@@ -56,6 +55,15 @@ class CouchDB(dict):
     :param bool auto_renew: Keyword argument, if set to True performs
         automatic renewal of expired session authentication settings.
         Default is False.
+    :param float timeout: Timeout in seconds (use float for milliseconds, for
+        example 0.1 for 100 ms) for connecting to and reading bytes from the
+        server.  If a single value is provided it will be applied to both the
+        connect and read timeouts.  To specify different values for each timeout
+        use a tuple.  For example, a 10 second connect timeout and a 1 minute
+        read timeout would be (10, 60).  This follows the same behaviour as the
+        `Requests library timeout argument
+        <http://docs.python-requests.org/en/master/user/quickstart/#timeouts>`_.
+        but will apply to every request made using this client.
     """
     _DATABASE_CLASS = CouchDatabase
 
@@ -69,6 +77,7 @@ def __init__(self, user, auth_token, admin_party=False, **kwargs):
         self.admin_party = admin_party
         self.encoder = kwargs.get('encoder') or json.JSONEncoder
         self.adapter = kwargs.get('adapter')
+        self._timeout = kwargs.get('timeout', None)
         self.r_session = None
         self._auto_renew = kwargs.get('auto_renew', False)
         connect_to_couch = kwargs.get('connect', False)
@@ -87,10 +96,16 @@ def connect(self):
             self.r_session = InfiniteSession(
                 self._user,
                 self._auth_token,
-                self.server_url
+                self.server_url,
+                timeout=self._timeout
             )
         else:
-            self.r_session = requests.Session()
+            self.r_session = ClientSession(
+                self._user,
+                self._auth_token,
+                self.server_url,
+                timeout=self._timeout
+            )
         # If a Transport Adapter was supplied add it to the session
         if self.adapter is not None:
             self.r_session.mount(self.server_url, self.adapter)

tests/unit/client_tests.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2015, 2016 IBM. All rights reserved.
+# Copyright (c) 2015, 2016, 2017 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.
@@ -28,6 +28,8 @@
 import os
 import datetime
 
+from requests import ConnectTimeout
+
 from cloudant import cloudant, couchdb, couchdb_admin_party
 from cloudant.client import Cloudant, CouchDB
 from cloudant.error import CloudantArgumentError, CloudantClientException
@@ -536,6 +538,15 @@ def test_connect_headers(self):
         finally:
             self.client.disconnect()
 
+    def test_connect_timeout(self):
+        """
+        Test that a connect timeout occurs when instantiating
+        a client object with a timeout of 10 ms.
+        """
+        with self.assertRaises(ConnectTimeout) as cm:
+            self.set_up_client(auto_connect=True, timeout=.01)
+        self.assertTrue(str(cm.exception).find('timed out.'))
+
     def test_db_updates_infinite_feed_call(self):
         """
         Test that infinite_db_updates() method call constructs and returns an

tests/unit/replicator_tests.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2015 IBM. All rights reserved.
+# Copyright (c) 2015, 2016, 2017 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.
@@ -25,9 +25,10 @@
 import unittest
 import uuid
 import time
-import requests
 
 from flaky import flaky
+import requests
+from requests import ConnectionError
 
 from cloudant.replicator import Replicator
 from cloudant.document import Document
@@ -210,6 +211,46 @@ def test_create_replication(self):
             ])
         )
 
+    def test_timeout_in_create_replication(self):
+        """
+        Test that a read timeout exception is thrown when creating a
+        replicator with a timeout value of 500 ms.
+        """
+        # Setup client with a timeout
+        self.set_up_client(auto_connect=True, timeout=.5)
+        self.db = self.client[self.test_target_dbname]
+        self.target_db = self.client[self.test_dbname]
+        # Construct a replicator with the updated client
+        self.replicator = Replicator(self.client)
+
+        repl_id = 'test-repl-{}'.format(unicode_(uuid.uuid4()))
+        repl_doc = self.replicator.create_replication(
+            self.db,
+            self.target_db,
+            repl_id
+        )
+        self.replication_ids.append(repl_id)
+        # Test that the replication document was created
+        expected_keys = ['_id', '_rev', 'source', 'target', 'user_ctx']
+        # If Admin Party mode then user_ctx will not be in the key list
+        if self.client.admin_party:
+            expected_keys.pop()
+        self.assertTrue(all(x in list(repl_doc.keys()) for x in expected_keys))
+        self.assertEqual(repl_doc['_id'], repl_id)
+        self.assertTrue(repl_doc['_rev'].startswith('1-'))
+        # Now that we know that the replication document was created,
+        # check that the replication timed out.
+        repl_doc = Document(self.replicator.database, repl_id)
+        repl_doc.fetch()
+        if repl_doc.get('_replication_state') not in ('completed', 'error'):
+            # assert that a connection error is thrown because the read timed out
+            with self.assertRaises(ConnectionError) as cm:
+                changes = self.replicator.database.changes(
+                    feed='continuous')
+                for change in changes:
+                    continue
+            self.assertTrue(str(cm.exception).endswith('Read timed out.'))
+
     def test_create_replication_without_a_source(self):
         """
         Test that the replication document is not created and fails as expected
@@ -357,5 +398,6 @@ def test_follow_replication(self):
         self.assertEqual(repl_states[-1], 'completed')
         self.assertNotIn('error', repl_states)
 
+
 if __name__ == '__main__':
     unittest.main()

tests/unit/unit_t_db_base.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2015 IBM. All rights reserved.
+# Copyright (c) 2015, 2016, 2017 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.
@@ -131,7 +131,8 @@ def setUp(self):
         """
         self.set_up_client()
 
-    def set_up_client(self, auto_connect=False, auto_renew=False, encoder=None):
+    def set_up_client(self, auto_connect=False, auto_renew=False, encoder=None,
+                      timeout=(30,300)):
         if os.environ.get('RUN_CLOUDANT_TESTS') is None:
             admin_party = False
             if (os.environ.get('ADMIN_PARTY') and
@@ -147,7 +148,8 @@ def set_up_client(self, auto_connect=False, auto_renew=False, encoder=None):
                 url=self.url,
                 connect=auto_connect,
                 auto_renew=auto_renew,
-                encoder=encoder
+                encoder=encoder,
+                timeout=timeout
             )
         else:
             self.account = os.environ.get('CLOUDANT_ACCOUNT')
@@ -163,7 +165,8 @@ def set_up_client(self, auto_connect=False, auto_renew=False, encoder=None):
                 x_cloudant_user=self.account,
                 connect=auto_connect,
                 auto_renew=auto_renew,
-                encoder=encoder
+                encoder=encoder,
+                timeout=timeout
             )