Transactions

Create / interact with Google Cloud Datastore transactions.

class google.cloud.datastore.transaction.Transaction(client, read_only=False)

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:

 >>> 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
Traceback (most recent call last):
  ...
SomeException 

If the transaction block exits 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 = 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 = 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 = Entity(key=client.key('Thing'))
>>> transaction.put(entity)
>>>
>>> transaction.commit() 

• Parameters

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

  • read_only( bool ) – indicates the transaction is read only.

begin(retry=None, timeout=None)

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.

• Parameters

  • retry( google.api_core.retry.Retry ) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

  • timeout( float ) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

• Raises

  ValueError if the transaction has already begun.

commit(retry=None, timeout=None)

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.

• Parameters

  • retry( google.api_core.retry.Retry ) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

  • timeout( float ) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

current()

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.

property id()

Getter for the transaction ID.

• Return type

  str

• Returns

  The ID of the current transaction.

property 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 datastore_pb2.Mutation protobufs to be sent in the commit request.

property namespace()

Getter for namespace in which the batch will run.

• Return type

  str

• Returns

  The namespace in which the batch will run.

property project()

Getter for project in which the batch will run.

• Return type

  str

• Returns

  The project in which the batch will run.

put(entity)

Adds an entity to be committed.

Ensures the transaction is not marked readonly. Please see documentation at put()

• Parameters

  entity( Entity ) – the entity to be saved.

• Raises

  RuntimeError if the transaction is marked ReadOnly

rollback(retry=None, timeout=None)

Rolls back the current transaction.

This method has necessary side-effects:

• Sets the current transaction’s ID to None.

• Parameters

  • retry( google.api_core.retry.Retry ) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

  • timeout( float ) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.