Seems that we're having some disagreements on what our surfaces should look like. Here's my opinion to start the discussion. I use a "thing API" that deals with "things". You can replace with "storage" and "bucket" if it that's easier.

/cc @daspecster @dhermes @tseaver @jonparrott

Client pattern

A client handles your credentials and acts as the pipe to the API.

from gcloud import thingifier
client = thingifier.Client()

Instantiate a thing

Create the thing object and eventually save it remotely.

thing = client.thing(parameters)
# ...
thing.save()

It's important that the there are no required parameters:

thing = client.thing()

If you want a one-liner to save a new thing remotely.

# Nuance here is that .save() returns the thing.
thing = client.thing(parameters).save()

# Note that we're explicitly NOT providing:
# thing = client.create_thing(parameters)

It's unusual, but perhaps you want to "load" a thing from the API by first creating the thing object with the right ID, and then reloading it.

thing = client.thing()
thing.id = 'identifier'
thing.reload()

Get a thing

Give me a thing from the API service.

thing = client.get_thing(identifier)

What if the thing doesn't exist?

thing = client.get_thing(identifier)
# thing is None

Update a thing

The same pattern as creating a thing, except I start with a loaded thing.

thing = client.get_thing(identifier)
thing.property = 'new value'
thing.save()

Reload a thing

I have a thing, but I suspect it's changed since I loaded it. I want to make sure what i have is fresh...

thing = client.get_thing(identifier)
# ... some time later ...
thing.reload()

List a bunch of things

I have many things stored and I want to go through all of them.

for thing in client.list_things():
  do_something_with(thing)

I have lots of things, but I only want 100 of them. I don't care how many API calls there are.

for thing in client.list_things(limit=100):
  do_something_with(thing)

I have lots of things, and I want to control specifically how many API calls I'm making -- I'm on a budget!

for thing in client.list_things(api_call_limit=5):
  do_something_with(thing)

Delete a thing

I have a thing that I loaded, or paged through, and I want to delete it.

thing = client.get_thing(identifier)
thing.delete()

And to do this in a one-liner, with a single API request:

client.thing(identifier).delete()

We may also want to support a single method, but I'm not 100% sure about this...

client.delete_thing(identifier)

Related

• Allow easy paging for list operations #895
• <noun>() vs get_<noun>() vs <verb>_<noun>() #911
• Add dns.Client.get_zone #1718
• http://stackoverflow.com/questions/30243687/verify-if-a-topic-exists-based-on-topic-name/32019553#32019553