feat: async support (#676)

Author: Hunga1

README.md

@@ -134,6 +134,26 @@ message = client.messages.create(to="+12316851234", from_="+15555555555",
                                  body="Hello there!")
 ```
 
+### Asynchronous API Requests
+
+By default, the Twilio Client will make synchronous requests to the Twilio API. To allow for asynchronous, non-blocking requests, we've included an optional asynchronous HTTP client. When used with the Client and the accompanying `*_async` methods, requests made to the Twilio API will be performed asynchronously.
+
+```python
+from twilio.http.async_http_client import AsyncTwilioHttpClient
+from twilio.rest import Client
+
+async def main():
+    account = "ACXXXXXXXXXXXXXXXXX"
+    token = "YYYYYYYYYYYYYYYYYY"
+    http_client = AsyncTwilioHttpClient()
+    client = Client(account, token, http_client=http_client)
+
+    message = await client.messages.create_async(to="+12316851234", from_="+15555555555",
+                                                 body="Hello there!")
+
+asyncio.run(main())
+```
+
 ### Enable Debug Logging
 
 Log the API request and response data to the console:

requirements.txt

@@ -2,3 +2,6 @@ pygments>=2.7.4 # not directly required, pinned by Snyk to avoid a vulnerability
 pytz
 requests>=2.0.0
 PyJWT>=2.0.0, <3.0.0
+asyncio>=3.4.3
+aiohttp>=3.8.4
+aiohttp-retry>=2.8.3

setup.py

@@ -24,6 +24,9 @@
         "pytz",
         "requests >= 2.0.0",
         "PyJWT >= 2.0.0, < 3.0.0",
+        "asyncio>=3.4.3",
+        "aiohttp>=3.8.4",
+        "aiohttp-retry>=2.8.3"
     ],
     packages=find_packages(exclude=['tests', 'tests.*']),
     include_package_data=True,

tests/integration/flex_api/v1/test_assessments.py

@@ -2,6 +2,7 @@ Sphinx>=1.8.0
 mock
 pytest
 pytest-cov
+aiounittest
 flake8
 wheel>=0.22.0
 cryptography

tests/requirements.txt

@@ -0,0 +1,127 @@
+import unittest
+import aiounittest
+
+from aiohttp import ClientSession
+from mock import patch, AsyncMock
+from twilio.http.async_http_client import AsyncTwilioHttpClient
+
+
+class MockResponse(object):
+    """
+    A mock of the aiohttp.ClientResponse class
+    """
+    def __init__(self, text, status):
+        self._text = text
+        self.status = status
+        self.headers = {}
+
+    async def text(self):
+        return self._text
+
+
+class TestAsyncHttpClientRequest(aiounittest.AsyncTestCase):
+    def setUp(self):
+        self.session_mock = AsyncMock(wraps=ClientSession)
+        self.session_mock.request.return_value = MockResponse('test', 200)
+
+        self.session_patcher = patch('twilio.http.async_http_client.aiohttp.ClientSession')
+        session_constructor_mock = self.session_patcher.start()
+        session_constructor_mock.return_value = self.session_mock
+
+        self.client = AsyncTwilioHttpClient()
+
+    def tearDown(self):
+        self.session_patcher.stop()
+
+    async def test_request_called_with_method_and_url(self):
+        await self.client.request('GET', 'https://mock.twilio.com')
+
+        self.session_mock.request.assert_called()
+        request_args = self.session_mock.request.call_args.kwargs
+        self.assertIsNotNone(request_args)
+        self.assertEqual(request_args['method'], 'GET')
+        self.assertEqual(request_args['url'], 'https://mock.twilio.com')
+
+    async def test_request_called_with_basic_auth(self):
+        await self.client.request('doesnt matter', 'doesnt matter', auth=('account_sid', 'auth_token'))
+
+        self.session_mock.request.assert_called()
+        auth = self.session_mock.request.call_args.kwargs['auth']
+        self.assertIsNotNone(auth)
+        self.assertEqual(auth.login, 'account_sid')
+        self.assertEqual(auth.password, 'auth_token')
+
+    async def test_invalid_request_timeout_raises_exception(self):
+        with self.assertRaises(ValueError):
+            await self.client.request('doesnt matter', 'doesnt matter', timeout=-1)
+
+
+class TestAsyncHttpClientRetries(aiounittest.AsyncTestCase):
+    def setUp(self):
+        self.session_mock = AsyncMock(wraps=ClientSession)
+        self.session_mock.request.side_effect = [MockResponse('Error', 500), MockResponse('Error', 500),
+                                                 MockResponse('Success', 200)]
+
+        self.session_patcher = patch('twilio.http.async_http_client.aiohttp.ClientSession')
+        session_constructor_mock = self.session_patcher.start()
+        session_constructor_mock.return_value = self.session_mock
+
+    def tearDown(self):
+        self.session_patcher.stop()
+
+    async def test_request_retries_until_success(self):
+        client = AsyncTwilioHttpClient(max_retries=99)
+        response = await client.request('doesnt matter', 'doesnt matter')
+
+        self.assertEqual(self.session_mock.request.call_count, 3)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.text, 'Success')
+
+    async def test_request_retries_until_max(self):
+        client = AsyncTwilioHttpClient(max_retries=2)
+        response = await client.request('doesnt matter', 'doesnt matter')
+
+        self.assertEqual(self.session_mock.request.call_count, 2)
+        self.assertEqual(response.status_code, 500)
+        self.assertEqual(response.text, 'Error')
+
+
+class TestAsyncHttpClientSession(aiounittest.AsyncTestCase):
+    def setUp(self):
+        self.session_patcher = patch('twilio.http.async_http_client.aiohttp.ClientSession')
+        self.session_constructor_mock = self.session_patcher.start()
+
+    def tearDown(self):
+        self.session_patcher.stop()
+
+    def _setup_session_response(self, value):
+        session_mock = AsyncMock(wraps=ClientSession)
+        session_mock.request.return_value = MockResponse(value, 200)
+        session_mock.close.return_value = None
+        self.session_constructor_mock.return_value = session_mock
+
+    async def test_session_preserved(self):
+        self._setup_session_response('response_1')
+
+        client = AsyncTwilioHttpClient()
+        response_1 = await client.request('GET', 'https://api.twilio.com')
+
+        self._setup_session_response('response_2')
+        response_2 = await client.request('GET', 'https://api.twilio.com')
+
+        # Used same session, response should be the same
+        self.assertEqual(response_1.content, 'response_1')
+        self.assertEqual(response_2.content, 'response_1')
+
+    async def test_session_not_preserved(self):
+        self._setup_session_response('response_1')
+
+        client = AsyncTwilioHttpClient(pool_connections=False)
+        response_1 = await client.request('GET', 'https://api.twilio.com')
+
+        self._setup_session_response('response_2')
+        response_2 = await client.request('GET', 'https://api.twilio.com')
+
+        # No session used, responses should be different (not cached)
+        self.assertEqual(response_1.content, 'response_1')
+        self.assertEqual(response_2.content, 'response_2')

tests/unit/http/test_async_http_client.py

@@ -1,5 +1,8 @@
 import unittest
+import aiounittest
 
+from mock import AsyncMock, Mock
+from twilio.http.response import Response
 from twilio.rest import (
     Client
 )
@@ -74,3 +77,34 @@ def test_set_user_agent_extensions(self):
         user_agent_headers = self.client.http_client._test_only_last_request.headers['User-Agent']
         user_agent_extensions = user_agent_headers.split(" ")[-len(expected_user_agent_extensions):]
         self.assertEqual(user_agent_extensions, expected_user_agent_extensions)
+
+
+class TestClientAsyncRequest(aiounittest.AsyncTestCase):
+    def setUp(self):
+        self.mock_async_http_client = AsyncMock()
+        self.mock_async_http_client.request.return_value = Response(200, 'test')
+        self.mock_async_http_client.is_async = True
+        self.client = Client('username', 'password', http_client=self.mock_async_http_client)
+
+    async def test_raise_error_if_client_not_marked_async(self):
+        mock_http_client = Mock()
+        mock_http_client.request.return_value = Response(200, 'doesnt matter')
+        mock_http_client.is_async = None
+
+        client = Client('username', 'password', http_client=mock_http_client)
+        with self.assertRaises(RuntimeError):
+            await client.request_async('doesnt matter', 'doesnt matter')
+
+    async def test_raise_error_if_client_is_not_async(self):
+        mock_http_client = Mock()
+        mock_http_client.request.return_value = Response(200, 'doesnt matter')
+        mock_http_client.is_async = False
+
+        client = Client('username', 'password', http_client=mock_http_client)
+        with self.assertRaises(RuntimeError):
+            await client.request_async('doesnt matter', 'doesnt matter')
+
+    async def test_request_async_called_with_method_and_url(self):
+        await self.client.request_async('GET', 'http://mock.twilio.com')
+        self.assertEqual(self.mock_async_http_client.request.call_args.args[0], 'GET')
+        self.assertEqual(self.mock_async_http_client.request.call_args.args[1], 'http://mock.twilio.com')