René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"PROPOSAL: Storage API consistency fix","articleBody":"Guiding principles:\n-   [x] Getters and setters should **never** make HTTP requests. Lazy loading is OK,\n  but only when it involves instance creation / other local (non-network bound) behavior. For [example](https://github.com/GoogleCloudPlatform/gcloud-python/blob/f73ad7e8fc877e14e2f9c0b4ec42430f2396f770/gcloud/storage/bucket.py#L139-L144), in `Bucket.acl` this already happens:\n  \n  ``` python\n  @property\n  def acl(self):\n      \"\"\"Create our ACL on demand.\"\"\"\n      if self._acl is None:\n          self._acl = BucketACL(self)\n      return self._acl\n  ```\n-   [ ] More generally HTTP requests should be limited to explicit method calls. This also rules out constructors loading data.\n-   [ ] `Blob`, `Bucket`, and `*ACL` (the only nouns) instances should have `load()`, `exists()`, `create()`, `delete()`, and `update()` methods. This design gives rise to code like\n  \n  ``` python\n  blob = Blob('/remote/path.txt', bucket=bucket, properties=properties)\n  try:\n      blob.load()  # Just metadata\n  except NotFound:\n      blob.upload_from_file(filename)  # Sends metadata from properties\n  ```\n  \n  (this maybe screams for `get_or_create()`, we'll feel it out as we develop). It's unclear if it's worth making a distinction between `storage.NOUN.update \u003c--\u003e PUT` and `storage.NOUN.patch \u003c--\u003e PATCH`. (As of right now, we don't implement `PUT` / `update` anywhere.)\n-   [x] `exists()` should use `fields` in the requests to minimize the payload.\n-   [ ] A `Connection` should not be required to be bound to any object (one of the nouns `Bucket`, `ACL`, or `Blob`) but should be an optional argument to methods which actually talk to the API.\n-   [ ] We should **strongly** consider adding a `last_updated` field to classes to indicate the last time the values were updated (from the server).\n-   [ ] For list methods: List all buckets top-level, e.g.\n  \n  ``` python\n  storage.get_all_buckets(connection=optional_connection)\n  ```\n  \n  and then `bucket.get_all_objects()`. It's unclear how the other 3 nouns (`objectAccessControls`, `bucketAccessControls` and `defaultObjectAccessControls`) will handle this. Right now they are handled via `ObjectACL.reload()` and `BucketACL.reload()` (a superclass of `DefaultObjectACL`).\n-   [x] Implicit behavior (default project, default bucket and/or default connection) should be used wherever possible (and documented)\n\n@tseaver Please weigh in. This was inspired by our [discussion](https://github.com/GoogleCloudPlatform/gcloud-python/pull/604#issuecomment-73929760) at the end of #604.\n\n/cc @thobrla I'd like to close #545 and focus on this (possibly broken down into sub-bugs). Does that sound OK?\n","author":{"url":"https://github.com/dhermes","@type":"Person","name":"dhermes"},"datePublished":"2015-02-13T07:57:26.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":11},"url":"https://github.com/632/google-cloud-python/issues/632"}