ACL

Manipulate access control lists that Cloud Storage provides.

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

client = storage.Client() bucket = client.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() 

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

acl.save() 

You can alternatively save any existing google.cloud.storage.acl.ACL object (whether it was created by a factory method or not) from a google.cloud.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 google.cloud.storage.acl.ACL()

Bases: object

Container class representing a list of access controls.

PREDEFINED_JSON_ACLS( = frozenset({'authenticatedRead', 'bucketOwnerFullControl', 'bucketOwnerRead', 'private', 'projectPrivate', 'publicRead', 'publicReadWrite'} )

See https://cloud.google.com/storage/docs/access-control/lists#predefined-acl

add_entity(entity)

Add an entity to the ACL.

• Parameters

  entity (_ACLEntity) – The entity to add to this ACL.

all()

Factory method for an Entity representing all users.

• Return type

  _ACLEntity

• Returns

  An entity representing all users.

all_authenticated()

Factory method for an Entity representing all authenticated users.

• Return type

  _ACLEntity

• Returns

  An entity representing all authenticated users.

clear(client=None, timeout=60)

Remove all ACL entries.

If user_project is set, bills the API request to that project.

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.

• Parameters

  • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

  • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

    Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

property client()

Abstract getter for the object client.

domain(domain)

Factory method for a domain Entity.

• Parameters

  domain (str) – The domain for this entity.

• Return type

  _ACLEntity

• Returns

  An entity corresponding to this domain.

entity(entity_type, identifier=None)

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 (str) – The type of entity to create (ie, user, group, etc)

  • identifier (str) – 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)

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

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)

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)

Factory method for a group Entity.

• Parameters

  identifier (str) – An id or e-mail for this particular group.

• Return type

  _ACLEntity

• Returns

  An Entity corresponding to this group.

has_entity(entity)

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

  bool

• Returns

  True of the entity exists in the ACL.

reload(client=None, timeout=60)

Reload the ACL data from Cloud Storage.

If user_project is set, bills the API request to that project.

• Parameters

  • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

  • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

    Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

reset()

Remove all entities from the ACL, and clear the loaded flag.

save(acl=None, client=None, timeout=60)

Save this ACL for the current bucket.

If user_project is set, bills the API request to that project.

• Parameters

  • acl (google.cloud.storage.acl.ACL, or a compatible list.) – The ACL object to save. If left blank, this will save current entries.

  • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

  • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

    Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

save_predefined(predefined, client=None, timeout=60)

Save this ACL for the current bucket using a predefined ACL.

If user_project is set, bills the API request to that project.

• Parameters

  • predefined (str) – An identifier for a predefined ACL. Must be one of the keys in PREDEFINED_JSON_ACLS or PREDEFINED_XML_ACLS (which will be aliased to the corresponding JSON name). If passed, acl must be None.

  • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

  • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

    Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

user(identifier)

Factory method for a user Entity.

• Parameters

  identifier (str) – An id or e-mail for this particular user.

• Return type

  _ACLEntity

• Returns

  An Entity corresponding to this user.

classmethod validate_predefined(predefined)

Ensures predefined is in list of predefined json values

• Parameters

  • predefined (str) – name of a predefined acl

  • predefined – validated JSON name of predefined acl

• Raises

  • exc

    ValueError: If predefined is not a valid acl

class google.cloud.storage.acl.BucketACL(bucket)

Bases: google.cloud.storage.acl.ACL

An ACL specifically for a bucket.

• Parameters

  bucket (google.cloud.storage.bucket.Bucket) – The bucket to which this ACL relates.

property client()

The client bound to this ACL’s bucket.

property reload_path()

Compute the path for GET API requests for this ACL.

property save_path()

Compute the path for PATCH API requests for this ACL.

property user_project()

Compute the user project charged for API requests for this ACL.

class google.cloud.storage.acl.DefaultObjectACL(bucket)

Bases: google.cloud.storage.acl.BucketACL

A class representing the default object ACL for a bucket.

class google.cloud.storage.acl.ObjectACL(blob)

Bases: google.cloud.storage.acl.ACL

An ACL specifically for a Cloud Storage object / blob.

• Parameters

  blob (google.cloud.storage.blob.Blob) – The blob that this ACL corresponds to.

property client()

The client bound to this ACL’s blob.

property reload_path()

Compute the path for GET API requests for this ACL.

property save_path()

Compute the path for PATCH API requests for this ACL.

property user_project()

Compute the user project charged for API requests for this ACL.