Ensure bucket upload methods return the blob.

[tseaver]

Fixes #596.

[coveralls]

Coverage remained the same at 100.0% when pulling d3bc612 on tseaver:596-return_blob_from_bucket_upload_file_obj into 9518db7 on GoogleCloudPlatform:master.

[dhermes]

@tseaver WDYT of having Blob.upload_* methods return nothing (Blob already around) and having the Bucket.upload_ methods return the new objects?

---

As an aside (outside of this PR), I feel like having a single upload() and a single download() method could be feasible / easy to use? This requires type / interface checking for the objects passed in.

We have (happily, for me) moved away from multi-type behavior for inputs, e.g. datastore.put(entity) fails and only a list is accepted, e.g. datastore.put([entity]).

Somehow I feel like this is slightly different since there is only one action (download) but 3 legitimate places to download to

• bytes object (return value)
• writable buffer (e.g. BytesIO or something attached to something other than the FS)
• buffer pointed to the filesystem

---

As another aside (outside of this PR), shall we cut a release tomorrow?

[coveralls]

Coverage remained the same at 100.0% when pulling dceabc6 on tseaver:596-return_blob_from_bucket_upload_file_obj into 9518db7 on GoogleCloudPlatform:master.

[tseaver]

dceabc6 drops the return self from the Blob.update_* methods.

---

I'm not sure that a single upload / download would be easier to use in practice, unless we just made the user pass / receive a file-like object everywhere. E.g.:

    def upload(self, name, file_obj):
        """Upload a blob into this bucket.

        :type name: string
        :param name: name of the blob within the bucket.

        :type file_obj: readable file-like object
        :param blob: an object that can be read like a file.

        :rtype: :class:`Blob`
        :returns: The created / updated Blob object.
        """

    def download(self, name, file_obj):
        """Download a blob from this bucket

        :type name: string
        :param name: name of the blob within the bucket.

        :type file_obj: writeable file-like object
        :param blob: an object that can be written like a file.
        """

---

A release today seems like a good plan. Is it just a matter of making a tag, or does somebody need to to PyPI stuff manually?

[dhermes]

LGTM.

---

Yeah I think the single-use upload() / download() may be tricky to do right, but still want to give it a try. I was more curious if you thought it was too inconsistent to "forbid" multi-type signatures in one place and to actively seek them out here.

---

I will prepare the tag today. Our Travis config deals with PyPI for us, so no issues there. The only effort is put release notes in the tag (which will be copious here).