Add timeout parameter to SendGrid API clients

Default to a 30 second HTTP timeout to prevent hung processes.
The timeout is passed through to python_http_client which already
supports it. Callers can override or disable (via None) as needed.
Timeouts via send() raise SendGridTimeoutError for clean handling.

Author: pellepim

README.md

@@ -137,6 +137,16 @@ print(response.body)
 print(response.headers)
 ```
 
+## Timeout
+
+By default, HTTP requests will time out after 30 seconds. You can change this by passing a `timeout` parameter (in seconds) when creating the client:
+
+```python
+sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'), timeout=60)
+```
+
+To disable the timeout, pass `None`.
+
 ## General v3 Web API Usage (With [Fluent Interface](https://sendgrid.com/blog/using-python-to-implement-a-fluent-interface-to-any-rest-api/))
 
 ```python

sendgrid/base_interface.py

@@ -3,7 +3,7 @@
 region_host_dict = {'eu':'https://api.eu.sendgrid.com','global':'https://api.sendgrid.com'}
 
 class BaseInterface(object):
-    def __init__(self, auth, host, impersonate_subuser):
+    def __init__(self, auth, host, impersonate_subuser, timeout=30):
         """
         Construct the Twilio SendGrid v3 API object.
         Note that the underlying client is being set up during initialization,
@@ -20,18 +20,23 @@ def __init__(self, auth, host, impersonate_subuser):
         :type impersonate_subuser: string
         :param host: base URL for API calls
         :type host: string
+        :param timeout: the timeout (in seconds) for HTTP requests.
+                        Defaults to 30. Set to None to disable.
+        :type timeout: int
         """
         from . import __version__
         self.auth = auth
         self.impersonate_subuser = impersonate_subuser
         self.version = __version__
         self.useragent = 'sendgrid/{};python'.format(self.version)
         self.host = host
+        self.timeout = timeout
 
         self.client = python_http_client.Client(
             host=self.host,
             request_headers=self._default_headers,
-            version=3)
+            version=3,
+            timeout=timeout)
 
     @property
     def _default_headers(self):
@@ -78,6 +83,7 @@ def set_sendgrid_data_residency(self, region):
                 self.client = python_http_client.Client(
                     host=self.host,
                     request_headers=self._default_headers,
-                    version=3)
+                    version=3,
+                    timeout=self.timeout)
         else:
             raise ValueError("region can only be \"eu\" or \"global\"")

sendgrid/sendgrid.py

@@ -33,7 +33,8 @@ def __init__(
             self,
             api_key=None,
             host='https://api.sendgrid.com',
-            impersonate_subuser=None):
+            impersonate_subuser=None,
+            timeout=30):
         """
         Construct the Twilio SendGrid v3 API object.
         Note that the underlying client is being set up during initialization,
@@ -51,8 +52,11 @@ def __init__(
         :type impersonate_subuser: string
         :param host: base URL for API calls
         :type host: string
+        :param timeout: the timeout (in seconds) for HTTP requests.
+                        Defaults to 30. Set to None to disable.
+        :type timeout: int
         """
         self.api_key = api_key or os.environ.get('SENDGRID_API_KEY')
         auth = 'Bearer {}'.format(self.api_key)
 
-        super(SendGridAPIClient, self).__init__(auth, host, impersonate_subuser)
+        super(SendGridAPIClient, self).__init__(auth, host, impersonate_subuser, timeout=timeout)

sendgrid/twilio_email.py

@@ -35,7 +35,8 @@ def __init__(
             username=None,
             password=None,
             host='https://email.twilio.com',
-            impersonate_subuser=None):
+            impersonate_subuser=None,
+            timeout=30):
         """
         Construct the Twilio Email v3 API object.
         Note that the underlying client is being set up during initialization,
@@ -59,6 +60,9 @@ def __init__(
         :type impersonate_subuser: string
         :param host: base URL for API calls
         :type host: string
+        :param timeout: the timeout (in seconds) for HTTP requests.
+                        Defaults to 30. Set to None to disable.
+        :type timeout: int
         """
         self.username = username or \
                         os.environ.get('TWILIO_API_KEY') or \
@@ -70,4 +74,4 @@ def __init__(
 
         auth = 'Basic ' + b64encode('{}:{}'.format(self.username, self.password).encode()).decode()
 
-        super(TwilioEmailAPIClient, self).__init__(auth, host, impersonate_subuser)
+        super(TwilioEmailAPIClient, self).__init__(auth, host, impersonate_subuser, timeout=timeout)

test/unit/test_sendgrid.py

@@ -24,4 +24,19 @@ def test_with_region_is_none(self):
     def test_with_region_is_invalid(self):
         sg = sendgrid.SendGridAPIClient(api_key='MY_API_KEY')
         with self.assertRaises(ValueError):
-            sg.set_sendgrid_data_residency("abc")
+            sg.set_sendgrid_data_residency("abc")
+
+    def test_timeout_default(self):
+        sg = sendgrid.SendGridAPIClient(api_key='MY_API_KEY')
+        self.assertEqual(sg.timeout, 30)
+        self.assertEqual(sg.client.timeout, 30)
+
+    def test_timeout_set_via_constructor(self):
+        sg = sendgrid.SendGridAPIClient(api_key='MY_API_KEY', timeout=10)
+        self.assertEqual(sg.timeout, 10)
+        self.assertEqual(sg.client.timeout, 10)
+
+    def test_timeout_preserved_after_data_residency_change(self):
+        sg = sendgrid.SendGridAPIClient(api_key='MY_API_KEY', timeout=10)
+        sg.set_sendgrid_data_residency("eu")
+        self.assertEqual(sg.client.timeout, 10)

test/unit/test_twilio_email.py

@@ -35,3 +35,13 @@ def test_init_args(self):
         self.assertEqual(mail_client.username, 'username')
         self.assertEqual(mail_client.password, 'password')
         self.assertEqual(mail_client.auth, 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=')
+
+    def test_timeout_default(self):
+        mail_client = TwilioEmailAPIClient('username', 'password')
+        self.assertEqual(mail_client.timeout, 30)
+        self.assertEqual(mail_client.client.timeout, 30)
+
+    def test_timeout_set_via_constructor(self):
+        mail_client = TwilioEmailAPIClient('username', 'password', timeout=10)
+        self.assertEqual(mail_client.timeout, 10)
+        self.assertEqual(mail_client.client.timeout, 10)