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`
"""
connection = _require_connection(connection)
bucket = Bucket(bucket_name, connection=connection)
bucket.reload(connection=connection)
return bucket
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::
>>> try:
>>> bucket = client.get_bucket('my-bucket')
>>> except gcloud.exceptions.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(self, name=bucket_name)
bucket.reload(client=self)
return bucket
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(bucket_name, project=None, 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".
If the bucket already exists, will raise
:class:`gcloud.exceptions.Conflict`.
:type project: string
:param project: Optional. The project to use when creating bucket.
If not provided, falls back to default.
: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.
"""
connection = _require_connection(connection)
bucket = Bucket(bucket_name, connection=connection)
bucket.create(project)
return bucket
def create_bucket(bucket_name, project=None, connection=None):
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> bucket = storage.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
This implements "storage.buckets.insert".
If the bucket already exists, will raise
:class:`gcloud.exceptions.Conflict`.
:type project: string
:param project: Optional. The project to use when creating bucket.
If not provided, falls back to default.
: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.
"""
connection = _require_connection(connection)
bucket = Bucket(bucket_name, connection=connection)
bucket.create(project, connection=connection)
return bucket
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::
>>> try:
>>> bucket = client.get_bucket('my-bucket')
>>> except gcloud.exceptions.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(self, name=bucket_name)
bucket.reload(client=self)
return bucket
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`
"""
connection = _require_connection(connection)
bucket = Bucket(bucket_name, connection=connection)
bucket.reload()
return bucket
def _makeOne(self, client=None, name=None, properties=None):
from gcloud.storage.bucket import Bucket
if client is None:
connection = _Connection()
client = _Client(connection)
bucket = Bucket(client, name=name)
bucket._properties = properties or {}
return bucket
def _makeOne(self, client=None, name=None, properties=None):
from gcloud.storage.bucket import Bucket
if client is None:
connection = _Connection()
client = _Client(connection)
bucket = Bucket(client, name=name)
bucket._properties = properties or {}
return bucket
def get_items_from_response(self, response):
"""Factory method which yields :class:`.Bucket` items from a response.
:type response: dict
:param response: The JSON API response for a page of buckets.
"""
for item in response.get('items', []):
name = item.get('name')
bucket = Bucket(self.client, name)
bucket._set_properties(item)
yield bucket
def get_items_from_response(self, response):
"""Factory method which yields :class:`.Bucket` items from a response.
:type response: dict
:param response: The JSON API response for a page of buckets.
"""
for item in response.get('items', []):
name = item.get('name')
bucket = Bucket(name, connection=self.connection)
bucket._properties = item
yield bucket
def get_bucket(self, bucket_name, *args, **kwargs):
"""Get a bucket by name.
If the bucket isn't found,
this will raise a :class:`gcloud.storage.exceptions.NotFoundError`.
If you would rather get a bucket by name,
and return ``None`` if the bucket isn't found
(like ``{}.get('...')``)
then use :func:`Connection.lookup`.
For example::
>>> from gcloud import storage
>>> from gcloud.storage import exceptions
>>> connection = storage.get_connection(project, email, key_path)
>>> try:
>>> bucket = connection.get_bucket('my-bucket')
>>> except exceptions.NotFoundError:
>>> print 'Sorry, that bucket does not exist!'
: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.storage.exceptions.NotFoundError`
"""
# TODO: URL-encode the bucket name to be safe?
bucket = self.new_bucket(bucket_name)
response = self.api_request(method='GET', path=bucket.path)
return Bucket.from_dict(response, connection=self)
def create_bucket(self, bucket_name):
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> connection = storage.get_connection(project)
>>> bucket = connection.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.
: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.)
"""
response = self.api_request(method='POST',
path='/b',
data={'name': bucket_name})
return Bucket(properties=response, connection=self)
def new_bucket(self, bucket):
"""Factory method for creating a new (unsaved) bucket object.
This method is really useful when you're not sure whether
you have an actual :class:`gcloud.storage.bucket.Bucket` object
or just a name of a bucket.
It always returns the object::
>>> bucket = connection.new_bucket('bucket')
>>> print bucket
<Bucket: bucket>
>>> bucket = connection.new_bucket(bucket)
>>> print bucket
<Bucket: bucket>
:type bucket: string or :class:`gcloud.storage.bucket.Bucket`
:param bucket: A name of a bucket or an existing Bucket object.
"""
if isinstance(bucket, Bucket):
return bucket
# Support Python 2 and 3.
try:
string_type = basestring
except NameError:
string_type = str
if isinstance(bucket, string_type):
return Bucket(connection=self, name=bucket)
raise TypeError('Invalid bucket: %s' % bucket)
def delete_bucket(self, bucket_name):
"""Delete a bucket.
You can use this method to delete a bucket by name.
>>> from gcloud import storage
>>> connection = storage.get_connection(project)
>>> connection.delete_bucket('my-bucket')
If the bucket doesn't exist, this will raise a
:class:`gcloud.exceptions.NotFound`::
>>> from gcloud.exceptions import NotFound
>>> try:
>>> connection.delete_bucket('my-bucket')
>>> except NotFound:
>>> print 'That bucket does not exist!'
If the bucket still has objects in it, this will raise a
:class:`gcloud.exceptions.Conflict`::
>>> from gcloud.exceptions import Conflict
>>> try:
>>> connection.delete_bucket('my-bucket')
>>> except Conflict:
>>> print 'That bucket is not empty!'
This implements "storage.buckets.delete".
:type bucket_name: string
:param bucket_name: The bucket name to delete.
"""
bucket_path = Bucket.path_helper(bucket_name)
self.api_request(method='DELETE', path=bucket_path)
def delete_bucket(self, bucket_name):
"""Delete a bucket.
You can use this method to delete a bucket by name.
>>> from gcloud import storage
>>> connection = storage.get_connection(project)
>>> connection.delete_bucket('my-bucket')
If the bucket doesn't exist, this will raise a
:class:`gcloud.exceptions.NotFound`::
>>> from gcloud.exceptions import NotFound
>>> try:
>>> connection.delete_bucket('my-bucket')
>>> except NotFound:
>>> print 'That bucket does not exist!'
If the bucket still has objects in it, this will raise a
:class:`gcloud.exceptions.Conflict`::
>>> from gcloud.exceptions import Conflict
>>> try:
>>> connection.delete_bucket('my-bucket')
>>> except Conflict:
>>> print 'That bucket is not empty!'
This implements "storage.buckets.delete".
:type bucket_name: string
:param bucket_name: The bucket name to delete.
"""
bucket_path = Bucket.path_helper(bucket_name)
self.api_request(method='DELETE', path=bucket_path)
def test_new_bucket_w_existing(self):
from gcloud.storage.bucket import Bucket
PROJECT = 'project'
KEY = 'key'
conn = self._makeOne(PROJECT)
existing = Bucket(self, KEY)
self.assertTrue(conn.new_bucket(existing) is existing)
def get_items_from_response(self, response):
"""Factory method which yields :class:`.Bucket` items from a response.
:type response: dict
:param response: The JSON API response for a page of buckets.
"""
for item in response.get('items', []):
yield Bucket.from_dict(item, connection=self.connection)
def get_items_from_response(self, response):
"""Factory method which yields :class:`.Bucket` items from a response.
:type response: dict
:param response: The JSON API response for a page of buckets.
"""
for item in response.get('items', []):
yield Bucket.from_dict(item, connection=self.connection)
def test_rename(self):
bucket = Bucket(self.connection, 'bucket')
key = Key(bucket, 'key')
orig_key_path = key.path
key.rename('new-name')
expected = [[
'POST', orig_key_path + '/copyTo/b/bucket/o/new-name', None
], ['DELETE', orig_key_path, None]]
self.assertEqual(key.name, 'new-name')
self.assertEqual(self.api_request_calls, expected)
def bucket(self, bucket_name):
"""Factory constructor for bucket object.
.. note::
This will not make an HTTP request; it simply instantiates
a bucket object owned by this client.
:type bucket_name: string
:param bucket_name: The name of the bucket to be instantiated.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The bucket object created.
"""
return Bucket(client=self, name=bucket_name)
def create_bucket(self, bucket_name):
"""Create a new bucket.
For example::
>>> bucket = client.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
This implements "storage.buckets.insert".
If the bucket already exists, will raise
:class:`gcloud.exceptions.Conflict`.
:type bucket_name: string
:param bucket_name: The bucket name to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
"""
bucket = Bucket(self, name=bucket_name)
bucket.create(client=self)
return bucket
def create_bucket(self, bucket_name):
"""Create a new bucket.
For example::
>>> bucket = client.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
This implements "storage.buckets.insert".
If the bucket already exists, will raise
:class:`gcloud.exceptions.Conflict`.
:type bucket_name: string
:param bucket_name: The bucket name to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
"""
bucket = Bucket(self, name=bucket_name)
bucket.create(client=self)
return bucket
def create_bucket(self, bucket, *args, **kwargs):
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> connection = storage.get_connection(project, client, key_path)
>>> bucket = connection.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
:type bucket: string or :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket name (or bucket object) to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
"""
bucket = self.new_bucket(bucket)
response = self.api_request(method='POST', path='/b',
data={'name': bucket.name})
return Bucket.from_dict(response, connection=self)
def create_bucket(self, bucket):
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> connection = storage.get_connection(project, client, key_path)
>>> bucket = connection.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
:type bucket: string or :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket name (or bucket object) to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
:raises: :class:`gcloud.storage.exceptions.Conflict` if
there is a confict (bucket already exists, invalid name, etc.)
"""
bucket = self.new_bucket(bucket)
response = self.api_request(method='POST', path='/b',
data={'name': bucket.name})
return Bucket.from_dict(response, connection=self)
def create_bucket(self, bucket, *args, **kwargs):
# TODO: Which exceptions will this raise?
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> connection = storage.get_connection(project, client, key_path)
>>> bucket = connection.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
:type bucket: string or :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket name (or bucket object) to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
"""
bucket = self.new_bucket(bucket)
response = self.api_request(method='POST', path='/b',
data={'name': bucket.name})
return Bucket.from_dict(response, connection=self)
def create_bucket(self, bucket):
"""Create a new bucket.
For example::
>>> from gcloud import storage
>>> connection = storage.get_connection(project)
>>> bucket = connection.create_bucket('my-bucket')
>>> print bucket
<Bucket: my-bucket>
:type bucket: string or :class:`gcloud.storage.bucket.Bucket`
:param bucket: The bucket name (or bucket object) to create.
:rtype: :class:`gcloud.storage.bucket.Bucket`
:returns: The newly created bucket.
:raises: :class:`gcloud.storage.exceptions.Conflict` if
there is a confict (bucket already exists, invalid name, etc.)
"""
bucket = self.new_bucket(bucket)
response = self.api_request(method='POST', path='/b',
data={'name': bucket.name})
return Bucket.from_dict(response, connection=self)
def set_default_bucket(bucket=None):
"""Set default bucket either explicitly or implicitly as fall-back.
In implicit case, currently only supports enviroment variable but will
support App Engine, Compute Engine and other environments in the future.
In the implicit case, relies on an implicit connection in addition to the
implicit bucket name.
Local environment variable used is:
- GCLOUD_BUCKET_NAME
:type bucket: :class:`gcloud.storage.bucket.Bucket`
:param bucket: Optional. The bucket to use as default.
"""
if bucket is None:
bucket_name = os.getenv(_BUCKET_ENV_VAR_NAME)
connection = get_default_connection()
if bucket_name is not None and connection is not None:
bucket = Bucket(bucket_name, connection=connection)
if bucket is not None:
_implicit_environ._DEFAULTS.bucket = bucket
def _makeOne(self, *args, **kw):
from gcloud.storage.bucket import Bucket
properties = kw.pop('properties', None)
bucket = Bucket(*args, **kw)
bucket._properties = properties or {}
return bucket
def _makeOne(self, *args, **kw):
from gcloud.storage.bucket import Bucket
return Bucket(*args, **kw)
def _makeOne(self, *args, **kw):
from gcloud.storage.bucket import Bucket
properties = kw.pop('properties', None)
bucket = Bucket(*args, **kw)
bucket._properties = properties or {}
return bucket