Python

0.4.0

Transactions#

Create / interact with gcloud datastore transactions.

class gcloud.datastore.transaction.Transaction(dataset_id=None, connection=None)[source]#

Bases: gcloud.datastore.batch.Batch

An abstraction representing datastore Transactions.

Transactions can be used to build up a bulk mutuation as well as provide isolation.

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

>>> from gcloud import datastore
>>> from gcloud.datastore.transaction import Transaction

>>> datastore.set_defaults()

>>> with Transaction():
...     datastore.put([entity1, entity2])

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

>>> with 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 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 Transaction():
...     entity = Entity(key=Key('Thing'))
...     datastore.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 Transaction():
...     entity = Entity(key=Key('Thing'))
...     datastore.put([entity])
...     assert entity.key.is_partial  # There is no ID on this key.
...
>>> assert not entity.key.is_partial  # There *is* an ID.

After completion, you can determine if a commit succeeded or failed. For example, trying to delete a key that doesn’t exist:

>>> with Transaction() as xact:
...     xact.delete(key)
...
>>> xact.succeeded
False

or successfully storing two entities:

>>> with Transaction() as xact:
...     datastore.put([entity1, entity2])
...
>>> xact.succeeded
True

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

>>> transaction = Transaction()
>>> transaction.begin()

>>> entity = Entity(key=Key('Thing'))
>>> transaction.put(entity)

>>> if error:
...     transaction.rollback()
... else:
...     transaction.commit()
Parameters:
Raises:

ValueError if either a connection or dataset ID are not set.
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.
static current()[source]#

Return the topmost transaction.

Note

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

Return type:gcloud.datastore.transaction.Transaction or None
id[source]#

Getter for the transaction ID.

Return type:string
Returns:The ID of the current transaction.
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.