Storage: updating Connection docstring; turning make_request private.

[dhermes]

Making it clear in the docstring that the Connection itself only handles storage.bucket... API methods and that the other classes handle the other 30 (give or take) methods of the API.

@tseaver This documents our decision from earlier today (about the responsibilities of Connection).

Also note

• We don't directly support storage.buckets.update anywhere (but Connection.api_request would allow it)
• We don't support storage.buckets.patch on Connection. Only via Bucket (through _PropertyMixin._patch_properties()).
• Both Bucket._reload_properties() (via _PropertyMixin) and Connection.get_bucket implement storage.buckets.get.

For your reference: discovery document.

[coveralls]

Coverage remained the same at 100.0% when pulling 58edd2e on dhermes:update-storage-docstring-connection into a6317d1 on GoogleCloudPlatform:master.

[tseaver]

LGTM

[dhermes]

@tseaver WDYT of missing support / overlapping support of storage.buckets API methods?

[tseaver]

I think we should remove the single-bucket-centric connection methods, and surface such operations only on Bucket methods.

• bucket = connection.get_bucket(bucket_name) -> bucket = Bucket(bucket_name, connection=connection)
• bucket = connection.create_bucket(bucket_name) -> bucket = Bucket(bucket_name, connection=connection, create=True)
• Connection.delete_bucket(bucket_name) -> Bucket(bucket_name, connection=connection).delete()

[dhermes]

I like it! In the implicit case, WDYT of:

>>> b = Bucket(bucket_name)
>>> b.exists()
False
>>> b.create()
>>> b.exists()
True

[dhermes]

In line with this would be putting most of the storage.objects... methods on Blob.

This leaves us storage.objects.list and storage.buckets.list in a somewhat strange place but (again, in an implicit CNXN future) we could say

storage.set_default_connection()

buckets = storage.get_all_buckets()

bucket = buckets.next()  # Iterator
for blob in bucket.get_all_blobs():
    do_something(blob)

or even in the more extreme scenario that there is a default bucket

storage.set_defaults()

for blob in storage.get_all_blobs():
    do_something(blob)

[tseaver]

I like b.create() and b.exists().

I'm not sure about calling buckets.next() manually: how do I know the first one is the one I want?

ISTM that storage.set_defaults() should probably return the default bucket, if there is one defined, or None.