Skip to content

Commit 58edd2e

Browse files
dhermesdhermes
committed
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.
1 parent a6317d1 commit 58edd2e

2 files changed

Lines changed: 29 additions & 16 deletions

File tree

‎gcloud/storage/connection.py‎

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,17 @@
2727
class Connection(_Base):
2828
"""A connection to Google Cloud Storage via the JSON REST API.
2929
30-
This class should understand only the basic types (and protobufs) in
31-
method arguments, however should be capable of returning advanced
32-
types.
30+
This defines :meth:`Connection.api_request` for making a generic JSON
31+
API request and most API requests are created elsewhere (e.g. in
32+
:class:`gcloud.storage.bucket.Bucket` and
33+
:class:`gcloud.storage.blob.Blob`).
34+
35+
Methods for getting, creating and deleting individual buckets as well
36+
as listing buckets associated with a project are defined here. This
37+
corresponds to the "storage.buckets" resource in the API.
3338
3439
See :class:`gcloud.connection.Connection` for a full list of
35-
parameters. :class:`Connection` differs only in needing a project
40+
parameters. This subclass differs only in needing a project
3641
name (which you specify when creating a project in the Cloud
3742
Console).
3843
@@ -47,14 +52,14 @@ class Connection(_Base):
4752
4853
>>> bucket.delete()
4954
>>> # or
50-
>>> connection.delete_bucket(bucket)
55+
>>> connection.delete_bucket(bucket.name)
5156
5257
If you want to access an existing bucket::
5358
5459
>>> bucket = connection.get_bucket('my-bucket-name')
5560
56-
A :class:`Connection` is actually iterable and will return the
57-
:class:`gcloud.storage.bucket.Bucket` objects inside the project::
61+
You can also iterate through all :class:`gcloud.storage.bucket.Bucket`
62+
objects inside the project::
5863
5964
>>> for bucket in connection.get_all_buckets():
6065
>>> print bucket
@@ -118,8 +123,8 @@ def build_api_url(self, path, query_params=None, api_base_url=None,
118123

119124
return url
120125

121-
def make_request(self, method, url, data=None, content_type=None,
122-
headers=None):
126+
def _make_request(self, method, url, data=None, content_type=None,
127+
headers=None):
123128
"""A low level method to send a request to the API.
124129
125130
Typically, you shouldn't need to use this method.
@@ -221,7 +226,7 @@ def api_request(self, method, path, query_params=None,
221226
data = json.dumps(data)
222227
content_type = 'application/json'
223228

224-
response, content = self.make_request(
229+
response, content = self._make_request(
225230
method=method, url=url, data=data, content_type=content_type)
226231

227232
if not 200 <= response.status < 300:
@@ -249,6 +254,8 @@ def get_all_buckets(self):
249254
>>> for bucket in connection.get_all_buckets():
250255
>>> print bucket
251256
257+
This implements "storage.buckets.list".
258+
252259
:rtype: list of :class:`gcloud.storage.bucket.Bucket` objects.
253260
:returns: All buckets belonging to this project.
254261
"""
@@ -270,6 +277,8 @@ def get_bucket(self, bucket_name):
270277
>>> except NotFound:
271278
>>> print 'Sorry, that bucket does not exist!'
272279
280+
This implements "storage.buckets.get".
281+
273282
:type bucket_name: string
274283
:param bucket_name: The name of the bucket to get.
275284
@@ -292,6 +301,8 @@ def create_bucket(self, bucket_name):
292301
>>> print bucket
293302
<Bucket: my-bucket>
294303
304+
This implements "storage.buckets.insert".
305+
295306
:type bucket_name: string
296307
:param bucket_name: The bucket name to create.
297308
@@ -331,6 +342,8 @@ def delete_bucket(self, bucket_name):
331342
>>> except Conflict:
332343
>>> print 'That bucket is not empty!'
333344
345+
This implements "storage.buckets.delete".
346+
334347
:type bucket_name: string
335348
:param bucket_name: The bucket name to delete.
336349
"""

‎gcloud/storage/test_connection.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,15 @@ def test_build_api_url_w_upload(self):
100100
])
101101
self.assertEqual(conn.build_api_url('/foo', upload=True), URI)
102102

103-
def test_make_request_no_data_no_content_type_no_headers(self):
103+
def test__make_request_no_data_no_content_type_no_headers(self):
104104
PROJECT = 'project'
105105
conn = self._makeOne(PROJECT)
106106
URI = 'http://example.com/test'
107107
http = conn._http = Http(
108108
{'status': '200', 'content-type': 'text/plain'},
109109
'',
110110
)
111-
headers, content = conn.make_request('GET', URI)
111+
headers, content = conn._make_request('GET', URI)
112112
self.assertEqual(headers['status'], '200')
113113
self.assertEqual(headers['content-type'], 'text/plain')
114114
self.assertEqual(content, '')
@@ -122,15 +122,15 @@ def test_make_request_no_data_no_content_type_no_headers(self):
122122
}
123123
self.assertEqual(http._called_with['headers'], expected_headers)
124124

125-
def test_make_request_w_data_no_extra_headers(self):
125+
def test__make_request_w_data_no_extra_headers(self):
126126
PROJECT = 'project'
127127
conn = self._makeOne(PROJECT)
128128
URI = 'http://example.com/test'
129129
http = conn._http = Http(
130130
{'status': '200', 'content-type': 'text/plain'},
131131
'',
132132
)
133-
conn.make_request('GET', URI, {}, 'application/json')
133+
conn._make_request('GET', URI, {}, 'application/json')
134134
self.assertEqual(http._called_with['method'], 'GET')
135135
self.assertEqual(http._called_with['uri'], URI)
136136
self.assertEqual(http._called_with['body'], {})
@@ -142,15 +142,15 @@ def test_make_request_w_data_no_extra_headers(self):
142142
}
143143
self.assertEqual(http._called_with['headers'], expected_headers)
144144

145-
def test_make_request_w_extra_headers(self):
145+
def test__make_request_w_extra_headers(self):
146146
PROJECT = 'project'
147147
conn = self._makeOne(PROJECT)
148148
URI = 'http://example.com/test'
149149
http = conn._http = Http(
150150
{'status': '200', 'content-type': 'text/plain'},
151151
'',
152152
)
153-
conn.make_request('GET', URI, headers={'X-Foo': 'foo'})
153+
conn._make_request('GET', URI, headers={'X-Foo': 'foo'})
154154
self.assertEqual(http._called_with['method'], 'GET')
155155
self.assertEqual(http._called_with['uri'], URI)
156156
self.assertEqual(http._called_with['body'], None)

0 commit comments

Comments
 (0)