What is the overall story on Connections?

@tseaver

I'm noticing that "Connection" objects are slowly being phased out, in favor of gcloud.<service>.do_thing (ie gcloud.storage.get_bucket() or gcloud.datastore.Query(...)).

Did we make a specific call to remove the concept of a connection? Was the a discussion somewhere that I can read up on to understand the background behind that?

/cc @tseaver @dhermes

@tseaver

They aren't being phased out and they aren't going anywhere.

We've discussed in our meetings that they be stateless and are simply a way to make HTTP requests to the service.

Datastore: We allow connection as an optional argument in methods / functions that use one. Using implicitly set connections, a user can happily use the library without needing to know what a connection is.

This was spurred on by comments that there were "too many classes". We realized that we didn't need the typical user to worry about a Connection (beyond setting the right environment variable for credentials).

We still made sure one could be used.

Storage: We are in the process of making the API surface easier to use. In this attempt we are trying to "hide" the Connection class from typical users and do the same thing.

I've created #632 for my proposal on storage, and @tseaver also made some previous remarks.