<noun>() vs get_<noun>() vs <verb>_<noun>()

[jgeewax]

Moved over from #910 per @dhermes

Goal of this issue is to decide:

1. Is it reasonable to provide one-liners to do things like create_topic() which is just a wrapper:
   python def create_topic(self, name): topic = self.topic(name) topic.create() return topic
2. Can we agree on the naming convention of what does and does not require an API request

---

Comment from the pull request was...

The name create_topic is ambiguous to new users. Does it mean create a Topic instance or actual insert one?

That's a good point. I think we should adopt the attitude that client.<verb>_<noun>() is an API request. So create_topic would hit the API trying to 'insert' the topic (using Google's API lingo). client.<noun> is nothing more than a factory for the noun which won't fire an API request but gives you back an instance of the .

We'd need to offer Client.topic and Client.create_topic side-by-side since users would need to construct pre-existing topics without sending insert.

Totally agree -- I think we had this debate already and I'm totally sold on the need for .topic() as the sole way to get a hold of a topic object, without hitting the API (as the topic literally has zero extra metadata).

For other APIs, where the object itself holds lots of (potentially important) metadata, I think it might be worthwhile to provide a get_<noun>() to pull down that metadata, in addition to the <noun>() method which just gives you an object which may not be tied to the remote (authoritative) representation.

An example here might be bucket.

• .bucket() gives me a bucket object, sans remote data (no API request).
• create_bucket() explicitly creates the bucket in the remote service, throwing an error if I was unable to do so.
• get_bucket() would be an API request that gives me all the metadata about a bucket.

Note that the <verb>_bucket() methods are really just shortcuts so that I can have one-liners for the common things I want to do with a bucket. (ie, create == bucket = client.bucket('name'); bucket.create(); return bucket;)

In boto for S3, they have this verify or check parameter on the bucket constructor, so the comparisons look like:

Action	boto	gcloud (suggestion)
Get a bucket, no API request	connection.get_bucket(validate=False)	client.bucket()
Get a bucket + metadata	connection.get_bucket()	client.get_bucket()

I personally don't love the boto method, and would much rather the "gcloud (suggestion)" option.

[dhermes]

At a glance, I'll say this is mixing an imperative approach (functions only) with an object oriented approach. By making half the HTTP requests with functions and half with object methods, we muddle what our approach / philosophy is.

[jgeewax]

That is a good point. My concern is that our staunch adherence to the "only one approach" means more code for people in simple cases.

That is, if we stick to the object-oriented approach, one-liners aren't possible because of our decision to never allow chaining:

# This is *NOT* possible:
topic = client.topic('name').create()

If we go with the imperative approach, one liners are possible, but it means the logic gets mixed up a bit:

topic = client.create_topic()  # What does this return? What can you do with the result?

I'm suggesting we actively decide to make the object-oriented approach the authoritative one, with shortcut helper methods for common simple tasks where a common user would want a one-liner.

class Client(...):
  def create_topic(self, *args, **kwargs):
    topic = self.topic(*args, **kwargs)
    topic.create()
    return topic

This way, all logic lives in one place, but we get the one-liners a lot of users want (me among them)

[dhermes]

I'm with most of it but "a lot of users want" isn't clearly true or false (you're the only user we really interact with).

[dhermes]

I'm happy to implement, but would love to hear what @tseaver has to say.

[tseaver]

I'm -1 on adding more topic- and subscription-specific methods to Client. Trading typing for clarity is not a win to me.

[jgeewax]

Where is the loss of clarity?

And how do I get a bucket and it's metadata? storage.bucket('...') doesn't do that does it?

[dhermes]

from gcloud import storage
b = storage.get_bucket('name')

which is equivalent to

from gcloud import storage
b = storage.Bucket('name')
b.reload()

[jgeewax]

OK, so we already have the short-cut method for "getting" a bucket.. why not for creating?

from gcloud import storage
b = storage.create_bucket('name')

which would be equivalent to

from gcloud import storage
b = storage.Bucket('name')
b.create()

Right?

[dhermes]

@jgeewax You ought to check out gcloud.storage.api, create_bucket also exists :)

FWIW The reason we have those bucket methods in storage.api is twofold

• They were all already implemented on Connection previously
• There is no "parent" for a bucket, so they are a top-level concept

[jgeewax]

So going back to the original thing... topic doesn't have a parent does it? So why wouldn't we add a shortcut method for create_topic too?

[dhermes]

The only difference here is that there is no "all already implemented on Connection previously" baggage.

Before, we ported the methods blindly. Now, we can actually think about it.

FWIW, when we ported them @tseaver said he'd prefer we nuke storage.create_bucket and just recommend Bucket.create() and he has continued to mention it for awhile. I mention this to say that it's been clear on our minds, not just an ad hoc stance.

[jgeewax]

So by that measure we should nuke storage.get_bucket too -- and ask people to do .Bucket() and bucket.reload() -- right?