Python

0.4.0

ACL#

Manipulate access control lists that Cloud Storage provides.

gcloud.storage.bucket.Bucket has a getting method that creates an ACL object under the hood, and you can interact with that using gcloud.storage.bucket.Bucket.acl():

>>> from gcloud import storage
>>> connection = storage.get_connection(project)
>>> bucket = connection.get_bucket(bucket_name)
>>> acl = bucket.acl

Adding and removing permissions can be done with the following methods (in increasing order of granularity):

ACL.all() corresponds to access for all users.
ACL.all_authenticated() corresponds to access for all users that are signed into a Google account.
ACL.domain() corresponds to access on a per Google Apps domain (ie, example.com).
ACL.group() corresponds to access on a per group basis (either by ID or e-mail address).
ACL.user() corresponds to access on a per user basis (either by ID or e-mail address).

And you are able to grant and revoke the following roles:

Reading: _ACLEntity.grant_read() and _ACLEntity.revoke_read()
Writing: _ACLEntity.grant_write() and _ACLEntity.revoke_write()
Owning: _ACLEntity.grant_owner() and _ACLEntity.revoke_owner()

You can use any of these like any other factory method (these happen to be _ACLEntity factories):

>>> acl.user('me@example.org').grant_read()
>>> acl.all_authenticated().grant_write()

You can also chain these grant_* and revoke_* methods together for brevity:

>>> acl.all().grant_read().revoke_write()

After that, you can save any changes you make with the gcloud.storage.acl.ACL.save() method:

>>> acl.save()

You can alternatively save any existing gcloud.storage.acl.ACL object (whether it was created by a factory method or not) from a gcloud.storage.bucket.Bucket:

>>> bucket.acl.save(acl=acl)

To get the list of entity and role for each unique pair, the ACL class is iterable:

>>> print list(ACL)
[{'role': 'OWNER', 'entity': 'allUsers'}, ...]

This list of tuples can be used as the entity and role fields when sending metadata for ACLs to the API.

class gcloud.storage.acl.ACL[source]#

Bases: object

Container class representing a list of access controls.

add_entity(entity)[source]#

Add an entity to the ACL.

Parameters:	entity (`_ACLEntity`) – The entity to add to this ACL.

all()[source]#

Factory method for an Entity representing all users.

Return type:	`_ACLEntity`
Returns:	An entity representing all users.

all_authenticated()[source]#

Factory method for an Entity representing all authenticated users.

Return type:	`_ACLEntity`
Returns:	An entity representing all authenticated users.

clear()[source]#: Remove all entities from the ACL.

domain(domain)[source]#

Factory method for a domain Entity.

Parameters:	domain (string) – The domain for this entity.
Return type:	`_ACLEntity`
Returns:	An entity corresponding to this domain.

entity(entity_type, identifier=None)[source]#

Factory method for creating an Entity.

If an entity with the same type and identifier already exists, this will return a reference to that entity. If not, it will create a new one and add it to the list of known entities for this ACL.

Parameters:	entity_type (string) – The type of entity to create (ie, `user`, `group`, etc) identifier (string) – The ID of the entity (if applicable). This can be either an ID or an e-mail address.
Return type:	`_ACLEntity`
Returns:	A new Entity or a reference to an existing identical entity.

entity_from_dict(entity_dict)[source]#

Build an _ACLEntity object from a dictionary of data.

An entity is a mutable object that represents a list of roles belonging to either a user or group or the special types for all users and all authenticated users.

Parameters:	entity_dict (dict) – Dictionary full of data from an ACL lookup.
Return type:	`_ACLEntity`
Returns:	An Entity constructed from the dictionary.

get_entities()[source]#

Get a list of all Entity objects.

Return type:	list of `_ACLEntity` objects
Returns:	A list of all Entity objects.

get_entity(entity, default=None)[source]#

Gets an entity object from the ACL.

Parameters:	entity (`_ACLEntity` or string) – The entity to get lookup in the ACL. default (anything) – This value will be returned if the entity doesn’t exist.
Return type:	`_ACLEntity`
Returns:	The corresponding entity or the value provided to `default`.

group(identifier)[source]#

Factory method for a group Entity.

Parameters:	identifier (string) – An id or e-mail for this particular group.
Return type:	`_ACLEntity`
Returns:	An Entity corresponding to this group.

has_entity(entity)[source]#

Returns whether or not this ACL has any entries for an entity.

Parameters:	entity (`_ACLEntity`) – The entity to check for existence in this ACL.
Return type:	boolean
Returns:	True of the entity exists in the ACL.

loaded = False#

reload()[source]#

Reload the ACL data from Cloud Storage.

Return type:	`ACL`
Returns:	The current ACL.

reset()[source]#: Remove all entities from the ACL, and clear the loaded flag.

save(acl=None)[source]#

A method to be overridden by subclasses.

Parameters:	acl (`gcloud.storage.acl.ACL`, or a compatible list.) – The ACL object to save. If left blank, this will save current entries.
Raises:	NotImplementedError

user(identifier)[source]#

Factory method for a user Entity.

Parameters:	identifier (string) – An id or e-mail for this particular user.
Return type:	`_ACLEntity`
Returns:	An Entity corresponding to this user.

class gcloud.storage.acl.BucketACL(bucket)[source]#

Bases: gcloud.storage.acl.ACL

An ACL specifically for a bucket.

Parameters:	bucket (`gcloud.storage.bucket.Bucket`) – The bucket to which this ACL relates.

clear()[source]#

Remove all ACL entries.

Note that this won’t actually remove ALL the rules, but it will remove all the non-default rules. In short, you’ll still have access to a bucket that you created even after you clear ACL rules with this method.

For example, imagine that you granted access to this bucket to a bunch of coworkers:

>>> acl.user('coworker1@example.org').grant_read()
>>> acl.user('coworker2@example.org').grant_read()
>>> acl.save()

Now they work in another part of the company and you want to ‘start fresh’ on who has access:

>>> acl.clear()

At this point all the custom rules you created have been removed.

Return type:	`gcloud.storage.acl.BucketACL`
Returns:	The current ACL.

reload()[source]#

Reload the ACL data from Cloud Storage.

Return type:	`gcloud.storage.acl.BucketACL`
Returns:	The current ACL.

save(acl=None)[source]#

Save this ACL for the current bucket.

If called without arguments, this will save the entries currently stored on this ACL:

>>> acl.save()

You can also provide a specific ACL to save instead of the one currently set on the Bucket object:

>>> acl.save(acl=my_other_acl)

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)
>>> bucket2.acl.save(bucket1.acl)

Parameters:	acl (`gcloud.storage.acl.ACL`, or a compatible list.) – The ACL object to save. If left blank, this will save current entries.
Return type:	`gcloud.storage.acl.BucketACL`
Returns:	The current ACL.

class gcloud.storage.acl.DefaultObjectACL(bucket)[source]#

Bases: gcloud.storage.acl.BucketACL

A class representing the default object ACL for a bucket.

Parameters:	bucket (`gcloud.storage.bucket.Bucket`) – The bucket to which this ACL relates.

class gcloud.storage.acl.ObjectACL(blob)[source]#

Bases: gcloud.storage.acl.ACL

An ACL specifically for a Cloud Storage object / blob.

Parameters:	blob (`gcloud.storage.blob.Blob`) – The blob that this ACL corresponds to.

clear()[source]#

Remove all ACL rules from the blob.

Note that this won’t actually remove ALL the rules, but it will remove all the non-default rules. In short, you’ll still have access to a blob that you created even after you clear ACL rules with this method.

reload()[source]#

Reload the ACL data from Cloud Storage.

Return type:	`ObjectACL`
Returns:	The current ACL.

save(acl=None)[source]#

Save the ACL data for this blob.

Parameters:	acl (`gcloud.storage.acl.ACL`) – The ACL object to save. If left blank, this will save the entries set locally on the ACL.