From 58edd2eb0f5a657773bcbd785894443a7f78a791 Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Mon, 9 Feb 2015 19:22:41 -0800 Subject: [PATCH] Storage: updating Connection docstring; turning make_request private. Making it clear in the docstring that the Connection itself only handles "bucket" queries and that the other classes handle the other 30 (give or take) methods of the API. --- gcloud/storage/connection.py | 33 +++++++++++++++++++++---------- gcloud/storage/test_connection.py | 12 +++++------ 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/gcloud/storage/connection.py b/gcloud/storage/connection.py index 84aa4d06774e..8a6b48b95508 100644 --- a/gcloud/storage/connection.py +++ b/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 + 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. """ diff --git a/gcloud/storage/test_connection.py b/gcloud/storage/test_connection.py index ce38b79d2c25..1073f0969d18 100644 --- a/gcloud/storage/test_connection.py +++ b/gcloud/storage/test_connection.py @@ -100,7 +100,7 @@ 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' @@ -108,7 +108,7 @@ def test_make_request_no_data_no_content_type_no_headers(self): {'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,7 +122,7 @@ 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' @@ -130,7 +130,7 @@ def test_make_request_w_data_no_extra_headers(self): {'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,7 +142,7 @@ 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' @@ -150,7 +150,7 @@ def test_make_request_w_extra_headers(self): {'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)