datastore.(set|get)_default_connection() is a bit misleading

[jgeewax]

I think set_default_connection is a bit misleading, in that it "tries to create a connection from the environment"... To put this in pseudo-code:

def get_default_connection():
 connection = <some pre-loaded connection already stored>
 if not connection:
 connection = <create a connection somehow from the environment>
 if not connection:
 connection = <create a connection from the environment another way>
 if not connection:
 raise EnvironmentError('Connection cannot be inferred from the environment :(')
 return connection

def set_default_connection(connection=None):
 <some safe place to store a connection> = connection # Yes, this could be None.

The idea being...

• set_default_connection() sets a variable, that's all.
• get_default_connection() goes through a list of possible ways to get a connection, raising an exception when we can't get one...

What we have today is:

• set_default_connection() sets a variable and tries to come up with a magical connection from the environment if possible.
• get_default_connection() only returns the variable

I'm sure this will be subject to a bunch of debate, but having a getter method also doing some setting seems really misleading to me.

[dhermes]

• We have get_default_connection() to access a value that is already set
• We have get_connection() to go through the motions that set_default_connection() goes through

I'm happy to consider renaming, but each of these actions needs to be possible for users.

[jgeewax]

OK, so let me know if I understand correctly what the intent here is (*** would be connection in the case we're discussing, but I'm generalizing):

• get_default_***() should just return what's stored in the variable.
• set_default_***() should just set the variable to whatever we passed.
• get_***() should get back a *** from the environment somehow.
• set_default_***(None) should call get_***() and store that in the variable. <- This is where I get confused.

Does that make any sense?

[dhermes]

I just realized that we need to find a way to get Sphinx to document method defined in _implicit_environ.py since they don't show up in
http://googlecloudplatform.github.io/gcloud-python

Why do you get confused?

Set default connection either explicitly or implicitly as fall-back.

Means the passed-in (or explicit) value is used to set or the implicit value is used. (Tiny nuance: passing an explicit None is the same as passing no arguments.)

[dhermes]

@jgeewax Did you want to continue this discussion?

[jgeewax]

Closing out for now... I think we may be going in circles (completely my fault....) regarding authentication and the magic that goes with it.