{"action":"created","issue":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1722","repository_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1722/labels{/name}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1722/comments","events_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1722/events","html_url":"https://github.com/GoogleCloudPlatform/gcloud-python/issues/1722","id":148073942,"number":1722,"title":"Policy on the basic CRUD operations","user":{"login":"jgeewax","id":112928,"avatar_url":"https://avatars.githubusercontent.com/u/112928?v=3","gravatar_id":"","url":"https://api.github.com/users/jgeewax","html_url":"https://github.com/jgeewax","followers_url":"https://api.github.com/users/jgeewax/followers","following_url":"https://api.github.com/users/jgeewax/following{/other_user}","gists_url":"https://api.github.com/users/jgeewax/gists{/gist_id}","starred_url":"https://api.github.com/users/jgeewax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jgeewax/subscriptions","organizations_url":"https://api.github.com/users/jgeewax/orgs","repos_url":"https://api.github.com/users/jgeewax/repos","events_url":"https://api.github.com/users/jgeewax/events{/privacy}","received_events_url":"https://api.github.com/users/jgeewax/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/labels/core","name":"core","color":"f7c6c7"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2016-04-13T14:09:49Z","updated_at":"2016-04-13T15:18:42Z","closed_at":null,"body":"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.\r\n\r\n/cc @daspecster @dhermes @tseaver @jonparrott \r\n\r\n### Client pattern\r\n\r\nA client handles your credentials and is the pipe to the API.\r\n\r\n```python\r\nfrom gcloud import thing\r\nclient = thing.Client()\r\n```\r\n\r\n### Instantiate a thing\r\n\r\nCreate the thing object and eventually save it remotely.\r\n\r\n```python\r\nthing = client.thing(parameters)\r\n# ...\r\nthing.save()\r\n```\r\n\r\nIt'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.\r\n\r\n```python\r\nthing = client.thing()\r\nthing.id = 'identifier'\r\nthing.reload()\r\n```\r\n\r\n### Get a thing\r\n\r\nGive me a thing from the API service.\r\n\r\n```python\r\nthing = client.get_thing(identifier)\r\n```\r\n\r\n### Update a thing\r\n\r\nThe same pattern as creating a thing, except I start with a loaded thing.\r\n\r\n```python\r\nthing = client.get_thing(identifier)\r\nthing.property = 'new value'\r\nthing.save()\r\n```\r\n\r\n### Reload a thing\r\n\r\nI have a thing, but I suspect it's changed since I loaded it. I want to make sure what i have is fresh...\r\n```python\r\nthing = client.get_thing(identifier)\r\n# ... some time later ...\r\nthing.reload()\r\n```\r\n\r\n### List a bunch of things\r\n\r\nI have many things stored and I want to go through all of them.\r\n\r\n```python\r\nfor thing in client.list_things():\r\n  do_something_with(thing)\r\n```\r\n\r\nI have lots of things, but I only want 100 of them. I don't care how many API calls there are.\r\n\r\n```python\r\nfor thing in client.list_things(limit=100):\r\n  do_something_with(thing)\r\n```\r\n\r\nI have lots of things, and I want to control specifically how many API calls I'm making -- I'm on a budget!\r\n\r\n```python\r\nfor thing in client.list_things(api_call_limit=5):\r\n  do_something_with(thing)\r\n```\r\n\r\n### Delete a thing\r\n\r\nI have a thing that I loaded, or paged through, and I want to delete it.\r\n\r\n```python\r\nthing = client.get_thing(identifier)\r\nthing.delete()\r\n```\r\n\r\nI want to delete a thing, but I know it's unique ID.\r\n\r\n```python\r\nclient.delete_thing(identifier)\r\n```\r\n\r\nTechnically this could also be done with...\r\n\r\n```python\r\nclient.thing(identifier).delete()\r\n```\r\n\r\n### Related\r\n\r\n- #895 \r\n- #911 \r\n- #1718 \r\n- http://stackoverflow.com/questions/30243687/verify-if-a-topic-exists-based-on-topic-name/32019553#32019553"},"comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/comments/209505057","html_url":"https://github.com/GoogleCloudPlatform/gcloud-python/issues/1722#issuecomment-209505057","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1722","id":209505057,"user":{"login":"dhermes","id":520669,"avatar_url":"https://avatars.githubusercontent.com/u/520669?v=3","gravatar_id":"","url":"https://api.github.com/users/dhermes","html_url":"https://github.com/dhermes","followers_url":"https://api.github.com/users/dhermes/followers","following_url":"https://api.github.com/users/dhermes/following{/other_user}","gists_url":"https://api.github.com/users/dhermes/gists{/gist_id}","starred_url":"https://api.github.com/users/dhermes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dhermes/subscriptions","organizations_url":"https://api.github.com/users/dhermes/orgs","repos_url":"https://api.github.com/users/dhermes/repos","events_url":"https://api.github.com/users/dhermes/events{/privacy}","received_events_url":"https://api.github.com/users/dhermes/received_events","type":"User","site_admin":false},"created_at":"2016-04-13T15:18:42Z","updated_at":"2016-04-13T15:18:42Z","body":"The main issue is really the disagreement about the [Zen of Python][1]:\r\n\r\n> There should be one-- and preferably only one --obvious way to do it.\r\n\r\nIn addition, we've never heard a request from a user for the extra methods.\r\n\r\nFWIW, I don't really have much fight in me on this one. I'm happy to acquiesce and implement whatever.\r\n\r\n[1]: https://www.python.org/dev/peps/pep-0020/"}}