René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"\u003cnoun\u003e() vs get_\u003cnoun\u003e() vs \u003cverb\u003e_\u003cnoun\u003e()","articleBody":"Moved over from #910 per @dhermes \n\nGoal of this issue is to decide:\n1. Is it reasonable to provide one-liners to do things like `create_topic()` which is just a wrapper:\n   `python\n   def create_topic(self, name):\n   topic = self.topic(name)\n   topic.create()\n   return topic\n   `\n2. Can we agree on the naming convention of what does and does not require an API request\n\n---\n\nComment from the pull request was...\n\n\u003e The name create_topic is ambiguous to new users. Does it mean create a Topic instance or actual insert one?\n\nThat's a good point. I think we should adopt the attitude that `client.\u003cverb\u003e_\u003cnoun\u003e()` is an API request. So `create_topic` would hit the API trying to 'insert' the topic (using Google's API lingo). `client.\u003cnoun\u003e` is nothing more than a factory for the noun which won't fire an API request but gives you back an instance of the \u003cnoun\u003e.\n\n\u003e 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.\n\nTotally 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).\n\nFor other APIs, where the object itself holds lots of (potentially important) metadata, I think it might be worthwhile to provide a `get_\u003cnoun\u003e()` to pull down that metadata, in addition to the `\u003cnoun\u003e()` method which just gives you an object which may not be tied to the remote (authoritative) representation.\n\nAn example here might be `bucket`.\n- `.bucket()` gives me a bucket object, sans remote data (no API request).\n- `create_bucket()` explicitly creates the bucket in the remote service, throwing an error if I was unable to do so.\n- `get_bucket()` would be an API request that gives me all the metadata about a bucket.\n\nNote that the `\u003cverb\u003e_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;`)\n\nIn boto for S3, they have this `verify` or `check` parameter on the bucket constructor, so the comparisons look like:\n\n| Action | boto | gcloud (suggestion) |\n| --- | --- | --- |\n| Get a bucket, no API request | `connection.get_bucket(validate=False)` | `client.bucket()` |\n| Get a bucket + metadata | `connection.get_bucket()` | `client.get_bucket()` |\n\nI personally don't love the boto method, and would much rather the \"gcloud (suggestion)\" option.\n","author":{"url":"https://github.com/jgeewax","@type":"Person","name":"jgeewax"},"datePublished":"2015-06-06T16:57:35.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":20},"url":"https://github.com/911/google-cloud-python/issues/911"}