googleapis · dhermes · Mar 13, 2015 · Mar 12, 2015 · Mar 12, 2015 · Mar 12, 2015
diff --git a/README.rst b/README.rst
@@ -99,7 +99,8 @@ to Cloud Storage using this Client Library.
 .. code:: python
 
     from gcloud import storage
-    bucket = storage.get_bucket('bucket-id-here', 'project-id')
+    storage.set_defaults()
+    bucket = storage.get_bucket('bucket-id-here')
     # Then do other things...
     blob = bucket.get_blob('/remote/path/to/file.txt')
     print blob.download_as_string()

diff --git a/docs/_components/storage-getting-started.rst b/docs/_components/storage-getting-started.rst
@@ -56,7 +56,7 @@ bucket.
 
 Let's create a bucket:
 
-  >>> bucket = connection.create_bucket('test')
+  >>> bucket = storage.create_bucket('test', connection=connection)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "gcloud/storage/connection.py", line 340, in create_bucket
@@ -151,11 +151,11 @@ in Python::
 Accessing a bucket
 ------------------
 
-If you already have a bucket, use :func:`get_bucket
-<gcloud.storage.connection.Connection.get_bucket>` to retrieve the bucket
-object::
+If you already have a bucket, use
+:func:`get_bucket <gcloud.storage.api.get_bucket>` to retrieve the
+bucket object::
 
-  >>> bucket = connection.get_bucket('my-bucket')
+  >>> bucket = storage.get_bucket('my-bucket', connection=connection)
 
 If you want to get all the blobs in the bucket, you can use
 :func:`get_all_blobs <gcloud.storage.bucket.Bucket.get_all_blobs>`::
@@ -171,17 +171,17 @@ bucket itself as an iterator::
 Deleting a bucket
 -----------------
 
-You can delete a bucket using the :func:`delete_bucket
-<gcloud.storage.connection.Connection.delete_bucket>` method::
+You can delete a bucket using the
+:meth:`delete <gcloud.storage.bucket.Bucket.delete>` method::
 
-  >>> connection.delete_bucket('my-bucket')
+  >>> bucket.delete()
 
 Remember, the bucket you're deleting needs to be empty, otherwise you'll
-get an error.
+get an error (409 conflict).
 
 If you have a full bucket, you can delete it this way::
 
-  >>> bucket = connection.delete_bucket('my-bucket', force=True)
+  >>> bucket.delete(force=True)
 
 Listing available buckets
 -------------------------

diff --git a/docs/_components/storage-quickstart.rst b/docs/_components/storage-quickstart.rst
@@ -58,7 +58,7 @@ you can create buckets and blobs::
   >>> from gcloud import storage
   >>> storage.get_all_buckets(connection)
   [<Bucket: ...>, ...]
-  >>> bucket = connection.create_bucket('my-new-bucket')
+  >>> bucket = storage.create_bucket('my-new-bucket', connection=connection)
   >>> print bucket
   <Bucket: my-new-bucket>
   >>> blob = bucket.new_blob('my-test-file.txt')

diff --git a/docs/index.rst b/docs/index.rst
@@ -47,6 +47,7 @@ Cloud Storage
 .. code-block:: python
 
   from gcloud import storage
-  bucket = storage.get_bucket('<your-bucket-name>', '<your-project-id>')
+  storage.set_defaults()
+  bucket = storage.get_bucket('<your-bucket-name>')
   blob = bucket.new_blob('my-test-file.txt')
   blob = blob.upload_contents_from_string('this is test content!')
diff --git a/gcloud/storage/__init__.py b/gcloud/storage/__init__.py
@@ -16,8 +16,9 @@
 
 You'll typically use these to get started with the API:
 
->>> import gcloud.storage
->>> bucket = gcloud.storage.get_bucket('bucket-id-here', 'project-id')
+>>> from gcloud import storage
+>>> storage.set_defaults()
+>>> bucket = storage.get_bucket('bucket-id-here')
 >>> # Then do other things...
 >>> blob = bucket.get_blob('/remote/path/to/file.txt')
 >>> print blob.download_as_string()
@@ -44,7 +45,9 @@
 from gcloud.storage._implicit_environ import get_default_bucket
 from gcloud.storage._implicit_environ import get_default_connection
 from gcloud.storage._implicit_environ import get_default_project
+from gcloud.storage.api import create_bucket
 from gcloud.storage.api import get_all_buckets
+from gcloud.storage.api import get_bucket
 from gcloud.storage.api import lookup_bucket
 from gcloud.storage.blob import Blob
 from gcloud.storage.bucket import Bucket
@@ -148,8 +151,8 @@ def get_connection(project=None):
 
     >>> from gcloud import storage
     >>> connection = storage.get_connection(project)
-    >>> bucket1 = connection.get_bucket('bucket1')
-    >>> bucket2 = connection.get_bucket('bucket2')
+    >>> bucket1 = storage.get_bucket('bucket1', connection=connection)
+    >>> bucket2 = storage.get_bucket('bucket2', connection=connection)
 
     :type project: string or ``NoneType``
     :param project: Optional. The name of the project to connect to. If not
@@ -163,28 +166,3 @@ def get_connection(project=None):
     implicit_credentials = credentials.get_credentials()
     scoped_credentials = implicit_credentials.create_scoped(SCOPE)
     return Connection(project=project, credentials=scoped_credentials)
-
-
-def get_bucket(bucket_name, project):
-    """Shortcut method to establish a connection to a particular bucket.
-
-    You'll generally use this as the first call to working with the API:
-
-    >>> from gcloud import storage
-    >>> bucket = storage.get_bucket(project, bucket_name)
-    >>> # Now you can do things with the bucket.
-    >>> bucket.exists('/path/to/file.txt')
-    False
-
-    :type bucket_name: string
-    :param bucket_name: The id of the bucket you want to use.
-                      This is akin to a disk name on a file system.
-
-    :type project: string
-    :param project: The name of the project to connect to.
-
-    :rtype: :class:`gcloud.storage.bucket.Bucket`
-    :returns: A bucket with a connection using the provided credentials.
-    """
-    connection = get_connection(project)
-    return connection.get_bucket(bucket_name)
diff --git a/gcloud/storage/acl.py b/gcloud/storage/acl.py
@@ -20,7 +20,7 @@
 
   >>> from gcloud import storage
   >>> connection = storage.get_connection(project)
-  >>> bucket = connection.get_bucket(bucket_name)
+  >>> bucket = storage.get_bucket(bucket_name, connection=connection)
   >>> acl = bucket.acl
 
 Adding and removing permissions can be done with the following methods
@@ -427,8 +427,8 @@ def save(self, acl=None):
         You can use this to set access controls to be consistent from
         one bucket to another::
 
-          >>> bucket1 = connection.get_bucket(bucket1_name)
-          >>> bucket2 = connection.get_bucket(bucket2_name)
+          >>> bucket1 = storage.get_bucket(bucket1_name, connection=connection)
+          >>> bucket2 = storage.get_bucket(bucket2_name, connection=connection)
           >>> bucket2.acl.save(bucket1.acl)
 
         :type acl: :class:`gcloud.storage.acl.ACL`, or a compatible list.

diff --git a/gcloud/storage/api.py b/gcloud/storage/api.py
@@ -54,7 +54,7 @@ def lookup_bucket(bucket_name, connection=None):
         connection = get_default_connection()
 
     try:
-        return connection.get_bucket(bucket_name)
+        return get_bucket(bucket_name, connection=connection)
     except NotFound:
         return None
 
@@ -84,6 +84,77 @@ def get_all_buckets(connection=None):
     return iter(_BucketIterator(connection=connection))
 
 
+def get_bucket(bucket_name, connection=None):
+    """Get a bucket by name.
+
+    If the bucket isn't found, this will raise a
+    :class:`gcloud.storage.exceptions.NotFound`.
+
+    For example::
+
+      >>> from gcloud import storage
+      >>> from gcloud.exceptions import NotFound
+      >>> try:
+      >>>   bucket = storage.get_bucket('my-bucket')
+      >>> except NotFound:
+      >>>   print 'Sorry, that bucket does not exist!'
+
+    This implements "storage.buckets.get".
+
+    :type bucket_name: string
+    :param bucket_name: The name of the bucket to get.
+
+    :type connection: :class:`gcloud.storage.connection.Connection` or
+                      ``NoneType``
+    :param connection: Optional. The connection to use when sending requests.
+                       If not provided, falls back to default.
+
+    :rtype: :class:`gcloud.storage.bucket.Bucket`
+    :returns: The bucket matching the name provided.
+    :raises: :class:`gcloud.exceptions.NotFound`
+    """
+    if connection is None:
+        connection = get_default_connection()
+
+    bucket_path = Bucket.path_helper(bucket_name)
+    response = connection.api_request(method='GET', path=bucket_path)
+    return Bucket(properties=response, connection=connection)
+
+
+def create_bucket(bucket_name, connection=None):
+    """Create a new bucket.
+
+    For example::
+
+      >>> from gcloud import storage
+      >>> storage.set_defaults()
+      >>> bucket = storage.create_bucket('my-bucket')
+      >>> print bucket
+      <Bucket: my-bucket>
+
+    This implements "storage.buckets.insert".
+
+    :type bucket_name: string
+    :param bucket_name: The bucket name to create.
+
+    :type connection: :class:`gcloud.storage.connection.Connection` or
+                      ``NoneType``
+    :param connection: Optional. The connection to use when sending requests.
+                       If not provided, falls back to default.
+
+    :rtype: :class:`gcloud.storage.bucket.Bucket`
+    :returns: The newly created bucket.
+    :raises: :class:`gcloud.exceptions.Conflict` if
+             there is a confict (bucket already exists, invalid name, etc.)
+    """
+    if connection is None:
+        connection = get_default_connection()
+
+    response = connection.api_request(method='POST', path='/b',
+                                      data={'name': bucket_name})
+    return Bucket(properties=response, connection=connection)
+
+
 class _BucketIterator(Iterator):
     """An iterator listing all buckets.
 

diff --git a/gcloud/storage/bucket.py b/gcloud/storage/bucket.py
@@ -191,7 +191,7 @@ def get_blob(self, blob):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> print bucket.get_blob('/path/to/blob.txt')
           <Blob: my-bucket, /path/to/blob.txt>
           >>> print bucket.get_blob('/does-not-exist.txt')
@@ -322,7 +322,7 @@ def delete(self, force=False):
             # Ignore 404 errors on delete.
             self.delete_blobs(blobs, on_error=lambda blob: None)
 
-        self.connection.delete_bucket(self.name)
+        self.connection.api_request(method='DELETE', path=self.path)
 
     def delete_blob(self, blob):
         """Deletes a blob from the current bucket.
@@ -335,7 +335,7 @@ def delete_blob(self, blob):
           >>> from gcloud.exceptions import NotFound
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> print bucket.get_all_blobs()
           [<Blob: my-bucket, my-file.txt>]
           >>> bucket.delete_blob('my-file.txt')
@@ -417,7 +417,7 @@ def upload_file(self, filename, blob=None):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> bucket.upload_file('~/my-file.txt', 'remote-text-file.txt')
           >>> print bucket.get_all_blobs()
           [<Blob: my-bucket, remote-text-file.txt>]
@@ -428,7 +428,7 @@ def upload_file(self, filename, blob=None):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> bucket.upload_file('~/my-file.txt')
           >>> print bucket.get_all_blobs()
           [<Blob: my-bucket, my-file.txt>]
@@ -460,7 +460,7 @@ def upload_file_object(self, file_obj, blob=None):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> bucket.upload_file(open('~/my-file.txt'), 'remote-text-file.txt')
           >>> print bucket.get_all_blobs()
           [<Blob: my-bucket, remote-text-file.txt>]
@@ -471,7 +471,7 @@ def upload_file_object(self, file_obj, blob=None):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket('my-bucket')
+          >>> bucket = storage.get_bucket('my-bucket', connection=connection)
           >>> bucket.upload_file(open('~/my-file.txt'))
           >>> print bucket.get_all_blobs()
           [<Blob: my-bucket, my-file.txt>]
@@ -725,7 +725,7 @@ def configure_website(self, main_page_suffix=None, not_found_page=None):
 
           >>> from gcloud import storage
           >>> connection = storage.get_connection(project)
-          >>> bucket = connection.get_bucket(bucket_name)
+          >>> bucket = storage.get_bucket(bucket_name, connection=connection)
           >>> bucket.configure_website('index.html', '404.html')
 
         You probably should also make the whole bucket public::