Merge pull request #604 from dhermes/update-storage-docstring-connection

Storage: updating Connection docstring; turning make_request private.

gcloud/storage/connection.py

@@ -27,12 +27,17 @@
 class Connection(_Base):
     """A connection to Google Cloud Storage via the JSON REST API.
 
-    This class should understand only the basic types (and protobufs) in
-    method arguments, however should be capable of returning advanced
-    types.
+    This defines :meth:`Connection.api_request` for making a generic JSON
+    API request and most API requests are created elsewhere (e.g. in
+    :class:`gcloud.storage.bucket.Bucket` and
+    :class:`gcloud.storage.blob.Blob`).
+
+    Methods for getting, creating and deleting individual buckets as well
+    as listing buckets associated with a project are defined here. This
+    corresponds to the "storage.buckets" resource in the API.
 
     See :class:`gcloud.connection.Connection` for a full list of
-    parameters.  :class:`Connection` differs only in needing a project
+    parameters. This subclass differs only in needing a project
     name (which you specify when creating a project in the Cloud
     Console).
 
@@ -47,14 +52,14 @@ class Connection(_Base):
 
       >>> bucket.delete()
       >>> # or
-      >>> connection.delete_bucket(bucket)
+      >>> connection.delete_bucket(bucket.name)
 
     If you want to access an existing bucket::
 
       >>> bucket = connection.get_bucket('my-bucket-name')
 
-    A :class:`Connection` is actually iterable and will return the
-    :class:`gcloud.storage.bucket.Bucket` objects inside the project::
+    You can also iterate through all :class:`gcloud.storage.bucket.Bucket`
+    objects inside the project::
 
       >>> for bucket in connection.get_all_buckets():
       >>>   print bucket
@@ -118,8 +123,8 @@ def build_api_url(self, path, query_params=None, api_base_url=None,
 
         return url
 
-    def make_request(self, method, url, data=None, content_type=None,
-                     headers=None):
+    def _make_request(self, method, url, data=None, content_type=None,
+                      headers=None):
         """A low level method to send a request to the API.
 
         Typically, you shouldn't need to use this method.
@@ -221,7 +226,7 @@ def api_request(self, method, path, query_params=None,
             data = json.dumps(data)
             content_type = 'application/json'
 
-        response, content = self.make_request(
+        response, content = self._make_request(
             method=method, url=url, data=data, content_type=content_type)
 
         if not 200 <= response.status < 300:
@@ -249,6 +254,8 @@ def get_all_buckets(self):
           >>> for bucket in connection.get_all_buckets():
           >>>   print bucket
 
+        This implements "storage.buckets.list".
+
         :rtype: list of :class:`gcloud.storage.bucket.Bucket` objects.
         :returns: All buckets belonging to this project.
         """
@@ -270,6 +277,8 @@ def get_bucket(self, bucket_name):
           >>> except NotFound:
           >>>   print 'Sorry, that bucket does not exist!'
 
+        This implements "storage.buckets.get".
+
         :type bucket_name: string
         :param bucket_name: The name of the bucket to get.
 
@@ -292,6 +301,8 @@ def create_bucket(self, bucket_name):
           >>> print bucket
           <Bucket: my-bucket>
 
+        This implements "storage.buckets.insert".
+
         :type bucket_name: string
         :param bucket_name: The bucket name to create.
 
@@ -331,6 +342,8 @@ def delete_bucket(self, bucket_name):
           >>> except Conflict:
           >>>   print 'That bucket is not empty!'
 
+        This implements "storage.buckets.delete".
+
         :type bucket_name: string
         :param bucket_name: The bucket name to delete.
         """

gcloud/storage/test_connection.py

@@ -100,15 +100,15 @@ def test_build_api_url_w_upload(self):
         ])
         self.assertEqual(conn.build_api_url('/foo', upload=True), URI)
 
-    def test_make_request_no_data_no_content_type_no_headers(self):
+    def test__make_request_no_data_no_content_type_no_headers(self):
         PROJECT = 'project'
         conn = self._makeOne(PROJECT)
         URI = 'http://example.com/test'
         http = conn._http = Http(
             {'status': '200', 'content-type': 'text/plain'},
             '',
         )
-        headers, content = conn.make_request('GET', URI)
+        headers, content = conn._make_request('GET', URI)
         self.assertEqual(headers['status'], '200')
         self.assertEqual(headers['content-type'], 'text/plain')
         self.assertEqual(content, '')
@@ -122,15 +122,15 @@ def test_make_request_no_data_no_content_type_no_headers(self):
         }
         self.assertEqual(http._called_with['headers'], expected_headers)
 
-    def test_make_request_w_data_no_extra_headers(self):
+    def test__make_request_w_data_no_extra_headers(self):
         PROJECT = 'project'
         conn = self._makeOne(PROJECT)
         URI = 'http://example.com/test'
         http = conn._http = Http(
             {'status': '200', 'content-type': 'text/plain'},
             '',
         )
-        conn.make_request('GET', URI, {}, 'application/json')
+        conn._make_request('GET', URI, {}, 'application/json')
         self.assertEqual(http._called_with['method'], 'GET')
         self.assertEqual(http._called_with['uri'], URI)
         self.assertEqual(http._called_with['body'], {})
@@ -142,15 +142,15 @@ def test_make_request_w_data_no_extra_headers(self):
         }
         self.assertEqual(http._called_with['headers'], expected_headers)
 
-    def test_make_request_w_extra_headers(self):
+    def test__make_request_w_extra_headers(self):
         PROJECT = 'project'
         conn = self._makeOne(PROJECT)
         URI = 'http://example.com/test'
         http = conn._http = Http(
             {'status': '200', 'content-type': 'text/plain'},
             '',
         )
-        conn.make_request('GET', URI, headers={'X-Foo': 'foo'})
+        conn._make_request('GET', URI, headers={'X-Foo': 'foo'})
         self.assertEqual(http._called_with['method'], 'GET')
         self.assertEqual(http._called_with['uri'], URI)
         self.assertEqual(http._called_with['body'], None)