Implement Basic Proxy Support(#407)

Author: Cary Cheng

boxsdk/config.py

@@ -26,3 +26,8 @@ class Client(object):
         py_version.minor,
         py_version.micro,
     )
+
+
+class Proxy(object):
+    URL = None
+    AUTH = None

boxsdk/network/default_network.py

@@ -15,7 +15,7 @@
 
 
 class DefaultNetwork(Network):
-    """Implementats the network interface using the requests library."""
+    """Implements the network interface using the requests library."""
 
     LOGGER_NAME = 'boxsdk.network'
     REQUEST_FORMAT = '\x1b[36m%(method)s %(url)s %(request_kwargs)s\x1b[0m'

boxsdk/session/session.py

@@ -8,9 +8,10 @@
 from functools import partial
 from logging import getLogger
 
+from boxsdk.exception import BoxException
 from .box_request import BoxRequest as _BoxRequest
 from .box_response import BoxResponse as _BoxResponse
-from ..config import API, Client
+from ..config import API, Client, Proxy
 from ..exception import BoxAPIException
 from ..network.default_network import DefaultNetwork
 from ..util.json import is_json_response
@@ -35,6 +36,7 @@ def __init__(
             default_network_request_kwargs=None,
             api_config=None,
             client_config=None,
+            proxy_config=None,
     ):
         """
         :param network_layer:
@@ -64,11 +66,16 @@ def __init__(
             Object containing client information, including user agent string.
         :type client_config:
             :class:`Client`
+        :param proxy_config:
+            Object containing proxy information.
+        :type proxy_config:
+            :class:`Proxy` or None
         """
         if translator is None:
             translator = Translator(extend_default_translator=True, new_child=True)
         self._api_config = api_config or API()
         self._client_config = client_config or Client()
+        self._proxy_config = proxy_config or Proxy()
         super(Session, self).__init__()
         self._network_layer = network_layer or DefaultNetwork()
         self._default_headers = {
@@ -184,6 +191,14 @@ def client_config(self):
         """
         return self._client_config
 
+    @property
+    def proxy_config(self):
+        """
+
+        :rtype:     :class:`Proxy`
+        """
+        return self._proxy_config
+
     def get_url(self, endpoint, *args):
         """
         Return the URL for the given Box API endpoint.
@@ -211,6 +226,7 @@ def get_constructor_kwargs(self):
             default_network_request_kwargs=self._default_network_request_kwargs.copy(),
             api_config=self._api_config,
             client_config=self._client_config,
+            proxy_config=self._proxy_config,
             default_headers=self._default_headers.copy(),
         )
 
@@ -425,6 +441,34 @@ def _get_retry_request_callable(self, network_response, attempt_number, request)
     def _get_request_headers(self):
         return self._default_headers.copy()
 
+    def _prepare_proxy(self):
+        """
+        Prepares basic authenticated and unauthenticated proxies for requests.
+
+        :return:
+            A prepared proxy dict to send along with the request. None if incorrect parameters were passed.
+        :rtype:
+            `dict` or None
+        """
+        proxy = {}
+        proxy_string = ''
+        if self._proxy_config.URL is None:
+            return None
+        if self._proxy_config.AUTH and {'user', 'password'} <= set(self._proxy_config.AUTH):
+            host = self._proxy_config.URL
+            address = host.split('//')[1]
+            proxy_string = 'http://{0}:{1}@{2}'.format(self._proxy_config.AUTH.get('user', None),
+                                                       self._proxy_config.AUTH.get('password', None),
+                                                       address)
+        elif self._proxy_config.AUTH is None:
+            proxy_string = self._proxy_config.URL
+        else:
+            raise BoxException("The proxy auth dict you provided does not match pattern {'user': 'example_user', 'password': 'example_password'}")
+        proxy['http'] = proxy_string
+        proxy['https'] = proxy['http']
+
+        return proxy
+
     def _send_request(self, request, **kwargs):
         """
         Make a request to the Box API.
@@ -443,6 +487,9 @@ def _send_request(self, request, **kwargs):
         files, file_stream_positions = kwargs.get('files'), kwargs.pop('file_stream_positions')
         request_kwargs = self._default_network_request_kwargs.copy()
         request_kwargs.update(kwargs)
+        proxy_dict = self._prepare_proxy()
+        if proxy_dict is not None:
+            request_kwargs.update({'proxies': proxy_dict})
         if files and file_stream_positions:
             for name, position in file_stream_positions.items():
                 files[name][1].seek(position)

docs/usage/configuration.md

@@ -0,0 +1,39 @@
+Configuration
+=============
+
+The Python SDK has helpful custom config that you can set for a variety of use cases.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Proxy](#proxy)
+  - [Unauthenticated Proxy](#unauthenticated-proxy)
+  - [Basic Authentication Proxy](#basic-authentication-proxy)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+Proxy
+-----
+
+### Unauthenticated Proxy
+
+In order to set up configuration for basic proxy with the Python SDK, simply specify the proxy address for the `PROXY.URL` field.
+
+```python
+from boxsdk.config import PROXY
+PROXY.URL = 'http://example-proxy-address.com'
+```
+
+### Basic Authentication Proxy
+
+The Python SDK also lets you set an authenticated proxy. To do this specify the `user` and `password` fields and pass set that on the `PROXY.AUTH` field.
+
+```python
+from boxsdk.config import PROXY
+PROXY.AUTH = {
+    'user': 'test_user',
+    'password': 'test_password',
+}
+```
+

test/unit/conftest.py

@@ -8,7 +8,7 @@
 from mock import Mock, MagicMock
 import pytest
 
-from boxsdk.config import API, Client
+from boxsdk.config import API, Client, Proxy
 from boxsdk.network import default_network
 from boxsdk.network.default_network import DefaultNetworkResponse, DefaultNetwork
 from boxsdk.session.box_response import BoxResponse
@@ -50,6 +50,7 @@ def mock_box_session(translator):
     # pylint:disable=protected-access
     mock_session._api_config = mock_session.api_config = API()
     mock_session._client_config = mock_session.client_config = Client()
+    mock_session._proxy_config = mock_session.proxy_config = Proxy()
     # pylint:enable=protected-access
     mock_session.get_url.side_effect = lambda *args, **kwargs: Session.get_url(mock_session, *args, **kwargs)
     mock_session.translator = translator
@@ -62,6 +63,7 @@ def mock_box_session_2(translator):
     # pylint:disable=protected-access
     mock_session._api_config = API()
     mock_session._client_config = Client()
+    mock_session._proxy_config = Proxy()
     # pylint:enable=protected-access
     mock_session.get_url.side_effect = lambda *args, **kwargs: Session.get_url(mock_session, *args, **kwargs)
     mock_session.translator = translator

test/unit/session/test_session.py

@@ -6,12 +6,12 @@
 from io import IOBase
 from numbers import Number
 
-from mock import MagicMock, Mock, PropertyMock, call, patch
+from mock import MagicMock, Mock, PropertyMock, call, patch, ANY
 import pytest
 
 from boxsdk.auth.oauth2 import OAuth2
-from boxsdk.config import API
-from boxsdk.exception import BoxAPIException
+from boxsdk.config import API, Proxy
+from boxsdk.exception import BoxAPIException, BoxException
 from boxsdk.network.default_network import DefaultNetwork, DefaultNetworkResponse
 from boxsdk.session.box_response import BoxResponse
 from boxsdk.session.session import Session, Translator, AuthorizedSession
@@ -293,3 +293,50 @@ def test_get_retry_after_time(box_session, attempt_number, retry_after_header, e
         retry_time = box_session._get_retry_after_time(attempt_number, retry_after_header)  # pylint: disable=protected-access
     retry_time = round(retry_time, 4)
     assert retry_time == expected_result
+
+
+@pytest.mark.parametrize(
+    'test_proxy_url,test_proxy_auth,expected_proxy_dict',
+    [
+        ('http://example-proxy.com', {'user': 'test_user', 'password': 'test_password', },
+         {'http': 'http://test_user:[email protected]', 'https': 'http://test_user:[email protected]'}),
+        ('http://example-proxy.com', None, {'http': 'http://example-proxy.com', 'https': 'http://example-proxy.com'}),
+    ]
+)
+def test_proxy_attaches_to_request_correctly(
+        box_session,
+        monkeypatch,
+        mock_network_layer,
+        generic_successful_response,
+        test_proxy_url, test_proxy_auth,
+        expected_proxy_dict):
+    monkeypatch.setattr(Proxy, 'URL', test_proxy_url)
+    monkeypatch.setattr(Proxy, 'AUTH', test_proxy_auth)
+    mock_network_layer.request.side_effect = [generic_successful_response]
+    box_session.request('GET', test_proxy_url)
+    mock_network_layer.request.assert_called_once_with(
+        'GET',
+        test_proxy_url,
+        access_token='fake_access_token',
+        headers=ANY,
+        proxies=expected_proxy_dict,
+    )
+
+
+def test_proxy_malformed_dict_does_not_attach(box_session, monkeypatch, mock_network_layer, generic_successful_response):
+    test_proxy_url = 'http://example.com'
+    test_proxy_auth = {
+        'foo': 'bar',
+    }
+    monkeypatch.setattr(Proxy, 'URL', test_proxy_url)
+    monkeypatch.setattr(Proxy, 'AUTH', test_proxy_auth)
+    mock_network_layer.request.side_effect = [generic_successful_response]
+    with pytest.raises(BoxException) as exc_info:
+        box_session.request('GET', test_proxy_url)
+    assert isinstance(exc_info.value, BoxException)
+    assert exc_info.value.args[0] == "The proxy auth dict you provided does not match pattern " \
+                                     "{'user': 'example_user', 'password': 'example_password'}"
+
+
+def test_proxy_network_config_property(box_session):
+    assert isinstance(box_session.proxy_config, Proxy)