Module transaction (2.1.6)

Version 2.1.6

• 2.20.1 (latest)
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.0
• 2.16.1
• 2.15.2
• 2.14.0
• 2.13.2
• 2.12.0
• 2.11.1
• 2.10.0
• 2.9.0
• 2.8.3
• 2.7.2
• 2.6.2
• 2.5.1
• 2.4.0
• 2.3.0
• 2.2.0
• 2.1.6
• 2.0.1
• 1.15.5
• 1.14.0
• 1.13.2
• 1.12.0
• 1.11.0
• 1.10.0
• 1.9.0

Create / interact with Google Cloud Datastore transactions.

Classes

Transaction

Transaction(client, read_only=False)

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:

.. testsetup:: txn-put-multi, txn-api

import os
import uuid

from google.cloud import datastore
from tests.system.test_system import Config  # system tests

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))
key1 = client.key('_Doctest')
entity1 = datastore.Entity(key=key1)
entity1['foo'] = 1337

key2 = client.key('_Doctest', 'abcd1234')
entity2 = datastore.Entity(key=key2)
entity2['foo'] = 42

Config.TO_DELETE.extend([entity1, entity2])

.. doctest:: txn-put-multi

>>> with client.transaction():
...     client.put_multi([entity1, entity2])

Because it derives from xref_Batch, Transaction also provides put and delete methods:

.. doctest:: txn-api

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:

.. testsetup:: txn-error

import os
import uuid

from google.cloud import datastore

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))

def do_some_work():
    return

class SomeException(Exception):
    pass

.. doctest:: txn-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:

.. testsetup:: txn-entity-key, txn-entity-key-after, txn-manual

    import os
    import uuid

    from google.cloud import datastore
    from tests.system.test_system import Config  # system tests

    unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
    client = datastore.Client(namespace='ns{}'.format(unique))

    def Entity(*args, **kwargs):
        entity = datastore.Entity(*args, **kwargs)
        Config.TO_DELETE.append(entity)
        return entity

.. doctest:: txn-entity-key

    >>> 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:

.. doctest:: txn-entity-key-after

  >>> 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:

.. doctest:: txn-manual

transaction = client.transaction() transaction.begin()

entity = Entity(key=client.key('Thing')) transaction.put(entity)

transaction.commit()

Parameters

Name	Description
client	Client the client used to connect to datastore.
read_only	bool indicates the transaction is read only.