Changing Key noun to be Blob in storage package.

[dhermes]

This involves changes in all documentation, renaming a module
and a test module, and updating the calls and variable names in
a regression test module.

Addresses #544.

See https://github.com/dhermes/gcloud-python/tree/fix-544-many-commits for a more digestible version of these commits (though it's still not very digestible).

To "check" I was finished I manually inspected the output of "git grep -i key".

[coveralls]

Coverage remained the same when pulling b5ceb5f on dhermes:fix-544 into 1bfa469 on GoogleCloudPlatform:master.

[dhermes]

@tseaver I'm not certain that object_ is the right name for the module, maybe gcs_object instead? Same applies to variable names. I'm also unsure if Object should be the class name or something else. I'm somewhat worried people will naively do things like:

>>> from gcloud.storage.object_ import Object
>>> object = Object('foo')
>>> 
>>> class MyClass(object):
...     pass
... 
>>> MyClass
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "gcloud/storage/object_.py", line 110, in __repr__
    bucket_name = self.bucket.name
AttributeError: 'str' object has no attribute 'name'
>>> m = MyClass()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'Object' object is not callable

and not understanding why they break.

[dhermes]

@tseaver @jgeewax This is what we discussed earlier today.

It's going to be a bear to manage this PR while also changing other parts of the storage API, so I'd prefer to get the noun remapping out of the way soon.

Ideas put forth today (in order of my preference, best to last):

• blob.Blob -- mirrors a concept similar / familiar to users
• gcs_object.GCSObject -- still probably too close to object
• file.File -- conflicts with (mostly defunct) builtin. File seems an imprecise mapping to an object.
• object_.Object -- hits too close to home with Python (uber-important object builtin), but matches the actual noun in the API

The current language (removed in this PR) is:

The fundamental container for a file in Cloud Storage is called an Object,
however gcloud uses the term Key to avoid confusion between
object and Object.

For me, this language is not prevalent enough and I worry that straying away from "object" (even for Blob) will cause frustration with users trying to Google search for API concepts.

[jgeewax]

Your list above is my exact order of preference.

What might be worthwhile is to figure out how to make the Sphinx documentation generate the left-hand navigation from "Storage --> Keys" to "Storage --> Blobs (Objects)".

This way, when I'm looking for familiar terms from the docs, I still see what I was looking for, but get the picture right away.

I think the note you have above should be a .. warning: (or something bright colored) so it's obvious what is going on.

[dhermes]

@jgeewax I was more worried about when they search in the API docs, not the docs for our library. The API docs will be more definitive / comprehensive than our library docs.

Do we think anyone from storage has gone through this existential naming issue with Object and object conflicting in Python? /cc @thobrla

[thobrla]

apitools autogenerates Object as part of its messages file, because that is the resource name. What makes it usable in practice is that the module name is not "object". That way, it's not that confusing in practice because you're typically referencing it via "messages.Object" or the like.

With that said, apitools maps 1:1 to the API, which I don't believe is the goal here. gcloud-python will have its own docs, yes? Are clients intended to interact with the API directly in the same codebase where they are using gcloud-python? If not, matching the API docs is reduced in importance.

[dhermes]

Yes we have our own docs. Your input "matching the API docs is reduced in importance" is good to know; I wasn't sure how worried we should be about a vocab gap.

I am going to go thrown and use blob.Blob. Let me know if this is an issue.

[dhermes]

@tseaver I just updated from object -> blob. PTAL.

If you want an ad hoc set of smaller commits, check out
https://github.com/dhermes/gcloud-python/tree/fix-544-blob-many-commits

[coveralls]

Changes Unknown when pulling 4570c43 on dhermes:fix-544 into * on GoogleCloudPlatform:master*.

[tseaver]

Reviewing now.

[tseaver]

LGTM. Since Travis doesn't check it for PRs, I also verified that the regression tests pass.

[dhermes]

Thanks. I also run the regression tests locally before sending PRs.