Repository: googleapis/google-cloud-python

Issue:
Make sure storage.bucket.Bucket.delete raises proper exceptions on failure
From TODO:

``` python
    # TODO: Make sure the proper exceptions are raised.
```

See [`storage.bucket.Bucket.delete`](https://github.com/GoogleCloudPlatform/gcloud-python/blob/1f2aaf3606802f4f02eeb30e22e1082ef7f4594e/gcloud/storage/bucket.py#L153) for relevant code and #146 for some context.

`git blame` output

```
b7f1b774 (JJ Geewax   2014-01-29 18:02:29 -0500 153)     # TODO: Make sure the proper exceptions are raised.
```

Make sure storage.bucket.Bucket.delete raises proper exceptions on failure
From TODO:

``` python
    # TODO: Make sure the proper exceptions are raised.
```

See [`storage.bucket.Bucket.delete`](https://github.com/GoogleCloudPlatform/gcloud-python/blob/1f2aaf3606802f4f02eeb30e22e1082ef7f4594e/gcloud/storage/bucket.py#L153) for relevant code and #146 for some context.

`git blame` output

```
b7f1b774 (JJ Geewax   2014-01-29 18:02:29 -0500 153)     # TODO: Make sure the proper exceptions are raised.
```



Discussion:
We should be able to rely on `Connection.delete_bucket` to raise appropriate exceptions here.

Question on the docs: should we document raised exceptions only in the function where they are actually raised? In this case, the documented exception is raised in `Connection.api_request`, 2 levels down.

Documenting exactly possible exceptions is hard to do thoroughly, because the back-end API docs don't specify which HTTP error response codes can be returned for each endpoint.  Of course, at the moment, we only raise either `exceptions.NotFoundError` (for 404) or `exceptions.ConnectionError` (for any other non-2xx code), but then again, #164 promises to make that much more elaborate.

It's not common (or really even possible) to list all exceptions raised within a method / function other than those explicitly `raise`d. For example, a strange system failure could always produce a `SystemError` or `OSError` in ANY function.

Ok, so we all agree :) Docs need some fixing then.

We should be able to rely on `Connection.delete_bucket` to raise appropriate exceptions here.

Question on the docs: should we document raised exceptions only in the function where they are actually raised? In this case, the documented exception is raised in `Connection.api_request`, 2 levels down.

Documenting exactly possible exceptions is hard to do thoroughly, because the back-end API docs don't specify which HTTP error response codes can be returned for each endpoint.  Of course, at the moment, we only raise either `exceptions.NotFoundError` (for 404) or `exceptions.ConnectionError` (for any other non-2xx code), but then again, #164 promises to make that much more elaborate.

It's not common (or really even possible) to list all exceptions raised within a method / function other than those explicitly `raise`d. For example, a strange system failure could always produce a `SystemError` or `OSError` in ANY function.

Ok, so we all agree :) Docs need some fixing then.


Resolving patch:
diff --git a/gcloud/storage/bucket.py b/gcloud/storage/bucket.py
--- a/gcloud/storage/bucket.py
+++ b/gcloud/storage/bucket.py
@@ -144,7 +144,10 @@ def delete(self, force=False):
         :type force: bool
         :param full: If True, empties the bucket's objects then deletes it.
 
-        :raises: :class:`gcloud.storage.exceptions.NotFoundError`
+        :raises: :class:`gcloud.storage.exceptions.NotFoundError` if the
+                 bucket does not exist, or
+                 :class:`gcloud.storage.exceptions.ConnectionError` if the
+                 bucket has keys and `force` is not passed.
         """
         return self.connection.delete_bucket(self.name, force=force)
 
diff --git a/gcloud/storage/connection.py b/gcloud/storage/connection.py
--- a/gcloud/storage/connection.py
+++ b/gcloud/storage/connection.py
@@ -378,7 +378,10 @@ def delete_bucket(self, bucket, force=False):
 
         :rtype: bool
         :returns: True if the bucket was deleted.
-        :raises: :class:`gcloud.storage.exceptions.NotFoundError`
+        :raises: :class:`gcloud.storage.exceptions.NotFoundError` if the
+                 bucket doesn't exist, or
+                 :class:`gcloud.storage.exceptions.ConnectionError` if the
+                 bucket has keys and `force` is not passed.
         """
         bucket = self.new_bucket(bucket)
 


Test patch: