STORAGE: Making Connection.get_bucket a standalone method.

Follows on googleapis#716.

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()

docs/_components/storage-getting-started.rst

@@ -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>`::

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!')

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()
@@ -45,6 +46,7 @@
 from gcloud.storage._implicit_environ import get_default_connection
 from gcloud.storage._implicit_environ import get_default_project
 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 +150,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 +165,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)

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.

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,43 @@ 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)
+
+
 class _BucketIterator(Iterator):
     """An iterator listing all buckets.
 

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')
@@ -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::

gcloud/storage/connection.py

@@ -52,10 +52,6 @@ class Connection(base_connection.Connection):
       >>> bucket.delete()
       >>> # or
       >>> connection.delete_bucket(bucket.name)
-
-    If you want to access an existing bucket::
-
-      >>> bucket = connection.get_bucket('my-bucket-name')
     """
 
     API_BASE_URL = base_connection.API_BASE_URL
@@ -260,35 +256,6 @@ def api_request(self, method, path, query_params=None,
 
         return content
 
-    def get_bucket(self, bucket_name):
-        """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
-          >>> connection = storage.get_connection(project)
-          >>> try:
-          >>>   bucket = connection.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.
-
-        :rtype: :class:`gcloud.storage.bucket.Bucket`
-        :returns: The bucket matching the name provided.
-        :raises: :class:`gcloud.exceptions.NotFound`
-        """
-        bucket = Bucket(connection=self, name=bucket_name)
-        response = self.api_request(method='GET', path=bucket.path)
-        return Bucket(properties=response, connection=self)
-
     def create_bucket(self, bucket_name):
         """Create a new bucket.
 

gcloud/storage/test___init__.py

@@ -54,41 +54,6 @@ def test_default_project(self):
         self.assertTrue(client._get_app_default_called)
 
 
-class Test_get_bucket(unittest2.TestCase):
-
-    def _callFUT(self, *args, **kw):
-        from gcloud.storage import get_bucket
-        return get_bucket(*args, **kw)
-
-    def test_it(self):
-        from gcloud import storage
-        from gcloud._testing import _Monkey
-
-        bucket = object()
-
-        class _Connection(object):
-
-            def get_bucket(self, bucket_name):
-                self._called_with = bucket_name
-                return bucket
-
-        connection = _Connection()
-        _called_with = []
-
-        def get_connection(*args, **kw):
-            _called_with.append((args, kw))
-            return connection
-
-        BUCKET = 'bucket'
-        PROJECT = 'project'
-        with _Monkey(storage, get_connection=get_connection):
-            found = self._callFUT(BUCKET, PROJECT)
-
-        self.assertTrue(found is bucket)
-        self.assertEqual(_called_with, [((PROJECT,), {})])
-        self.assertEqual(connection._called_with, BUCKET)
-
-
 class Test_set_default_bucket(unittest2.TestCase):
 
     def setUp(self):