Allow http as an argument to base Connection class.

gcloud/connection.py

@@ -24,6 +24,34 @@ class Connection(object):
 
     Subclasses should understand only the basic types in method arguments,
     however they should be capable of returning advanced types.
+
+    If no value is passed in for ``http``, a :class:`httplib2.Http` object
+    will be created and authorized with the ``credentials``. If not, the
+    ``credentials`` and ``http`` need not be related.
+
+    Subclasses may seek to use the private key from ``credentials`` to sign
+    data.
+
+    A custom (non-``httplib2``) HTTP object must have a ``request`` method
+    which accepts the following arguments:
+
+    * ``uri``
+    * ``method``
+    * ``body``
+    * ``headers``
+
+    In addition, ``redirections`` and ``connection_type`` may be used.
+
+    Without the use of ``credentials.authorize(http)``, a custom ``http``
+    object will also need to be able to add a bearer token to API
+    requests and handle token refresh on 401 errors.
+
+    :type credentials: :class:`oauth2client.client.OAuth2Credentials` or
+                       :class:`NoneType`
+    :param credentials: The OAuth2 Credentials to use for this connection.
+
+    :type http: :class:`httplib2.Http` or class that defines ``request()``.
+    :param http: An optional HTTP object to make requests.
     """
 
     API_BASE_URL = 'https://www.googleapis.com'
@@ -35,14 +63,8 @@ class Connection(object):
     USER_AGENT = "gcloud-python/{0}".format(get_distribution('gcloud').version)
     """The user agent for gcloud-python requests."""
 
-    def __init__(self, credentials=None):
-        """Constructor for Connection.
-
-        :type credentials: :class:`oauth2client.client.OAuth2Credentials` or
-                           :class:`NoneType`
-        :param credentials: The OAuth2 Credentials to use for this connection.
-        """
-        self._http = None
+    def __init__(self, credentials=None, http=None):
+        self._http = http
         self._credentials = credentials
 
     @property

gcloud/test_connection.py

@@ -32,6 +32,13 @@ def test_ctor_explicit(self):
         creds = object()
         conn = self._makeOne(creds)
         self.assertTrue(conn.credentials is creds)
+        self.assertEqual(conn._http, None)
+
+    def test_ctor_explicit_http(self):
+        http = object()
+        conn = self._makeOne(http=http)
+        self.assertEqual(conn.credentials, None)
+        self.assertTrue(conn.http is http)
 
     def test_http_w_existing(self):
         conn = self._makeOne()