Shared Core Modules#

Configuration#

>>> from google.cloud import bigquery
>>> client = bigquery.Client()

>>> from google.cloud import bigquery
>>> client = bigquery.Client(project='my-project')

>>> client.project
u'my-project'

$ gcloud config set project my-new-default-project

Authentication#

from google.cloud import datastore
client = datastore.Client()

client = Client(credentials=credentials)

from oauth2client.contrib.appengine import AppAssertionCredentials
credentials = AppAssertionCredentials([])

from oauth2client.contrib.gce import AppAssertionCredentials
credentials = AppAssertionCredentials([])

client = Client.from_service_account_json('/path/to/keyfile.json')

from oauth2client.client import GoogleCredentials
credentials = GoogleCredentials.get_application_default()

http.request(uri, method=method_name, body=body, headers=headers)

Long-Running Operations#

Wrap long-running operations returned from Google Cloud APIs.

class google.cloud.operation.Operation(name, client, pb_metadata=None, **kw)[source]#

Bases: object

Representation of a Google API Long-Running Operation.

Parameters:	name (str) – The fully-qualified path naming the operation. client (object: must provide _operations_stub accessor.) – The client used to poll for the status of the operation. pb_metadata (object) – Instance of protobuf metadata class kw (dict) – caller-assigned metadata about the operation

complete#

Has the operation already completed?

Return type:	bool
Returns:	True if already completed, else false.

classmethod from_pb(op_pb, client, **kw)[source]#

Factory: construct an instance from a protobuf.

Parameters:	op_pb (google.longrunning.operations_pb2.Operation) – Protobuf to be parsed. client (object: must provide _operations_stub accessor.) – The client used to poll for the status of the operation. kw (dict) – caller-assigned metadata about the operation
Return type:	Operation
Returns:	new instance, with attributes based on the protobuf.

poll()[source]#

Check if the operation has finished.

Return type:	bool
Returns:	A boolean indicating if the current operation has completed.
Raises:	ValueError if the operation has already completed.

target = None#

Instance assocated with the operations: callers may set.

Datastore Client#

Convenience wrapper for invoking APIs/factories w/ a project.

class google.cloud.datastore.client.Client(project=None, namespace=None, credentials=None, http=None)[source]#

Bases: google.cloud.client.Client, google.cloud.client._ClientProjectMixin

Convenience wrapper for invoking APIs/factories w/ a project.

Parameters:

project (string) – (optional) The project to pass to proxied API methods. namespace (string) – (optional) namespace to pass to proxied API methods. credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment. http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

allocate_ids(incomplete_key, num_ids)[source]#

Allocate a list of IDs from a partial key.

Parameters:	incomplete_key (google.cloud.datastore.key.Key) – Partial key to use as base for allocated IDs. num_ids (int) – The number of IDs to allocate.
Return type:	list of google.cloud.datastore.key.Key
Returns:	The (complete) keys allocated with incomplete_key as root.
Raises:	ValueError if incomplete_key is not a partial key.

batch()[source]#

Proxy to google.cloud.datastore.batch.Batch.

current_batch#

Currently-active batch.

Return type:	google.cloud.datastore.batch.Batch, or an object implementing its API, or NoneType (if no batch is active).
Returns:	The batch/transaction at the top of the batch stack.

current_transaction#

Currently-active transaction.

Return type:	google.cloud.datastore.transaction.Transaction, or an object implementing its API, or NoneType (if no transaction is active).
Returns:	The transaction at the top of the batch stack.

delete(key)[source]#

Delete the key in the Cloud Datastore.

Note

This is just a thin wrapper over delete_multi(). The backend API does not make a distinction between a single key or multiple keys in a commit request.

Parameters:	key (google.cloud.datastore.key.Key) – The key to be deleted from the datastore.

delete_multi(keys)[source]#

Delete keys from the Cloud Datastore.

Parameters:	keys (list of google.cloud.datastore.key.Key) – The keys to be deleted from the Datastore.

get(key, missing=None, deferred=None, transaction=None)[source]#

Retrieve an entity from a single key (if it exists).

Note

This is just a thin wrapper over get_multi(). The backend API does not make a distinction between a single key or multiple keys in a lookup request.

Parameters:	key (google.cloud.datastore.key.Key) – The key to be retrieved from the datastore. missing (list) – (Optional) If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. deferred (list) – (Optional) If a list is passed, the keys returned by the backend as “deferred” will be copied into it. transaction (Transaction) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:	google.cloud.datastore.entity.Entity or NoneType
Returns:	The requested entity if it exists.

get_multi(keys, missing=None, deferred=None, transaction=None)[source]#

Retrieve entities, along with their attributes.

Parameters:	keys (list of google.cloud.datastore.key.Key) – The keys to be retrieved from the datastore. missing (list) – (Optional) If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. If the list is not empty, an error will occur. deferred (list) – (Optional) If a list is passed, the keys returned by the backend as “deferred” will be copied into it. If the list is not empty, an error will occur. transaction (Transaction) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:	list of google.cloud.datastore.entity.Entity
Returns:	The requested entities.
Raises:	ValueError if one or more of keys has a project which does not match our project.

key(*path_args, **kwargs)[source]#

Proxy to google.cloud.datastore.key.Key.

Passes our project.

put(entity)[source]#

Save an entity in the Cloud Datastore.

Note

This is just a thin wrapper over put_multi(). The backend API does not make a distinction between a single entity or multiple entities in a commit request.

Parameters:	entity (google.cloud.datastore.entity.Entity) – The entity to be saved to the datastore.

put_multi(entities)[source]#

Save entities in the Cloud Datastore.

Parameters:	entities (list of google.cloud.datastore.entity.Entity) – The entities to be saved to the datastore.
Raises:	ValueError if entities is a single entity.

query(**kwargs)[source]#

Proxy to google.cloud.datastore.query.Query.

Passes our project.

Using query to search a datastore:

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='MyKind')
>>> query.add_filter('property', '=', 'val')

Using the query iterator’s next_page() method:

>>> query_iter = query.fetch()
>>> entities, more_results, cursor = query_iter.next_page()
>>> entities
[<list of Entity unmarshalled from protobuf>]
>>> more_results
<boolean of more results>
>>> cursor
<string containing cursor where fetch stopped>

Under the hood this is doing:

>>> connection.run_query('project', query.to_protobuf())
[<list of Entity Protobufs>], cursor, more_results, skipped_results

Parameters:	kwargs (dict) – Parameters for initializing and instance of google.cloud.datastore.query.Query.
Return type:	google.cloud.datastore.query.Query
Returns:	An instance of google.cloud.datastore.query.Query

transaction()[source]#

Proxy to google.cloud.datastore.transaction.Transaction.

Entities#

Class for representing a single entity in the Cloud Datastore.

class google.cloud.datastore.entity.Entity(key=None, exclude_from_indexes=())[source]#

Bases: dict

Entities are akin to rows in a relational database

An entity storing the actual instance of data.

Each entity is officially represented with a google.cloud.datastore.key.Key class, however it is possible that you might create an Entity with only a partial Key (that is, a Key with a Kind, and possibly a parent, but without an ID). In such a case, the datastore service will automatically assign an ID to the partial key.

Entities in this API act like dictionaries with extras built in that allow you to delete or persist the data stored on the entity.

Entities are mutable and act like a subclass of a dictionary. This means you could take an existing entity and change the key to duplicate the object.

Use google.cloud.datastore.get() to retrieve an existing entity.

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> client.get(key)
<Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>

You can the set values on the entity just like you would on any other dictionary.

>>> entity['age'] = 20
>>> entity['name'] = 'JJ'
>>> entity
<Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>

And you can convert an entity to a regular Python dictionary with the dict builtin:

>>> dict(entity)
{'age': 20, 'name': 'JJ'}

Note

When saving an entity to the backend, values which are “text” (unicode in Python2, str in Python3) will be saved using the ‘text_value’ field, after being encoded to UTF-8. When retrieved from the back-end, such values will be decoded to “text” again. Values which are “bytes” (str in Python2, bytes in Python3), will be saved using the ‘blob_value’ field, without any decoding / encoding step.

Parameters:	key (google.cloud.datastore.key.Key) – Optional key to be set on entity. exclude_from_indexes (tuple of string) – Names of fields whose values are not to be indexed for this entity.

exclude_from_indexes#

Names of fields which are not to be indexed for this entity.

Return type:	sequence of field names
Returns:	The set of fields excluded from indexes.

kind#

Get the kind of the current entity.

Note

This relies entirely on the google.cloud.datastore.key.Key set on the entity. That means that we’re not storing the kind of the entity at all, just the properties and a pointer to a Key which knows its Kind.

Keys#

Create / interact with Google Cloud Datastore keys.

class google.cloud.datastore.key.Key(*path_args, **kwargs)[source]#

Bases: object

An immutable representation of a datastore Key.

To create a basic key:

>>> Key('EntityKind', 1234)
<Key[{'kind': 'EntityKind', 'id': 1234}]>
>>> Key('EntityKind', 'foo')
<Key[{'kind': 'EntityKind', 'name': 'foo'}]>

To create a key with a parent:

>>> Key('Parent', 'foo', 'Child', 1234)
<Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child', 'id': 1234}]>
>>> Key('Child', 1234, parent=parent_key)
<Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child', 'id': 1234}]>

To create a partial key:

>>> Key('Parent', 'foo', 'Child')
<Key[{'kind': 'Parent', 'name': 'foo'}, {'kind': 'Child'}]>

Parameters:	path_args (tuple of string and integer) – May represent a partial (odd length) or full (even length) key path. kwargs (dict) – Keyword arguments to be passed in.

Accepted keyword arguments are

• namespace (string): A namespace identifier for the key.
• project (string): The project associated with the key.
• parent (google.cloud.datastore.key.Key): The parent of the key.

The project argument is required unless it has been set implicitly.

completed_key(id_or_name)[source]#

Creates new key from existing partial key by adding final ID/name.

Parameters:	id_or_name (string or integer) – ID or name to be added to the key.
Return type:	google.cloud.datastore.key.Key
Returns:	A new Key instance with the same data as the current one and an extra ID or name added.
Raises:	ValueError if the current key is not partial or if id_or_name is not a string or integer.

flat_path#

Getter for the key path as a tuple.

Return type:	tuple of string and integer
Returns:	The tuple of elements in the path.

id#

ID getter. Based on the last element of path.

Return type:	integer
Returns:	The (integer) ID of the key.

id_or_name#

Getter. Based on the last element of path.

Return type:	integer (if id) or string (if name)
Returns:	The last element of the key’s path if it is either an id or a name.

is_partial#

Boolean indicating if the key has an ID (or name).

Return type:	bool
Returns:	True if the last element of the key’s path does not have an id or a name.

kind#

Kind getter. Based on the last element of path.

Return type:	string
Returns:	The kind of the current key.

name#

Name getter. Based on the last element of path.

Return type:	string
Returns:	The (string) name of the key.

namespace#

Namespace getter.

Return type:	string
Returns:	The namespace of the current key.

parent#

The parent of the current key.

Return type:	google.cloud.datastore.key.Key or NoneType
Returns:	A new Key instance, whose path consists of all but the last element of current path. If the current key has only one path element, returns None.

path#

Path getter.

Returns a copy so that the key remains immutable.

Return type:	list of dict
Returns:	The (key) path of the current key.

project#

Project getter.

Return type:	string
Returns:	The key’s project.

to_protobuf()[source]#

Return a protobuf corresponding to the key.

Return type:	google.cloud.datastore._generated.entity_pb2.Key
Returns:	The protobuf representing the key.

Queries#

Create / interact with Google Cloud Datastore queries.

class google.cloud.datastore.query.Iterator(query, client, limit=None, offset=None, start_cursor=None, end_cursor=None)[source]#

Bases: object

Represent the state of a given execution of a Query.

Parameters:

query (google.cloud.datastore.query.Query) – Query object holding permanent configuration (i.e. things that don’t change on with each page in a results set). client (google.cloud.datastore.client.Client) – The client used to make a request. limit (integer) – (Optional) Limit the number of results returned. offset (integer) – (Optional) Offset used to begin a query. start_cursor (bytes) – (Optional) Cursor to begin paging through query results. end_cursor (bytes) – (Optional) Cursor to end paging through query results.

next_page()[source]#

Fetch a single “page” of query results.

Low-level API for fine control: the more convenient API is to iterate on the current Iterator.

Return type:	tuple, (entities, more_results, cursor)
Returns:	The next page of results.

class google.cloud.datastore.query.Query(client, kind=None, project=None, namespace=None, ancestor=None, filters=(), projection=(), order=(), distinct_on=())[source]#

Bases: object

A Query against the Cloud Datastore.

This class serves as an abstraction for creating a query over data stored in the Cloud Datastore.

Parameters:

client (google.cloud.datastore.client.Client) – The client used to connect to Datastore. kind (string) – The kind to query. project (string) – The project associated with the query. If not passed, uses the client’s value. namespace (string or None) – The namespace to which to restrict results. If not passed, uses the client’s value. ancestor (google.cloud.datastore.key.Key or None) – key of the ancestor to which this query’s results are restricted. filters (sequence of (property_name, operator, value) tuples) – property filters applied by this query. projection (sequence of string) – fields returned as part of query results. order (sequence of string) – field names used to order query results. Prepend ‘-‘ to a field name to sort it in descending order. distinct_on (sequence of string) – field names used to group query results.

Raises:

ValueError if project is not passed and no implicit default is set.

OPERATORS = {'>': 3, '<=': 2, '=': 5, '>=': 4, '<': 1}#

Mapping of operator strings and their protobuf equivalents.

add_filter(property_name, operator, value)[source]#

Filter the query based on a property name, operator and a value.

Expressions take the form of:

.add_filter('<property>', '<operator>', <value>)

where property is a property stored on the entity in the datastore and operator is one of OPERATORS (ie, =, <, <=, >, >=):

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='Person')
>>> query.add_filter('name', '=', 'James')
>>> query.add_filter('age', '>', 50)

Parameters:	property_name (string) – A property name. operator (string) – One of =, <, <=, >, >=. value (int, str, bool, float, NoneType, datetime.datetime, google.cloud.datastore.key.Key) – The value to filter on.
Raises:	ValueError if operation is not one of the specified values, or if a filter names '__key__' but passes an invalid value (a key is required).

ancestor#

The ancestor key for the query.

Return type:	Key or None
Returns:	The ancestor for the query.

distinct_on#

Names of fields used to group query results.

Return type:	sequence of string
Returns:	The “distinct on” fields set on the query.

fetch(limit=None, offset=0, start_cursor=None, end_cursor=None, client=None)[source]#

Execute the Query; return an iterator for the matching entities.

For example:

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='Person')
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

Parameters:	limit (integer or None) – An optional limit passed through to the iterator. offset (integer) – An optional offset passed through to the iterator. start_cursor (bytes) – An optional cursor passed through to the iterator. end_cursor (bytes) – An optional cursor passed through to the iterator. client (google.cloud.datastore.client.Client) – client used to connect to datastore. If not supplied, uses the query’s value.
Return type:	Iterator
Returns:	The iterator for the query.
Raises:	ValueError if connection is not passed and no implicit default has been set.

filters#

Filters set on the query.

Return type:	sequence of (property_name, operator, value) tuples.
Returns:	The filters set on the query.

key_filter(key, operator='=')[source]#

Filter on a key.

Parameters:	key (google.cloud.datastore.key.Key) – The key to filter on. operator (string) – (Optional) One of =, <, <=, >, >=. Defaults to =.

keys_only()[source]#

Set the projection to include only keys.

kind#

Get the Kind of the Query.

Return type:	string
Returns:	The kind for the query.

namespace#

This query’s namespace

Return type:	string or None
Returns:	the namespace assigned to this query

order#

Names of fields used to sort query results.

Return type:	sequence of string
Returns:	The order(s) set on the query.

project#

Get the project for this Query.

Return type:	str
Returns:	The project for the query.

projection#

Fields names returned by the query.

Return type:	sequence of string
Returns:	Names of fields in query results.

Transactions#

Create / interact with Google Cloud Datastore transactions.

class google.cloud.datastore.transaction.Transaction(client)[source]#

Bases: google.cloud.datastore.batch.Batch

An abstraction representing datastore Transactions.

Transactions can be used to build up a bulk mutation and ensure all or none succeed (transactionally).

For example, the following snippet of code will put the two save operations (either insert or upsert) into the same mutation, and execute those within a transaction:

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> with client.transaction():
...     client.put_multi([entity1, entity2])

Because it derives from Batch, Transaction also provides put() and delete() methods:

>>> with client.transaction() as xact:
...     xact.put(entity1)
...     xact.delete(entity2.key)

By default, the transaction is rolled back if the transaction block exits with an error:

>>> with client.transaction():
...     do_some_work()
...     raise SomeException()  # rolls back

If the transaction block exists without an exception, it will commit by default.

Warning

Inside a transaction, automatically assigned IDs for entities will not be available at save time! That means, if you try:

>>> with client.transaction():
...     entity = datastore.Entity(key=client.key('Thing'))
...     client.put(entity)

entity won’t have a complete key until the transaction is committed.

Once you exit the transaction (or call commit()), the automatically generated ID will be assigned to the entity:

>>> with client.transaction():
...     entity = datastore.Entity(key=client.key('Thing'))
...     client.put(entity)
...     print(entity.key.is_partial)  # There is no ID on this key.
...
True
>>> print(entity.key.is_partial)  # There *is* an ID.
False

If you don’t want to use the context manager you can initialize a transaction manually:

>>> transaction = client.transaction()
>>> transaction.begin()
>>>
>>> entity = datastore.Entity(key=client.key('Thing'))
>>> transaction.put(entity)
>>>
>>> if error:
...     transaction.rollback()
... else:
...     transaction.commit()

Parameters:	client (google.cloud.datastore.client.Client) – the client used to connect to datastore.

begin()[source]#

Begins a transaction.

This method is called automatically when entering a with statement, however it can be called explicitly if you don’t want to use a context manager.

Raises:	ValueError if the transaction has already begun.

commit()[source]#

Commits the transaction.

This is called automatically upon exiting a with statement, however it can be called explicitly if you don’t want to use a context manager.

This method has necessary side-effects:

• Sets the current transaction’s ID to None.

connection#

Getter for connection over which the batch will run.

Return type:	google.cloud.datastore.connection.Connection
Returns:	The connection over which the batch will run.

current()[source]#

Return the topmost transaction.

Note

If the topmost element on the stack is not a transaction, returns None.

Return type:	google.cloud.datastore.transaction.Transaction or None
Returns:	The current transaction (if any are active).

delete(key)#

Remember a key to be deleted during commit().

Parameters:	key (google.cloud.datastore.key.Key) – the key to be deleted.
Raises:	ValueError if the batch is not in progress, if key is not complete, or if the key’s project does not match ours.

id#

Getter for the transaction ID.

Return type:	string
Returns:	The ID of the current transaction.

mutations#

Getter for the changes accumulated by this batch.

Every batch is committed with a single commit request containing all the work to be done as mutations. Inside a batch, calling put() with an entity, or delete() with a key, builds up the request by adding a new mutation. This getter returns the protobuf that has been built-up so far.

Return type:	iterable
Returns:	The list of _generated.datastore_pb2.Mutation protobufs to be sent in the commit request.

namespace#

Getter for namespace in which the batch will run.

Return type:	str
Returns:	The namespace in which the batch will run.

project#

Getter for project in which the batch will run.

Return type:	str
Returns:	The project in which the batch will run.

put(entity)#

Remember an entity’s state to be saved during commit().

Note

Any existing properties for the entity will be replaced by those currently set on this instance. Already-stored properties which do not correspond to keys set on this instance will be removed from the datastore.

Note

Property values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) map to ‘string_value’ in the datastore; values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3) map to ‘blob_value’.

When an entity has a partial key, calling commit() sends it as an insert mutation and the key is completed. On return, the key for the entity passed in is updated to match the key ID assigned by the server.

Parameters:	entity (google.cloud.datastore.entity.Entity) – the entity to be saved.
Raises:	ValueError if the batch is not in progress, if entity has no key assigned, or if the key’s project does not match ours.

rollback()[source]#

Rolls back the current transaction.

This method has necessary side-effects:

• Sets the current connection’s transaction reference to None.
• Sets the current transaction’s ID to None.

Batches#

Create / interact with a batch of updates / deletes.

Batches provide the ability to execute multiple operations in a single request to the Cloud Datastore API.

See https://cloud.google.com/datastore/docs/concepts/entities#Datastore_Batch_operations

class google.cloud.datastore.batch.Batch(client)[source]#

Bases: object

An abstraction representing a collected group of updates / deletes.

Used to build up a bulk mutation.

For example, the following snippet of code will put the two save operations and the delete operation into the same mutation, and send them to the server in a single API request:

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> batch = client.batch()
>>> batch.put(entity1)
>>> batch.put(entity2)
>>> batch.delete(key3)
>>> batch.commit()

You can also use a batch as a context manager, in which case commit() will be called automatically if its block exits without raising an exception:

>>> with batch:
...     batch.put(entity1)
...     batch.put(entity2)
...     batch.delete(key3)

By default, no updates will be sent if the block exits with an error:

>>> with batch:
...     do_some_work(batch)
...     raise Exception()  # rolls back

Parameters:	client (google.cloud.datastore.client.Client) – The client used to connect to datastore.

begin()[source]#

Begins a batch.

This method is called automatically when entering a with statement, however it can be called explicitly if you don’t want to use a context manager.

Overridden by google.cloud.datastore.transaction.Transaction.

Raises:	ValueError if the batch has already begun.

commit()[source]#

Commits the batch.

This is called automatically upon exiting a with statement, however it can be called explicitly if you don’t want to use a context manager.

Raises:	ValueError if the batch is not in progress.

connection#

Getter for connection over which the batch will run.

Return type:	google.cloud.datastore.connection.Connection
Returns:	The connection over which the batch will run.

current()[source]#

Return the topmost batch / transaction, or None.

delete(key)[source]#

Remember a key to be deleted during commit().

Parameters:	key (google.cloud.datastore.key.Key) – the key to be deleted.
Raises:	ValueError if the batch is not in progress, if key is not complete, or if the key’s project does not match ours.

mutations#

Getter for the changes accumulated by this batch.

Every batch is committed with a single commit request containing all the work to be done as mutations. Inside a batch, calling put() with an entity, or delete() with a key, builds up the request by adding a new mutation. This getter returns the protobuf that has been built-up so far.

Return type:	iterable
Returns:	The list of _generated.datastore_pb2.Mutation protobufs to be sent in the commit request.

namespace#

Getter for namespace in which the batch will run.

Return type:	str
Returns:	The namespace in which the batch will run.

project#

Getter for project in which the batch will run.

Return type:	str
Returns:	The project in which the batch will run.

put(entity)[source]#

Remember an entity’s state to be saved during commit().

Note

Any existing properties for the entity will be replaced by those currently set on this instance. Already-stored properties which do not correspond to keys set on this instance will be removed from the datastore.

Note

Property values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) map to ‘string_value’ in the datastore; values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3) map to ‘blob_value’.

When an entity has a partial key, calling commit() sends it as an insert mutation and the key is completed. On return, the key for the entity passed in is updated to match the key ID assigned by the server.

Parameters:	entity (google.cloud.datastore.entity.Entity) – the entity to be saved.
Raises:	ValueError if the batch is not in progress, if entity has no key assigned, or if the key’s project does not match ours.

rollback()[source]#

Rolls back the current batch.

Marks the batch as aborted (can’t be used again).

Overridden by google.cloud.datastore.transaction.Transaction.

Raises:	ValueError if the batch is not in progress.

Helpers#

Helper functions for dealing with Cloud Datastore’s Protobuf API.

The non-private functions are part of the API.

google.cloud.datastore.helpers.entity_from_protobuf(pb)[source]#

Factory method for creating an entity based on a protobuf.

The protobuf should be one returned from the Cloud Datastore Protobuf API.

Parameters:	pb (google.cloud.datastore._generated.entity_pb2.Entity) – The Protobuf representing the entity.
Return type:	google.cloud.datastore.entity.Entity
Returns:	The entity derived from the protobuf.

google.cloud.datastore.helpers.key_from_protobuf(pb)[source]#

Factory method for creating a key based on a protobuf.

The protobuf should be one returned from the Cloud Datastore Protobuf API.

Parameters:	pb (google.cloud.datastore._generated.entity_pb2.Key) – The Protobuf representing the key.
Return type:	google.cloud.datastore.key.Key
Returns:	a new Key instance

Storage Client#

Client for interacting with the Google Cloud Storage API.

class google.cloud.storage.client.Client(project=None, credentials=None, http=None)[source]#

Bases: google.cloud.client.JSONClient

Client to bundle configuration needed for API requests.

Parameters:

project (string) – the project which the client acts on behalf of. Will be passed when creating a topic. If not passed, falls back to the default inferred from the environment. credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment. http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

batch()[source]#

Factory constructor for batch object.

Note

This will not make an HTTP request; it simply instantiates a batch object owned by this client.

Return type:	google.cloud.storage.batch.Batch
Returns:	The batch object created.

bucket(bucket_name)[source]#

Factory constructor for bucket object.

Note

This will not make an HTTP request; it simply instantiates a bucket object owned by this client.

Parameters:	bucket_name (string) – The name of the bucket to be instantiated.
Return type:	google.cloud.storage.bucket.Bucket
Returns:	The bucket object created.

connection#

Get connection or batch on the client.

Return type:	google.cloud.storage.connection.Connection
Returns:	The connection set on the client, or the batch if one is set.

create_bucket(bucket_name)[source]#

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 google.cloud.exceptions.Conflict.

Parameters:	bucket_name (string) – The bucket name to create.
Return type:	google.cloud.storage.bucket.Bucket
Returns:	The newly created bucket.

current_batch#

Currently-active batch.

Return type:	google.cloud.storage.batch.Batch or NoneType (if no batch is active).
Returns:	The batch at the top of the batch stack.

get_bucket(bucket_name)[source]#

Get a bucket by name.

If the bucket isn’t found, this will raise a google.cloud.storage.exceptions.NotFound.

For example:

>>> try:
>>>   bucket = client.get_bucket('my-bucket')
>>> except google.cloud.exceptions.NotFound:
>>>   print('Sorry, that bucket does not exist!')

This implements “storage.buckets.get”.

Parameters:	bucket_name (string) – The name of the bucket to get.
Return type:	google.cloud.storage.bucket.Bucket
Returns:	The bucket matching the name provided.
Raises:	google.cloud.exceptions.NotFound

list_buckets(max_results=None, page_token=None, prefix=None, projection='noAcl', fields=None)[source]#

Get all buckets in the project associated to the client.

This will not populate the list of blobs available in each bucket.

>>> for bucket in client.list_buckets():
...   print(bucket)

This implements “storage.buckets.list”.

Parameters:	max_results (integer or NoneType) – Optional. Maximum number of buckets to return. page_token (string or NoneType) – Optional. Opaque marker for the next “page” of buckets. If not passed, will return the first page of buckets. prefix (string or NoneType) – Optional. Filter results to buckets whose names begin with this prefix. projection (string or NoneType) – If used, must be ‘full’ or ‘noAcl’. Defaults to ‘noAcl’. Specifies the set of properties to return. fields (string or NoneType) – Selector specifying which fields to include in a partial response. Must be a list of fields. For example to get a partial response with just the next page token and the language of each bucket returned: ‘items/id,nextPageToken’
Return type:	iterable of google.cloud.storage.bucket.Bucket objects.
Returns:	All buckets belonging to this project.

lookup_bucket(bucket_name)[source]#

Get a bucket by name, returning None if not found.

You can use this if you would rather check for a None value than catching an exception:

>>> bucket = client.lookup_bucket('doesnt-exist')
>>> print(bucket)
None
>>> bucket = client.lookup_bucket('my-bucket')
>>> print(bucket)
<Bucket: my-bucket>

Parameters:	bucket_name (string) – The name of the bucket to get.
Return type:	google.cloud.storage.bucket.Bucket
Returns:	The bucket matching the name provided or None if not found.

Blobs / Objects#

Create / interact with Google Cloud Storage blobs.

class google.cloud.storage.blob.Blob(name, bucket, chunk_size=None)[source]#

Bases: google.cloud.storage._helpers._PropertyMixin

A wrapper around Cloud Storage’s concept of an Object.

Parameters:	name (string) – The name of the blob. This corresponds to the unique path of the object in the bucket. bucket (google.cloud.storage.bucket.Bucket) – The bucket to which this blob belongs. chunk_size (integer) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.

acl#

Create our ACL on demand.

cache_control#

HTTP ‘Cache-Control’ header for this object.

See: https://tools.ietf.org/html/rfc7234#section-5.2 and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

chunk_size#

Get the blob’s default chunk size.

Return type:	integer or NoneType
Returns:	The current blob’s chunk size, if it is set.

client#

The client bound to this blob.

component_count#

Number of underlying components that make up this object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	integer or NoneType
Returns:	The component count (in case of a composed object) or None if the property is not set locally. This property will not be set on objects not created via compose.

content_disposition#

HTTP ‘Content-Disposition’ header for this object.

See: https://tools.ietf.org/html/rfc6266 and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

content_encoding#

HTTP ‘Content-Encoding’ header for this object.

See: https://tools.ietf.org/html/rfc7231#section-3.1.2.2 and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

content_language#

HTTP ‘Content-Language’ header for this object.

See: http://tools.ietf.org/html/bcp47 and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

content_type#

HTTP ‘Content-Type’ header for this object.

See: https://tools.ietf.org/html/rfc2616#section-14.17 and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

crc32c#

CRC32C checksum for this object.

See: http://tools.ietf.org/html/rfc4960#appendix-B and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

delete(client=None)[source]#

Deletes a blob from Cloud Storage.

Parameters:	client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:	Blob
Returns:	The blob that was just deleted.
Raises:	google.cloud.exceptions.NotFound (propagated from google.cloud.storage.bucket.Bucket.delete_blob()).

download_as_string(encryption_key=None, client=None)[source]#

Download the contents of this blob as a string.

Parameters:	encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:	bytes
Returns:	The data stored in this blob.
Raises:	google.cloud.exceptions.NotFound

download_to_file(file_obj, encryption_key=None, client=None)[source]#

Download the contents of this blob into a file-like object.

Note

If the server-set property, media_link, is not yet initialized, makes an additional API request to load it.

Downloading a file that has been encrypted with a customer-supplied encryption key:

>>> from google.cloud import storage
>>> from google.cloud.storage import Blob

>>> client = storage.Client(project='my-project')
>>> bucket = client.get_bucket('my-bucket')
>>> encryption_key = 'aa426195405adee2c8081bb9e7e74b19'
>>> blob = Blob('secure-data', bucket)
>>> with open('/tmp/my-secure-file', 'wb') as file_obj:
>>>     blob.download_to_file(file_obj,
...                           encryption_key=encryption_key)

The encryption_key should be a str or bytes with a length of at least 32.

Parameters:	file_obj (file) – A file handle to which to write the blob’s data. encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:	google.cloud.exceptions.NotFound

download_to_filename(filename, encryption_key=None, client=None)[source]#

Download the contents of this blob into a named file.

Parameters:	filename (string) – A filename to be passed to open. encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Raises:	google.cloud.exceptions.NotFound

etag#

Retrieve the ETag for the object.

See: http://tools.ietf.org/html/rfc2616#section-3.11 and

https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string or NoneType
Returns:	The blob etag or None if the property is not set locally.

exists(client=None)[source]#

Determines whether or not this blob exists.

Parameters:	client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.
Return type:	boolean
Returns:	True if the blob exists in Cloud Storage.

generate_signed_url(expiration, method='GET', content_type=None, generation=None, response_disposition=None, response_type=None, client=None, credentials=None)[source]#

Generates a signed URL for this blob.

Note

If you are on Google Compute Engine, you can’t generate a signed URL. Follow Issue 922 for updates on this. If you’d like to be able to generate a signed URL from GCE, you can use a standard service account from a JSON file rather than a GCE service account.

If you have a blob that you want to allow access to for a set amount of time, you can use this method to generate a URL that is only valid within a certain time period.

This is particularly useful if you don’t want publicly accessible blobs, but don’t want to require users to explicitly log in.

Parameters:	expiration (int, long, datetime.datetime, datetime.timedelta) – When the signed URL should expire. method (str) – The HTTP verb that will be used when requesting the URL. content_type (str) – (Optional) The content type of the object referenced by resource. generation (str) – (Optional) A value that indicates which generation of the resource to fetch. response_disposition (str) – (Optional) Content disposition of responses to requests for the signed URL. For example, to enable the signed URL to initiate a file of blog.png, use the value 'attachment; filename=blob.png'. response_type (str) – (Optional) Content type of responses to requests for the signed URL. Used to over-ride the content type of the underlying blob/object. client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the blob’s bucket. credentials (oauth2client.client.OAuth2Credentials or NoneType) – (Optional) The OAuth2 credentials to use to sign the URL. Defaults to the credentials stored on the client used.
Return type:	str
Returns:	A signed URL you can use to access the resource until expiration.

generation#

Retrieve the generation for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	integer or NoneType
Returns:	The generation of the blob or None if the property is not set locally.

id#

Retrieve the ID for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string or NoneType
Returns:	The ID of the blob or None if the property is not set locally.

make_public(client=None)[source]#

Make this blob public giving all users read access.

Parameters:	client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.

md5_hash#

MD5 hash for this object.

See: http://tools.ietf.org/html/rfc4960#appendix-B and

https://cloud.google.com/storage/docs/json_api/v1/objects

If the property is not set locally, returns None.

Return type:	string or NoneType

media_link#

Retrieve the media download URI for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string or NoneType
Returns:	The media link for the blob or None if the property is not set locally.

metadata#

Retrieve arbitrary/application specific metadata for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	dict or NoneType
Returns:	The metadata associated with the blob or None if the property is not set locally.

metageneration#

Retrieve the metageneration for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	integer or NoneType
Returns:	The metageneration of the blob or None if the property is not set locally.

owner#

Retrieve info about the owner of the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	dict or NoneType
Returns:	Mapping of owner’s role/ID. If the property is not set locally, returns None.

path#

Getter property for the URL path to this Blob.

Return type:	string
Returns:	The URL path to this Blob.

static path_helper(bucket_path, blob_name)[source]#

Relative URL path for a blob.

Parameters:	bucket_path (string) – The URL path for a bucket. blob_name (string) – The name of the blob.
Return type:	string
Returns:	The relative URL path for blob_name.

public_url#

The public URL for this blob’s object.

Return type:	string
Returns:	The public URL for this blob.

self_link#

Retrieve the URI for the object.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	string or NoneType
Returns:	The self link for the blob or None if the property is not set locally.

size#

Size of the object, in bytes.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	integer or NoneType
Returns:	The size of the blob or None if the property is not set locally.

storage_class#

Retrieve the storage class for the object.

See: https://cloud.google.com/storage/docs/storage-classes https://cloud.google.com/storage/docs/nearline-storage https://cloud.google.com/storage/docs/durable-reduced-availability

Return type:	string or NoneType
Returns:	If set, one of “STANDARD”, “NEARLINE”, or “DURABLE_REDUCED_AVAILABILITY”, else None.

time_deleted#

Retrieve the timestamp at which the object was deleted.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	datetime.datetime or NoneType
Returns:	Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally. If the blob has not been deleted, this will never be set.

updated#

Retrieve the timestamp at which the object was updated.

See: https://cloud.google.com/storage/docs/json_api/v1/objects

Return type:	datetime.datetime or NoneType
Returns:	Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally.

upload_from_file(file_obj, rewind=False, size=None, encryption_key=None, content_type=None, num_retries=6, client=None)[source]#

Upload the contents of this blob from a file-like object.

The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The default value of ‘application/octet-stream’

Note

The effect of uploading to an existing blob depends on the “versioning” and “lifecycle” policies defined on the blob’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

Uploading a file with a customer-supplied encryption key:

>>> from google.cloud import storage
>>> from google.cloud.storage import Blob

>>> client = storage.Client(project='my-project')
>>> bucket = client.get_bucket('my-bucket')
>>> encryption_key = 'aa426195405adee2c8081bb9e7e74b19'
>>> blob = Blob('secure-data', bucket)
>>> with open('my-file', 'rb') as my_file:
>>>     blob.upload_from_file(my_file,
...                           encryption_key=encryption_key)

The encryption_key should be a str or bytes with a length of at least 32.

Parameters:

file_obj (file) – A file handle open for reading. rewind (boolean) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage. size (int) – The number of bytes to read from the file handle. If not provided, we’ll try to guess the size using os.fstat(). (If the file handle is not from the filesystem this won’t be possible.) encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. content_type (string or NoneType) – Optional type of content being uploaded. num_retries (integer) – Number of upload retries. Defaults to 6. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.

Raises:

ValueError if size is not passed in and can not be determined; google.cloud.exceptions.GoogleCloudError if the upload response returns an error status.

upload_from_filename(filename, content_type=None, encryption_key=None, client=None)[source]#

Upload this blob’s contents from the content of a named file.

The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The value given by mimetypes.guess_type

Note

The effect of uploading to an existing blob depends on the “versioning” and “lifecycle” policies defined on the blob’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

Parameters:	filename (string) – The path to the file. content_type (string or NoneType) – Optional type of content being uploaded. encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.

upload_from_string(data, content_type='text/plain', encryption_key=None, client=None)[source]#

Upload contents of this blob from the provided string.

Note

The effect of uploading to an existing blob depends on the “versioning” and “lifecycle” policies defined on the blob’s bucket. In the absence of those policies, upload will overwrite any existing contents.

See the object versioning and lifecycle API documents for details.

Parameters:

data (bytes or text) – The data to store in this blob. If the value is text, it will be encoded as UTF-8. content_type (string) – Optional type of content being uploaded. Defaults to 'text/plain'. encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the blob’s bucket.

Buckets#

Create / interact with Google Cloud Storage buckets.

class google.cloud.storage.bucket.Bucket(client, name=None)[source]#

Bases: google.cloud.storage._helpers._PropertyMixin

A class representing a Bucket on Cloud Storage.

Parameters:	client (google.cloud.storage.client.Client) – A client which holds credentials and project configuration for the bucket (which requires a project). name (string) – The name of the bucket.

acl#

Create our ACL on demand.

blob(blob_name, chunk_size=None)[source]#

Factory constructor for blob object.

Note

This will not make an HTTP request; it simply instantiates a blob object owned by this bucket.

Parameters:	blob_name (string) – The name of the blob to be instantiated. chunk_size (integer) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.
Return type:	google.cloud.storage.blob.Blob
Returns:	The blob object created.

client#

The client bound to this bucket.

configure_website(main_page_suffix=None, not_found_page=None)[source]#

Configure website-related properties.

See: https://developers.google.com/storage/docs/website-configuration

Note

This (apparently) only works if your bucket name is a domain name (and to do that, you need to get approved somehow...).

If you want this bucket to host a website, just provide the name of an index page and a page to use when a blob isn’t found:

>>> from google.cloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket(bucket_name)
>>> bucket.configure_website('index.html', '404.html')

You probably should also make the whole bucket public:

>>> bucket.make_public(recursive=True, future=True)

This says: “Make the bucket public, and all the stuff already in the bucket, and anything else I add to the bucket. Just make it all public.”

Parameters:	main_page_suffix (string) – The page to use as the main page of a directory. Typically something like index.html. not_found_page (string) – The file to use when a page isn’t found.

copy_blob(blob, destination_bucket, new_name=None, client=None, preserve_acl=True)[source]#

Copy the given blob to the given bucket, optionally with a new name.

Parameters:	blob (google.cloud.storage.blob.Blob) – The blob to be copied. destination_bucket (google.cloud.storage.bucket.Bucket) – The bucket into which the blob should be copied. new_name (string) – (optional) the new name for the copied file. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket. preserve_acl (bool) – Optional. Copies ACL from old blob to new blob. Default: True.
Return type:	google.cloud.storage.blob.Blob
Returns:	The new Blob.

cors#

Retrieve CORS policies configured for this bucket.

See: http://www.w3.org/TR/cors/ and

https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	list of dictionaries
Returns:	A sequence of mappings describing each CORS policy.

create(client=None)[source]#

Creates current bucket.

If the bucket already exists, will raise google.cloud.exceptions.Conflict.

This implements “storage.buckets.insert”.

Parameters:	client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.

default_object_acl#

Create our defaultObjectACL on demand.

delete(force=False, client=None)[source]#

Delete this bucket.

The bucket must be empty in order to submit a delete request. If force=True is passed, this will first attempt to delete all the objects / blobs in the bucket (i.e. try to empty the bucket).

If the bucket doesn’t exist, this will raise google.cloud.exceptions.NotFound. If the bucket is not empty (and force=False), will raise google.cloud.exceptions.Conflict.

If force=True and the bucket contains more than 256 objects / blobs this will cowardly refuse to delete the objects (or the bucket). This is to prevent accidental bucket deletion and to prevent extremely long runtime of this method.

Parameters:	force (boolean) – If True, empties the bucket’s objects then deletes it. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:	ValueError if force is True and the bucket contains more than 256 objects / blobs.

delete_blob(blob_name, client=None)[source]#

Deletes a blob from the current bucket.

If the blob isn’t found (backend 404), raises a google.cloud.exceptions.NotFound.

For example:

>>> from google.cloud.exceptions import NotFound
>>> from google.cloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket('my-bucket')
>>> print(bucket.list_blobs())
[<Blob: my-bucket, my-file.txt>]
>>> bucket.delete_blob('my-file.txt')
>>> try:
...   bucket.delete_blob('doesnt-exist')
... except NotFound:
...   pass

Parameters:	blob_name (string) – A blob name to delete. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:	google.cloud.exceptions.NotFound (to suppress the exception, call delete_blobs, passing a no-op on_error callback, e.g.: >>> bucket.delete_blobs([blob], on_error=lambda blob: None)

delete_blobs(blobs, on_error=None, client=None)[source]#

Deletes a list of blobs from the current bucket.

Uses Bucket.delete_blob() to delete each individual blob.

Parameters:	blobs (list of string or google.cloud.storage.blob.Blob) – A list of blob names or Blob objects to delete. on_error (a callable taking (blob)) – If not None, called once for each blob raising google.cloud.exceptions.NotFound; otherwise, the exception is propagated. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Raises:	google.cloud.exceptions.NotFound (if on_error is not passed).

disable_logging()[source]#

Disable access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#disabling

disable_website()[source]#

Disable the website configuration for this bucket.

This is really just a shortcut for setting the website-related attributes to None.

enable_logging(bucket_name, object_prefix='')[source]#

Enable access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#delivery

Parameters:	bucket_name (string) – name of bucket in which to store access logs object_prefix (string) – prefix for access log filenames

etag#

Retrieve the ETag for the bucket.

See: http://tools.ietf.org/html/rfc2616#section-3.11 and

https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	string or NoneType
Returns:	The bucket etag or None if the property is not set locally.

exists(client=None)[source]#

Determines whether or not this bucket exists.

Parameters:	client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:	boolean
Returns:	True if the bucket exists in Cloud Storage.

get_blob(blob_name, client=None)[source]#

Get a blob object by name.

This will return None if the blob doesn’t exist:

>>> from google.cloud import storage
>>> client = storage.Client()
>>> bucket = client.get_bucket('my-bucket')
>>> print(bucket.get_blob('/path/to/blob.txt'))
<Blob: my-bucket, /path/to/blob.txt>
>>> print(bucket.get_blob('/does-not-exist.txt'))
None

Parameters:	blob_name (string) – The name of the blob to retrieve. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:	google.cloud.storage.blob.Blob or None
Returns:	The blob object if it exists, otherwise None.

get_logging()[source]#

Return info about access logging for this bucket.

See: https://cloud.google.com/storage/docs/accesslogs#status

Return type:	dict or None
Returns:	a dict w/ keys, logBucket and logObjectPrefix (if logging is enabled), or None (if not).

id#

Retrieve the ID for the bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	string or NoneType
Returns:	The ID of the bucket or None if the property is not set locally.

lifecycle_rules#

Lifecycle rules configured for this bucket.

See: https://cloud.google.com/storage/docs/lifecycle and

https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	list(dict)
Returns:	A sequence of mappings describing each lifecycle rule.

list_blobs(max_results=None, page_token=None, prefix=None, delimiter=None, versions=None, projection='noAcl', fields=None, client=None)[source]#

Return an iterator used to find blobs in the bucket.

Parameters:	max_results (integer or NoneType) – maximum number of blobs to return. page_token (string) – opaque marker for the next “page” of blobs. If not passed, will return the first page of blobs. prefix (string or NoneType) – optional prefix used to filter blobs. delimiter (string or NoneType) – optional delimter, used with prefix to emulate hierarchy. versions (boolean or NoneType) – whether object versions should be returned as separate blobs. projection (string or NoneType) – If used, must be ‘full’ or ‘noAcl’. Defaults to ‘noAcl’. Specifies the set of properties to return. fields (string or NoneType) – Selector specifying which fields to include in a partial response. Must be a list of fields. For example to get a partial response with just the next page token and the language of each blob returned: ‘items/contentLanguage,nextPageToken’ client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:	_BlobIterator.
Returns:	An iterator of blobs.

location#

Retrieve location configured for this bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets and https://cloud.google.com/storage/docs/concepts-techniques#specifyinglocations

If the property is not set locally, returns None.

Return type:	string or NoneType

make_public(recursive=False, future=False, client=None)[source]#

Make a bucket public.

If recursive=True and the bucket contains more than 256 objects / blobs this will cowardly refuse to make the objects public. This is to prevent extremely long runtime of this method.

Parameters:	recursive (boolean) – If True, this will make all blobs inside the bucket public as well. future (boolean) – If True, this will make all objects created in the future public as well. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.

metageneration#

Retrieve the metageneration for the bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	integer or NoneType
Returns:	The metageneration of the bucket or None if the property is not set locally.

owner#

Retrieve info about the owner of the bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	dict or NoneType
Returns:	Mapping of owner’s role/ID. If the property is not set locally, returns None.

path#

The URL path to this bucket.

static path_helper(bucket_name)[source]#

Relative URL path for a bucket.

Parameters:	bucket_name (string) – The bucket name in the path.
Return type:	string
Returns:	The relative URL path for bucket_name.

project_number#

Retrieve the number of the project to which the bucket is assigned.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	integer or NoneType
Returns:	The project number that owns the bucket or None if the property is not set locally.

rename_blob(blob, new_name, client=None)[source]#

Rename the given blob using copy and delete operations.

Effectively, copies blob to the same bucket with a new name, then deletes the blob.

Warning

This method will first duplicate the data and then delete the old blob. This means that with very large objects renaming could be a very (temporarily) costly or a very slow operation.

Parameters:	blob (google.cloud.storage.blob.Blob) – The blob to be renamed. new_name (string) – The new name for this blob. client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current bucket.
Return type:	Blob
Returns:	The newly-renamed blob.

self_link#

Retrieve the URI for the bucket.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	string or NoneType
Returns:	The self link for the bucket or None if the property is not set locally.

storage_class#

Retrieve the storage class for the bucket.

See: https://cloud.google.com/storage/docs/storage-classes https://cloud.google.com/storage/docs/nearline-storage https://cloud.google.com/storage/docs/durable-reduced-availability

Return type:	string or NoneType
Returns:	If set, one of “STANDARD”, “NEARLINE”, or “DURABLE_REDUCED_AVAILABILITY”, else None.

time_created#

Retrieve the timestamp at which the bucket was created.

See: https://cloud.google.com/storage/docs/json_api/v1/buckets

Return type:	datetime.datetime or NoneType
Returns:	Datetime object parsed from RFC3339 valid timestamp, or None if the property is not set locally.

versioning_enabled#

Is versioning enabled for this bucket?

See: https://cloud.google.com/storage/docs/object-versioning for details.

Return type:	boolean
Returns:	True if enabled, else False.