As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Transactions

Create / interact with Google Cloud Datastore transactions.

class google.cloud.datastore.transaction.Transaction(client, read_only=False, read_time=None, begin_later=False)[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:

>>> entity1 = datastore.Entity(client.key('EntityKind', 1234))
>>> entity2 = datastore.Entity(client.key('EntityKind', 2345))
>>> 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:

>>> def do_some_work():
...    return
>>> class SomeException(Exception):
...    pass
>>> 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():
...     thing1 = datastore.Entity(key=client.key('Thing'))
...     client.put(thing1)

thing1 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():
...     thing2 = datastore.Entity(key=client.key('Thing'))
...     client.put(thing2)
...     print(thing2.key.is_partial)  # There is no ID on this key.
...
True
>>> print(thing2.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()
>>>
>>> thing3 = datastore.Entity(key=client.key('Thing'))
>>> transaction.put(thing3)
>>>
>>> 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.

  • read_time (datetime) – (Optional) Time at which the transaction reads entities. Only allowed when read_only=True. This feature is in private preview.

  • begin_later (bool) – (Optional) If True, the transaction will be started lazily (i.e. when the first RPC is made). If False, the transaction will be started as soon as the context manager is entered. self.begin() can also be called manually to begin the transaction at any time. Default is False.

Raises

ValueError if read_time is specified when read_only=False.

begin(retry=None, timeout=None)[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.

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)[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.

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

property database

Getter for database in which the batch will run.

Return type

str

Returns

The database in which the batch will run.

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

bytes or None

Returns

The ID of the current transaction, or None if not started.

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)[source]

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)[source]

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.